stingray.Light object reference

Description

Describes a game light.

Constructors and accessors

stingray.Unit.light()

Other related reference items

	stingray.Unit.set_light_material()
	Units

Related help topics

	Building Levels > Organize level objects in categories
	Lighting and Rendering > Lighting > Light sources > Create a light source
	Lighting and Rendering > Lighting > Light sources > Change light source properties

Functions

baked ( self ) : boolean Indicates whether or not the light is tagged for baking and should be excluded when doing realtime lighting

Parameters

self :

stingray.Light

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

boolean

Returns true if the light is tagged for baking, and false otherwise.

casts_shadows ( self ) : boolean Indicates whether or not the light casts shadows.

Parameters

self :

stingray.Light

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

boolean

Returns true if the light casts shadows, and false otherwise.

color ( self ) : stingray.Vector3 Retrieves the color of the light.

Parameters

self :

stingray.Light

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

The color of the light. The values for the X, Y and Z axes indicate the red, green, and blue color channels respectively; each is a value in linear space between 0 and 1.

falloff_end ( self ) : number Retrieves the distance at which the light has reached zero intensity.

Parameters

self :

stingray.Light

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

number

The distance at which the light has reached zero intensity.

falloff_start ( self ) : number Retrieves the distance at which the light starts to fall off: i.e., to lose its intensity.

Parameters

self :

stingray.Light

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

number

The distance at which the light starts to lose its intensity.

intensity ( self ) : number Retrieves the intensity of the light.

Parameters

self :

stingray.Light

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

number

The intensity of the light.

set_baked ( self, enabled ) Determines whether this light should contribute to the realtime rendering path

Parameters

self :	stingray.Light	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
enabled :	boolean	Use true to remove light from realtime rendering path.

Returns

This function does not return any values.

set_casts_shadows ( self, enabled ) Determines whether or not the light casts shadows.

Parameters

self :	stingray.Light	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
enabled :	boolean	Use true to enable shadow casting, or false to disable.

Returns

This function does not return any values.

set_color ( self, color ) Sets the color of the light.

Parameters

self :	stingray.Light	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.
color :	stingray.Vector3	The color to set for the light. The values for the X, Y and Z axes indicate the red, green, and blue color channels respectively; each should be a value in linear space between 0 and 1.

Returns

This function does not return any values.

set_data ( unit, src, dst ) Sets the data of one light to another light in the unit.

Parameters

unit :	stingray.Unit	The game unit that the destination light is part of.
src :	stingray.Light	The source light whose data is copied over.
dst :	stingray.Light	The destination light that will receive the data.

Returns

This function does not return any values.

set_enabled ( self, enabled ) Turns the light on or off.

Parameters

self :	stingray.Light	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
enabled :	boolean	Use true to enable the light, or false to disable.

Returns

This function does not return any values.

set_falloff_end ( self, distance ) Sets the distance at which the light should reach zero intensity.

Parameters

self :	stingray.Light	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.
distance :	number	The distance at which the light should reach zero intensity.

Returns

This function does not return any values.

set_falloff_start ( self, distance ) Sets the distance at which the light start to fall off: i.e., to lose its intensity.

Parameters

self :	stingray.Light	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.
distance :	number	The distance at which the light should start to lose its intensity.

Returns

This function does not return any values.

set_intensity ( self, intensity ) Sets the intensity of the light.

Parameters

self :	stingray.Light	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.
intensity :	number	The intensity to set for the light.

Returns

This function does not return any values.

set_shadow_depth_bias ( self, value ) Sets the shadow depth bias value to use when rendering shadow maps (0-1 range).

Parameters

self :	stingray.Light	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.
value :	number	Shadow depth bias value to use when rendering shadow maps (0-1 range).

Returns

This function does not return any values.

A too low value causes shadow acne, a too high value causes peter panning.

set_spot_angle_end ( self, spot_angle_end ) Sets the cone angle at which the light has reached zero intensity.

Parameters

self :	stingray.Light	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.
spot_angle_end :	number	The new cone angle, in radians.

Returns

This function does not return any values.

Valid only for spot lights.

set_spot_angle_start ( self, spot_angle_start ) Sets the cone angle at which the light starts to fall off.

Parameters

self :	stingray.Light	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.
spot_angle_start :	number	The new cone angle, in radians.

Returns

This function does not return any values.

Valid only for spot lights.

set_type ( self, type ) Sets the type of the light source.

Parameters

self :	stingray.Light	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.
type :	string	The type of the light source. Valid input values are: omni: Radiates light in all directions. spot: A focused beam of light from a single point source. box: Radiates light from a single inner face of a box volume. directional: Parallel light rays.

Returns

This function does not return any values.

shadow_depth_bias ( self ) : number Retrieves the user controlled shadow depth bias value (0-1 range).

Parameters

self :

stingray.Light

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

number

Returns user specified shadow depth bias (0-1 range).

A too low value causes shadow acne, a too high value causes peter panning.

spot_angle_end ( self ) : number Retrieves the cone angle at which the light has reached zero intensity.

Parameters

self :

stingray.Light

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

number

The cone angle, in radians.

Valid only for spot lights.

spot_angle_start ( self ) : number Retrieves the cone angle at which the light starts to fall off.

Parameters

self :

stingray.Light

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

number

The cone angle, in radians.

Valid only for spot lights.

type ( self ) : string Retrieves the type of the light source.

Parameters

self :

stingray.Light

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

string

The type of the light source. Can be any of :omni, spot, box or directional.

Scene placement

The functions in this group control the placement of an object of this type in the scene.

local_pose ( self ) : stingray.Matrix4x4 Returns the position and orientation of the specified scene graph object in local space: i.e. relative to its parent in the scene graph.

Parameters

self :

stingray.Light

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 position and orientation of the object in local space.

local_position ( self ) : stingray.Vector3 Returns the position of the specified scene graph object in local space: i.e. relative to its parent in the scene graph.

Parameters

self :

stingray.Light

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

The position of the object in local space.

local_rotation ( self ) : stingray.Quaternion Returns the orientation of the specified scene graph object in local space: i.e. relative to its parent in the scene graph.

Parameters

self :

stingray.Light

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

The rotation of the object in local space.

node ( self ) : integer Returns the ID of the specified object within the scene graph.

Parameters

self :

stingray.Light

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 ID of the specified object in the scene graph.

set_local_pose ( self, parent, pose ) Sets the position and orientation of the specified scene graph object in local space: i.e. relative to its parent in the scene graph.

Parameters

self :	stingray.Light	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.
parent :	stingray.Unit	The parent Unit that owns this object.
pose :	stingray.Matrix4x4	The new position and orientation for the object in local space.

Returns

This function does not return any values.

set_local_position ( self, parent, position ) Sets the position of the specified scene graph object in local space: i.e. relative to its parent in the scene graph.

Parameters

self :	stingray.Light	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.
parent :	stingray.Unit	The parent Unit that owns this object.
position :	stingray.Vector3	The new position for the object in local space.

Returns

This function does not return any values.

set_local_rotation ( self, parent, rotation ) Sets the orientation of the specified scene graph object in local space: i.e. relative to its parent in the scene graph.

Parameters

self :	stingray.Light	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.
parent :	stingray.Unit	The parent Unit that owns this object.
rotation :	stingray.Quaternion	The new rotation for the object in local space.

Returns

This function does not return any values.

world_pose ( self ) : stingray.Matrix4x4 Returns the position and orientation of the specified scene graph object in world space.

Parameters

self :

stingray.Light

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 position and orientation of the object in world space.

world_position ( self ) : stingray.Vector3 Returns the position of the specified scene graph object in world space.

Parameters

self :

stingray.Light

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

The position of the object in world space.

world_rotation ( self ) : stingray.Quaternion Returns the rotation of the specified scene graph object in world space.

Parameters

self :

stingray.Light

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

The rotation of the object in world space.