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

stingray.ScriptComponent object reference

Description

A component that adds scripting support to entities.

An example script. The script file must return a table with a name field.

CustomBehaviour = CustomBehaviour or { name = "mybehaviour" }

-- Callback triggered when one or more entity has spawned
-- Instances is an interleaved list of entities and component instances, i.e [e1, c1, e1, c2, e2, c1, ...].
function CustomBehaviour.spawned(instances, world)
end

-- Callback triggered when one or more entity has unspawned
function CustomBehaviour.unspawned(instances, world)
end

-- Callback triggered when calling stingray.ScriptComponent.update(deltatime)
function CustomBehaviour.update(deltatime, world)
end

return CustomBehaviour

Functions

Parameters

self :

stingray.ScriptComponent

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.

function_name :

string

The name of the function to call.

Returns
This function does not return any values.

Typically used in the game loop to trigger all update functions on all scripts.

Parameters

self :

stingray.ScriptComponent

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.

Parameters

self :

stingray.ScriptComponent

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

self :

stingray.ScriptComponent

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

self :

stingray.ScriptComponent

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.

instances :

table

An optional interleaved list of entities and component instance ids, i.e [e1, c1, e1, c2, e2, c1, ...].

function_name :

string

Name of the function to call.

Returns
This function does not return any values.
Parameters

self :

stingray.ScriptComponent

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.

script_name :

string

Name of the script.

Returns

stingray.Entity[]

An array of entities linked to the script name.

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

self :

stingray.ScriptComponent

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.

Parameters

self :

stingray.ScriptComponent

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.

Parameters

self :

stingray.ScriptComponent

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.

Parameters

self :

stingray.ScriptComponent

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.

Parameters

self :

stingray.ScriptComponent

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

An optional entity to query for script components.

script_name :

string

Name of the script.

result_table :

table?

An optional table for the result.

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

any(stingray.Entity, integer)[]

Interleaved pairs of entities and component instance ids.

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

integer

The number of results written to the table.

Example usage:

-- We can pass a cached table for better performance or we can omit the parameter and have it allocated for us.
local components, num_components = script_component:instances_with_script("myscript_name", self._query_cache)
local arg1 = -- some argument
local arg2 = -- some argument
script_component:call_function(components, "some_function", arg1, arg2)

local entity = -- some entity
local arg1 = -- some argument
local arg2 = -- some argument
local components = script_component:instances_with_script(entity, "myscript_name", self._query_cache)
script_component:call_function(components, "some_function", arg1, arg2)
Parameters

self :

stingray.ScriptComponent

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.

Parameters

self :

stingray.ScriptComponent

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.

Parameters

self :

stingray.ScriptComponent

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.

Parameters

self :

stingray.ScriptComponent

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.

Parameters

self :

stingray.ScriptComponent

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.