Actor - stingray.Actor object reference - Stingray Lua API Reference
Description
Interface to a physics actor.
An actor is a rigid body living in the physics world.
The Lua Actor object will become invalid if the physics actor is destroyed. To prevent against using an invalid Actor, you can store an Actor in an ActorBox for access in future frames. The ActorBox will detect whether or not the corresponding physics actor has become destroyed since the Actor was stored in the box.
Constructors and accessors 
Related sample code
Other related reference items
Related help topics
Functions
 |
add_angular_velocity ( self, velocity ) Adds a delta angular velocity to the actor's current velocity.
|
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. | |
velocity : | A delta angular velocity added to the actor's current velocity. |
| This function does not return any values. |
This call, and all other calls that change velocity or add forces, only affect physical actors.
| |
add_impulse ( self, impulse )Adds a momentary impulse to the actor, expressed as (mass * velocity) in three dimensions.
|
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. | |
impulse : | The impulse added to the actor. |
| This function does not return any values. |
This call, and all other calls that change velocity or add forces, only affect physical actors.
| |
add_impulse_at ( self, impulse, pos )Adds a impulse at a particular position in the actor, causing rotation.
|
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. | |
impulse : | The impulse added to actor. | |
pos : | The position where the impulse is applied. |
| This function does not return any values. |
The impulse is expressed as (mass * velocity) in three dimensions.
This call, and all other calls that change velocity or add forces, only affect physical actors.
| |
add_torque_impulse ( self, impulse )Adds a rotational impulse to the actor.
|
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. | |
impulse : | The rotational impulse that will be applied to the actor. |
| This function does not return any values. |
This call, and all other calls that change velocity or add forces, only affect physical actors.
| |
add_velocity ( self, velocity )Adds a delta velocity to the actor's current velocity.
|
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. | |
velocity : | The change in velocity that will be added to the actor's current velocity. |
| This function does not return any values. |
This call, and all other calls that change velocity or add forces, only affect physical actors.
| |
add_velocity_at ( self, velocity, pos )Adds a delta velocity to the actor's current velocity at a particular position in the actor, causing rotation.
|
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. | |
velocity : | The change in velocity that will be added to the actor's current velocity. | |
pos : | The position at which the velocity is added. |
| This function does not return any values. |
This call, and all other calls that change velocity or add forces, only affect physical actors.
| |
angular_damping ( self ) : numberReturns the angular damping of the actor.
|
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. |
number |
The angular damping of the actor. |
| |
angular_velocity ( self ) : stingray.Vector3Returns the angular velocity of the actor.
|
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. |
|
The angular velocity of the actor. |
| |
center_of_mass ( self ) : stingray.Vector3Returns the position of the actor's center of mass.
|
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. |
|
The position of the actor's center of mass. |
| |
is_collision_enabled ( self ) : booleanIndicates if an actor is set up to collide with others during physics simulations.
|
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. |
boolean |
Returns true if this actor can collide with other actors, or false otherwise. |
| |
is_dynamic ( self ) : booleanIndicates whether or not the actor is dynamic (non-static).
|
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. |
boolean |
Returns true if the actor is dynamic, or false otherwise. |
Non-static actors may be either kinematic/keyframed or physical (physics-driven).
| |
is_gravity_enabled ( self ) : booleanIndicates whether or not this actor is affected by gravity.
|
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. |
boolean |
Returns true if the actor is affected by gravity, or false otherwise. |
| |
is_kinematic ( self ) : booleanIndicates whether or not the actor is a kinematic actor: i.e. driven by keyframed animation.
|
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. |
boolean |
Returns true if the actor is kinematic, or false otherwise. |
| |
is_physical ( self ) : booleanIndicates whether or not the actor is a physical (physics-driven) actor.
|
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. |
boolean |
Returns true if the actor is physical (physics-driven), or false otherwise. |
| |
is_scene_query_enabled ( self ) : booleanIndicates whether or not this actor is included when performing scene queries such as raycasts or overlap tests.
|
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. |
boolean |
Returns true if this actor is included when performing scene queries. |
| |
is_sleeping ( self ) : booleanIndicates whether or not this actor is sleeping.
|
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. |
boolean |
Returns true if the actor is sleeping, or false otherwise. |
| |
is_static ( self ) : booleanIndicates whether or not the actor is a static actor.
|
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. |
boolean |
Returns true if the actor is static, or false otherwise. |
| |
linear_damping ( self ) : numberReturns the linear damping of the actor.
|
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. |
number |
The linear damping of the actor. |
| |
mass ( self ) : numberReturns the mass of the actor.
|
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. |
number |
The mass of the actor. |
| |
node ( self ) : integerReturns the index of the node this actor occupies in the scene graph of its owning Unit.
|
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. |
integer |
The index of the actor in the scene graph of its owning Unit. |
Note that some actors may not have an owning Unit.
| |
point_velocity ( self, p ) : stingray.Vector3Returns the velocity at a point p on the surface of the actor.
|
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. | |
p : | A point on the surface of the actor. |
|
The velocity at the specified point on the surface of the actor. |
The point is specified in global coordinates.
| |
pose ( self ) : stingray.Matrix4x4Returns the current pose of the actor: its position and rotation expressed as a Matrix4x4.
|
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. |
|
The position and rotation of the actor. |
| |
position ( self ) : stingray.Vector3Returns the position of the specified actor.
|
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. |
|
The position of the actor. |
| |
push ( self, velocity, mass )Pushes the specified actor as if it were hit by an object with the specified velocity and mass.
|
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. | |
velocity : | The velocity of the pushing object. | |
mass : | number | The mass of the pushing object. |
| This function does not return any values. |
Use this to simulate a collision with objects that are not in the physics simulation, such as bullets.
This call, and all other calls that change velocity or add forces, only affect physical actors.
| |
push_at ( self, velocity, mass, pos )Pushes the specified actor as if it were hit by an object with the specified velocity and mass.
|
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. | |
velocity : | The velocity of the pushing object. | |
mass : | number | The mass of the pushing object. |
pos : | The position where the actor is pushed. |
| This function does not return any values. |
The force is applied at the specified position, causing the object to rotate.
This call, and all other calls that change velocity or add forces, only affect physical actors.
| |
put_to_sleep ( self )Puts the specified actor to sleep.
|
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. |
| This function does not return any values. |
| |
rotation ( self ) : stingray.QuaternionReturns the rotation of the actor.
|
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. |
|
The rotation of the actor. |
| |
set_angular_damping ( self, damping )Sets the angular damping of the actor.
|
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. | |
damping : | number | The new angular damping value for the actor. |
| This function does not return any values. |
| |
set_angular_velocity ( self, velocity )Sets the angular velocity of the actor.
|
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. | |
velocity : | The new angular velocity to set for the actor. |
| This function does not return any values. |
This call, and all other calls that change velocity or add forces, only affect physical actors.
| |
set_collision_enabled ( self, enabled )Determines whether or not this actor collides with other actors during physics simulation.
|
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. | |
enabled : | boolean | true to enable collision, or false otherwise. |
| This function does not return any values. |
| |
set_collision_filter ( self, filter )Changes the collision filter used by the actor.
|
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. | |
filter : | string | The new collision filter to set for the actor. |
| This function does not return any values. |
| |
set_gravity_enabled ( self, enabled )Determines whether or not this actor is affected by gravity.
|
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. | |
enabled : | boolean | true to make this actor subject to gravity, or false otherwise. |
| This function does not return any values. |
| |
set_kinematic ( self, kinematic )Determines whether or not this actor is kinematic: i.e. driven by keyframed animation.
|
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. | |
kinematic : | boolean | true to mark the actor as kinematic, or false otherwise. |
| This function does not return any values. |
A kinematic actor will push dynamic actors, but won't slow down while doing so. Note that you can only use this on dynamic actors, not on static actors.
Related sample code
| |
set_linear_damping ( self, damping )Sets the linear damping of the actor.
|
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. | |
damping : | number | The new linear damping value for the actor. |
| This function does not return any values. |
| |
set_scene_query_enabled ( self, enabled )Determines whether or not this actor is included when performing scene queries such as raycasts or overlap tests.
|
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. | |
enabled : | boolean | true to enable scene queries for this actor, or false otherwise. |
| This function does not return any values. |
| |
set_velocity ( self, velocity )Sets the velocity of the actor.
|
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. | |
velocity : | The new velocity to set for the actor. |
| This function does not return any values. |
This call, and all other calls that change velocity or add forces, only affect physical actors.
| |
teleport_pose ( self, pos )Sets the new pose of the actor: its position and rotation expressed as a Matrix4x4.
|
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. | |
pos : | The new position and rotation to set for the actor. |
| This function does not return any values. |
You should only call this function for dynamic actors. The position of static and keyframed actors is controlled by the position of the corresponding scene graph node.
| |
teleport_position ( self, pos )Sets a new position for the actor.
|
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. | |
pos : | The new position to set for the actor. |
| This function does not return any values. |
| |
teleport_rotation ( self, pos )Sets a new rotation for the actor.
|
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. | |
pos : | The new rotation to set for the actor. |
| This function does not return any values. |
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. |
|
The Unit that owns the actor, if any. |
Note that some actors may not have an owning Unit.
Related sample code
| |
velocity ( self ) : stingray.Vector3Returns the velocity of the actor.
|
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. |
|
The velocity of the actor. |
| |
wake_up ( self )Wakes up the specified actor.
|
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. |
| This function does not return any values. |
Development only
The elements in this group are only available in development builds.
Do not use them in your final builds.
| |
debug_draw ( self, lineobject, color, camera_tm )Draws the actor using the specified line object.
|
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. | |
lineobject : | The LineObject to use for representing this actor. | |
color : | The color used in the draw. | |
camera_tm : | The position and rotation of the camera. This is used when drawing huge physics meshes and height fields: only the triangles close to the camera are drawn. If the camera pose is not specified, the engine uses World.debug_camera_pose(). The ? notation indicates that this type is optional: there may be zero or one instances of it. |
| This function does not return any values. |
Use this function only for debugging your development builds.