Script bindings: Scenes and movies¶

Verified against: SLUS_212.15 (NTSC-U, SHA1 e9cb2cc49aa046b9e494313dce2f5038ed17b2f4).

Bindings for in-engine cutscenes and full-motion movies: 16 in all. Conventions, the other categories and how to read an entry are on the masterlist.

Binding	Returns	Scripts	Boot	Mission 1	Evidence
`PlayMovie`	-	1	yes	no	confirmed (code)
`SceneAddObject`	-	9	yes	yes	confirmed (code)
`SceneDone`	boolean	0	no	no	confirmed (code)
`SceneInvoke`	boolean	0	no	no	confirmed (code)
`SceneInvokeInPlace`	boolean	0	no	no	confirmed (code)
`SceneIsPreloaded`	boolean	3	yes	no	confirmed (code)
`SceneLength`	number	0	no	no	confirmed (code)
`ScenePlay`	boolean	1	no	no	confirmed (code)
`ScenePlayAnimation`	boolean	2	yes	yes	confirmed (code)
`ScenePlayCinematic`	boolean	9	yes	yes	confirmed (code)
`ScenePlayFixedScene`	boolean	4	yes	yes	confirmed (code)
`ScenePreload`	number	110	yes	yes	confirmed (code)
`SceneSetCallback`	-	6	no	no	confirmed (code)
`SceneStop`	-	53	yes	no	confirmed (code)
`SceneTerminate`	-	1	no	no	confirmed (code)
`SceneUnload`	-	8	yes	no	confirmed (code)

PlayMovie¶

PlayMovie(name, skippable)

#	Argument	Read as	Meaning
1	`name`	string	Movie name, the file `PSS/<name>.BIK` (level100 passes `TRAILER` or `L1_IN`; the 16 movies are on Movies).
2	`skippable`	boolean (nil or 0 is false); default true	Whether any pad button ends the movie early (Movies); default true.

Returns nothing.

Plays a full-screen Bink movie and returns when it ends or is skipped. Around it the music and sounds are stopped and the screen blacked; when the loaded level's Subtitles chunk has captions for <name>_sub, the scene <name>_sub.scn times them and they show if the subtitle option is on. The front end uses it for the trailer (EXTRAS) and the attract movie.

Notes. The wrapper reads the flag as a number, default 1, and passes flag != 0. The movie player (0x0042a938) stops the music and sounds first; it looks for <name>_sub.scn only when a level's Subtitles chunk is loaded (the global 0x0050ea74; the subtitle option is read when drawing). On return it sets both screen-effects managers fully black, so the screen stays black until a fade in (Front end). The C++ code calls Movie_Play itself for the boot movies (LOGO cannot be skipped) and the levels' intro and outro movies. Nothing else in the game runs while a movie plays.

Evidence: confirmed (code) at 0x0042a938; detail: traced
Wrapper 0x0036c258 (registered by RegisterBindings); calls 0x0042a938 Movie_Play
Used by 1 of 467 script chunks (1 reference); boot to menu: yes; mission 1: no; result used: no
Coney: partial

SceneAddObject¶

SceneAddObject(scene, object, slot)

#	Argument	Read as	Meaning
1	`scene`	number, truncated to an unsigned integer	Scene id.
2	`object`	number, truncated to an unsigned integer	Handle of the world object (or human) the scene should animate.
3	`slot`	number, truncated to an unsigned integer	The scene's object slot, from 0; ignored when the scene has fewer slots.

Returns nothing.

Binds a world object to one of a scene's object slots, so the scene moves that object when it plays.

Evidence: confirmed (code) at 0x00354280; detail: traced
Wrapper 0x00367f48 (registered by RegisterBindings); calls 0x00354280 Scene_BindObject
Used by 9 of 467 script chunks (12 references); boot to menu: yes; mission 1: yes; result used: no
Later in the story: 26 of 28 levels, first level80 (mission 2)
Coney: implemented

SceneDone¶

SceneDone(scene) -> boolean

#	Argument	Read as	Meaning
1	`scene`	number, truncated to an unsigned integer	Scene id.

Returns boolean (1 for true, nil for false): nil while that scene is starting or playing, else true (1), including when it is not loaded.

Reports whether a scene has finished. No script calls it.

Evidence: confirmed (code) at 0x00354058; detail: brief
Wrapper 0x00367e80 (registered by RegisterBindings); calls 0x00354058
Used by no script on the disc
Coney: implemented

SceneInvoke¶

SceneInvoke(scene, pos, rot, delay, onEnd, flag) -> boolean

#	Argument	Read as	Meaning
1	`scene`	number, truncated to an unsigned integer	Scene id.
2	`pos`	table of 3 numbers (t[1]..t[3])	World position {x, y, z}.
3	`rot`	table of 4 numbers (t[1]..t[4])	Orientation quaternion {i, j, k, r}.
4	`delay`	number, truncated to an unsigned integer	Delay before it starts.
5	`onEnd`	string	Name of the Lua function called when it ends.
6	`flag`	boolean (nil or 0 is false)	A flag passed to the scene player.

Returns boolean (1 for true, nil for false): true (1) when the scene started.

Starts a scene at a given position and orientation. No script calls it.

Evidence: confirmed (code) at 0x00354bb8; detail: brief
Wrapper 0x00368078 (registered by RegisterBindings); calls 0x00354bb8
Used by no script on the disc
Coney: not implemented

SceneInvokeInPlace¶

SceneInvokeInPlace(scene, onEnd, flag) -> boolean

#	Argument	Read as	Meaning
1	`scene`	number, truncated to an unsigned integer	Scene id.
2	`onEnd`	string	Name of the Lua function called when it ends.
3	`flag`	boolean (nil or 0 is false)	A flag passed to the scene player.

Returns boolean (1 for true, nil for false): true (1) when the scene started.

Starts a scene where it is, through the scene player with no delay. No script calls it.

Evidence: confirmed (code) at 0x00354c00; detail: brief
Wrapper 0x00367fe8 (registered by RegisterBindings); calls 0x00354c00
Used by no script on the disc
Coney: not implemented

SceneIsPreloaded¶

SceneIsPreloaded(name) -> boolean

#	Argument	Read as	Meaning
1	`name`	string	Scene name.

Returns boolean (1 for true, nil for false): true (1) when a slot holds that scene fully loaded and idle, else nil.

Reports whether a scene has finished loading.

Evidence: confirmed (code) at 0x00354178; detail: traced
Wrapper 0x003674d0 (registered by RegisterBindings); calls 0x00354178
Used by 3 of 467 script chunks (6 references); boot to menu: yes; mission 1: no; result used: yes
Later in the story: 1 of 28 levels, first level87 (mission 3)
Coney: implemented

SceneLength¶

SceneLength(scene) -> number

#	Argument	Read as	Meaning
1	`scene`	number, truncated to an unsigned integer	Scene id.

Returns number: The first part's length in milliseconds (its first track's duration), not the whole of a scene with segments; 0 when it has no tracks.

Returns a scene's length. No script calls it.

Evidence: confirmed (code) at 0x003540b8; detail: brief
Wrapper 0x00367ed0 (registered by RegisterBindings); calls 0x003540b8
Used by no script on the disc
Coney: implemented

ScenePlay¶

ScenePlay(scene, pos, heading, delay, onEnd, looping, freeze, blendCam) -> boolean

#	Argument	Read as	Meaning
1	`scene`	number, truncated to an unsigned integer	Scene id from ScenePreload; a scene not yet loaded is requested and waited for on the spot.
2	`pos`	table of 3 numbers (t[1]..t[3])	World position `{x, y, z}` in metres the scene's origin is placed at; written back.
3	`heading`	number (single precision)	Rotation of the scene about the vertical in radians (a quaternion about `(0, 0, -1)`, 0x00335ea0). Was listed as degrees.
4	`delay`	number, truncated to an unsigned integer	The longest the start waits for the bound humans to reach their marks, delay × 60 scene updates, as in ScenePlayCinematic; 0 does not wait.
5	`onEnd`	string	Name of the Lua function called with the scene id when it ends, or nil.
6	`looping`	boolean (nil or 0 is false)	true loops the scene (task `+0xeb`).
7	`freeze`	boolean (nil or 0 is false); default true	true (the default) suspends every brain while it plays (task `+0xef`).
8	`blendCam`	number (single precision)	Camera blend time in seconds when the scene hands the camera back (task `+0x94`).

Returns boolean (1 for true, nil for false): true (1) when the scene task was created and started; false when the scene could not be loaded or no task was free.

Plays a loaded scene placed at a given world position and orientation instead of the world origin (Scenes: playing). It is not a cinematic: no letterbox, preload or player hand-over, and it cannot be skipped; only the looping and freeze flags are set (bars, skippable, final and chain are 0).

Notes. Flag mapping confirmed (code) through 0x00353e70 / 0x00353e38 into Scene_Play and the task constructor 0x003a13d0.

Overload (registered first; the wrapper above checks its argument types and calls this one when they do not match): The quaternion form is used when argument 3 is a table; the heading form's type check fails then and it falls back to this one.

ScenePlay(scene, pos, rot, delay, onEnd, looping, freeze, blendCam) -> boolean

#	Argument	Read as	Meaning
1	`scene`	number, truncated to an unsigned integer	Scene id.
2	`pos`	table of 3 numbers (t[1]..t[3])	World position {x, y, z}.
3	`rot`	table of 4 numbers (t[1]..t[4])	Orientation as a quaternion {i, j, k, r}.
4	`delay`	number, truncated to an unsigned integer	As above.
5	`onEnd`	string	Name of the Lua function called when it ends.
6	`looping`	boolean (nil or 0 is false)	true loops the scene.
7	`freeze`	boolean (nil or 0 is false); default true	true (the default) suspends every brain while it plays.
8	`blendCam`	number (single precision)	Camera blend time in seconds.

Returns boolean (1 for true, nil for false): true (1) when the scene started.

Wrapper 0x00367810; calls 0x00353e38.

Evidence: confirmed (code) at 0x00353e70, 0x00335ea0, 0x00353818, 0x003a13d0; detail: traced
Wrapper 0x00367a20 (registered by RegisterBindings); calls 0x00353e70, 0x00335ea0, 0x00353818 Scene_Play, 0x003a13d0
Used by 1 of 467 script chunks (1 reference); boot to menu: no; mission 1: no; result used: no
Later in the story: 1 of 28 levels, first level14 (mission 12)
Coney: implemented

ScenePlayAnimation¶

ScenePlayAnimation(scene, onEnd, looping, flag, delay, flag2, freeze, blendCam) -> boolean

#	Argument	Read as	Meaning
1	`scene`	number, truncated to an unsigned integer	Scene id from ScenePreload.
2	`onEnd`	string	Name of the Lua function called when it ends.
3	`looping`	boolean (nil or 0 is false)	true loops it.
4	`flag`	boolean (nil or 0 is false)	A flag (global.lua passes false).
5	`delay`	number, truncated to an unsigned integer	Delay before it starts.
6	`flag2`	boolean (nil or 0 is false)	A flag (global.lua passes false).
7	`freeze`	boolean (nil or 0 is false)	true freezes the world while it plays.
8	`blendCam`	number (single precision)	Camera blend time (inferred).

Returns boolean (1 for true, nil for false): true (1) when the scene started.

Plays a loaded scene as an animation only (no position or orientation override), for global.lua's scene helpers.

Evidence: confirmed (code) at 0x00353f40; detail: traced
Wrapper 0x00367cd8 (registered by RegisterBindings); calls 0x00353f40 Scene_PlayAnimation
Used by 2 of 467 script chunks (2 references); boot to menu: yes; mission 1: yes; result used: no
Later in the story: 26 of 28 levels, first level80 (mission 2)
Coney: implemented

ScenePlayCinematic¶

ScenePlayCinematic(scene, delay, onEnd, bars, skippable, looping, freeze, blendCam, final, chain) -> boolean

#	Argument	Read as	Meaning
1	`scene`	number, truncated to an unsigned integer	Scene id from ScenePreload.
2	`delay`	number, truncated to an unsigned integer	The longest the start waits for the bound humans to walk to their marks: delay × 60 scene updates (30 a second). 0 (global.lua's default) does not wait.
3	`onEnd`	string	Name of the Lua function called with the scene id when the scene ends, or nil.
4	`bars`	boolean (nil or 0 is false)	true makes it a full cinematic: letterbox in and out over 1.5 s, the world preloaded around the scene camera, the player handed back at the end. false plays the tracks only.
5	`skippable`	boolean (nil or 0 is false)	true lets cross or START skip it after 2 s (global.lua passes `not NoSkip`); also sets the flag 0x00510174.
6	`looping`	boolean (nil or 0 is false)	true loops the scene (from a loop-point event when it has one).
7	`freeze`	boolean (nil or 0 is false); default true	true suspends every brain while it plays and resumes them all after. Defaults to true only when omitted; an explicit nil is false, which is what global.lua passes.
8	`blendCam`	number (single precision)	Seconds of camera blend when the scene camera hands back (0 or below is a cut); after a skip, also the fade-in time when above 0.
9	`final`	boolean (nil or 0 is false)	true skips preloading `<scene>_end.pak` around the camera at the end (global.lua passes the scene table's Final).
10	`chain`	boolean (nil or 0 is false)	true letterboxes in at once and keeps a START skip going into this scene; false clears it (global.lua passes the scene table's Chain).

Returns boolean (1 for true, nil for false): true (1) when the scene started, nil when it could not.

Plays a loaded scene as a cinematic at its authored position, taking over the camera and optionally the player's control until it ends or is skipped.

Notes. Plays at the world origin with no rotation, so the record's coordinates are world coordinates. Task flags +0xed bars, +0xe5 skippable, +0xeb looping, +0xef freeze, +0xe7 final, +0xe8 chain, BlendCam at +0x94 (0x003a13d0, 0x00353818). Research: docs/research/scenes.md#playing.

Evidence: confirmed (code) at 0x00353c68; detail: traced
Wrapper 0x00367580 (registered by RegisterBindings); calls 0x00353c68 Scene_PlayCinematic
Used by 9 of 467 script chunks (14 references); boot to menu: yes; mission 1: yes; result used: no
Later in the story: 26 of 28 levels, first level80 (mission 2)
Coney: implemented

ScenePlayFixedScene¶

ScenePlayFixedScene(scene, delay, onEnd, looping, freeze, blendCam) -> boolean

#	Argument	Read as	Meaning
1	`scene`	number, truncated to an unsigned integer	Scene id from ScenePreload.
2	`delay`	number, truncated to an unsigned integer	Delay before it starts (scripts pass 0).
3	`onEnd`	string	Name of the Lua function called when it ends, or nil (level99 passes 0).
4	`looping`	boolean (nil or 0 is false)	true loops it.
5	`freeze`	boolean (nil or 0 is false)	true freezes the world while it plays.
6	`blendCam`	number (single precision)	Camera blend time (seconds, inferred).

Returns boolean (1 for true, nil for false): true (1) when the scene started.

Plays a loaded scene at its authored position without the cinematic extras (no letterbox, preload or player hand-over). level99 runs its Wonder Wheel with it (WonderWheel_99, 29 objects, looping, not frozen); global.lua's helpers use it for scene tables whose Animation field is a value other than 1.

Evidence: confirmed (code) at 0x00353d60; detail: traced
Wrapper 0x00367708 (registered by RegisterBindings); calls 0x00353d60 Scene_PlayFixed
Used by 4 of 467 script chunks (4 references); boot to menu: yes; mission 1: yes; result used: no
Later in the story: 26 of 28 levels, first level80 (mission 2)
Coney: implemented

ScenePreload¶

ScenePreload(name, onLoaded) -> number

#	Argument	Read as	Meaning
1	`name`	string	Scene name (for example `l11_c2`); the first record of `scene_list.cnk` whose name contains it is loaded.
2	`onLoaded`	string	Optional name of a Lua function called with the scene id when the scene has loaded (0x003531c8).

Returns number: The scene's id (its index in the global scene list scene_list.cnk, Scenes and movies), used by the other Scene bindings. An unknown name gives 0, the first scene.

Starts loading a scripted scene (in-engine cutscene or animation set) into one of 12 scene slots and returns its id; a scene already loaded or loading is not loaded again.

Notes. Scene table at 0x006eba10 (0x18-byte entries, count at 0x00512aec); slots at 0x006eba18 (0x40 bytes each). A slot is unloaded when its scene has played (0x00353bf0), so a scene is preloaded again before its next play. Research: docs/research/scenes.md#loading.

Evidence: confirmed (code) at 0x00353f88; detail: traced
Wrapper 0x00367448 (registered by RegisterBindings); calls 0x00353f88 Scene_Preload
Used by 110 of 467 script chunks (256 references); boot to menu: yes; mission 1: yes; result used: yes
Later in the story: 26 of 28 levels, first level80 (mission 2)
Coney: implemented

SceneSetCallback¶

SceneSetCallback(name)

#	Argument	Read as	Meaning
1	`name`	string	Name of a Lua function; nil or an empty string clears it.

Returns nothing.

Sets a global scene callback name (interned, at 0x00512af4) that every scene calls, with no arguments, at the moment it actually starts (used for bus and chase set-ups and the credits).

Notes. Called from the scene start 0x0039d870 once everything is loaded, before the camera and tracks start.

Evidence: confirmed (code) at 0x00354710; detail: traced
Wrapper 0x00367550 (registered by RegisterBindings); calls 0x00354710
Used by 6 of 467 script chunks (14 references); boot to menu: no; mission 1: no; result used: no
Later in the story: 3 of 28 levels, first level93 (mission 10)
Coney: implemented

SceneStop¶

SceneStop(scene, force)

#	Argument	Read as	Meaning
1	`scene`	number, truncated to an unsigned integer	Scene id.
2	`force`	boolean (nil or 0 is false); default false	true ends it at once; false does too, except on a looping scene with a loop point (event 29), which only stops looping and ends after the current pass.

Returns nothing.

Stops a playing scene (state 4 or 5); nothing happens when it is not playing.

Notes. A starting scene goes to its end at once; a playing one has its roles' clips ended (0x003a0a68) and then ends as usual (docs/research/scenes.md#ending). The non-forced path on a looping scene is 0x003a0be8.

Evidence: confirmed (code) at 0x00354038; detail: traced
Wrapper 0x00367e20 (registered by RegisterBindings); calls 0x00354038 Scene_Stop
Used by 53 of 467 script chunks (62 references); boot to menu: yes; mission 1: no; result used: no
Later in the story: 12 of 28 levels, first level87 (mission 3)
Coney: implemented

SceneTerminate¶

SceneTerminate(scene)

#	Argument	Read as	Meaning
1	`scene`	number, truncated to an unsigned integer	Scene id (as given to `ScenePlay`).

Returns nothing.

Stops a scene without forcing it, exactly SceneStop(scene, false) (Scene_Stop 0x00353a10): a starting scene ends at once, a playing one with roles has its clips ended (waiting while a role is in a paired move), and a looping one only stops looping and ends after its current pass. Once ended the scene's humans are released and its slot unloaded.

Notes. States and unloading: Scenes.

Evidence: confirmed (code) at 0x00354c48; detail: traced
Wrapper 0x00368240 (registered by RegisterBindings); calls 0x00354c48 Scene_Terminate
Used by 1 of 467 script chunks (1 reference); boot to menu: no; mission 1: no; result used: no
Later in the story: 1 of 28 levels, first level80 (mission 2)
Coney: implemented

SceneUnload¶

SceneUnload(scene)

#	Argument	Read as	Meaning
1	`scene`	number, truncated to an unsigned integer	Scene id from ScenePreload.

Returns nothing.

Frees a loaded scene's slot, but only while the scene is loaded and not playing.

Evidence: confirmed (code) at 0x00353fc8; detail: traced
Wrapper 0x00367518 (registered by RegisterBindings); calls 0x00353fc8
Used by 8 of 467 script chunks (9 references); boot to menu: yes; mission 1: no; result used: no
Later in the story: 4 of 28 levels, first level87 (mission 3)
Coney: implemented