stingray.Vehicle object reference

Description

Interface to a physics vehicle.

A vehicle is a rigid body living in the physics world. The Lua Vehicle object will become invalid if the vehicle is destroyed.

Constructors and accessors

stingray.Unit.create_vehicle() stingray.Unit.vehicle()

Other related reference items

	stingray.Unit.create_vehicle() stingray.Unit.destroy_vehicle() stingray.Unit.vehicle()
	Physics

Functions

actor ( self ) : stingray.Actor Returns the Unit Actor the vehicle was constructed from.

Parameters

self :

stingray.Vehicle

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.

Returns

stingray.Actor

The Actor associated with the vehicle.

add_force ( self, force ) Adds the specified force to the vehicle's center of mass.

Parameters

self :	stingray.Vehicle	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
force :	stingray.Vector3	The force to apply to the vehicle.

Returns

This function does not return any values.

This will not induce a torque.

current_gear ( self ) : integer Indicates the gear the vehicle is currently in.

Parameters

self :

stingray.Vehicle

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.

Returns

integer

The current gear.

engine_rotation_speed ( self ) : number Returns the engine rotation speed.

Parameters

self :

stingray.Vehicle

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.

Returns

number

The engine rotation speed, in radians per second.

forward ( self ) : stingray.Vector3 Returns the forward direction of the vehicle's chassis.

Parameters

self :

stingray.Vehicle

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.

Returns

stingray.Vector3

The forward direction.

forward_speed ( self ) : number Indicates the vehicle's current forward speed along the forward direction of its chassis.

Parameters

self :

stingray.Vehicle

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.

Returns

number

The forward speed.

Related sample code

Vehicle template: /vehicle_follow_cam.lua Vehicle template: /vehicle_unit_controller.lua

has_tank_physics ( self ) : boolean Indicates whether or not the vehicle uses the tank physics model.

Parameters

self :

stingray.Vehicle

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.

Returns

boolean

Returns true if this vehicle physics model is tank, or false otherwise.

has_wheeled_physics ( self ) : boolean Indicates whether or not the vehicle uses the wheeled physics model.

Parameters

self :

stingray.Vehicle

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.

Returns

boolean

Returns true if this vehicle physics model is wheeled, or false otherwise.

is_auto_gears_enabled ( self ) : boolean Indicates whether or not automatic gears are enabled for this vehicle.

Parameters

self :

stingray.Vehicle

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.

Returns

boolean

Returns true if automatic gears are enabled, or false otherwise.

is_in_air ( self ) : boolean Indicates whether or not the vehicle is in air: i.e. none of its wheels have contact with a driveable surface.

Parameters

self :

stingray.Vehicle

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.

Returns

boolean

Returns true if all wheels do not have contact with a drivable surface, and false otherwise.

num_forward_gears ( self ) : integer Returns the total number of forward gears the vehicle has.

Parameters

self :

stingray.Vehicle

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.

Returns

integer

The number of forward gears.

Neutral and reverse gears are not included.

num_wheels ( self ) : integer Returns the total number of wheels on the vehicle.

Parameters

self :

stingray.Vehicle

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.

Returns

integer

The number of wheels on the vehicle.

position ( self ) : stingray.Vector3 Returns the position of the vehicle's center of mass.

Parameters

self :

stingray.Vehicle

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.

Returns

stingray.Vector3

The position of the vehicle chassis.

Related sample code

Vehicle template: /vehicle_follow_cam.lua

set_accelerator ( self, accelerator ) Sets the acceleration value for the vehicle.

Parameters

self :	stingray.Vehicle	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
accelerator :	number	The vehicle acceleration value. The acceleration value range is between 0 (no acceleration) and 1 (full acceleration).

Returns

This function does not return any values.

Related sample code

Vehicle template: /vehicle_unit_controller.lua

set_auto_gears_enabled ( self, enabled ) Determines whether or not automatic gears are enabled for this vehicle.

Parameters

self :	stingray.Vehicle	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
enabled :	boolean	true to enable automatic gears for this vehicle, or false to disable.

Returns

This function does not return any values.

set_engine_rotation_speed ( self, speed ) Sets the engine rotation speed.

Parameters

self :	stingray.Vehicle	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
speed :	number	The new engine rotation speed, in radians per second.

Returns

This function does not return any values.

set_gear ( self, gear ) Sets the current gear for the vehicle.

Parameters

self :	stingray.Vehicle	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
gear :	integer	The gear value applied to the vehicle. The gear range is between 1 and the maximum number of gears the vehicle has; use 0 for neutral; use -1 for reverse.

Returns

This function does not return any values.

Related sample code

Vehicle template: /vehicle_unit_controller.lua

set_gear_down ( self, gear_down ) Decrements the current gear of the vehicle by one.

Parameters

self :	stingray.Vehicle	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
gear_down :	boolean	true to shift into a lower gear.

Returns

This function does not return any values.

set_gear_up ( self, gear_up ) Increments the current gear of the vehicle by one.

Parameters

self :	stingray.Vehicle	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
gear_up :	boolean	true to shift into a higher gear.

Returns

This function does not return any values.

set_input_smoothing_enabled ( self, enabled ) Determines whether or not input smoothing is enabled for this vehicle.

Parameters

self :	stingray.Vehicle	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
enabled :	boolean	true to enable input smoothing, or false to disable input smoothing.

Returns

This function does not return any values.

set_tank_left_brake ( self, fval ) Sets the brake value for the tank's left wheels.

Parameters

self :	stingray.Vehicle	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
fval :	number	The brake to be applied to the wheels on the left. The brake value range is between 0 (no brake) and 1 (full brake).

Returns

This function does not return any values.

set_tank_left_thrust ( self, fval ) Sets the thrust value for the tank's left wheels.

Parameters

self :	stingray.Vehicle	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
fval :	number	The thrust value applied to the wheels on the left. For tanks with standard drive model the thrust value range is between 0 (no thrust) and 1 (full thrust). For tanks with special drive model the range is between -1 (full backwards thrust) and 1 (full forward thrust).

Returns

This function does not return any values.

set_tank_right_brake ( self, fval ) Sets the brake value for the tank's right wheels.

Parameters

self :	stingray.Vehicle	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
fval :	number	The brake applied to the wheels on the right. The brake value range is between 0 (no brake) and 1 (full brake).

Returns

This function does not return any values.

set_tank_right_thrust ( self, fval ) Sets the thrust value for the tank's right wheels.

Parameters

self :	stingray.Vehicle	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
fval :	number	The thrust value applied to the wheels on the right. For tanks with standard drive model the thrust value range is between 0 (no thrust) and 1 (full thrust). For tanks with 'special' drive model the range is between -1 (full backwards thrust) and 1 (full forward thrust).

Returns

This function does not return any values.

set_wheeled_brake ( self, brake ) Sets the brake value for the wheels.

Parameters

self :	stingray.Vehicle	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
brake :	number	The brake to be applied to the wheels. The brake value range is between 0 (no brake) and 1 (full brake).

Returns

This function does not return any values.

Related sample code

Vehicle template: /vehicle_unit_controller.lua

set_wheeled_handbrake ( self, handbrake ) Sets the handbrake value for the wheels in wheeled vehicles.

Parameters

self :	stingray.Vehicle	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
handbrake :	number	The handbrake applied to the wheel. The handbrake value range is between 0 (no handbrake) and 1 (full handbrake).

Returns

This function does not return any values.

Related sample code

Vehicle template: /vehicle_unit_controller.lua

set_wheeled_steer ( self, steer ) Sets the steering value for the wheel in wheeled vehicles.

Parameters

self :	stingray.Vehicle	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
steer :	number	The steering value applied to the wheels. The steer value range is between -1 (full left) and 1 (full right).

Returns

This function does not return any values.

Related sample code

Vehicle template: /vehicle_unit_controller.lua

set_wheel_rotation_angle ( self, wheel_index, angle ) Sets the wheel rotation angle for the specifed wheel.

Parameters

self :	stingray.Vehicle	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
wheel_index :	integer	The index of the wheels in the vehicle.
angle :	number	The new wheel rotation angle, in radians.

Returns

This function does not return any values.

set_wheel_rotation_speed ( self, wheel_index, speed ) Sets the wheel rotation speed for the specifed wheel.

Parameters

self :	stingray.Vehicle	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
wheel_index :	integer	The index of the wheel.
speed :	number	The new wheel rotation speed, in radians/sec.

Returns

This function does not return any values.

sideways_speed ( self ) : number Indicates the vehicle's current speed along the right direction of its chassis.

Parameters

self :

stingray.Vehicle

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.

Returns

number

The sideways speed.

steer_angle ( self, wheel_index ) : number Returns the current steering angle of the specified wheel.

Parameters

self :	stingray.Vehicle	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
wheel_index :	integer	The index of the wheel.

Returns

number

The steering angle, ranging from -1 (full left) to 1 (full right).

suspension_force ( self, wheel_index ) : number Returns the suspension force for the specifed wheel.

Parameters

self :	stingray.Vehicle	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
wheel_index :	integer	The index of the wheel.

Returns

number

The suspension force.

suspension_jounce ( self, wheel_index ) : number Returns the suspension jounce for the specifed wheel.

Parameters

self :	stingray.Vehicle	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
wheel_index :	integer	The index of the wheel.

Returns

number

The suspension jounce, ranging from -1 (fully extended) to 1 (fully compressed)..

suspension_line_dir ( self, wheel_index ) : stingray.Vector3 Returns the suspension line direction unit vector for the specifed wheel.

Parameters

self :	stingray.Vehicle	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
wheel_index :	integer	The index of the wheel.

Returns

stingray.Vector3

The suspension line direction unit vector.

suspension_line_start ( self, wheel_index ) : stingray.Vector3 Returns the suspension line start in world coordinates for the specifed wheel.

Parameters

self :	stingray.Vehicle	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
wheel_index :	integer	The index of the wheel.

Returns

stingray.Vector3

The suspension line start in world coordinates.

tire_drivable_surface_contact_normal ( self, wheel_index ) : stingray.Vector3 Returns the normal of the contact between the specified wheel and the drivable surface.

Parameters

self :	stingray.Vehicle	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
wheel_index :	integer	The index of the wheel.

Returns

stingray.Vector3

The normal of the contact between the specified wheel and the drivable surface, or the zero vector if the wheel is not in contact with a drivable surface.

tire_drivable_surface_contact_point ( self, wheel_index ) : stingray.Vector3 Returns the contact position between the specified wheel and the drivable surface.

Parameters

self :	stingray.Vehicle	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
wheel_index :	integer	The index of the wheel.

Returns

stingray.Vector3

The contact position between the specified wheel and the drivable surface it is in contact with, or the zero vector if the wheel is not in contact with a drivable surface.

tire_drivable_surface_index ( self, wheel_index ) : integer Returns the index of the drivable surface value underneath the tire of the specified wheel.

Parameters

self :	stingray.Vehicle	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
wheel_index :	integer	The index of the wheel.

Returns

integer

The index of the drivable surface under the tire, or -1 if the tire is not in contact with any surface. The index corresponds to the drivable_surface array set up in the global.physics_properties data file.

tire_friction ( self, wheel_index ) : number Returns the friction currently applied to the tire for the specified wheel.

Parameters

self :	stingray.Vehicle	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
wheel_index :	integer	The index of the wheel.

Returns

number

The friction applied to the tire.

tire_lateral_dir ( self, wheel_index ) : stingray.Vector3 Returns the lateral direction of the tire, as used in the calculation of lateral slip for the specified wheel.

Parameters

self :	stingray.Vehicle	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
wheel_index :	integer	The index of the wheel.

Returns

stingray.Vector3

The lateral direction of the tire, or the zero vector if the tire does not have contact with a drivable surface.

tire_lateral_slip ( self, wheel_index ) : number Returns the lateral slip of the tire for the specified wheel.

Parameters

self :	stingray.Vehicle	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
wheel_index :	integer	The index of the wheel.

Returns

number

The lateral slip of the tire. Increasing positive values are proportial to the amount of slip. A value of 0 indicates zero slip.

tire_longitudinal_dir ( self, wheel_index ) : stingray.Vector3 Returns the longitudinal direction of the tire, as used in the calculation of longitudinal slip for the specified wheel.

Parameters

self :	stingray.Vehicle	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
wheel_index :	integer	The index of the wheel.

Returns

stingray.Vector3

The longitudinal direction of the tire, or the zero vector if the tire does not have contact with a drivable surface.

tire_longitudinal_slip ( self, wheel_index ) : number Returns the longitudinal slip of the tire for the specified wheel.

Parameters

self :	stingray.Vehicle	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
wheel_index :	integer	The index of the wheel.

Returns

number

The longitudinal slip of the tire. Increasing positive values are proportial to the amount of slip. A value of 0 indicates zero slip.

unit ( self ) : stingray.Unit Returns the Unit that owns the vehicle.

Parameters

self :

stingray.Vehicle

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.

Returns

stingray.Unit

The Unit that owns the vehicle, if any.

wheel_rotation_angle ( self, wheel_index ) : number Returns the rotation angle of the specified wheel.

Parameters

self :	stingray.Vehicle	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
wheel_index :	integer	The index of the wheel.

Returns

number

The wheel rotation angle, in radians.

wheel_rotation_speed ( self, wheel_index ) : number Returns the rotation speed of the specified wheel.

Parameters

self :	stingray.Vehicle	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
wheel_index :	integer	The index of the wheel.

Returns

number

The rotation speed of the wheel, in radians per second.