🚙 Vehicle

Vehicles are wheeled entities which Characters can possesses and drive.

info

🟦 Authority: This class can only be spawned on Server.

⏬ Inheritance: This class inherits from Base Actor and 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.

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

Usage

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 Parameters

Type	Name	Default	Description
Vector	location	Vector(0, 0, 0)
Rotator	rotation	Rotator(0, 0, 0)
SkeletalMesh Reference	asset	``
CollisionType	collision_type	CollisionType.Normal
boolean	gravity_enabled	true
boolean	auto_create_physics	true	(can be disabled to improve performance when setting several configs. Must call RecreatePhysics() after all)
boolean	auto_unflip	true	(auto rotates the vehicle if flipped)
Sound Reference	engine_sound_asset	nanos-world::A_Vehicle_Engine_01
Sound Reference	horn_sound_asset	nanos-world::A_Vehicle_Horn_Toyota
Sound Reference	brake_sound_asset	nanos-world::A_Vehicle_Brake
Sound Reference	engine_start_sound_asset	nanos-world::A_Car_Engine_Start
Sound Reference	vehicle_door_sound_asset	nanos-world::A_Vehicle_Door
boolean	auto_start_engine	true

Functions

Inherited Actor Functions

Base Actorscripting-reference/classes/base-classes/actor

	Returns	Name	Description
		AddImpulse	Applies a Force in world space to this Actor
		AttachTo	Attaches this Actor to another Actor
		Destroy	Destroys this Actor
		Detach	Detaches this Actor if attached
		SetCollision	Sets this Actor's collision type
		SetForce	Adds a permanent force to this Actor
		SetGravityEnabled	Sets whether gravity is enabled on this Actor
		SetVisibility	Sets the Actor visibility
		SetHighlightEnabled	Sets whether the highlight is enabled on this Actor, and which highlight index to use
		SetOutlineEnabled	Sets whether the outline is enabled on this Actor, and which outline index to use
		SetLifeSpan	Sets the time (in seconds) before this Actor is destroyed
		SetLocation	Sets this Actor's location in the game world
		SetNetworkAuthority	Sets the Player this Actor will have its physics calculated on Network Authority
		SetRelativeLocation	Sets this Actor's relative location in local space
		SetRelativeRotation	Sets this Actor's relative rotation in local space
		SetRotation	Sets this Actor's rotation in the game world
		SetScale	Sets this Actor's scale
		SetValue	Sets a value in this Actor, which can be accessed by any package
		TranslateTo	Smoothly moves this Actor to the specified location
		RotateTo	Smoothly rotates this Actor to the specified angle
	boolean	HasNetworkAuthority	Gets if the LocalPlayer is currently the Network Authority of this Actor
	boolean	HasAuthority	Gets if this Actor was spawned by the client side
	boolean	IsBeingDestroyed	Gets if this Actor is being destroyed
	boolean	IsGravityEnabled	Gets whether gravity is enabled on this Actor
	boolean	IsVisible	Gets whether this actor is Visible or not
	boolean	IsInWater	Gets if this Actor is in water
	boolean	IsNetworkDistributed	Gets if this Actor is currently Network Distributed
	boolean	IsValid	Returns if this Actor is valid (i.e. not destroyed)
	table	GetAttachedEntities	Gets all Actors attached to this Actor
	any	GetAttachedTo	Gets the Actor this Actor is attached to
	table	GetBounds	Gets this Actor's bounds
	number	GetCollision	Gets this Actor's collision type
	number	GetID	Gets the universal network ID of this Actor
	Vector	GetLocation	Gets this Actor's location in the game world
	Rotator	GetRotation	Gets this Actor's angle in the game world
	Vector	GetForce	Gets this Actor's scale
	Vector	GetScale	Gets this Actor's scale
	string	GetType	Gets the type of this Actor
	any	GetValue	Gets a value stored on this Actor at the given key
	Vector	GetVelocity	Returns this Actor's current velocity
	string	AddActorTag	Adds an Unreal Actor Tag to this Actor
	string	RemoveActorTag	Remove an Unreal Actor Tag from this Actor
	table	GetActorTags	Gets all Unreal Actor Tags from this Actor
	function	Subscribe	Subscribes to an Event
		Unsubscribe	Unsubscribes from an Event

Inherited Paintable Functions

Base Paintablescripting-reference/classes/base-classes/paintable

	Returns	Name	Description
		SetMaterial	Sets the material at the specified index of this Actor
		SetMaterialFromWebUI	Sets the material at the specified index of this Actor to a WebUI object
		SetMaterialFromSceneCapture	Sets the material at the specified index of this Actor to a SceneCapture object
		ResetMaterial	Resets the material from the specified index to the original one
		SetMaterialColorParameter	Sets a Color parameter in this Actor’s material
		SetMaterialScalarParameter	Sets a scalar parameter in this Actor’s material
		SetMaterialTextureParameter	Sets a texture parameter in this Actor's material to an image on disk
		SetMaterialVectorParameter	Sets a Vector parameter in this Actor’s material
		SetPhysicalMaterial	Overrides this Actor's Physical Material with a new one

	Returns	Name	Description
		AddStaticMeshAttached	Spawns and Attaches a StaticMesh into this Vehicle
		Horn	Starts or stops the vehicles horn
		RecreatePhysics	Recreate the Vehicle Physics
		RemoveStaticMeshAttached	Removes, if existing, a StaticMesh from this Vehicle given it's custom ID
		RemoveAllStaticMeshesAttached	Removes all StaticMeshes attached
		SetAutoStartEngine	Sets if the Engine auto starts when the driver enters the Vehicle
		SetEngineStarted	Starts/Stops the Engine
		SetDifferentialSetup	Configures the Vehicle Differential
		SetEngineSetup	Configures the Vehicle Engine
		SetAerodynamicsSetup	Configures the Vehicle Aerodynamics Settings
		SetTransmissionSetup	Configures the Vehicle Transmission
		SetWheel	Configures a Vehicle Wheel
		SetDoor	Adds a Door
		SetSteeringWheelSetup	Configures where the Steering Wheel is located
		SetHeadlightsSetup	Configures the Headlights Offset and Color
		SetTaillightsSetup	Configures the Taillights Offset
	string	GetAssetName	Gets the Asset name
	Character	GetPassenger	Gets a passengers at an index
	table	GetPassengers	Gets all passengers
	number	GetRPM	Gets the current RPM
	number	GetGear	Gets the current Gear

Events

Inherited Actor Events

Base Actorscripting-reference/classes/base-classes/actor

	Name	Description
	Destroy	Triggered when an Actor is destroyed
	Spawn	Triggered when an Actor is spawned/created
	ValueChange	Triggered when an Actor has a value changed with :SetValue()

	Name	Description
	Horn	When Vehicle honks
	Hit	When Vehicle hits something
	CharacterEntered	When a Character enters the Vehicle
	CharacterLeft	When Character leaves the Vehicle
	CharacterAttemptEnter	When a Character attempts to Enter the Vehicle
	CharacterAttemptLeave	When 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

For customizing the Materials specific of a StaticMeshAttached, please use the following syntax as the parameter_name in the Base Paintable methods: attachable///[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_path, socket, relative_location, relative_rotation)

Type	Parameter	Default Value	Description
string	id
string	static_mesh_path
string	socket	``
Vector	relative_location	Vector()
Rotator	relative_rotation	Rotator()

Horn

Starts or stops the vehicles horn

my_vehicle:Horn(enable_horn)

Type	Parameter	Default Value	Description
boolean	enable_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)

Type	Parameter	Default Value	Description
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)

Type	Parameter	Default Value	Description
	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)

Type	Parameter	Default Value	Description
	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)

Type	Parameter	Default Value	Description
DifferentialType	differential_type	LimitedSlip_4W
number	front_rear_split	0.45	Ratio of torque split between front and rear. >0.5 means more to front <0.5 means more to rear (works only with 4W type)
number	front_left_right_split	0.5	Ratio 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)
number	rear_left_right_split	0.5	Ratio 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)
number	center_bias	1.3	Maximum 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.3	Maximum 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.3	Maximum 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)

Type	Parameter	Default Value	Description
number	max_torque	700	Max Engine Torque (Nm) is multiplied by TorqueCurve
number	max_rpm	5700	Maximum revolutions per minute of the engine
number	idle_rpm	1200	Idle RMP of engine then in neutral/stationary
number	brake_effect	0.05	Braking effect from engine, when throttle released
number	rev_up_moi	5	Affects how fast the engine RPM speed up
number	rev_down_rate	600	Affects 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)

Type	Parameter	Default Value	Description
number	mass	1500	Mass of the vehicle chassis
number	drag_coefficient	0.3	Force resisting forward motion at speed
number	vehicle_chassis_width	180	Chassis width used for drag force computation (cm)
number	vehicle_chassis_height	140	Chassis height used for drag force computation (cm)
number	vehicle_downforce_coefficient	0.3	Force 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)

Type	Parameter	Default Value	Description
boolean	transmission_final_ratio	3.08	The final gear ratio multiplies the transmission gear ratios
number	transmission_change_up_rpm	4500	Engine Revs at which gear up change ocurrs
number	transmission_change_down_rpm	2000	Engine Revs at which gear down change ocurrs
number	transmission_gear_change_time	0.4	Time it takes to switch gears (seconds)
number	transmission_efficiency	0.94	Mechanical frictional losses mean transmission might operate at 0.94 (94% efficiency)

SetWheel

Configures a Vehicle Wheel

tip

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)

Type	Parameter	Default Value	Description
number	index		Index of the wheel (0-N). Set it in ASC order
string	bone_name		Name of the bone to attach this wheel to
number	radius	32	Radius of the wheel
number	width	20	Width of the wheel
number	max_steer_angle	50	Steer 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	true	Whether engine should power this wheel
boolean	is_affected_by_brake	true	Whether brake should affect this wheel
boolean	is_affected_by_handbrake	true	Whether handbrake should affect this wheel
boolean	has_abs_enabled	false	Advanced Braking System Enabled
boolean	has_traction_control_enabled	false	Straight Line Traction Control Enabled
number	max_brake_torque	1500	Max brake torque for this wheel (Nm)
number	max_handbrake_torque	3000	Max handbrake brake torque for this wheel (Nm). A handbrake should have a stronger brake torque than the brake
number	cornering_stiffness	1000	Tyre Cornering Ability
number	side_slip_modifier	1	Wheel Lateral Skid Grip Loss, lower number less grip on skid
number	friction_force_multiplier	2	Friction Force Multiplier
number	slip_threshold	20	Wheel Longitudinal Slip Threshold
number	skid_threshold	20	Wheel Lateral Skid Threshold
number	suspension_spring_rate	250	Spring Force (N/m)
number	suspension_spring_preload	50	Spring Preload (N/m)
number	suspension_max_raise	10	How far the wheel can go above the resting position
number	suspension_max_drop	10	How far the wheel can drop below the resting position
number	suspension_smoothing	0	Smooth suspension [0-off, 10-max] - Warning might cause momentary visual inter-penetration of the wheel against objects/terrain
number	suspension_damping_ratio	0.5	Suspension damping, larger value causes the suspension to come to rest faster [range 0 to 1]
number	suspension_wheel_load_ratio	0.5	Amount 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 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)

Type	Parameter	Default Value	Description
number	seat_index
Vector	offset_location
Vector	seat_location
Rotator	seat_rotation
number	trigger_radius
number	leave_lateral_offset

SetSteeringWheelSetup

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

my_vehicle:SetSteeringWheelSetup(location, radius)

Type	Parameter	Default Value	Description
Vector	location
number	radius

SetHeadlightsSetup

Configures the Headlights Offset and Color.

my_vehicle:SetHeadlightsSetup(location, color)

Type	Parameter	Default Value	Description
Vector	location
Color	color	Color(1, 0.86, 0.5)

SetTaillightsSetup

Configures the Taillights Offset.

my_vehicle:SetTaillightsSetup(location)

Type	Parameter	Default Value	Description
Vector	location

GetAssetName

Gets the Asset name

Returns string

my_vehicle:GetAssetName()

GetPassenger

Gets a passenger from a seat

returns Character or nil if Seat is invalid or empty

my_vehicle:GetPassenger(seat)

Type	Parameter	Default Value	Description
number	seat

GetPassengers

Gets all passengers

Returns table of Characters

my_vehicle:GetPassengers()

GetRPM

Gets the current RPM

Returns number

my_vehicle:GetRPM()

GetGear

Gets the current Gear

Returns number

my_vehicle:GetGear()

Events Detailed

Horn

Triggered when Vehicle honks

Vehicle.Subscribe("Horn", function(self, is_honking)

end)

Type	Parameter	Description
Vehicle	self
boolean	is_honking

Hit

Triggered when Vehicle hits something

Vehicle.Subscribe("Hit", function(self, impact_force, normal_impulse, impact_location, velocity)

end)

Type	Parameter	Description
Vehicle	self
number	impact_force	The intensity of the Hit normalized by the Vehicle's weight
Vector	normal_impulse	The impulse direction it hits
Vector	impact_location	The world 3D location of the impact
Vector	velocity	The Vehicle velocity at the moment it hits

CharacterEntered

Triggered when a Character fully enters the Vehicle

Vehicle.Subscribe("CharacterEntered", function(self, character, seat)

end)

Type	Parameter	Description
Vehicle	self
Character	character
number	seat	The seat index

CharacterLeft

Triggered when a Character fully leaves the Vehicle

Vehicle.Subscribe("CharacterLeft", function(self, character)

end)

Type	Parameter	Description
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)

Type	Parameter	Description
Vehicle	self
Character	character
number	seat	The seat index

CharacterAttemptLeave

Triggered when a Character attempts to enter the Vehicle

Return false to prevent it

Vehicle.Subscribe("CharacterAttemptLeave", function(self, character)

end)

Type	Parameter	Description
Vehicle	self
Character	character