Unit - stingray.Unit object reference - Stingray Lua API Reference

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

string

The current animation bone mode. May be any one of: ignore, transform, position, rotation, scale, position_and_rotation, position_and_scaleor rotation_and_scale. See set_animation_bone_mode() for a description of these modes.

animation_event ( self, event, parameters )

Triggers the specified event in the unit's animation state machine, which may cause a transition to a different animation state.

Parameters

self :

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.

event :

string

The name of the animation event.

parameters :

any?

Can be specified as a sequence of keys and values. Currently, only one parameter is supported.

Unit.ANIMATION_OVERRIDE_PERCENT_SYNC: If supplied, overrides the percent value for percent sync transitions. This allows the script to force the transition into a certain percentage of the destination animation. If you specify this parameter, you must follow it with a number value that specifies the percentage as a value between 0 and 1.

The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

This function does not return any values.

Call this function only on units that have an animation state machine.

NOTE: This feature should be considered experimental.

Other related reference items

animation_find_constraint_target ( self, name ) : integer

Retrieves the index of a constraint target in the unit's animation state machine.

Parameters

self :	stingray.Unit	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.
name :	string	The name of the constraint target.

Returns

integer

The index of the constraint target.

animation_find_variable ( self, name ) : integer

Finds the index of a specified variable in the unit's animation state machine.

Parameters

self :	stingray.Unit	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.
name :	string	The name of the variable.

Returns

integer

The index of the specified variable.

animation_get_constraint_target ( self, index ) : stingray.Matrix4x4

Retrieves the value of a constraint target from the unit's animation state machine.

Parameters

self :	stingray.Unit	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.
index :	integer	The index of the constraint target to retrieve.

Returns

The value of the constraint target.

animation_get_curve_value ( self, object, parameter, float_index ) : boolean, number

Retrieves the current value of the animation curve.

Parameters

self :	stingray.Unit	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.
object :	string	The name of the animated node
parameter :	string	The name of the animated parameter.
float_index :	number	Optional; The 0-based float index of within the channel floats that will be returned (from 0 to 3). default is 0

Returns

boolean	Does the curve exists.
number	The value of curve evaluation.

animation_get_length ( animation ) : number

Retrieves the length of the animation.

Parameters

animation :

string

The name of the animation.

Returns

number

The length of the animation.

animation_get_seeds ( self ) : any(integer)+

Retrieves the current seeds of the layers random number generators of the unit animation state machine as a tuple of data.

Parameters

self :

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

any(integer)+

The current seeds of the unit animation state machine. The seeds are returned as a series of numbers that are the current seed used by each layer's random number generator.

The + notation indicates that there may be one or more instances of the specified type.

The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.

animation_get_state ( self ) : any(integer, nil)+

Retrieves the current animation state of the unit as a tuple of data.

Parameters

self :

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

any(integer, nil)+

The current animation state of the unit. The state is returned as a series of numbers that indicate the current state for each layer. For layers that are not playing a state, nil is returned.

The + notation indicates that there may be one or more instances of the specified type.

The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.

You can restore the state later by calling animation_set_state() and passing the same series of values. Note that the state only includes the state of the state machine, not the play head offsets, animation variables or constraint targets.

Other related reference items

animation_get_variable ( self, index ) : number

Retrieves the value of a specified variable from the unit's animation state machine.

Parameters

self :	stingray.Unit	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.
index :	integer	The index of the variable.

Returns

number

The value of the variable in the unit's animation state machine.

animation_has_constraint_target ( self, name ) : boolean

Returns true if the constraint target is defined for the unit, or false otherwise.

Parameters

self :	stingray.Unit	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.
name :	string	The name of the constraint target.

Returns

boolean

Returns true if the constraint target is defined for the unit, or false otherwise.

animation_has_variable ( self, name ) : boolean

Indicates whether or not the unit's animation state machine has the specified variable.

Parameters

self :	stingray.Unit	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.
name :	string	The name of the variable.

Returns

boolean

Returns true if the specified unit's animation state machine has the specified variable, or false otherwise.

animation_layer_info ( self, layer ) : number, number

Retrieves information about the animation playing in the specified layer.

Parameters

self :	stingray.Unit	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.
layer :	integer	The index of the animation layer.

Returns

number	The current time of the animation.
number	The total length of the animation.

You can figure out the percentage of the animation that has played by dividing the returned time value by the returned length value: time / length.

Note: This feature should be considered experimental.

animation_root_mode ( self ) : string

Retrieves the current animation root mode.

Parameters

self :

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

string

The current animation root mode. May be any one of: ignore, delta_transform, delta_position, delta_rotation, delta_scale, delta_position_and_rotation, delta_position_and_scale or delta_rotation_and_scale. See set_animation_root_mode() for a description of these modes.

animation_set_constraint_target ( self, index, value )

Sets the value of a constraint target in the unit's animation state machine.

Parameters

self :	stingray.Unit	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.
index :	integer	The index of the constraint target to set.
value :	any(stingray.Matrix4x4, stingray.Quaternion, stingray.Vector3)	The new value to set for the constraint target. Can be a Matrix4x4, a Quaternion or a Vector3, depending on whether you want to set both the position and rotation or just one of them. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.

Returns

This function does not return any values.

animation_set_seeds ( self, seeds )

set seeds to Layers random number generator in the animation controller of the unit.

Parameters

self :	stingray.Unit	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.
seeds :	integer+	The seeds to set to Layer's random number generator in the animation state machine of the unit. The + notation indicates that there may be one or more instances of the specified type.

Returns

This function does not return any values.

animation_set_state ( self, state )

Restores a state fetched with animation_get_state().

Parameters

self :	stingray.Unit	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.
state :	integer+	The animation state to set for the unit. The + notation indicates that there may be one or more instances of the specified type.

Returns

This function does not return any values.

Other related reference items

animation_set_variable ( self, index, value )

Sets the value of a specified variable in the unit's animation state machine.

Parameters

self :	stingray.Unit	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.
index :	integer	The index of the variable whose value you want to set.
value :	number	The new value tp set for the variable in the unit's animation state machine.

Returns

This function does not return any values.

animation_wanted_root_pose ( self ) : stingray.Matrix4x4

In the ignore root mode, this function returns the position and rotation that the animation would have moved the root node to.

Parameters

self :

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

The pose of the root node.

You can use this value to apply the animation movement manually from your script, or pass it through other systems (such as the unit's mover, etc).

Other related reference items

crossfade_animation ( self, animation, layer, blend_time, loop, blend_type ) : integer

Crossfades in the animation on the specified unit in the specified animation layer over the specified blend time.

Parameters

self :	stingray.Unit	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.
animation :	string	The name of the animation.
layer :	integer?	The index of the animation layer to use. Optional; default value is 1. The ? notation indicates that this type is optional: there may be zero or one instances of it.
blend_time :	number?	Time for the crossfade. Optional; default value is 0. The ? notation indicates that this type is optional: there may be zero or one instances of it.
loop :	boolean?	If true, the animation will loop in the specified time interval; if false the unit will remain in the last pose. Optional; default value is true. The ? notation indicates that this type is optional: there may be zero or one instances of it.
blend_type :	string?	Specifies how an animation should be blended with other animations, values may be normal and offset. Optional; default value is normal. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

integer

An id that you can use to control the animation.

Call this function only on units that have an animation blender but no animation state machine: i.e., units with a script-driven blender.

Other related reference items

crossfade_animation_set_speed ( self, id, speed )

Sets the speed at which the crossfaded animation will play with respect to the blender.

Parameters

self :	stingray.Unit	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.
id :	integer	The ID of the crossfaded animation.
speed :	number	The speed at which the animation should play.

Returns

This function does not return any values.

A value of 1 means it uses the same time step as the blender. A value of 0 means it is frozen. You cannot use negative values for the speed.

crossfade_animation_set_time ( self, id, time, cap_to_range )

Explicitly sets the time of the crossfaded animation to the specified time.

Parameters

self :	stingray.Unit	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.
id :	integer	The ID of the crossfaded animation.
time :	number	The time to set for the animation.
cap_to_range :	boolean	if true, the given time will be capped to be in the time range of the animation. Optional; default value is false.

Returns

This function does not return any values.

disable_animation_state_machine ( self )

Disables the unit's animation state machine, so that you can control its blender directly with crossfade_animation() and its related functions.

Parameters

self :

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

This function does not return any values.

This is typically only used for debugging purposes or by editing tools.

enable_animation_state_machine ( self )

Enables the animation state machine for the unit, if it has been previously disabled.

Parameters

self :

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

This function does not return any values.

has_animation_event ( self, event ) : boolean

Indicates whether or not the specified unit has the named animation event.

Parameters

self :	stingray.Unit	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.
event :	string	The name of the animation event.

Returns

boolean

Returns true if the specified unit has the named animation event, or false otherwise.

Call this function only on units that have an animation state machine.

has_animation_state_machine ( self ) : boolean

Indicates whether or not the specified unit has an animation state machine.

Parameters

self :

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 the specified unit has an animation state machine, or false otherwise.

is_crossfading_animation ( self ) : boolean

Indicates whether or not the unit is currently crossfading any animation.

Parameters

self :

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 the unit is currently crossfading any animation, or false otherwise.

This can be used to avoid overlaying too many crossfading animations on top of each other.

set_animation_bone_mode ( self, mode )

Sets the way animations can update the bone nodes of a unit.

Parameters

self :

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.

mode :

string

The animation bone mode to set. Possible values include:

ignore: Bone animations are ignored; they will not affect the unit's bone nodes.
transform: Default mode. The bone position, rotation and scale that occur in the animation will be applied to the bone nodes of the Unit.
position: only bone positions are transferred to the bone nodes.
rotation: only bone rotations are transferred to the bone nodes.
scale: only bone scales are transferred to the bone nodes.
position_and_rotation: only bone positions and rotations are transferred to the bone nodes.
position_and_scale: only bone positions and scales are transferred to the bone nodes.
rotation_and_scale: only bone rotations and scales are transferred to the bone nodes.

Returns

This function does not return any values.

All bones will follow the same update mode, except root node which mode is set separately (see set_animation_root_mode()).

Other related reference items

set_animation_logging ( self, enabled )

Determines whether or not animation state machine events will be logged to the command console.

Parameters

self :	stingray.Unit	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	Use true to enable logging of state machine events, or false to disable.

Returns

This function does not return any values.

This method is only available in development mode.

set_animation_merge_options ( self, parameters )

Controls the settings used to merge evaluations of the same animation that are playing close in time.

Parameters

self :

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.

parameters :

any(string, number)+

The merge options for the animation playing. Possible parameters are:

"max_start_time": Sets the maximum time into an animation that we can start, in seconds. If a value of 0.2 is set, it means that if we can find any existing player playing this animation that has played for 0-0.2 seconds, then we will reuse that player instead of creating a new one. The animation will jump to the position where that player is, instead of starting at t=0. If you specify this parameter, you must follow it with a number parameter that provides the time value in seconds. The default value is 0, which allows animation evaluations to be merged only if they began in the same frame.
"max_drift": Controls how much the displayed animation time is allowed to drift from the actual animation time. If two animations that are sharing a player are played with different speeds, they will eventually drift apart. At some point the animations will be considered too different and the evaluator will be split in two. This parameter controls when that happens. A value of 0.2 means that if the animations differs more than 0.2 seconds, the evaluator will be split. If you specify this parameter, you must follow it with a number parameter that provides the time value in seconds. The default value is 0.
"clock_fidelity": This controls how much the animation will respect the set playing speed. By slightly changing the playing speed of an animation, the animation player can prevent two playing animations from drifting apart and thus forcing a split of the evaluators. A clock fidelity of 0.9 means that the speed will be within 90%% of what has been requested: i.e. it is allowed to change by 10 percent. If you specify this parameter, you must follow it with a number parameter that provides the fidelity as a ratio between 0 and 1. The default value of 1.0 means that the speed will be exactly what has been requested.

The + notation indicates that there may be one or more instances of the specified type.

The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.

Returns

This function does not return any values.

The Stingray engine has an optimization system that can merge evaluations of the same animation played close together in time. This can improve performance when there are multiple instances of the same animation playing. This function allows you to control the merge settings.

NOTE: This feature should be considered experimental, and may be subject to change.

set_animation_root_mode ( self, mode )

Sets the way in which animations can update the root node of a unit.

Parameters

self :

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.

mode :

string

The animation root mode to set. Possible values include:

ignore: Default mode. Root animations are ignored; they will not affect the unit's root node. When using this mode, use animation_wanted_root_pose() to extract the position the animation wanted to move the root to, and apply that position programmatically.
delta_transform: The delta changes to the root position, rotation and scale that occur in the animation will be applied to the root node of the Unit. The unit's root will be moved by the animation.
delta_position: Same as delta_transform, but only position updates are transferred to the root node.
delta_rotation: Same as delta_transform, but only rotation updates are transferred to the root node.
delta_scale: Same as delta_transform, but only scale updates are transferred to the root node.
delta_position_and_rotation: Same as delta_transform, but only position and rotation updates are transferred to the root node.
delta_position_and_scale: Same as delta_transform, but only position and scale updates are transferred to the root node.
delta_rotation_and_scale: Same as delta_transform, but only rotation and scale updates are transferred to the root node.

Returns

This function does not return any values.

Other related reference items

set_animation_state_machine ( self, machine )

Sets the animation state machine of the unit to something other than the default.

Parameters

self :	stingray.Unit	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.
machine :	string	The name of the state machine resource to use.

Returns

This function does not return any values.

set_bones_lod ( self, lod_level )

Sets the LOD level for animation bones.

Parameters

self :	stingray.Unit	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.
lod_level :	integer	The new LOD level to set for bones.

Returns

This function does not return any values.

The LOD level determines which bones in the animation will be evaluated. Bones that are not evaluated will freeze in local space. This can be used to reduce the animation cost of units that are far away from the camera.

The LOD levels for bones are defined in the Unit Editor.

Bounding boxes

box ( self, ignore_invisble_meshes ) : stingray.Matrix4x4, stingray.Vector3

Retrieves an oriented bounding box that encloses all the meshes in the unit.

Parameters

self :	stingray.Unit	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.
ignore_invisble_meshes :	boolean?	If true, discard the invisible mesh in the box computation. Default to false. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

stingray.Matrix4x4	The position and rotation of the center of the bounding box.
stingray.Vector3	The half-extents of the bounding box along all three axes.

Cameras

camera ( self, camera ) : stingray.Camera

Retrieves the specified camera owned by the unit.

Parameters

self :	stingray.Unit	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.
camera :	any(integer, string)	The index or name of the camera to retrieve. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.

Returns

stingray.Camera

The specified camera.

has_camera ( self, camera ) : boolean

Indicates whether or not the unit contains a camera with the specified name.

Parameters

self :	stingray.Unit	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.
camera :	string	The name of the camera.

Returns

boolean

Returns true if the unit contains the camera, or false otherwise.

num_cameras ( self ) : integer

Retrieves the number of cameras in the unit.

Parameters

self :

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 cameras in the unit.

Dynamic Data

get_data ( self, indices ) : any

Retrieves the data set at the specified indices within the unit's script data object from the unit.

Parameters

self :	stingray.Unit	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.
indices :	any(integer, string)+	One or more indices for the data, which may be integers or strings. The + notation indicates that there may be one or more instances of the specified type. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.

Returns

any	The value previously set at the specified sequence of indices.

Other related reference items

has_data ( self, indices ) : boolean

Indicates whether or not any data has been saved at the specified indices in the unit's script data object.

Parameters

self :	stingray.Unit	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.
indices :	any(integer, string)+	One or more indices for the data, which may be integers or strings. The + notation indicates that there may be one or more instances of the specified type. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.

Returns

boolean

Returns true if a data value is stored at the specified sequence of indices, or false otherwise.

Other related reference items

set_data ( self, indices, indices, indices, value ) set_data ( self, indices, indices, value ) set_data ( self, indices, value )

Stores the specified value in the unit's script data object, at a location determined by the specified indices.

Parameters

self :	stingray.Unit	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.
indices :	any(integer, string)	One or more indices for the data, which may be integers or strings. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.
value :	any	The value to store.

Returns

This function does not return any values.

You can retrieve the data later by passing the same indices in a call to get_data().

Other related reference items

Flow

flow_event ( self, name )

Triggers the External In Event node with the specified name in the unit's flow graph.

Parameters

self :	stingray.Unit	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.
name :	string	The name of the flow event to trigger.

Returns

This function does not return any values.

flow_variable ( self, name ) : any

Returns the value of the External Output flow variable with the specified name in the unit flow.

Parameters

self :	stingray.Unit	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.
name :	string	The name of the external flow variable to retrieve.

Returns

any	The value of the flow variable. The type of this value depends on the type of the External Output variable that matches the specified name.

Note that this function works with the external variable Flow nodes, which you can find under the **External > Output** category. It is not related to the nodes under the Variables category, which can only be set and retrieved in Flow graphs.

Note: A variable shown as "My Unit" in the editor has the real name: my_unit.

set_flow_variable ( self, name, value )

Sets the value of the the External Input flow variable with the specified name in the unit flow.

Parameters

self :	stingray.Unit	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.
name :	string	The name of the external flow variable to set.
value :	any	The new value to set for the flow variable. The type of this value depends on the type of the External Input variable that matches the specified name.

Returns

This function does not return any values.

Note that this function works with the external variable Flow nodes, which you can find under the **External > Input** category. It is not related to the nodes under the Variables category, which can only be set and retrieved in Flow graphs.

Lights

has_light ( self, light ) : boolean

Indicates whether or not the unit contains a light with the specified name.

Parameters

self :	stingray.Unit	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.
light :	string	The name of the light.

Returns

boolean

Returns true if the unit contains the light, or false otherwise.

light ( self, light ) : stingray.Light

Retrieves the specified light owned by the unit.

Parameters

self :	stingray.Unit	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.
light :	any(string, integer)	The name or index of the light to retrieve. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.

Returns

stingray.Light

The specifed light.

num_lights ( self ) : integer

Retrieves the number of lights in the unit.

Parameters

self :

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 lights in the unit.

LOD Objects

has_lod_object ( self, lod ) : boolean

Indicates whether or not the unit contains an LOD Object with the specified name.

Parameters

self :	stingray.Unit	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.
lod :	string	The name of the LOD Object.

Returns

boolean

Returns true if the unit contains the LOD Object, or false otherwise.

lod_object ( self, lod ) : stingray.LODObject

Retrieves the specified LOD Object owned by the unit.

Parameters

self :	stingray.Unit	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.
lod :	any(string, integer)	The name or index of the LOD Object to retrieve. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.

Returns

stingray.LODObject

The specifed LOD Object.

num_lod_objects ( self ) : integer

Retrieves the number of LOD Objects in the unit.

Parameters

self :

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 LOD Objects in the unit.

Materials

set_light_material ( self, light, material_resource )

Assigns a material resource to a specified light source within the unit.

Parameters

self :	stingray.Unit	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.
light :	stingray.Light	The stingray.Light whose material you want to change. Must be owned by this unit.
material_resource :	string	The name of the .material resource you want to assign to the light.

Returns

This function does not return any values.

Note that the shader graph for the specified material must use the **Output > Light Base** node to produce the color that the light will project.

set_material ( self, slot_name, material_resource ) : stingray.IdString64

Assigns a material resource to a specified material slot within the unit.

Parameters

self :	stingray.Unit	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.
slot_name :	string	The name of the slot whose material you want to set.
material_resource :	string?	The name of the .material resource you want to assign to the slot. If this value is nil, the slot is cleared. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

stingray.IdString64

The resource ID of the material assigned to the slot.

Meshes

has_mesh ( self, mesh ) : boolean

Indicates whether or not the unit contains a mesh with the specified name.

Parameters

self :	stingray.Unit	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.
mesh :	string	The name of the mesh.

Returns

boolean

Returns true if the unit contains the mesh, or false otherwise.

mesh ( self, mesh ) : stingray.Mesh

Retrieves the specified mesh owned by the unit.

Parameters

self :	stingray.Unit	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.
mesh :	any(string, integer)	The name or index of the mesh to retrieve. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.

Returns

stingray.Mesh

The specified mesh.

num_meshes ( self ) : integer

Retrieves the number of meshes in the unit.

Parameters

self :

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 meshes in the unit.

Miscellaneous

alive ( self ) : boolean

Indicates whether the unit exists, or whether it has been deleted.

Parameters

self :

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 false if the unit has been deleted or if the unit is nil.

Units are always held as weak references. You can call Unit.alive() on any unit to check that the reference is still valid. Calling any function other than alive() on a unit that has been deleted will result in a script error.

Note: only units are held as weak references. You cannot call alive() on any other objects to detect if they have been deleted.

debug_name ( self ) : string

Retrieves the name of the unit.

Parameters

self :

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

string

The name of the unit.

This should only be used to print the name for debugging purposes. In release versions the real name will not be available, and this function will return a hexadecimal string instead of the name.

id ( self ) : stingray.IdString64

Retrieves a unique ID for the unit within its level.

Parameters

self :

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.IdString64

The numeric ID of the unit within its level if the unit was placed in the level in the editor, or nil if the unit was spawned dynamically.

This ID will remain the same even if the level file is modified. It roughly corresponds to the unit's object ID in the level file. If the unit is spawned through a nested level, the ID is a function of the nested level instance ID and the unit object IDs below it. Thus, every unit spawned through a level will have a unique ID in the world.

is_a ( self, name ) : boolean

Indicates whether or not the unit is a resource of type name.

Parameters

self :	stingray.Unit	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.
name :	string	The name of a unit resource type.

Returns

boolean

Returns true if the unit's resource type matches the specified name, or false otherwise.

mesh_pick_raycast ( self, from, direction, length, include_hidden_meshes ) : number?, stingray.Vector3?, integer?, integer?

Tests for ray intersections with visual meshes within the provided Unit.

Parameters

self :	stingray.Unit	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.
from :	stingray.Vector3	The start position of the raycast.
direction :	stingray.Vector3	The direction that the ray will be cast from its starting point as a unit vector.
length :	number	The length of the ray.
include_hidden_meshes :	boolean	Specifies whether the raycast should hit hidden meshes or not.

Returns

number?	The distance of the collision point from the starting point of the collision test. The ? notation indicates that this type is optional: there may be zero or one instances of it.
stingray.Vector3?	The normal of the surface that was hit. The ? notation indicates that this type is optional: there may be zero or one instances of it.
integer?	The index of the mesh. The ? notation indicates that this type is optional: there may be zero or one instances of it.
integer?	The index of the triangle. The ? notation indicates that this type is optional: there may be zero or one instances of it.

If a mesh triangle is hit, the function returns the mesh index and the index of the intersected triangle within the mesh along with the world normal of the triangle hit. If no triangle is hit, the function doesn't return anything.

Note: Will be very expensive for units containing high density meshes.

name_hash ( self ) : string

Retrieves a hashed representation of the unit name.

Parameters

self :

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

string

The hash representation of the unit name.

The representation will not be meaningful, but it can be passed as an argument to World.spawn_unit() in order to create another unit of the same type.

Physics

apply_initial_actor_velocities ( self, wake_sleeping_actors )

Applies any initial velocities that have been defined for actors inside this unit.

Parameters

self :	stingray.Unit	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.
wake_sleeping_actors :	boolean	Determines whether or not sleeping actors should be awakened when the effect is applied. Optional; default value is true. If set to false, velocities will still be applied to sleeping actors, but the effect will not be apparent until an external event wakes the actors up.

Returns

This function does not return any values.

Initial velocities can currently only be set up for physics scene objects exported from a modeling package.

disable_physics ( self )

Disables all physics for the unit.

Parameters

self :

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

This function does not return any values.

This is typically only used for debugging purposes or by editing tools.

enable_physics ( self )

Re-enables the physics system for the unit, if it has been previously disabled.

Parameters

self :

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

This function does not return any values.

Properties

get_property ( self, properties ) : number

Retrieves the value of a property on a unit, or on any object owned by the unit, such as a material, mesh or light.

Parameters

self :	stingray.Unit	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.
properties :	any(string)	A sequence of strings which together make up the path to the property. See set_property() for details. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.

Returns

number

The value currently set for the property.

set_property ( self, properties, properties, properties, value ) set_property ( self, properties, properties, value ) set_property ( self, properties, value )

Sets the value of a property on a unit, or on any object owned by the unit, such as a material, mesh or light.

Parameters

self :	stingray.Unit	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.
properties :	string	A sequence of strings which together make up the path to the property.
value :	number	The value to set for the property.

Returns

This function does not return any values.

The properties can take multiple string arguments, which together make up the path to the property. For example, you might write:

stingray.Unit.set_property(myUnit, "meshes", "my_unit_mesh_name", "materials", "slot_name", "albedo", "x", 0.25)

This example would set the red component of the albedo color of a material on the unit.

Note that these paths are the same as the ones used in the curve editor tree view in the StoryTeller.

Other related reference items

Scene Graphs

bones ( self ) : string[]

Retrieves a list of all bones in the unit's state machine.

Parameters

self :

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

string[]

A list of bone names in the unit's state machine.

The [] notation indicates that this type is an array: a table in which the keys of the members are sequential integers, and the value of each element is an instance of the type shown.

copy_scene_graph_local_from ( dest_unit, src_unit )

Copies all local matrices from the source unit src_unit to the destination unit dest_unit, except for the root node.

Parameters

dest_unit :	stingray.Unit	The destination unit to which the scene graph nodes are copied to.
src_unit :	stingray.Unit	The source unit from which the nodes are copied over.

Returns

This function does not return any values.

This can be used to support "instancing", where an expensive unit is simulated and then its transforms are copied to simpler units.

delta_pose ( self, i ) : stingray.Matrix4x4

Retrieves the delta world position and orientation of a node in the unit since the last frame.

Parameters

self :	stingray.Unit	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.
i :	integer	The index of the node.

Returns

The position and orientation of the node, in global coordinates.

delta_position ( self, i ) : stingray.Vector3

Retrieves the delta world position of a node in the unit since the last frame.

Parameters

self :	stingray.Unit	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.
i :	integer	The index of the node.

Returns

The position of the node, in global coordinates.

delta_rotation ( self, i ) : stingray.Quaternion

Retrieves the delta world rotation of a node in the unit since the last frame.

Parameters

self :	stingray.Unit	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.
i :	integer	The index of the node.

Returns

stingray.Quaternion

The rotation of the node, in global coordinates.

has_node ( self, name ) : boolean

Indicates whether or not the unit has an object node that matches the specified name.

Parameters

self :	stingray.Unit	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.
name :	string	The name of the node to look for.

Returns

boolean

Returns true if the unit has a matching node, or false otherwise.

level ( self ) : stingray.World

Retrieves the World that the Unit lives in.

Parameters

self :

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.World

The world the unit lives in.

level ( self ) : stingray.Level?

Retrieves the Level that spawned the Unit.

Parameters

self :

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.Level?

The level that spawned the unit, or nil if the unit does not belong to a level.

The ? notation indicates that this type is optional: there may be zero or one instances of it.

local_pose ( self, i ) : stingray.Matrix4x4

Retrieves the local position and orientation of a node in the unit.

Parameters

self :	stingray.Unit	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.
i :	integer	The index of the node.

Returns

The position and orientation of the node.

Other related reference items

local_position ( self, i ) : stingray.Vector3

Retrieves the local position of a node in the unit.

Parameters

self :	stingray.Unit	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.
i :	integer	The index of the node.

Returns

The position of the node.

local_rotation ( self, i ) : stingray.Quaternion

Retrieves the local rotation of a node in the unit.

Parameters

self :	stingray.Unit	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.
i :	integer	The index of the node.

Returns

stingray.Quaternion

The rotation of the node.

local_scale ( self, i ) : stingray.Vector3

Retrieves the local scale of a node in the unit.

Parameters

self :	stingray.Unit	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.
i :	integer	The index of the node.

Returns

The scale of the node.

node ( self, name ) : integer

Retrieves the index of the object node that matches the specified name.

Parameters

self :	stingray.Unit	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.
name :	string	The name of the node to retrieve.

Returns

integer

The index of the object node.

num_scene_graph_items ( self ) : integer

Retrieves the number of nodes in the unit's scene graph.

Parameters

self :

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 nodes in the unit's scene graph.

scene_graph_link ( self, i, parent )

Links the scene graph node i to the scene graph node parent.

Parameters

self :	stingray.Unit	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.
i :	integer	The index of the scene graph node that will be linked to a new parent.
parent :	integer?	The new parent scene graph node, or nil to unlink i from any parents. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

This function does not return any values.

Note that you can only link objects to earlier objects in the scene graph: i.e. objects with a lower index.

Other related reference items

scene_graph_parent ( self, i ) : integer

Retrieves the parent of a node in the unit's scene graph.

Parameters

self :	stingray.Unit	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.
i :	integer	The index of the node in the scene graph whose parent node will be retrieved.

Returns

integer

The index of the parent node, or nil if the node is a root node.

set_local_pose ( self, i, pose )

Sets the local position and orientation of a node in the unit.

Parameters

self :	stingray.Unit	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.
i :	integer	The index of the node.
pose :	stingray.Matrix4x4	The new position and orientation to set for the node.

Returns

This function does not return any values.

If you want to change just the rotation or scale of a node, use set_local_rotation() and set_local_scale(). If you use local_pose() to fetch the current pose, modify the rotation or scale of that matrix, and then pass the resulting matrix to set_local_pose(), you will lose some floating point precision in the values.

set_local_position ( self, i, position )

Sets the local position of a node in the unit.

Parameters

self :	stingray.Unit	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.
i :	integer	The index of the node.
position :	stingray.Vector3	The new position to set for the node.

Returns

This function does not return any values.

Other related reference items

set_local_rotation ( self, i, rotation )

Sets the local rotation of a node in the unit.

Parameters

self :	stingray.Unit	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.
i :	integer	The index of the node.
rotation :	stingray.Quaternion	The new rotation to set for the node.

Returns

This function does not return any values.

Other related reference items

set_local_scale ( self, i, scale )

Sets the local scale of a node in the unit.

Parameters

self :	stingray.Unit	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.
i :	integer	The index of the node.
scale :	stingray.Vector3	The new scale to set for the node.

Returns

This function does not return any values.

If your unit has active physics actor, scaling it will not scale its actors. Scaling the actors too depends on their type: 1. if this is a ragdoll, just deactivate it, scale your unit, reactivate the ragdoll 2. for other cases (e.g. vehicle), you must unspawn the unit and respawn a new one specifying the scale into the pose matrix (see World.spawn_unit()].

Other related reference items

teleport_local_pose ( self, i, pose )

Teleports the position and orientation of a node in the unit.

Parameters

self :	stingray.Unit	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.
i :	integer	The index of the node.
pose :	stingray.Matrix4x4	The position and orientation set for the node.

Returns

This function does not return any values.

teleport_local_position ( self, i, position )

Similar to set_local_position(), but the node is teleported rather than moved to the specified location.

Parameters

self :	stingray.Unit	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.
i :	integer	The index of the node.
position :	stingray.Vector3	The new position to set for the node.

Returns

This function does not return any values.

This affects how keyframed physics objects behave. When objects are moved, they will collide with everything between the current position and the destination. When they are teleported, they will pop up at the destination without colliding with objects on the way there.

teleport_local_rotation ( self, i, rotation )

Teleports the rotation of a node in the unit.

Parameters

self :	stingray.Unit	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.
i :	integer	The index of the node.
rotation :	stingray.Quaternion	The new rotation to set for the node.

Returns

This function does not return any values.

teleport_local_scale ( self, i, scale )

Teleports the scale of a node in the unit.

Parameters

self :	stingray.Unit	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.
i :	integer	The index of the node.
scale :	stingray.Vector3	The new scale to set for the node.

Returns

This function does not return any values.

world_pose ( self, i ) : stingray.Matrix4x4

Retrieves the world position and orientation of a node in the unit.

Parameters

self :	stingray.Unit	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.
i :	integer	The index of the node.

Returns

The position and orientation of the node, in global coordinates.

world_position ( self, i ) : stingray.Vector3

Retrieves the world position of a node in the unit.

Parameters

self :	stingray.Unit	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.
i :	integer	The index of the node.

Returns

The position of the node, in global coordinates.

world_rotation ( self, i ) : stingray.Quaternion

Retrieves the world rotation of a node in the unit.

Parameters

self :	stingray.Unit	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.
i :	integer	The index of the node.

Returns

stingray.Quaternion

The rotation of the node, in global coordinates.

Terrains

has_terrain ( self, terrain ) : boolean

Indicates whether or not the unit contains a terrain with the specified name.

Parameters

self :	stingray.Unit	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.
terrain :	string	The name of the terrain.

Returns

boolean

Returns true if the unit contains the terrain, or false otherwise.

num_terrains ( self ) : integer

Retrieves the number of terrains in the unit.

Parameters

self :

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 terrains in the unit.

terrain ( self, terrain ) : stingray.Terrain

Retrieves the specified terrain owned by the unit.

Parameters

self :	stingray.Unit	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.
terrain :	any(string, integer)	The name or index of the terrain to retrieve. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.

Returns

stingray.Terrain

The specifed terrain.

Unit Objects

actor ( self, actor ) : stingray.Actor

Retrieves the specified actor owned by the unit.

Parameters

self :	stingray.Unit	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.
actor :	any(string, integer)	The name or index of the actor to retrieve. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.

Returns

stingray.Actor

The specified actor.

cloth ( self, cloth ) : stingray.Cloth

Retrieves the Apex cloth with the specified name or index from the unit.

Parameters

self :	stingray.Unit	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.
cloth :	any(string, integer)	The name or index of the cloth. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.

Returns

stingray.Cloth

The specified cloth.

create_actor ( self, id, inherit_velocity ) : stingray.Actor

Creates an Actor with the specified name or index in the unit, if it has not been created already.

Parameters

self :	stingray.Unit	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.
id :	any(string, integer)	Specifies either the name or index of the actor. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.
inherit_velocity :	number?	Optional; specifies to what extent the physics actor should inherit the velocity of the animated objects that it is connected to. A value of 1.0 means it completely inherits the animated velocity. Default value is 0.0. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

stingray.Actor

Returns the created actor.

create_cloth ( self, id ) : stingray.Cloth

Creates an Apex cloth with the specified name or index in the unit, if it has not been created already.

Parameters

self :	stingray.Unit	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.
id :	any(string, integer)	The name or index of the new cloth. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.

Returns

stingray.Cloth

The newly created cloth.

create_custom_joint ( self, name, params ) : stingray.Joint

Creates a physics joint in the unit based on a joint description.

Parameters

self :

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.

name :

string

The name of the joint to create.

params :

any(string, stingray.Vector3)+

A list of parameters to configure the joint. The parameter list is a sequence of strings followed by arguments. The following arguments are supported:

"actor_1": Specifies the first actor that should be joined by the constraint. Must be followed by a string parameter that specifies the name of the actor.
"actor_2": Specifies the second actor that should be joined by the constraint. Must be followed by a string parameter that specifies the name of the actor.
"anchor_1": Specifies the first anchor point in local coordinates of the first actor. Must be followed by a Vector3 parameter.
"anchor_2": Specifies the second anchor point in local coordinates of the second actor. Must be followed by a Vector3 parameter.
"global_anchor": Specifies an anchor point, in global coordinates, that will be used for both the joined actors. Must be followed by a Vector3 parameter.
"global_axis": Specifies a constraint axis in global coordinates that will be used for both the joined actors. Must be followed by a Vector3 parameter.

The + notation indicates that there may be one or more instances of the specified type.

The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.

Returns

stingray.Joint

The newly created joint.

create_joint ( self, name ) : stingray.Joint

Creates a physics joint with the specified name, if it has not been created already in the unit.

Parameters

self :	stingray.Unit	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.
name :	string	The name of the joint to create.

Returns

stingray.Joint

The newly created joint.

create_vehicle ( self ) : stingray.Vehicle

Creates a Vehicle in the unit, if it has not been created already.

Parameters

self :

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.Vehicle

The newly created vehicle.

destroy_actor ( self, actor )

Destroys the actor with the specified name or index, if it has been created previously in the unit.

Parameters

self :	stingray.Unit	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.
actor :	any(string, integer)	The name or index of the actor. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.

Returns

This function does not return any values.

destroy_cloth ( self, id )

Destroys an Apex cloth with the specified name or index, if it has been created previously in the unit.

Parameters

self :	stingray.Unit	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.
id :	any(string, integer)	The name or index of the cloth to destroy. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.

Returns

This function does not return any values.

destroy_joint ( self, name )

Destroys a joint with the specified name, if it has been created previously in the unit.

Parameters

self :	stingray.Unit	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.
name :	string	The name of the joint to destroy.

Returns

This function does not return any values.

destroy_vehicle ( self )

Destroys the unit's Vehicle, if one exists.

Parameters

self :

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

This function does not return any values.

find_actor ( self, name ) : integer?

Retrieves the index of the actor with the specified name.

Parameters

self :	stingray.Unit	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.
name :	string	The name to the actor to search for.

Returns

integer?

The index of the actor, or nil if there is no matching actor.

The ? notation indicates that this type is optional: there may be zero or one instances of it.

find_cloth ( self, name ) : integer?

Retrieves the index of the Apex cloth with the specified name in the unit.

Parameters

self :	stingray.Unit	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.
name :	string	The name of the cloth to search for.

Returns

integer?

The index of the cloth in the unit, or nil if no matching cloth exists.

The ? notation indicates that this type is optional: there may be zero or one instances of it.

find_mover ( self, name ) : integer?

Retrieves the index of the Mover with the specified name.

Parameters

self :	stingray.Unit	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.
name :	string	The name of the mover to search for.

Returns

integer?

The index of the mover, or nil if no matching mover exists.

The ? notation indicates that this type is optional: there may be zero or one instances of it.

mover ( self ) : stingray.Mover?

Retrieves the unit's current physics mover, if any.

Parameters

self :

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.Mover?

Returns the current mover for the unit, or nil if the unit has no active mover.

The ? notation indicates that this type is optional: there may be zero or one instances of it.

mover_fits_at ( self, id, position, allow_move ) : boolean, stingray.Vector3?

Indicates whether or not the mover fits at the specified position without colliding with any world geometry.

Parameters

self :	stingray.Unit	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.
id :	any(string, integer)	The name or index of the mover. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.
position :	stingray.Vector3	The position to place the mover.
allow_move :	number?	If non-zero, specifies the distance to search for a non-colliding position. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

boolean	Returns true if the mover fits at the position, or false otherwise.
stingray.Vector3?	If a non-colliding position was found, it is returned as the second paramter. The ? notation indicates that this type is optional: there may be zero or one instances of it.

num_actors ( self ) : integer

Retrieves the number of actors owned by the unit.

Parameters

self :

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 actors in the unit.

num_cloths ( self ) : integer

Retrieves the number of Apex cloths in the unit.

Parameters

self :

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 cloths in the unit.

num_movers ( self ) : integer

Retrieves the number of movers in the unit.

Parameters

self :

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 movers in the unit.

set_cloth_visibilty ( self, id, visibility, context )

Sets the visibility of the Apex cloth with the specified name or index.

Parameters

self :	stingray.Unit	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.
id :	any(string, integer)	The name or index of the cloth. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.
visibility :	boolean	Use true to make the cloth visible, or false to make it hidden.
context :	string?	Optional; can be used to toggle visibility separately for each culling context. Valid values for the context are: default, shadow_caster or occluder. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

This function does not return any values.

set_mover ( self, mover ) : stingray.Mover?

Sets the unit to use the mover with the specified name or index.

Parameters

self :	stingray.Unit	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.
mover :	any(string, integer)?	The name or index of the mover. If nil, the unit's current mover is disabled. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

stingray.Mover?

Returns the mover now set for the unit, or nil if the mover was disabled.

The ? notation indicates that this type is optional: there may be zero or one instances of it.

set_moving ( self, frames )

Marks the unit as moving for the specified number of frames, meaning that the world will update the unit's position automatically.

Parameters

self :	stingray.Unit	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.
frames :	integer	Number of frames in the animation.

Returns

This function does not return any values.

You don't need to mark the unit as moving in cases where you call one of the set_local...() functions on the unit, because those functions automatically mark the unit as moving. However, if you do some other special processing on the unit, you may need to call this function.

Note: Currently this function is not required. It is a tradeoff between speed and convenience if all operations that change a unit should automatically set it as moving, or if the gameplay programmer has to do that explicitly.

vehicle ( self ) : stingray.Vehicle?

Retrieves the Vehicle from the unit.

Parameters

self :