Skip to main content
Version: latest - a1.15.x βš–οΈ

πŸš™ Vehicle

Vehicles are wheeled entities which Characters can possesses and drive.

πŸ’‚Authority
This class can only be spawned on 🟦 Server.
πŸ‘ͺInheritance
This class inherits from Base Actor Base Paintable .

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.

πŸŽ’ Examples​

Server/Index.lua
-- Spawns a Pickup Vehicle
local vehicle = Vehicle(location or Vector(), rotation or Rotator(), "nanos-world::SK_Pickup", CollisionType.Normal, true, false, true, "nanos-world::A_Vehicle_Engine_10")

-- Configure it's Engine power and Aerodynamics
vehicle:SetEngineSetup(700, 5000)
vehicle:SetAerodynamicsSetup(2500)

-- Configure it's Steering Wheel and Headlights location
vehicle:SetSteeringWheelSetup(Vector(0, 27, 120), 24)
vehicle:SetHeadlightsSetup(Vector(270, 0, 70))

-- Configures each Wheel
vehicle:SetWheel(0, "Wheel_Front_Left", 27, 18, 45, Vector(), true, true, false, false, false, 1500, 3000, 1000, 1, 3, 20, 20, 250, 50, 10, 10, 0, 0.5, 0.5)
vehicle:SetWheel(1, "Wheel_Front_Right", 27, 18, 45, Vector(), true, true, false, false, false, 1500, 3000, 1000, 1, 3, 20, 20, 250, 50, 10, 10, 0, 0.5, 0.5)
vehicle:SetWheel(2, "Wheel_Rear_Left", 27, 18, 0, Vector(), false, true, true, false, false, 1500, 3000, 1000, 1, 4, 20, 20, 250, 50, 10, 10, 0, 0.5, 0.5)
vehicle:SetWheel(3, "Wheel_Rear_Right", 27, 18, 0, Vector(), false, true, true, false, false, 1500, 3000, 1000, 1, 4, 20, 20, 250, 50, 10, 10, 0, 0.5, 0.5)

-- Adds 6 Doors/Seats
vehicle:SetDoor(0, Vector( 50, -75, 105), Vector( 8, -32.5, 95), Rotator(0, 0, 10), 70, -150)
vehicle:SetDoor(1, Vector( 50, 75, 105), Vector( 25, 50, 90), Rotator(0, 0, 0), 70, 150)
vehicle:SetDoor(2, Vector( -90, -75, 130), Vector( -90, -115, 155), Rotator(0, 90, 20), 60, -150)
vehicle:SetDoor(3, Vector( -90, 75, 130), Vector( -90, 115, 155), Rotator(0, -90, 20), 60, 150)
vehicle:SetDoor(4, Vector(-195, -75, 130), Vector(-195, -115, 155), Rotator(0, 90, 20), 60, -150)
vehicle:SetDoor(5, Vector(-195, 75, 130), Vector(-195, 115, 155), Rotator(0, -90, 20), 60, 150)

-- Make it ready (so clients only create Physics once and not for each function call above)
vehicle:RecreatePhysics()

πŸ—οΈ Constructor​

local my_vehicle = Vehicle(location?, rotation?, asset?, collision_type?, gravity_enabled?, auto_create_physics?, auto_unflip?, engine_sound?, horn_sound?, brake_sound?, engine_start_sound?, vehicle_door_sound?, auto_start_engine?)
TypeNameDefaultDescription
Vector locationVector(0, 0, 0)
Rotator rotationRotator(0, 0, 0)
SkeletalMesh Reference asset
CollisionTypecollision_typeCollisionType.Normal
boolean gravity_enabledtrue
boolean auto_create_physicstrueCan be disabled to improve performance when setting several configs. Must call RecreatePhysics() after all
boolean auto_unfliptrueAuto rotates the vehicle if flipped
Sound Reference engine_soundnanos-world::A_Vehicle_Engine_01
Sound Reference horn_soundnanos-world::A_Vehicle_Horn_Toyota
Sound Reference brake_soundnanos-world::A_Vehicle_Brake
Sound Reference engine_start_soundnanos-world::A_Car_Engine_Start
Sound Reference vehicle_door_soundnanos-world::A_Vehicle_Door
boolean auto_start_enginetrue
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.

More related examples:

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

🦠 Functions​

Inherited Actor Functions
Base Actorscripting-reference/classes/base-classes/actor
ReturnsNameDescription
AddImpulseApplies a force in world world to this Actor
AttachToAttaches this Actor to any other Actor, optionally at a specific bone
DestroyDestroys this Actor
DetachDetaches this Actor from AttachedTo Actor
SetCollisionSets this Actor's collision type
SetForceAdds a permanent force to this Actor, set to Vector(0, 0, 0) to cancel
SetGravityEnabledSets whether gravity is enabled on this Actor
SetVisibilitySets whether the actor is visible or not
SetHighlightEnabledSets whether the highlight is enabled on this Actor, and which highlight index to use
SetOutlineEnabledSets whether the outline is enabled on this Actor, and which outline index to use
SetLifeSpanSets the time (in seconds) before this Actor is destroyed. After this time has passed, the actor will be automatically destroyed.
SetLocationSets this Actor's location in the game world
SetRotationSets this Actor's rotation in the game world
SetRelativeLocationSets this Actor's relative location in local space (only if this actor is attached)
SetRelativeRotationSets this Actor's relative rotation in local space (only if this actor is attached)
SetScaleSets this Actor's scale
SetNetworkAuthoritySets the Player to have network authority over this Actor
SetValueSets a value in this Actor
TranslateToSmoothly moves this actor to a location over a certain time
RotateToSmoothly rotates this actor to an angle over a certain time
boolean IsBeingDestroyedReturns true if this Actor is being destroyed
boolean IsVisibleReturns true if this Actor is visible
boolean IsGravityEnabledReturns true if gravity is enabled on this Actor
boolean IsInWaterReturns true if this Actor is in water
boolean IsNetworkDistributedReturns true if this Actor is currently network distributed
boolean IsValidReturns true if this Actor is valid (i.e. wasn't destroyed and points to a valid Actor)
table of Base Actor GetAttachedEntitiesGets all Actors attached to this Actor
Base Actor or nilGetAttachedToGets the Actor this Actor is attached to
table GetBoundsGets this Actor's bounds
CollisionTypeGetCollisionGets this Actor's collision type
number GetIDGets the universal network ID of this Actor (same on both client and server)
Vector GetLocationGets this Actor's location in the game world
Rotator GetRotationGets this Actor's angle in the game world
Vector GetForceGets this Actor's force (set by SetForce())
boolean HasNetworkAuthorityReturns true if the local Player is currently the Network Authority of this Actor
boolean HasAuthorityGets if this Actor was spawned by the client side
Vector GetScaleGets this Actor's scale
string GetTypeGets the type of this Actor
any GetValueGets a value stored on this Actor at the given key. Please refer to Entity Values for more information
Vector GetVelocityGets this Actor's current velocity
AddActorTagAdds an Unreal Actor Tag to this Actor
RemoveActorTagRemoves an Unreal Actor Tag from this Actor
table of string GetActorTagsGets all Unreal Actor Tags on this Actor
function SubscribeSubscribes to an Event
UnsubscribeUnsubscribes all callbacks from this Event in this Actor within this Package, or only the callback passed
Inherited Paintable Functions
Base Paintablescripting-reference/classes/base-classes/paintable
ReturnsNameDescription
SetMaterialSets the material at the specified index of this Actor
SetMaterialFromCanvasSets the material at the specified index of this Actor to a Canvas object
SetMaterialFromSceneCaptureSets the material at the specified index of this Actor to a SceneCapture object
SetMaterialFromWebUISets the material at the specified index of this Actor to a WebUI object
ResetMaterialResets the material from the specified index to the original one
SetMaterialColorParameterSets a Color parameter in this Actor's material
SetMaterialScalarParameterSets a Scalar parameter in this Actor's material
SetMaterialTextureParameterSets a texture parameter in this Actor's material to an image on disk
SetMaterialVectorParameterSets a Vector parameter in this Actor's material
SetPhysicalMaterialOverrides this Actor's Physical Material with a new one
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
RemoveAllStaticMeshesAttachedRemoves all StaticMeshes attached
SetAutoStartEngineSets if the Engine auto starts when the driver enters the Vehicle
SetEngineStartedSets if the Engine is turned off/on
SetDifferentialSetupConfigures the Vehicle Differential
SetEngineSetupConfigures the Vehicle Engine (Torque, RPM, Braking)
SetAerodynamicsSetupConfigures the Vehicle Aerodynamics Settings
SetTransmissionSetupConfigures the Vehicle Transmission
SetWheelConfigures a Vehicle Wheel
SetDoorAdds a Door to the Vehicle
SetSteeringWheelSetupConfigures where the Steering Wheel is located
SetHeadlightsSetupConfigures the Headlights Offset and Color.
SetTaillightsSetupConfigures the Taillights Offset.
VehiclePathGetAssetNameGets the Asset name
Character GetPassengerGets a passenger from a seat
table of Character GetPassengersGets all passengers
number GetRPMGets the current RPM
number GetGearGets the current Gear

AddStaticMeshAttached​

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

For customizing the Materials specific of a StaticMeshAttached, please use the following syntax as the parameter_nameattachable///[ATTACHABLE_ID]/[PARAMETER_NAME], where [ATTACHABLE_ID] is the ID of the Attachable, and [PARAMETER_NAME] is the name of the parameter you want to change.
my_vehicle:AddStaticMeshAttached(id, static_mesh_asset?, socket?, relative_location?, relative_rotation?)
TypeParameterDefaultDescription
string idUsed further for removing or applying material settings on it
StaticMesh Reference static_mesh_asset?
string socket?
Vector relative_location?Vector(0, 0, 0)
Rotator relative_rotation?Rotator(0, 0, 0)

Horn​

Starts or stops the vehicles horn
my_vehicle:Horn(enable_horn)
TypeParameterDefaultDescription
boolean enable_horn

RecreatePhysics​

Call this after configuring the vehicle if passed auto_create_physics to constructor
my_vehicle:RecreatePhysics()

RemoveStaticMeshAttached​

Removes, if existing, a StaticMesh from this Vehicle given it's custom ID
my_vehicle:RemoveStaticMeshAttached(id)
TypeParameterDefaultDescription
string id

RemoveAllStaticMeshesAttached​

Removes all StaticMeshes attached
my_vehicle:RemoveAllStaticMeshesAttached()

SetAutoStartEngine​

Sets if the Engine auto starts when the driver enters the Vehicle
my_vehicle:SetAutoStartEngine(auto_start)
TypeParameterDefaultDescription
boolean auto_start

SetEngineStarted​

Sets if the Engine is turned off/on (this will affect Lights, Sounds and ability to Throttle)
my_vehicle:SetEngineStarted(started)
TypeParameterDefaultDescription
boolean started

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?)
TypeParameterDefaultDescription
DifferentialTypedifferential_type?LimitedSlip_4W
number front_rear_split?0.45Ratio of torque split between front and rear
bigger than 0.5 means more to front
lower than 0.5 means more to rear (works only with 4W type)
number front_left_right_split?0.5Ratio of torque split between front-left and front-right
bigger than 0.5 means more to front-left
lower than 0.5 means more to front-right (works only with 4W and LimitedSlip_FrontDrive)
number rear_left_right_split?0.5Ratio of torque split between rear-left and rear-right
bigger than 0.5 means more to rear-left
lower than 0.5 means more to rear-right (works only with 4W and LimitedSlip_RearDrive)
number center_bias?1.3Maximum allowed ratio of average front wheel rotation speed and rear wheel rotation speeds Acceptable range: 1 .. infinite (works only with LimitedSlip_4W)
number front_bias?1.3Maximum allowed ratio of front-left and front-right wheel rotation speeds Acceptable range: 1 .. infinite (works only with LimitedSlip_4W, LimitedSlip_FrontDrive)
number rear_bias?1.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 (Torque, RPM, Braking)
my_vehicle:SetEngineSetup(max_torque?, max_rpm?, idle_rpm?, brake_effect?, rev_up_moi?, rev_down_rate?)
TypeParameterDefaultDescription
number max_torque?700Max Engine Torque (Nm) is multiplied by TorqueCurve
number max_rpm?5700Maximum revolutions per minute of the engine
number idle_rpm?1200Idle RMP of engine then in neutral/stationary
number brake_effect?0.05Braking effect from engine, when throttle released
number rev_up_moi?5Affects how fast the engine RPM speed up
number rev_down_rate?600Affects how fast the engine RPM slows down

SetAerodynamicsSetup​

Configures the Vehicle Aerodynamics Settings
my_vehicle:SetAerodynamicsSetup(mass?, drag_coefficient?, vehicle_chassis_width?, vehicle_chassis_height?, vehicle_downforce_coefficient?)
TypeParameterDefaultDescription
number mass?1500Mass of the vehicle chassis
number drag_coefficient?0.3Force resisting forward motion at speed
number vehicle_chassis_width?180Chassis width used for drag force computation (cm)
number vehicle_chassis_height?140Chassis height used for drag force computation (cm)
number vehicle_downforce_coefficient?0.3Force pressing vehicle into ground at speed

SetTransmissionSetup​

Configures the Vehicle Transmission
my_vehicle:SetTransmissionSetup(transmission_final_ratio?, transmission_change_up_rpm?, transmission_change_down_rpm?, transmission_gear_change_time?, transmission_efficiency?)
TypeParameterDefaultDescription
number transmission_final_ratio?3.08The final gear ratio multiplies the transmission gear ratios
number transmission_change_up_rpm?4500Engine Revs at which gear up change ocurrs
number transmission_change_down_rpm?2000Engine Revs at which gear down change ocurrs
number transmission_gear_change_time?0.4Time it takes to switch gears (seconds)
number transmission_efficiency?0.94Mechanical frictional losses mean transmission might operate at 0.94 (94% efficiency)

SetWheel​

Wheels can be updated in runtime by calling SetWheel again, you can for example change the suspension high or disable a wheel totally by toggling affected_by_engine off or setting radius to 0.
my_vehicle:SetWheel(index, bone_name, radius?, width?, max_steer_angle?, offset?, is_affected_by_engine?, is_affected_by_brake?, is_affected_by_handbrake?, has_abs_enabled?, has_traction_control_enabled?, max_brake_torque?, max_handbrake_torque?, cornering_stiffness?, side_slip_modifier?, friction_force_multiplier?, slip_threshold?, skid_threshold?, suspension_spring_rate?, suspension_spring_preload?, suspension_max_raise?, suspension_max_drop?, suspension_smoothing?, suspension_damping_ratio?, suspension_wheel_load_ratio?, suspension_axis?, suspension_force_offset?)
TypeParameterDefaultDescription
number indexIndex of the wheel (0-N). Set it in ASC order
string bone_nameName of the bone to attach this wheel to
number radius?32Radius of the wheel
number width?20Width of the wheel
number max_steer_angle?50Steer angle in degrees for this wheel
Vector offset?Vector(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
boolean is_affected_by_engine?trueWhether engine should power this wheel
boolean is_affected_by_brake?trueWhether brake should affect this wheel
boolean is_affected_by_handbrake?trueWhether handbrake should affect this wheel
boolean has_abs_enabled?falseAdvanced Braking System Enabled
boolean has_traction_control_enabled?falseStraight Line Traction Control Enabled
number max_brake_torque?1500Max brake torque for this wheel (Nm)
number max_handbrake_torque?3000Max handbrake brake torque for this wheel (Nm). A handbrake should have a stronger brake torque than the brake
number cornering_stiffness?1000Tyre Cornering Ability
number side_slip_modifier?1Wheel Lateral Skid Grip Loss, lower number less grip on skid
number friction_force_multiplier?2Friction Force Multiplier
number slip_threshold?20Wheel Longitudinal Slip Threshold
number skid_threshold?20Wheel Lateral Skid Threshold
number suspension_spring_rate?250Spring Force (N/m)
number suspension_spring_preload?50Spring Preload (N/m)
number suspension_max_raise?10How far the wheel can go above the resting position
number suspension_max_drop?10How far the wheel can drop below the resting position
number suspension_smoothing?0Smooth suspension [0-off, 10-max] - Warning might cause momentary visual inter-penetration of the wheel against objects/terrain
number suspension_damping_ratio?0.5Suspension damping, larger value causes the suspension to come to rest faster [range 0 to 1]
number suspension_wheel_load_ratio?0.5Amount wheel load effects wheel friction.
- At 0 wheel friction is completely independent of the loading on the wheel (This is artificial as it always assumes even balance between all wheels)
- At 1 wheel friction is based on the force pressing wheel into the ground. This is more realistic.
- Lower value cures lift off over-steer, generally makes vehicle easier to handle under extreme motions.
Vector suspension_axis?Vector(0, 0, -1)Local body direction in which where suspension forces are applied (typically along -Z-axis)
Vector suspension_force_offset?Vector(0, 0, 0)Vertical offset from where suspension forces are applied (along Z-axis)

SetDoor​

Adds a Door at offset_location from root which will pose the Character at seat_location with seat_rotation rotation.
my_vehicle:SetDoor(seat_index, offset_location, seat_location, seat_rotation, trigger_radius, leave_lateral_offset)
TypeParameterDefaultDescription
number seat_index
Vector offset_location
Vector seat_location
Rotator seat_rotation
number trigger_radius
number leave_lateral_offsetIt's where the Character will be ejected when leaving it (e.g. -150 for left door or 150 for right door)

SetSteeringWheelSetup​

Configures where the Steering Wheel is located, so Characters can grab it procedurally properly
my_vehicle:SetSteeringWheelSetup(location, radius)
TypeParameterDefaultDescription
Vector location
number radius

SetHeadlightsSetup​

Configures the Headlights Offset and Color.
my_vehicle:SetHeadlightsSetup(location, color?)
TypeParameterDefaultDescription
Vector location
Color color?Color(1, 0.86, 0.5)

SetTaillightsSetup​

Configures the Taillights Offset.
my_vehicle:SetTaillightsSetup(location)
TypeParameterDefaultDescription
Vector location

GetAssetName​

Gets the Asset name

Returns VehiclePath (asset path)
local ret = my_vehicle:GetAssetName()

GetPassenger​

Gets a passenger from a seat

Returns Character (or nil if no passenger in seat)
local ret = my_vehicle:GetPassenger(seat)
TypeParameterDefaultDescription
number seat

GetPassengers​

Gets all passengers

Returns table of Character ()
local ret = my_vehicle:GetPassengers()

GetRPM​

Gets the current RPM

Returns number ()
local ret = my_vehicle:GetRPM()

GetGear​

Gets the current Gear

Returns number ()
local ret = my_vehicle:GetGear()

πŸš€ Events​

Inherited Actor Events
Base Actorscripting-reference/classes/base-classes/actor
NameDescription
DestroyTriggered when an Actor is destroyed
SpawnTriggered when an Actor is spawned/created
ValueChangeTriggered when an Actor has a value changed with :SetValue()
NameDescription
HornTriggered when Vehicle honks
HitTriggered when Vehicle hits something
CharacterEnteredTriggered when a Character fully enters the Vehicle
CharacterLeftTriggered when a Character fully leaves the Vehicle
CharacterAttemptEnterTriggered when a Character attempts to enter the Vehicle
CharacterAttemptLeaveTriggered when a Character attempts to leave the Vehicle

Horn​

Triggered when Vehicle honks
Vehicle.Subscribe("Horn", function(self, is_honking)

end)
TypeArgumentDescription
Vehicle self
boolean is_honking

Hit​

Triggered when Vehicle hits something
Vehicle.Subscribe("Hit", function(self, impact_force, normal_impulse, impact_location, velocity)

end)
TypeArgumentDescription
Vehicle self
number impact_forceThe intensity of the Hit normalized by the Vehicle's weight
Vector normal_impulseThe impulse direction it hits
Vector impact_locationThe world 3D location of the impact
Vector velocityThe Vehicle velocity at the moment it hits

CharacterEntered​

Triggered when a Character fully enters the Vehicle
Vehicle.Subscribe("CharacterEntered", function(self, character, seat)

end)
TypeArgumentDescription
Vehicle self
Character character
number seatThe seat index

CharacterLeft​

Triggered when a Character fully leaves the Vehicle
Vehicle.Subscribe("CharacterLeft", function(self, character)

end)
TypeArgumentDescription
Vehicle self
Character character

CharacterAttemptEnter​

Triggered when a Character attempts to enter the Vehicle

Return false to prevent it
Vehicle.Subscribe("CharacterAttemptEnter", function(self, character, seat)

end)
TypeArgumentDescription
Vehicle self
Character character
number seatThe seat index

CharacterAttemptLeave​

Triggered when a Character attempts to leave the Vehicle

Return false to prevent it
Vehicle.Subscribe("CharacterAttemptLeave", function(self, character)

end)
TypeArgumentDescription
Vehicle self
Character character