Skip to main content
Version: latest - a1.0.0 ⚖️

🚙 Vehicle

Vehicles are 4-wheeled entities which Characters can possesses and drive.

Any Skeletal Mesh can be used to create a Vehicle, although only Skeletal Meshes with Wheels bones can use the built-in feature of animated Wheels.

caution

Currently only 4-Wheeled vehicles are supported.

tip

Please take a look at our Default’s Vehicle package with all built-in Vehicles already properly configured and ready to use: https://github.com/nanos-world/nanos-world-vehicles.

Monster Truckgetting-started/tutorials-and-examples/monster-truck
info

Inheritance: This class inherits from Actor and Paintable. Please check their pages for inherited Methods and Events.

Usage#

Server/Index.lua
-- Spawns a SUV Vehiclelocal vehicle = Vehicle(Vector(0, 0, 100), Rotator(), "nanos-world::SK_SUV", 0, true, false, true, "nanos-world::A_Vehicle_Engine_14")
-- Configure it's Engine Speed and Steering Wheel locationvehicle:SetEngineSetup(4500)vehicle:SetSteeringWheelSetup(Vector(0, 20, 131), 26)
-- Configures each Wheelvehicle:SetWheel(0, "Wheel_Front_Left",  35, 22, 50, 20, 0.25, 2, 17, 1000, 50, 50, 10)vehicle:SetWheel(1, "Wheel_Front_Right", 35, 22, 50, 20, 0.25, 2, 17, 1000, 50, 50, 10)vehicle:SetWheel(2, "Wheel_Rear_Left",   35, 22,  0, 20, 0.25, 2, 17, 1000, 50, 50, 10)vehicle:SetWheel(3, "Wheel_Rear_Right",  35, 22,  0, 20, 0.25, 2, 17, 1000, 50, 50, 10)
-- Adds 4 Doors/Seatsvehicle:SetDoor(0, Vector( 22, -80, 120), Vector(-18, -47, 110), Rotator(0, 0, 15), 75, -150)vehicle:SetDoor(1, Vector( 22,  80, 120), Vector( 5,   39,  90), Rotator(0, 0,  0), 60,  150)vehicle:SetDoor(2, Vector(-80, -80, 120), Vector(-60, -39,  90), Rotator(0, 0,  0), 60, -150)vehicle:SetDoor(3, Vector(-80,  80, 120), Vector(-60,  39,  90), Rotator(0, 0,  0), 60,  150)
-- Make it ready (so clients only create Physics once and not for each function call above)vehicle:RecreatePhysics()

Constructor Parameters#

TypeNameDefault
VectorlocationVector(0, 0, 0)
RotatorrotationRotator(0, 0, 0)
stringmodel_name (Skeletal Mesh)
CollisionTypecollision_typeCollisionType.Normal
booleangravity_enabledtrue
booleanauto_create_physics (can be disabled to improve performance when setting several configs. Must call RecreatePhysics() after all)true
booleanauto_unflip (auto rotates the vehicle if flipped)true
stringengine_sound_assetnanos-world::A_Vehicle_Engine_01
stringhorn_sound_assetnanos-world::A_Vehicle_Horn_Toyota
stringbrake_sound_assetnanos-world::A_Vehicle_Brake
stringengine_start_sound_assetnanos-world::A_Car_Engine_Start
stringvehicle_door_sound_assetnanos-world::A_Vehicle_Door

Functions#

Inherited Actor Functions
Base Actorscripting-reference/classes/base-classes/actor
ReturnsNameDescription
AddImpulseApplies a Force in world coordinate on this Actor
AttachToAttaches this Actor to any other Actor
DestroyDestroys this Actor
DetachDetaches this Actor if attached
SetCollisionSets the actor’s collision type
SetForceAdds a permanent force to this actor
SetGravityEnabledSets the actor’s gravity enabled
SetHighlightEnabledEnables this Actor Highlighting at a specific Index color
SetLifeSpanSets the actor’s life span to be destroyed
SetLocationSets the actor’s location in the game world
SetNetworkAuthoritySets this actor’s new Player Network Authority
SetRelativeLocationSets the actor’s relative location in local space
SetRelativeRotationSets the actor’s relative rotation in local space
SetRotationSets the actor’s rotation in the game world
SetScaleSets the actor’s scale
SetValueSets a value in this entity, which can be accessed by any package
TranslateToSmoothly moves this actor to a Location
RotateToSmoothly rotates this actor to a Rotation
booleanIsGravityEnabledGets the actor’s gravity enabled
booleanIsInWaterGets if the actor is in Water
booleanIsNetworkDistributedGets if the actor is Network Distributed
booleanIsValidReturns if this entity is valid (i.e. not destroyed)
tableGetAttachedEntitiesGets all actors attached to this entity
anyGetAttachedToGets the actor this actor is attached to
tableGetBoundsGets the actor bounds size
numberGetCollisionGets the current actor’s collision
numberGetIDGets the universal network ID of this entity
VectorGetLocationGet the actor’s position in the game world
VectorGetInitialLocationGets the initial location
RotatorGetRotationGets the actor’s rotation in the game world
VectorGetScaleGets the actor’s scale
stringGetTypeReturns the type of this Actor
anyGetValueGets a value given a key
VectorGetVelocityReturns the current actor Velocity
SubscribeSubscribes for an Event
UnsubscribeUnsubscribes from Events
Inherited Paintable Functions
Base Paintablescripting-reference/classes/base-classes/paintable
ReturnsNameDescription
SetMaterialReplace a materials of this actor with another Material
SetMaterialFromWebUIReplace a materials of this actor with a WebUI
SetMaterialColorParameterSets a Color parameter in this actor’s material
SetMaterialScalarParameterSets a scalar parameter in this actor’s material
SetMaterialTextureParameterLoads a image from computer (relative to Assets/ folder) and sets as parameter in this actor’s material
SetMaterialVectorParameterSets a Vector parameter in this actor’s material
caution

Most of the functions below will reset the vehicle Physics State (automatically), which means the vehicle will stop immediately if moving.

ReturnsNameDescription
AddStaticMeshAttachedSpawns and Attaches a StaticMesh into this Vehicle
HornStarts or stops the vehicles horn
RecreatePhysicsRecreate the Vehicle Physics
RemoveStaticMeshAttachedRemoves, if existing, a StaticMesh from this Vehicle given it’s custom ID
SetDifferentialSetupConfigures the Vehicle Differential
SetEngineSetupConfigures the Vehicle Engine
SetVehicleSetupConfigures the Vehicle General Settings
SetTransmissionSetupConfigures the Vehicle Transmission
SetWheelConfigures a Vehicle Wheel
SetDoorAdds a Door
SetSteeringWheelSetupConfigures where the Steering Wheel is located
SetHeadlightsSetupConfigures the Headlights Offset and Color
stringGetAssetNameGets the Asset name
CharacterGetPassengerGets a passengers at an index
tableGetPassengersGets all passengers

Events#

Inherited Actor Events
Base Actorscripting-reference/classes/base-classes/actor
NameDescription
DestroyTriggered when an Entity is Destroyed
SpawnTriggered when an Entity is Spawned/Created
ValueChangeTriggered when an Entity has it’s value changed
NameDescription
HornWhen Vehicle honks
HitWhen Vehicle hits something
CharacterEnteredWhen a Character enters the Vehicle
CharacterLeftWhen Character leaves the Vehicle
CharacterAttemptEnterWhen a Character attempts to Enter the Vehicle
CharacterAttemptLeaveWhen a Character attempts to Leave the Vehicle

Functions Detailed#

AddStaticMeshAttached#

Spawns and Attaches a StaticMesh into this Character in a Socket with relative Location and Rotation. Uses a custom ID to be used for removing it further

my_vehicle:AddStaticMeshAttached(id, static_mesh_path, socket, relative_location, relative_rotation)
TypeParameterDefault ValueDescription
stringid
stringstatic_mesh_path
stringsocket``
Vectorrelative_locationVector()
Rotatorrelative_rotationRotator()

Horn#

Starts or stops the vehicles horn

my_vehicle:Horn(enable_horn)
TypeParameterDefault ValueDescription
booleanenable_horn

RecreatePhysics#

Recreate the Vehicle Physics

Call this after configuring the vehicle if using auto_create_physics= false

my_vehicle:RecreatePhysics()

RemoveStaticMeshAttached#

Removes, if existing, a StaticMesh from this Vehicle given it's custom ID

my_vehicle:RemoveStaticMeshAttached(id)
TypeParameterDefault ValueDescription
stringid

SetDifferentialSetup#

Configures the Vehicle Differential

my_vehicle:SetDifferentialSetup(differential_type, front_rear_split, front_left_right_split, rear_left_right_split, center_bias, front_bias, rear_bias)
TypeParameterDefault ValueDescription
DifferentialTypedifferential_typeLimitedSlip_4W
numberfront_rear_split0.45Ratio of torque split between front and rear.
>0.5 means more to front
<0.5 means more to rear
(works only with 4W type)
numberfront_left_right_split0.5Ratio of torque split between front-left and front-right.
>0.5 means more to front-left
<0.5 means more to front-right
(works only with 4W and LimitedSlip_FrontDrive)
numberrear_left_right_split0.5Ratio of torque split between rear-left and rear-right
>0.5 means more to rear-left
<0.5 means more to rear-right
(works only with 4W and LimitedSlip_RearDrive)
numbercenter_bias1.3Maximum allowed ratio of average front wheel rotation speed and rear wheel rotation speeds
Acceptable range: 1 .. infinite
(works only with LimitedSlip_4W)
numberfront_bias1.3Maximum allowed ratio of front-left and front-right wheel rotation speeds
Acceptable range: 1 .. infinite
(works only with LimitedSlip_4W, LimitedSlip_FrontDrive)
numberrear_bias1.3Maximum allowed ratio of rear-left and rear-right wheel rotation speeds
Acceptable range: 1 .. infinite
(works only with LimitedSlip_4W, LimitedSlip_FrontDrive)

SetEngineSetup#

Configures the Vehicle Engine

my_vehicle:SetEngineSetup(max_rpm, moi, damping_rate_full_throttle, d_r_zero_trt_clutch_engaged, d_r_zero_trt_clutch_disengaged)
TypeParameterDefault ValueDescription
numbermax_rpm4500Maximum revolutions per minute of the engine
number
number
number
number

SetVehicleSetup#

Configures the Vehicle General Settings

my_vehicle:SetVehicleSetup(drag_coefficient, throttle_input_rise_rate, throttle_input_fall_rate, brake_input_rise_rate, brake_input_fall_rate, handbrake_input_rise_rate, handbrake_input_fall_rate, steering_input_rise_rate, steering_input_fall_rate)
TypeParameterDefault ValueDescription
numberdrag_coefficient0.3DragCoefficient of the vehicle chassis
numberthrottle_input_rise_rate6Rate at which the input value rises
numberthrottle_input_fall_rate10Rate at which the input value falls
numberbrake_input_rise_rate6Rate at which the input value rises
numberbrake_input_fall_rate10Rate at which the input value falls
numberhandbrake_input_rise_rate12Rate at which the input value rises
numberhandbrake_input_fall_rate12Rate at which the input value falls
numbersteering_input_rise_rate2.5Rate at which the input value rises
numbersteering_input_fall_rate5Rate at which the input value falls

SetTransmissionSetup#

Configures the Vehicle Transmission

my_vehicle:SetTransmissionSetup(has_automatic_transmission, gear_switch_time, gear_auto_box_latency, final_ratio, clutch_strength)
TypeParameterDefault ValueDescription
booleanhas_automatic_transmissiontrueWhether to use automatic transmission
numbergear_switch_time0.5Time it takes to switch gears (seconds)
numbergear_auto_box_latency2Minimum time it takes the automatic transmission to initiate a gear change (seconds)
numberfinal_ratio4The final gear ratio multiplies the transmission gear ratios
numberclutch_strength10Strength of clutch (Kgm^2/s)

SetWheel#

Configures a Vehicle Wheel

my_vehicle:SetWheel(index, bone_name, shape_radius, shape_width, steer_angle, mass, damping_rate, lat_stiff_max_load, lat_stiff_value, long_stiff_value, suspension_force_offset, suspension_max_raise, suspension_max_drop, suspension_natural_frequency, suspension_damping_ratio, max_brake_torque, max_handbrake_torque, is_affected_by_handbrake, offset)
TypeParameterDefault ValueDescription
number
stringbone_name
numbershape_radius30Radius of the wheel
numbershape_width10Width of the wheel
numbersteer_angle70Steer angle in degrees for this wheel
numbermass20Mass of this wheel
numberdamping_rate0.25Damping rate for this wheel (Kgm^2/s)
numberlat_stiff_max_load2Max normalized tire load at which the tire can deliver no more lateral stiffness no matter how much extra load is applied to the tire
numberlat_stiff_value17How much lateral stiffness to have given lateral slip
numberlong_stiff_value1000How much longitudinal stiffness to have given longitudinal slip
numbersuspension_force_offset0Vertical offset from where suspension forces are applied (along Z-axis)
numbersuspension_max_raise10How far the wheel can go above the resting position
numbersuspension_max_drop10How far the wheel can drop below the resting position
numbersuspension_natural_frequency7Oscillation frequency of suspension. Standard cars have values between 5 and 10
numbersuspension_damping_ratio1The rate at which energy is dissipated from the spring. Standard cars have values between 0.8 and 1.2. Values < 1 are more sluggish, values > 1 or more twitchy
numbermax_brake_torque1500Max brake torque for this wheel
numbermax_handbrake_torque3000Max handbrake brake torque for this wheel. A handbrake should have a stronger brake torque than the brake. This will be ignored for wheels that are not affected by the handbrake.
booleanis_affected_by_handbraketrue
VectoroffsetVector(0, 0, 0)If bone_name is specified, offset the wheel from the bone’s location. Otherwise this offsets the wheel from the vehicle’s origin

SetDoor#

Adds a Door at OffsetLocation from root which will pose the Character at SeatLocation with SeatRotation rotation. LeaveLateralOffset is where the Character will be ejected when leaving it (e.g. -150 for left door or 150 for right door)

my_vehicle:SetDoor(seat_index, offset_location, seat_location, seat_rotation, trigger_radius, leave_lateral_offset)
TypeParameterDefault ValueDescription
numberseat_index
Vectoroffset_location
Vectorseat_location
Rotatorseat_rotation
numbertrigger_radius
numberleave_lateral_offset

SetSteeringWheelSetup#

Configures where the Steering Wheel is located, so Characters can grab it procedurally properly

my_vehicle:SetSteeringWheelSetup(location, radius)
TypeParameterDefault ValueDescription
Vectorlocation
numberradius

SetHeadlightsSetup#

Configures the Headlights Offset and Color.

my_vehicle:SetHeadlightsSetup(location, color)
TypeParameterDefault ValueDescription
Vectorlocation
ColorcolorColor(1, 0.86, 0.5)

GetAssetName#

Gets the Asset name

Returns string

my_vehicle:GetAssetName()

GetPassenger#

Gets a passenger from a seat

returns Player or nil if Seat is invalid or empty

my_vehicle:GetPassenger(seat)
TypeParameterDefault ValueDescription
numberseat

GetPassengers#

Gets all passengers

Returns table of Players

my_vehicle:GetPassengers()

Events Detailed#

Horn#

Triggered when Vehicle honks

Vehicle.Subscribe("Horn", function(self, is_honking)
end)
TypeParameterDescription
Vehicleself
booleanis_honking

Hit#

Triggered when Vehicle hits something

Vehicle.Subscribe("Hit", function(self, impact_force, normal_impulse, impact_location, velocity)
end)
TypeParameterDescription
Vehicleself
numberimpact_forceThe intensity of the Hit normalized by the Vehicle's weight
Vectornormal_impulseThe impulse direction it hits
Vectorimpact_locationThe world 3D location of the impact
VectorvelocityThe Vehicle velocity at the moment it hits

CharacterEntered#

Triggered when a Character fully enters the Vehicle

Vehicle.Subscribe("CharacterEntered", function(self, character, seat)
end)
TypeParameterDescription
Vehicleself
Charactercharacter
numberseatThe seat index

CharacterLeft#

Triggered when a Character fully leaves the Vehicle

Vehicle.Subscribe("CharacterLeft", function(self, character)
end)
TypeParameterDescription
Vehicleself
Charactercharacter

CharacterAttemptEnter#

Triggered when a Character attempts to enter the Vehicle

Return false to prevent it

Vehicle.Subscribe("CharacterAttemptEnter", function(self, character, seat)
end)
TypeParameterDescription
Vehicleself
Charactercharacter
numberseatThe seat index

CharacterAttemptLeave#

Triggered when a Character attempts to enter the Vehicle

Return false to prevent it

Vehicle.Subscribe("CharacterAttemptLeave", function(self, character)
end)
TypeParameterDescription
Vehicleself
Charactercharacter