stingray.World object reference

Description

Represents a game world.

Constructors and accessors

stingray.Application.flow_callback_context_world() stingray.Application.main_world() stingray.Application.new_world() stingray.Application.worlds() stingray.Level.world() stingray.Unit.level()

Related sample code

Appkit: /app.lua Appkit: /debug_menu.lua Appkit: /debug_scrollbox.lua Appkit: /level_wrapper.lua Appkit: /loading_screen.lua Appkit: /simple_project.lua Appkit: /unit_link.lua Appkit: /world_wrapper.lua Basic template: /player.lua Character template: /player.lua Vehicle template: /player.lua Oculus VR template: /player.lua Oculus VR template: /project_utils.lua Steam VR template: /player.lua Steam VR template: /project_utils.lua Minimal template: /boot.lua

Other related reference items

	stingray.Replay stingray.WwiseWorld
	stingray.Application.create_viewport() stingray.Application.destroy_viewport() stingray.Application.main_world() stingray.Application.new_world() stingray.Application.release_world() stingray.Application.render_world() stingray.Application.worlds() stingray.EntityManager.actor_component() stingray.EntityManager.animation_blender_component() stingray.EntityManager.animation_state_machine_component() stingray.EntityManager.create() stingray.EntityManager.flow_component() stingray.EntityManager.mesh_component() stingray.EntityManager.render_data_component() stingray.EntityManager.scene_graph_component() stingray.EntityManager.script_component() stingray.EntityManager.spawn() stingray.EntityManager.spawn() stingray.EntityManager.tag_component() stingray.EntityManager.transform_component() stingray.EntityManager.unit_component() stingray.GearVR.link_node_to_tracker() stingray.GoogleVR.link_node_to_eye() stingray.Hololens.attach_entity() stingray.Hololens.initialize() stingray.Hololens.spatial_map_setup() stingray.Level.pose() stingray.Level.world() stingray.LineObject.dispatch() stingray.NavigationMesh.destroy() stingray.NavigationMesh.merge() stingray.Oculus.initialize() stingray.Oculus.link_node_to_tracker() stingray.Oculus.set_camera() stingray.SteamVR.initialize() stingray.SteamVR.link_node_to_tracker() stingray.SteamVR.set_camera() stingray.TerrainDecoration.create_observer() stingray.TerrainDecoration.destroy_observer() stingray.TerrainDecoration.move_observer() stingray.Unit.level() stingray.UnitSynchronizer.set_world() stingray.Wwise.wwise_world()
	Core

Related help topics

	Lighting and Rendering > Lighting > Light sources > Create a light source
	Lighting and Rendering > Lighting > Light sources > Change light source properties
	Lighting and Rendering > Shading > Project a material as a decal
	Lighting and Rendering > The Shading environment and post effects > Change shading environment properties
	Creating Gameplay > Scripting with Lua > Starting Lua from a template: Using the Appkit > Managing worlds, levels and cameras through the Appkit
	Creating Gameplay > Scripting with Lua > Starting Lua from scratch: using a custom boot script
	Creating Gameplay > Scripting with Lua > Starting Lua from scratch: using a custom boot script > Example Boot Script
	Creating Gameplay > Scripting with Lua > Using the Lua API > Object lifetimes and userdata binding
	Creating Gameplay > Physics > Set up vector field (wind) effects
	Using Entities in your Project > Interact with entities during gameplay

Functions

delta_time ( self ) : number Retrieves the delta time value used during the last world update.

Parameters

self :

stingray.World

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.

Returns

number

The delta time value.

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

Parameters

self :

stingray.World

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.

Returns

stingray.Entity[]

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

replay ( self ) : stingray.Replay? Returns a Replay object, which you can use to replay events in the world.

Parameters

self :

stingray.World

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.

Returns

stingray.Replay?

The replay object owned by the world, or nil if the replay system was not enabled for the world. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Other related reference items

stingray.Replay

scatter_system ( self ) : stingray.ScatterSystem Returns the scatter brush system owned by the world.

Parameters

self :

stingray.World

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.

Returns

stingray.ScatterSystem

The scatter system owned by the world.

The brush system is used for mass unit spawning.

Related sample code

Appkit: /camera_wrapper.lua

storyteller ( self ) : stingray.StoryTeller Returns the StoryTeller for the world, which you can use to play stories or cutscenes.

Parameters

self :

stingray.World

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.

Returns

stingray.StoryTeller

The storyteller owned by the world.

Other related reference items

stingray.StoryTeller

time ( self ) : number Retrieves the current time in the world: i.e. the sum of all the delta times for every update since the world was created.

Parameters

self :

stingray.World

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.

Returns

number

The current time in the world.

Related sample code

Basic template: /main_menu.lua Character template: /main_menu.lua Vehicle template: /main_menu.lua Oculus VR template: /main_menu.lua

update ( self, delta_time ) Updates the engine representation of the world.

Parameters

self :	stingray.World	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.
delta_time :	number?	The time step that the world should use when updating. Optional; if not specified, the application's global time step will be used. 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.

You should typically call this function in your implementation of the update() callback you provide to the engine in your Lua boot script.

Instead of calling update(), you can call update_animations() and then update_scene() separately. This allows your boot script to do some processing in between the update of the animations and the update of the scene.

update_animations ( self, delta_time ) Updates the animations in the world.

Parameters

self :	stingray.World	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.
delta_time :	number?	The time step that the world should use when updating. Optional; if not specified, the application's global time step will be used. 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.

Other related reference items

stingray.World.update() stingray.World.update_animations_with_callback()

update_animations_with_callback ( self, delta_time, callback ) As update_animations(), but calls the callback function you provide during the animation player update.

Parameters

self :	stingray.World	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.
delta_time :	number	The time step that the world should use when updating.
callback :	fun(nil:nil)	A callback function that will be invoked. The fun(...) notation indicates that this is a function that accepts parameters of the types shown to the left of the colon :, and that returns the types shown to the right of the colon..

Returns

This function does not return any values.

This may be useful on the PlayStation 3, because the animation player update runs entirely on the SPUs, which frees the PPU to do other things. Thus, you can save precious milliseconds by putting some of your Lua updates in the callback function so that its code can be executed in parallel. Note that you must not create or destroy animations in the callback, since that would interfere with the update of the animation player.

update_scene ( self, delta_time ) Updates the physics and scene graphs in the world.

Parameters

self :	stingray.World	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.
delta_time :	number?	The time step that the world should use when updating. Optional; if not specified, the application's global time step will be used. 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.

Other related reference items

stingray.World.update()

Script data

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

Parameters

self :	stingray.World	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.
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 saved at the specified sequence of indices.

Similar to Unit.get_data().

Other related reference items

stingray.World.set_data()

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

Parameters

self :	stingray.World	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.
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().

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

Parameters

self :	stingray.World	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.
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().

Debugging

clear_permanent_lines ( self ) Clears any permanent debug lines that have been drawn into the world.

Parameters

self :

stingray.World

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.

Returns

This function does not return any values.

create_line_object ( self, disable_depth_test ) : stingray.LineObject Creates a new line object to be used for debug drawing.

Parameters

self :	stingray.World	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.
disable_depth_test :	boolean?	If true, lines will be drawn without depth test. Optional; default is false. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

stingray.LineObject

The newly created line object.

Other related reference items

	stingray.LineObject
	stingray.World.destroy_line_object()

debug_camera_pose ( self ) : stingray.Matrix4x4 Returns the position and orientation of the last camera that was used to render the world.

Parameters

self :

stingray.World

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.

Returns

stingray.Matrix4x4

The position and orientation of the camera.

Other related reference items

stingray.Actor.debug_draw()

destroy_line_object ( self, line ) Destroys a line object previously created by a call to create_line_object().

Parameters

self :	stingray.World	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.
line :	stingray.LineObject	The line object to be destroyed.

Returns

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.

num_particles ( self, effect_id, cloud_index ) : integer Returns the number of active particles in a world, a particle effect, or a cloud.

Parameters

self :	stingray.World	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.
effect_id :	integer?	The ID of the particle effect. Optional; if specified, the return value will give the number of particles in the specified particle effect only. The ? notation indicates that this type is optional: there may be zero or one instances of it.
cloud_index :	integer?	The index of a particle cloud. Optional; if specified, the return value will give the number of particles in the specified cloud only. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

integer

The number of active particles.

set_frustum_inspector_camera ( self, camera ) Passing in a camera to this function overrides the regular camera passed to Application.render_world(), after all culling has been performed.

Parameters

self :	stingray.World	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.
camera :	stingray.Camera	The override camera.

Returns

This function does not return any values.

This may be very useful for debugging problems related to culling.

GUI

create_screen_gui ( self, x, y, params ) : stingray.Gui Creates a new screen space Gui at pixel coordinates (x,y).

Parameters

self :	stingray.World	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.
x :	number?	The x coordinate of the screen space. Optional. The ? notation indicates that this type is optional: there may be zero or one instances of it.
y :	number?	The y coordinate of the screen space. Required if and only if x is specified. The ? notation indicates that this type is optional: there may be zero or one instances of it.
params :	any(string, number)*	Settings for the gui. The possible values are: "scale": Specifies the amount with which to scale the coordinates in gui. If you specify this parameter, you must follow it with two additional numbers that specify scale factors for the width and height respectively. With a scale of 2 an object that has size 100 pixels in the gui will be drawn with 200 pixels on the screen. "immediate": If specified, the gui will be run in immediate mode. This means that everything you place on the gui will be drawn for just one frame. You have to redraw the objects you want to see every frame. If not in immediate mode, objects remain until you explicitly remove them. "dock_right": Specifies that the gui should dock to the right margin when the window is resized. "dock_top": Specifies that the gui should dock to the top when the window is resized. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses. The * notation indicates that there may be zero or more instances of the specified type.

Returns

stingray.Gui

The newly created gui.

(0,0) is the bottom left corner of the screen.

Note that to find the size of the screen, you can call Application.back_buffer_size().

Related sample code

Appkit: /debug_scrollbox.lua Appkit: /world_wrapper.lua

Other related reference items

	stingray.Gui
	stingray.World.destroy_gui()

create_video_player ( self, resource, loop ) : stingray.VideoPlayer Creates a new VideoPlayer that plays the specified .IVF resource.

Parameters

self :	stingray.World	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.
resource :	string	The video resource to play.
loop :	boolean?	Determines whether or not the video loops. If true, the video will continue playing to the start when it reaches the end, otherwise it will freeze at the last frame. Optional; the default is true. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

stingray.VideoPlayer

The newly created video player.

The video player can be used with Gui video objects.

This function will return trigger a script error if the video player is not supported. To test if the video player is supported, use [has_video_player()].

Note: This video playing interface is under development. It should be considered temporary and currently only works on Windows platforms.

Other related reference items

	stingray.VideoPlayer
	stingray.World.destroy_video_player()

create_world_gui ( self, pose, width, height, params ) : stingray.Gui Creates a new Gui that lives in the 3D world.

Parameters

self :	stingray.World	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.
pose :	stingray.Matrix4x4	The position and orientation of the gui in 3D space.
width :	number	The ratio between Gui units and world space units along the X axis of the Gui's drawing plane. Increasing this value causes shapes drawn in the Gui to appear smaller than in world space, and vice-versa.
height :	number	The ratio between Gui units and world space units along the Y axis of the Gui's drawing plane. Increasing this value causes shapes drawn in the Gui to appear smaller than in world space, and vice-versa.
params :	string*	Settings for the gui. The possible values are: "shadow_caster": Specifies that the objects in the GUI should cast shadows. Note that for this to work, the objects must also be drawn with a shader that supports shadow casting, such as the base shader. "immediate": If specified, the gui will be run in immediate mode. This means that everything you place on the gui will be drawn for just one frame. You have to redraw the objects you want to see every frame. If not in immediate mode, objects remain until you explicitly remove them. The * notation indicates that there may be zero or more instances of the specified type.

Returns

stingray.Gui

The newly created gui.

Other related reference items

	stingray.Gui
	stingray.World.destroy_gui()

destroy_gui ( self, gui ) Destroys a gui created with create_screen_gui() or create_world_gui().

Parameters

self :	stingray.World	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.
gui :	stingray.Gui	The gui to remove from the world.

Returns

This function does not return any values.

destroy_video_player ( self, video_player ) Destroys the video player created by create_video_player().

Parameters

self :	stingray.World	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.
video_player :	stingray.VideoPlayer	The video player to remove.

Returns

This function does not return any values.

Video players consume a lot of resources, so you should destroy the video player as soon as you are done with it.

get_gui_by_id ( self, id ) : stingray.Gui Returns the Gui with that ID in the world.

Parameters

self :	stingray.World	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.
id :	integer	The id of the gui

Returns

stingray.Gui

The gui with that id.

Levels

destroy_level ( self, level ) Destroys the specified level and all units spawned by the level (or units placed in the level editor) when loaded.

Parameters

self :	stingray.World	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.
level :	stingray.Level	The name of the level you want to destroy.

Returns

This function does not return any values.

Take care to clean up the units spawned in Lua (or in the level flow editor) for these are not destroyed when the level is unloaded. You are not required to call this function, since all levels will be destroyed when the world ends. Nested levels cannot be destroyed using this function.

levels ( self ) : stingray.Level[] Returns all the levels in the world.

Parameters

self :

stingray.World

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.

Returns

stingray.Level[]

A table that contains all levels in the world. 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.

Note that the table returned by this function does not contain nested levels; use Level.nested_levels() to access those.

load_level ( self, name, position, rotation, scale ) : stingray.Level Loads the named level into the world at the specified position, rotation, and per-axis scale factors.

Parameters

self :	stingray.World	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.
name :	string	The name of the level you want to load.
position :	stingray.Vector3?	Optional; the position of the level. The ? notation indicates that this type is optional: there may be zero or one instances of it.
rotation :	stingray.Quaternion?	Optional; the rotation of the level. The ? notation indicates that this type is optional: there may be zero or one instances of it.
scale :	stingray.Vector3?	Optional; the per-axis scale factors of the level. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

stingray.Level

The loaded level in the world.

If position, rotation, scale are not supplied, the level will be loaded at the world origin with the default rotation and scale.

Other related reference items

stingray.World.load_level_with_object_sets()

load_level_with_object_sets ( self, name, obj_set_names, ignored_obj_set_names, position, rotation, scale ) : stingray.Level Identical to load_level(), but does not spawn any objects that are members of object sets unless explicitly told to do so.

Parameters

self :	stingray.World	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.
name :	string	The name of the level you want to load.
obj_set_names :	string[]	A table that contains the names of the object sets to spawn. 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.
ignored_obj_set_names :	string[]	A table that contains object set names that will be ignored. 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.
position :	stingray.Vector3?	Optional; the position of the level. The ? notation indicates that this type is optional: there may be zero or one instances of it.
rotation :	stingray.Quaternion?	Optional; the rotation of the level. The ? notation indicates that this type is optional: there may be zero or one instances of it.
scale :	stingray.Vector3?	Optional; the per-axis scale factors of the level. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

stingray.Level

The loaded level in the world.

Units, particle effects, sounds, triggers, prototypes and volumes can be added to object sets using the level editor. An object can belong to several object sets. An object will be spawned if any of these conditions is true:

• it is a member of any of the named object sets;
• it is not a member of any object set;
• all the object sets it is a member of are listed in the ignored_object_set_names parameter.

For performance reasons, prototypes and volumes do not take the ignored_object_set_names parameter into account. They are spawned only if they are members of any of the named object sets, or if they do not belong to any object set. This allows the engine to merge prototype and volume geometry into larger batches.

You can get a list of all object set names within a level resource by calling the LevelResource.object_set_names() function.

num_level ( self ) : integer Returns the number of levels in the world.

Parameters

self :

stingray.World

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.

Returns

integer

The total number of levels in the world.

Particles

are_particles_playing ( self, effect_id ) : boolean Indicates whether or not the particle effect with the specified ID is currently spawning particles.

Parameters

self :	stingray.World	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.
effect_id :	integer	The integer ID of the particle effect to test.

Returns

boolean

true if the particle effect is spawning particles, or false otherwise.

create_particles ( self, effect_name, position, rotation, scale ) : integer Creates a new particle effect with the specified name at the specified position, with the specified rotation and per-axis scale factor.

Parameters

self :	stingray.World	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.
effect_name :	string	The name of the particle effect to be created.
position :	stingray.Vector3	The position of the particle effect.
rotation :	stingray.Quaternion?	The orientation of the particle effect. Optional. The ? notation indicates that this type is optional: there may be zero or one instances of it.
scale :	stingray.Vector3?	The scaling factor of the particle effect. Optional. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

integer

An integer ID for the newly created particle effect.

destroy_particles ( self, effect_id ) Destroys the particle effect with the specified id.

Parameters

self :	stingray.World	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.
effect_id :	integer	The integer ID of the particle effect to be destroyed.

Returns

This function does not return any values.

find_particles_variable ( self, effect_name, variable_name ) : integer Finds the index of a particle effect variable with the specified name.

Parameters

self :	stingray.World	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.
effect_name :	string	The name of the particle effect whose index will be checked.
variable_name :	string	The name of the variable to find within the particle effect.

Returns

integer

The index of the specified variable within the particle effect.

link_particles ( self, effect_id, unit, object, pose, orphaned_policy ) Links the particle effect with the specified ID to the specified unit.

Parameters

self :	stingray.World	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.
effect_id :	integer	The integer ID of the particle effect to link.
unit :	stingray.Unit	The unit to which the particle effect will be linked.
object :	integer	The index of the target node in the unit's scene graph.
pose :	stingray.Matrix4x4	The new local coordinates of the particle system relative to object.
orphaned_policy :	string	Determines what happens to the particle effect if the unit is destroyed. May be any of the following values: "destroy": The effect is destroyed automatically when the unit is destroyed. "stop": The effect stops spawning particles, but remains in place. "unlink": The effect is unlinked from the destroyed unit, but remains at its current position and continues spawning particles.

Returns

This function does not return any values.

The effect is linked to the specified object within the unit's scene graph. Its new coordinates are determined by the pose argument, which should be expressed in the local coordinate system of the parent object.

move_particles ( self, effect_id, position, rotation, scale ) Moves the spawn point of the particle effect with the specified id to the given position and rotation, with the specified per-axis scale factor.

Parameters

self :	stingray.World	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.
effect_id :	integer	The integer ID of the particle effect to move.
position :	stingray.Vector3	The new position of the particle effect.
rotation :	stingray.Quaternion?	The new orientation of the particle effect. Optional. The ? notation indicates that this type is optional: there may be zero or one instances of it.
scale :	stingray.Vector3?	The new scaling factor of the particle effect. Optional. 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 existing particles are not affected.

set_particles_collision_filter ( self, collision_filter ) Sets the collision filter to use for particle collisions.

Parameters

self :	stingray.World	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.
collision_filter :	string	The collision filter to set.

Returns

This function does not return any values.

If an effect_id is specified, the collision filter is set for just that effect. Otherwise, the default collision_filter to be used for all particle effects is set.

set_particles_variable ( self, effect_id, variable_index, value ) Sets the value of the specified variable within a particle effect.

Parameters

self :	stingray.World	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.
effect_id :	integer	The ID of the particle effect.
variable_index :	integer	The index of the variable whose value will be set.
value :	stingray.Vector3	The value to set for the specified variable within the particle effect.

Returns

This function does not return any values.

stop_spawning_particles ( self, effect_id ) Stops the particle effect with the specified id from spawning.

Parameters

self :	stingray.World	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.
effect_id :	integer	The integer ID of the particle effect to stop.

Returns

This function does not return any values.

The effect will be destroyed when all the particles have been played out.

Physics

physics_world ( self ) : stingray.PhysicsWorld Retrieves the physics world maintained by the specified game world.

Parameters

self :

stingray.World

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.

Returns

stingray.PhysicsWorld

The physics world.

Related sample code

Picking a unit with the mouse

vector_field ( self, name ) : stingray.VectorField Retrieves the vector field with the specified name in the world.

Parameters

self :	stingray.World	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.
name :	string	The name of the vector field to retrieve, such as "wind".

Returns

stingray.VectorField

The retrieved vector field.

Other related reference items

stingray.VectorField

Shading environments

create_shading_environment ( self, name ) : stingray.ShadingEnvironment Creates a new ShadingEnvironment object with the specified name.

Parameters

self :	stingray.World	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.
name :	string	The name of the shading environment to be created.

Returns

stingray.ShadingEnvironment

The newly created shading environment.

Other related reference items

stingray.World.destroy_shading_environment()

destroy_shading_environment ( self, environment ) Destroys a shading environment previously created by a call to create_shading_environment().

Parameters

self :	stingray.World	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.
environment :	stingray.ShadingEnvironment	The shading environment to be destroyed.

Returns

This function does not return any values.

set_shading_environment ( self, environment, name ) Changes the ShadingEnvironment instance to point to shading environment data with the specified name.

Parameters

self :	stingray.World	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.
environment :	stingray.ShadingEnvironment	The shading environment to be changed.
name :	string	The name of the new shading environment data the environment should use.

Returns

This function does not return any values.

Units

destroy_unit ( self, unit ) Destroys a game unit that was previously created by a call to spawn_unit().

Parameters

self :	stingray.World	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.
unit :	stingray.Unit	The unit to be destroyed.

Returns

This function does not return any values.

link_unit ( self, child, child_node_index, parent, parent_node_index ) link_unit ( self, child, parent, parent_node_index ) Links a node in one unit to a node in another unit, creating a child-parent relationship.

Parameters

self :	stingray.World	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.Unit	The unit that will become the child.
child_node_index :	integer	The index of the node in the child that will be linked to the parent. Optional; if omitted, the root node of the child will be used.
parent :	stingray.Unit	The unit that will become the parent.
parent_node_index :	integer?	The index of the node in the parent that will be linked to the child. Optional; if omitted, the root node of the parent will be used. 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 this call, the child object will be a slave of the parent object. Any changes you make to the parent unit's position and rotation will also be applied to the child.

Calling this function automatically resets the local transform of the child node, so that it is positioned at the exact location of the parent node, with the same rotation, and the same scale. If you want to offset the child, you need to set its local position, rotation and scale after the call to link_unit().

You can call this function multiple times in order to link different nodes in the child unit to different nodes in the parent unit. This can be used, for instance, to link up a piece of clothing to multiple skin bones in the character that is wearing the clothing.

You cannot link one child unit to nodes in different parent units. A unit must have a single, well-defined parent unit. If a unit is already linked to a parent, you must first unlink it by calling unlink_unit() before linking it to a different parent unit.

Other related reference items

stingray.World.update_unit()

num_units ( self ) : integer Indicates the number of units that have been created in the specified world.

Parameters

self :

stingray.World

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.

Returns

integer

The number of units in the world.

This includes units that were placed into levels in the editor and spawned when the levels were loaded, and units that have been spawned dynamically on the fly.

spawn_unit ( self, unit_name, transform ) : stingray.Unit Spawns a new instance of a game unit at a specified location.

Parameters

self :	stingray.World	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.
unit_name :	string	The name of the unit to spawn.
transform :	stingray.Matrix4x4?	Optional. The starting position and orientation for the new unit. If omitted, the unit will be spawned at the default position (the origin of the 3D coordinate system), with a default rotation. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

stingray.Unit

The newly created Unit object.

spawn_unit ( self, unit_name, position, orientation ) : stingray.Unit Spawns a new instance of a game unit at a specified location.

Parameters

self :	stingray.World	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.
unit_name :	string	The name of the unit to spawn.
position :	stingray.Vector3?	Optional. The starting position for the new unit. If omitted, the unit will be spawned at the default position (the origin of the 3D coordinate system). The ? notation indicates that this type is optional: there may be zero or one instances of it.
orientation :	stingray.Quaternion?	The starting orientation for the new unit. If omitted, the unit will be spawned with a default rotation. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

stingray.Unit

The newly created Unit object.

Related sample code

Creating meshes procedurally

Other related reference items

stingray.Unit.name_hash() stingray.World.destroy_unit()

units ( self ) : stingray.Unit[] Retrieves all units in the specified world.

Parameters

self :

stingray.World

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.

Returns

stingray.Unit[]

A table that contains all Unit objects that exist in the world. 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.

This includes units that were placed into levels in the editor and spawned when the levels were loaded, and units that have been spawned dynamically on the fly.

units_by_resource ( self, resource_name ) : stingray.Unit[] Retrieves all unit instances of the specified resource in the world.

Parameters

self :	stingray.World	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.
resource_name :	string	The resource name of the units to look for.

Returns

stingray.Unit[]

A table that contains all Unit objects that exist in the world and that match the specified resource type. 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.

Related sample code

Oculus VR template: /project.lua Steam VR template: /project.lua

unit_by_id ( self, id ) : stingray.Unit? Finds the unit with the id id (as defined by the Level Editor) and returns it.

Parameters

self :	stingray.World	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.
id :	string	The id of the unit to look for.

Returns

stingray.Unit?

A unit with the specified id, or nil if no unit exists with that id. The ? notation indicates that this type is optional: there may be zero or one instances of it.

If no such unit exists, nil is returned.

unit_by_name ( self, name ) : stingray.Unit? Finds the unit with the name name (as set in the Level Editor) and returns it.

Parameters

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

Returns

stingray.Unit?

A unit with the specified name, or nil if no unit exists with that name. The ? notation indicates that this type is optional: there may be zero or one instances of it.

If no such unit exists, nil is returned. If there are multiple units with the same name, a random one will be returned.

unlink_unit ( self, child ) Unlinks the specified unit from its parent, if any.

Parameters

self :	stingray.World	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.Unit	The unit that will be unlinked from its parent.

Returns

This function does not return any values.

All the linked nodes in the child are unlinked, and their local positions are reset to match their current world positions. Therefore, unlinked objects will remain where they currently are, unless you move them after they are unlinked.

Note that if you linked an object other than the root node, unlinking the unit will not relink that object back to its previous parent in the unit's scene graph. You must explicitly call Unit.scene_graph_link() to do that.

Other related reference items

stingray.World.link_unit()

update_unit ( self, unit ) Forces an update of a unit's scene graph after the main world update has been performed.

Parameters

self :	stingray.World	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.
unit :	stingray.Unit	The unit to be updated.

Returns

This function does not return any values.

This can be used to implement units that are dependent on other units positions in complicated ways that cannot be expressed solely by linking units through calls to link_unit().

It is recommended that you use this approach sparingly.

Note that update_unit() does not automatically update linked child units. You have to call update_unit() on each child unit manually, if you want their positions to be updated to reflect the new position of the parent.

Related sample code

Vehicle template: /vehicle_follow_cam.lua Vehicle template: /vehicle_unit_controller.lua