stingray.Level object reference

Description

Represents a level that has been loaded into the runtime game world.

Constructors and accessors

stingray.Application.flow_callback_context_level() stingray.Level.nested_levels() stingray.Unit.level() stingray.World.levels() stingray.World.load_level() stingray.World.load_level_with_object_sets()

Related sample code

Appkit: /app.lua Appkit: /camera_wrapper.lua Appkit: /level_wrapper.lua Basic template: /player.lua Oculus VR template: /player.lua Steam VR template: /player.lua Minimal template: /boot.lua

Other related reference items

	stingray.StoryTeller.play_level_story() stingray.Unit.level() stingray.World.destroy_level()
	Core

Related help topics

	Building Levels > Create game objects > Create splines
	Creating Gameplay > Visual programming using Flow > Example workflow: Trigger a door opening
	Creating Gameplay > Scripting with Lua > Starting Lua from a template: Using the Appkit > Using the SimpleProject
	Creating Gameplay > Communicating between Flow and Lua
	Managing Content and Resources > Loading and unloading content at runtime > Example: Loading and unloading one resource package per level
	Using Entities in your Project > Interact with entities during gameplay

Functions

entities ( self ) : stingray.Entity[] Returns a table with all the entities in the level.

Parameters

self :

stingray.Level

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.Entity[]

A table with all the entities in the level. 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.

flow_variable ( self, name ) : any Returns the value of the External Output flow variable with the specified name in the level flow.

Parameters

self :	stingray.Level	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".

get_data ( self, indices ) : any Retrieves the data set at the specified indices within the level's script data object.

Parameters

self :	stingray.Level	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 data previously stored at the specified sequence of indices.

Similar to Unit.get_data().

Other related reference items

	stingray.DynamicData
	stingray.Level.set_data() stingray.LevelResource.data()

has_data ( self, indices ) : boolean Indicates whether or not any data has been saved at the specified indices in the level's script data object.

Parameters

self :	stingray.Level	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.

Similar to Unit.has_data().

has_volume ( self, volume_name ) : boolean Indicates whether or not the level has a volume with the specified name.

Parameters

self :	stingray.Level	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.
volume_name :	string	The name of the volume.

Returns

boolean

Returns true if the level has the specified volume, and false otherwise.

is_point_inside_volume ( self, volume_name, point ) : boolean Indicates whether or not the point is inside the named volume in the level.

Parameters

self :	stingray.Level	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.
volume_name :	string	The name of the volume.
point :	stingray.Vector3	The point that is tested.

Returns

boolean

Returns true if the point is inside the named volume, and false otherwise.

navigation_mesh ( self ) : stingray.NavigationMesh Returns the navigation mesh for the level.

Parameters

self :

stingray.Level

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

The navigation mesh of the level.

Other related reference items

stingray.LevelResource.destroy_navigation_mesh()

nested_levels ( self ) : stingray.Level[] Returns a list of the levels that are nested directly below the specified level.

Parameters

self :

stingray.Level

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

Other related reference items

stingray.World.levels()

next_random_point_inside_volume ( self, volume_name, seed ) : integer, stingray.Vector3 A pure random point function.

Parameters

self :	stingray.Level	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.
volume_name :	string	The name of the volume.
seed :	integer	A seed parameter.

Returns

integer	The new seed generated.
stingray.Vector3	The random point inside the named volume.

Similar to random_point_inside_volume(), but takes a seed parameter and returns a new seed along with the random point. Typically, next_random_point_inside_volume() is used when you want to query a reproducible sequence of random points inside a volume.

num_nested_levels ( self ) : integer Returns the number of nested levels inside the level.

Parameters

self :

stingray.Level

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 total number of nested levels.

num_splines ( self ) : integer Returns the number of splines in the level.

Parameters

self :

stingray.Level

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 total number of splines.

pose ( self ) : stingray.Matrix4x4 Returns the Matrix4x4 that placed the Level in its World.

Parameters

self :

stingray.Level

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

The transform used when spawning the level from the world

random_point_inside_volume ( self, volume_name ) : stingray.Vector3 Returns the world-space position of a random point inside the named volume.

Parameters

self :	stingray.Level	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.
volume_name :	string	The name of the volume.

Returns

stingray.Vector3

A random point inside the named volume.

Other related reference items

stingray.Level.next_random_point_inside_volume()

set_data ( self, indices, indices, indices, value ) set_data ( self, indices, indices, value ) set_data ( self, indices, value ) Stores the specified value in a global script data object, at a location determined by the specified indices.

Parameters

self :	stingray.Level	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(). Similar to Unit.set_data().

set_flow_variable ( self, name, value ) Sets the value of the the External Input flow variable with the specified name in the level flow.

Parameters

self :	stingray.Level	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.

spawn_background ( self ) Spawns all background elements in the level.

Parameters

self :

stingray.Level

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.

Typically, these will be skybox units or other elements that one would want to add to the scene when spawning a root level, but not when spawning a nested level or sub-level. If you don't call this function, you will typically get a black sky with some rendering artifacts, since background objects will typically be visible in the level editor.

spline ( self, name ) : stingray.Vector3[] Returns the control points for the bezier spline with the specified name.

Parameters

self :	stingray.Level	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 spline.

Returns

stingray.Vector3[]

A table that contains the control points for the spline, or an empty table if no spline exists with the specified 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.

spline_by_index ( self, index ) : stingray.Vector3[] Returns the control points for the bezier spline with the specified index.

Parameters

self :	stingray.Level	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 spline in the level.

Returns

stingray.Vector3[]

A table that contains the control points for the spline, or an empty table if no spline exists with the specified index. 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.

trigger_event ( self, event ) Triggers the external event in the level flow script.

Parameters

self :	stingray.Level	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 external event to trigger.

Returns

This function does not return any values.

trigger_level_loaded ( self ) Triggers the "level loaded" event in the level's flow graph.

Parameters

self :

stingray.Level

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.

trigger_level_shutdown ( self ) Triggers the "level shutdown" event in the level's flow graph.

Parameters

self :

stingray.Level

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.

trigger_level_update ( self ) Triggers the "level updated" event in the level's flow graph.

Parameters

self :

stingray.Level

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.

units ( self ) : stingray.Unit[] Returns a list of all the units that were placed into the level in the editor, and that have not yet been unspawned since the level was loaded.

Parameters

self :

stingray.Level

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

Returns

stingray.Unit[]

The list of remaining units that were spawned when the level was loaded. 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.

Do not keep this list across multiple frames, since it will contain invalid references if one or more units are destroyed after the list was obtained. Call this method again to get a fresh list of valid references.

unit_by_index ( self, index ) : stingray.Unit Retrieves the unit with the specified index in the level.

Parameters

self :	stingray.Level	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 unit.

Returns

stingray.Unit

The Unit that corresponds to the index, or nil if no unit was found with the specified index.

The index is typically retrieved from unit_index().

Other related reference items

stingray.Level.unit_index()

unit_index ( self, unit ) : integer? Returns the index of the unit in the level.

Parameters

self :	stingray.Level	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.
unit :	stingray.Unit	A unit in the level.

Returns

integer?

The index of the specified unit, or nil if no matching unit was found. The ? notation indicates that this type is optional: there may be zero or one instances of it.

You can turn the index back to a unit by calling unit_by_index(). You can use this, for example, to send unit IDs across the network to other players.

Note: You can only use this function with units that are statically spawned in the level, not with units that are spawned by scripts or flow nodes.

Other related reference items

stingray.Level.unit_by_index()

world ( self ) : stingray.World Returns the World that the Level has been spawned in.

Parameters

self :

stingray.Level

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 that the level is spawned in.

Related sample code

Appkit: /unit_link.lua