stingray.TransformComponent object reference

Description

A component that lets entities be positioned in the world.

The TransformComponent creates a scene graph for entities. Entities can be linked to other entities and their local positions changed. The TransformComponent is responsible for computing the world position of all the entities.

Constructors and accessors

stingray.EntityManager.transform_component()

Other related reference items

	stingray.EntityManager.transform_component()
	Entity

Related help topics

	Using Entities in your Project > About built-in components
	Using Entities in your Project > Interact with entities during gameplay

Functions

children ( self, parent ) : stingray.Entity[] Returns the first-level children of the parent entity.

Parameters

self :	stingray.TransformComponent	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
parent :	stingray.Entity	The entity whose children we are looking for.

Returns

stingray.Entity[]

The children of the parent entity. 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.

If the parent does not have any children, an empty table is returned.

create ( self, entity, id ) : integer Creates a component instance for the entity with the specified component id.

Parameters

self :	stingray.TransformComponent	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
entity :	stingray.Entity	The entity.
id :	any(integer, string)	The component id. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.

Returns

integer

The component instance.

destroy ( self, instance ) Destroys a particular component instance for an entity.

Parameters

self :	stingray.TransformComponent	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
instance :	integer	The component instance to destroy.

Returns

This function does not return any values.

destroy_all ( self, entity ) Destroys all component instance(s) for an entity.

Parameters

self :	stingray.TransformComponent	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
entity :	stingray.Entity	The entity to destroy all component instances for.

Returns

This function does not return any values.

get_property ( self, instance, key ) : any* Gets the value of a property key.

Parameters

self :	stingray.TransformComponent	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
instance :	integer	The component instance.
key :	any(string, string[])	The key for the property whose value you want to get. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.

Returns

any*	The value of the key. The * notation indicates that there may be zero or more instances of the specified type.

The key can either be a dot separated string "fog.color.red" or an array of strings {"fog", "color", "red"}. Both methods can be used interchangeably.

The value will be one of the values supported by the property system: nil, boolean, number, string or an array of floats.

Float arrays are returned as multiple return values. Use a wrapper if you want them as a table or a Vector3.

If the key doesn't exist, nil will be returned.

get_property_by_id ( self, entity, id, key ) : any* Gets the property value for the component instance matching the specified id.

Parameters

self :	stingray.TransformComponent	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
entity :	stingray.Entity	The entity.
id :	integer	The component instance id.
key :	any(string, string[])	The key for the property whose value you want to get. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.

Returns

any*	The value of the key. The * notation indicates that there may be zero or more instances of the specified type.

The key can either be a dot separated string "fog.color.red" or an array of strings {"fog", "color", "red"}. Both methods can be used interchangeably.

The value will be one of the values supported by the property system: nil, boolean, number, string or an array of floats.

Float arrays are returned as multiple return values. Use a wrapper if you want them as a table or a Vector3.

If the key doesn't exist, nil will be returned.

Calling this function will do an additional lookup from the specified component id to component instance. When getting multiple properties it is better to to first lookup the component instance with the component id and then call get_property.

instances ( self, entity ) : integer* Returns all component instances for the specified entity.

Parameters

self :	stingray.TransformComponent	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
entity :	stingray.Entity	The entity.

Returns

integer*

All entity component instances. The * notation indicates that there may be zero or more instances of the specified type.

Note that the instances are returned on the stack.

instance_ids ( self, entity ) : integer* Returns the IDs for all the entity's components.

Parameters

self :	stingray.TransformComponent	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
entity :	stingray.Entity	The entity.

Returns

integer*

All entity instance IDs. The * notation indicates that there may be zero or more instances of the specified type.

Note that the IDs are returned on the stack.

link ( self, child, parent, position, rotation, scale ) Links the child entity to the parent.

Parameters

self :	stingray.TransformComponent	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
child :	stingray.Entity	The entity that we want to link.
parent :	stingray.Entity	The entity that the child should be linked to.
position :	stingray.Vector3?	The local position that the child should have after linking. The ? notation indicates that this type is optional: there may be zero or one instances of it.
rotation :	stingray.Quaternion?	The local rotation that the child should have after linking. The ? notation indicates that this type is optional: there may be zero or one instances of it.
scale :	stingray.Vector3?	The local scale that the child should have after linking. 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.

After linking, the child will follow the movement of the parent.

If local transforms are specified they give the orientation of the child with respect to the parent. If not, the position is the same as the parent.

link ( self, child, parent, pose ) Links the child entity to the parent.

Parameters

self :	stingray.TransformComponent	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
child :	stingray.Entity	The entity that we want to link.
parent :	stingray.Entity	The entity that the child should be linked to.
pose :	stingray.Matrix4x4?	The local pose that the child should have after linking. 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.

After linking, the child will follow the movement of the parent.

If local transforms are specified they give the orientation of the child with respect to the parent. If not, the position is the same as the parent.

link_to_scene_graph ( self, child, parent, node, pose ) Links the child entity to the parent.

Parameters

self :	stingray.TransformComponent	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
child :	stingray.Entity	The entity that we want to link.
parent :	stingray.Entity	The entity that the child should be linked to.
node :	integer	The node in the parent's scene graph that the child should be linked to.
pose :	stingray.Matrix4x4?	The local pose that the child should have after linking. 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.

After linking, the child will follow the movement of the parent.

If local transforms are specified they give the orientation of the child with respect to the parent node. If not, the position is the same as the parent.

link_to_scene_graph ( self, child, parent, node, position, rotation, scale ) Links the child entity to the parent.

Parameters

self :	stingray.TransformComponent	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
child :	stingray.Entity	The entity that we want to link.
parent :	stingray.Entity	The entity that the child should be linked to.
node :	integer	The node in the parent's scene graph that the child should be linked to.
position :	stingray.Vector3?	The local position that the child should have after linking. The ? notation indicates that this type is optional: there may be zero or one instances of it.
rotation :	stingray.Quaternion?	The local rotation that the child should have after linking. The ? notation indicates that this type is optional: there may be zero or one instances of it.
scale :	stingray.Vector3?	The local scale that the child should have after linking. 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.

After linking, the child will follow the movement of the parent.

If local transforms are specified they give the orientation of the child with respect to the parent node. If not, the position is the same as the parent.

local_pose ( self, entity ) : stingray.Matrix4x4 Returns the local pose of the entity with respect to its parent.

Parameters

self :	stingray.TransformComponent	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
entity :	stingray.Entity	The entity whose pose we are looking for.

Returns

stingray.Matrix4x4

The local pose of the entity.

If the entity doesn't have a parent, the local pose is identical to the world pose.

local_position ( self, entity ) : stingray.Vector3 Returns the local position of the entity with respect to its parent.

Parameters

self :	stingray.TransformComponent	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
entity :	stingray.Entity	The entity whose position we are looking for.

Returns

stingray.Vector3

The local position of the entity.

If the entity doesn't have a parent, the local position is identical to the world position.

local_rotation ( self, entity ) : stingray.Quaternion Returns the local rotation of the entity with respect to its parent.

Parameters

self :	stingray.TransformComponent	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
entity :	stingray.Entity	The entity whose rotation we are looking for.

Returns

stingray.Quaternion

The local rotation of the entity.

If the entity doesn't have a parent, the local rotation is identical to the world rotation.

local_scale ( self, entity ) : stingray.Vector3 Returns the local scale of the entity with respect to its parent.

Parameters

self :	stingray.TransformComponent	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
entity :	stingray.Entity	The entity whose scale we are looking for.

Returns

stingray.Vector3

The local scale of the entity.

If the entity doesn't have a parent, the local scale is identical to the world scale.

lookup ( self, entity, id ) : integer Returns the component instance for the specified id.

Parameters

self :	stingray.TransformComponent	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
entity :	stingray.Entity	The entity.
id :	integer	The component instance id.

Returns

integer

The component instance.

parent ( self, child ) : stingray.Entity? Returns the parent of the child or nil if the child is unlinked.

Parameters

self :	stingray.TransformComponent	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
child :	stingray.Entity	The child whose parent we are interested in.

Returns

stingray.Entity?

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

set_local_pose ( self, entity, pose ) Sets the local pose of the entity.

Parameters

self :	stingray.TransformComponent	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
entity :	stingray.Entity	The entity whose pose we want to change.
pose :	stingray.Matrix4x4	The new local pose of the entity.

Returns

This function does not return any values.

If the entity does not have any parents, the local pose is identical to the world pose.

Changing the local pose will immediately change the world pose of the entity and all its children to reflect the new pose scale.

set_local_position ( self, entity, position ) Sets the local position of the entity.

Parameters

self :	stingray.TransformComponent	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
entity :	stingray.Entity	The entity whose position we want to change.
position :	stingray.Vector3	The new local position of the entity.

Returns

This function does not return any values.

If the entity does not have any parents, the local position is identical to the world position.

Changing the local position will immediately change the world position of the entity and all its children to reflect the new local position.

set_local_rotation ( self, entity, rotation ) Sets the local rotation of the entity.

Parameters

self :	stingray.TransformComponent	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
entity :	stingray.Entity	The entity whose rotation we want to change.
rotation :	stingray.Quaternion	The new local rotation of the entity.

Returns

This function does not return any values.

If the entity does not have any parents, the local rotation is identical to the world rotation.

Changing the local rotation will immediately change the world rotation of the entity and all its children to reflect the new local rotation.

set_local_scale ( self, entity, scale ) Sets the local scale of the entity.

Parameters

self :	stingray.TransformComponent	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
entity :	stingray.Entity	The entity whose scale we want to change.
scale :	stingray.Vector3	The new local scale of the entity.

Returns

This function does not return any values.

If the entity does not have any parents, the local scale is identical to the world scale.

Changing the local scale will immediately change the world scale of the entity and all its children to reflect the new local scale.

set_parent ( self, entities, parent_indices ) For each entity, looks in the parent_indices and sets the parent to the given parent index.

Parameters

self :	stingray.TransformComponent	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
entities :	table	A list of entities to set parent/child relationships for.
parent_indices :	table	A list of the same length as the entity list of parent indexes. Use false as an index for an entity that has no parent.

Returns

This function does not return any values.

This function should be called after adding and configuring all components, but before spawned.

set_property ( self, instance, key, value ) Sets the value for a property key.

Parameters

self :	stingray.TransformComponent	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
instance :	integer	The component instance.
key :	any(string, string[])	The key for the property whose value you want to set. 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 set for the key.

Returns

This function does not return any values.

The key can either be a dot separated string "fog.color.red" or an array of strings {"fog", "color", "red"}. Both methods can be used interchangeably.

The value can be any value supported by the property system: nil, boolean, number, string or an array of floats.

You can use a Vector3 or a Quaternion instead of passing an array of 3 or 4 floats.

Setting the value to nil can be used to erase the property.

set_property_by_id ( self, entity, id, key, value ) : integer Sets the property value and returns the component instance matching the specified id.

Parameters

self :	stingray.TransformComponent	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
entity :	stingray.Entity	The entity.
id :	integer	The component instance id.
key :	any(string, string[])	The key for the property whose value you want to set. 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 set for the key.

Returns

integer

The component instance.

The key can either be a dot separated string "fog.color.red" or an array of strings {"fog", "color", "red"}. Both methods can be used interchangeably.

The value can be any value supported by the property system: nil, boolean, number, string or an array of floats.

You can use a Vector3 or a Quaternion instead of passing an array of 3 or 4 floats.

Setting the value to nil can be used to erase the property.

Calling this function will do an additional lookup from the specified component id to component instance. When setting multiple properties it is better to to first lookup the component instance with the component id and then call set_property.

spawned ( self, entities ) For each entity, calls spawned for this component type.

Parameters

self :	stingray.TransformComponent	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
entities :	table	A list of entities to call spawned for.

Returns

This function does not return any values.

This should be called after creating and configuring and entity and its components, to finalize its introduction to the world.

unlink ( self, child ) Unlinks the child from its parent node.

Parameters

self :	stingray.TransformComponent	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
child :	stingray.Entity	The entity that should be unlinked.

Returns

This function does not return any values.

After the unlink, the child will no longer follow the movements of the parent.

world_pose ( self, entity ) : stingray.Matrix4x4 Returns the world pose of the entity.

Parameters

self :	stingray.TransformComponent	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
entity :	stingray.Entity	The entity whose pose we are looking for.

Returns

stingray.Matrix4x4

The world pose of the entity.

world_position ( self, entity ) : stingray.Vector3 Returns the world position of the entity.

Parameters

self :	stingray.TransformComponent	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
entity :	stingray.Entity	The entity whose position we are looking for.

Returns

stingray.Vector3

The world position of the entity.

world_rotation ( self, entity ) : stingray.Quaternion Returns the world rotation of the entity.

Parameters

self :	stingray.TransformComponent	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
entity :	stingray.Entity	The entity whose rotation we are looking for.

Returns

stingray.Quaternion

The world rotation of the entity.