stingray.StoryTeller object reference

Description

A class that can play stories, or cutscenes.

Each game world maintains its own StoryTeller object, which you can retrieve by calling World.storyteller().

Note that in addition to playing stories from the Lua StoryTeller object, you can also play stories from flow.

Constructors and accessors

stingray.World.storyteller()

Other related reference items

	stingray.World.storyteller()
	Core

Related help topics

Cinematics > Story Editor

Functions

end_time ( self, id ) : number Returns the global end time of the playing story with the specified ID.

Parameters

self :	stingray.StoryTeller	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 Object lifetimes and userdata binding, or this page in the Lua documentation.
id :	integer	The ID of the story whose end time you want to retrieve.

Returns

number

The global end time of the story.

is_playing ( self, id ) : boolean Indicates whether or not the specified story is playing.

Parameters

self :	stingray.StoryTeller	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 Object lifetimes and userdata binding, or this page in the Lua documentation.
id :	integer	The ID of the story to test.

Returns

boolean

Returns true if the story is playing, or false otherwise.

length ( self, id ) : number Retrieves the length of the specified story.

Parameters

self :	stingray.StoryTeller	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 Object lifetimes and userdata binding, or this page in the Lua documentation.
id :	integer	The ID of the story.

Returns

number

The length of the story.

play_level_story ( self, level, name ) : integer Starts playing the specified story from the specified level.

Parameters

self :	stingray.StoryTeller	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 Object lifetimes and userdata binding, or this page in the Lua documentation.
level :	stingray.Level	The level that contains the story to play.
name :	string	The name of the story to play.

Returns

integer

An ID for the playing story that you can use to control playback.

set_loop_mode ( self, id, mode ) Determines what should happen when the story reaches its end, or the end of the loop range.

Parameters

self :	stingray.StoryTeller	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 Object lifetimes and userdata binding, or this page in the Lua documentation.
id :	integer	The ID of the story.
mode :	integer	The new loop mode to set for the story. Can be any loop mode value.

Returns

This function does not return any values.

By default, stories loop over the entire range of the story.

set_loop_range ( self, id, start, stop ) Sets the start and stop times that mark the range the story should loop over.

Parameters

self :	stingray.StoryTeller	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 Object lifetimes and userdata binding, or this page in the Lua documentation.
id :	integer	The ID of the story to set up.
start :	integer	The start time of the new loop range.
stop :	integer	The end time of the new loop range.

Returns

This function does not return any values.

set_speed ( self, id, speed ) Sets the speed at which the story will be played back.

Parameters

self :	stingray.StoryTeller	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 Object lifetimes and userdata binding, or this page in the Lua documentation.
id :	integer	The ID of the story whose speed you want to set.
speed :	number	The speed at which to play the story, expressed as a multiplier of the normal speed.

Returns

This function does not return any values.

The default is 1.0, which means the story plays at normal speed. A value of 0.5 would play the story at half speed.

If you want complete manual control over how the time in the story is advanced, set the speed to 0.0 and use set_time() to manually advance the time in the story.

set_time ( self, id, time ) Sets the current time in the playing story with the specified ID.

Parameters

self :	stingray.StoryTeller	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 Object lifetimes and userdata binding, or this page in the Lua documentation.
id :	integer	The ID of the story whose time you want to set.
time :	number	The new time within the story.

Returns

This function does not return any values.

Other related reference items

stingray.StoryTeller.set_speed()

start_time ( self, id ) : number Returns the global start time of the playing story with the specified ID.

Parameters

self :	stingray.StoryTeller	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 Object lifetimes and userdata binding, or this page in the Lua documentation.
id :	integer	The ID of the story whose start time you want to retrieve.

Returns

number

The global start time of the story.

stop ( self, id ) Stops playing the specified story.

Parameters

self :	stingray.StoryTeller	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 Object lifetimes and userdata binding, or this page in the Lua documentation.
id :	integer	The ID of the story you want to stop.

Returns

This function does not return any values.

time ( self, id ) : number Returns the current elapsed time in the playing story with the specified ID.

Parameters

self :	stingray.StoryTeller	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 Object lifetimes and userdata binding, or this page in the Lua documentation.
id :	integer	The ID of the story whose time you want to retrieve.

Returns

number

The current time within the story.

Loop modes

The constants in this group refer to the different ways that the StoryTeller can handle reaching the end of a story or the end of a loop range.

LOOP : integer When the story reaches the end, it will loop back to the beginning and continue playing.

This is the default mode.

NONE : integer When the story reaches the end, it will stop playing.

It will not loop back to the beginning.

PING_PONG : integer When the story reaches the end, it will continue to play the story backward until it reaches the beginning, then continue forward again.