Lua Cutscenes

• Index

Contents

• Functions

Modules

• example_cutscene
• example_talker
• helper_functions

Module helper_functions

Helper functions that can be used in cutscenes.

Please do not edit this file to add your own helper functions, put them in your own cutscenes. Optionally load them with `loadCelesteAsset` and put it in a common library. When using from a cutscene "helpers." is not required. For example "helpers.say" will be just "say". Return values starting with # are from C#.

Functions

helpers.setClassNamePrefix (prefix)	Set the prefix for getting Celeste classes.
helpers.getClassNamePrefix ()	Get the prefix for getting Celeste classes.
helpers.readCelesteAsset (filename)	Get the content of a file from a Celeste asset.
helpers.loadCelesteAsset (filename)	Loads and returns the result of a Lua asset.
helpers.log (message[, tag="Lua Cutscenes"])	Put debug message in the Celeste console.
helpers.getEnum (enum, value)	Gets enum value.
helpers.wait (duration)	Pause code exection for duration seconds.
helpers.getRoom ()	Gets the current room the player is in.
helpers.getSession ()	Gets the current session.
helpers.say (dialog)	Display textbox with dialog.
helpers.miniTextbox (dialog)	Display minitextbox with dialog.
helpers.choice (...)	Allow the user to select one of several minitextboxes, similar to intro cutscene of Reflection.
helpers.choiceDialog (Table)	Displays a choice dialog, similar to intro cutscene of Reflection.
helpers.closeChoiceDialog ()	Closes the choice dialog previously opened by helpers.choiceDialog
helpers.postcard (dialog, sfxIn[, sfxOut=nil])	Display postcard.
helpers.walkTo (x[, walkBackwards=false[, speedMultiplier=1.0[, keepWalkingIntoWalls=false]]])	Player walks to the given X coordinate.
helpers.walk (x[, walkBackwards=false[, speedMultiplier=1.0[, keepWalkingIntoWalls=false]]])	Player walks x pixels from current position.
helpers.runTo (x, fastAnimation)	Player runs to the given X coordinate.
helpers.run (x, fastAnimation)	Player runs x pixels from current position.
helpers.die ([direction={0⸴ 0}[, evenIfInvincible=false[, registerDeathInStats=true]]])	Kills the player.
helpers.setPlayerState (state[, locked=false])	Sets the current player state.
helpers.getPlayerState ()	Gets the current state of the player.
helpers.disableMovement ()	Disable player movement.
helpers.enableMovement ()	Enable player movement.
helpers.jump ([duration=2.0])	Make the player jump.
helpers.waitUntilOnGround ()	Waits until the player is on the ground.
helpers.changeRoom (name[, spawnX[, spawnY]])	Changes the room the game thinks the player is in.
helpers.teleportTo (x, y[, room[, introType]])	Sets the player position to the absolute coordinates.
helpers.teleport (x, y[, room[, introType]])	Teleport the player to (x, y) pixels from current position.
helpers.instantTeleportTo (x, y[, room])	Instantly teleport the player seamlessly.
helpers.instantTeleport (x, y[, room])	Instantly teleport the player to the same coordinates in another room seamlessly.
helpers.completeArea ([spotlightWipe=false[, skipScreenWipe=false[, skipCompleteScreen=false]]])	Completes the level and returns the player to the chapter screen.
helpers.playSound (name[, position])	Plays a sound.
helpers.getEntities (name[, prefix])	Gets all tracked entities by class name.
helpers.getEntity (name[, prefix])	Gets the first tracked entity by class name.
helpers.getAllEntities (name[, prefix])	Gets all entities by class name.
helpers.getFirstEntity (name[, prefix])	Gets the first entity by class name.
helpers.giveFeather ()	Puts player in feather state.
helpers.deathsInCurrentRoom ()	Get amount of deaths in current room.
helpers.playMusic (track, progress)	Play and update the current music track.
helpers.getMusic ()	Get the current music track name.
helpers.setMusicProgression (progress)	Sets music progression.
helpers.getMusicProgression ()	Gets the current music progression.
helpers.setMusicLayer (layer, value)	Set music layer on/off.
helpers.setSpawnPoint ([target={0⸴ 0}[, absolute=false]])	Attempt to set the player spawnpoint.
helpers.shake (Direction[, duration])	Shakes the camera.
helpers.setInventory (name)	Set player inventory
helpers.getInventory ([inventory])	Get player inventory
helpers.setCameraOffset (x[, y])	Offset the camera by x and y like in camera offset trigger.
helpers.getCameraOffset ()	Get the current offset struct.
helpers.getRoomCoordinates ()	Get the current room coordinates.
helpers.getRoomCoordinatesOffset (x[, y])	Get the current room coordinates offset by x and y.
helpers.setFlag (flag, value)	Set session flag.
helpers.getFlag (flag)	Get session flag.
helpers.endCutscene ()	Ends the current cutscene.
helpers.setBloomStrength (amount)	Sets the current bloom strength.
helpers.getBloomStrength ()	Returns the current bloom strength.
helpers.setDarkness (amount)	Sets the current darkness (bloom) strength.
helpers.getDarkness ()	Returns the current darkness (bloom) strength.
helpers.setCoreMode (mode)	Sets the current core mode.
helpers.getCoreMode ()	Returns the current core mode.
helpers.setColorGrade (colorGrade[, instant=false])	Changes the current colorgrade to the new one.
helpers.cassetteFlyTo (endX, endY[, controllX=endX[, controllY=endY]])	Bubble flies (cassette collection) to the target.
helpers.cassetteFly (endX, endY[, controllX=endX[, controllY=endY]])	Bubble flies (cassette collection) to the target relative to player.
helpers.giveKey ()	Gives the player a key.
helpers.makeUnskippable ()	Disables skip cutscene from menu.
helpers.enableRetry ()	Enables retrying from menu.
helpers.disableRetry ()	Disables retrying from menu.
helpers.disablePause ()	Prevents the player from even accessing the pause menu.
helpers.enablePause ()	Reenables the player to pause the game.

Functions

helpers.setClassNamePrefix (prefix)

Set the prefix for getting Celeste classes. By default this is "Celeste.".

prefix string

The new prefix.

helpers.getClassNamePrefix ()

Get the prefix for getting Celeste classes. By default this is "Celeste.".

Returns

#Monocle.Entity First entity of given class.

helpers.readCelesteAsset (filename)

Get the content of a file from a Celeste asset.

filename string

Filename to load. Filename should not have a extention.

helpers.loadCelesteAsset (filename)

Loads and returns the result of a Lua asset.

filename string

Filename to load. Filename should not have a extention.

helpers.log (message[, tag="Lua Cutscenes"])

Put debug message in the Celeste console.

message string

The debug message.

tag string (default "Lua Cutscenes")

The tag in the console.

helpers.getEnum (enum, value)

Gets enum value.

enum string

String name of enum.

value any

string name or enum value to get.

helpers.wait (duration)

Pause code exection for duration seconds.

duration number

Duration to wait (in seconds).

helpers.getRoom ()

Gets the current room the player is in.

Returns

#Celeste.Level The current room.

helpers.getSession ()

Gets the current session.

Returns

#Celeste.Session The current session.

helpers.say (dialog)

Display textbox with dialog.

dialog string

Dialog ID used for the conversation.

helpers.miniTextbox (dialog)

Display minitextbox with dialog.

dialog string

Dialog ID used for the textbox.

helpers.choice (...)

Allow the user to select one of several minitextboxes, similar to intro cutscene of Reflection.

... string

Dialog IDs for each of the textboses as varargs.

Returns

number The index of the option the player selected.

helpers.choiceDialog (Table)

Displays a choice dialog, similar to intro cutscene of Reflection. Unlike helpers.choice, this function also handles displaying dialogs and keeping track of which choices were already picked. Check the 'example_talker.lua' file for a usage example.

Table table

describing all choices and requirements, etc.

helpers.closeChoiceDialog ()

Closes the choice dialog previously opened by helpers.choiceDialog

helpers.postcard (dialog, sfxIn[, sfxOut=nil])

Display postcard.

dialog string

Dialog ID or message to show in the postcard.

sfxIn any

effect when opening the postcard or area ID.

sfxOut string (default nil)

Sound effect when closing the postcard. If not used then second argument is assumed to be area ID.

helpers.walkTo (x[, walkBackwards=false[, speedMultiplier=1.0[, keepWalkingIntoWalls=false]]])

Player walks to the given X coordinate. This is in pixels and uses map based coordinates.

x number

X coordinate to walk to.

walkBackwards bool (default false)

If the player should visually be walking backwards.

speedMultiplier number (default 1.0)

How fast the player should move. Walking is considered a speed multiplier of 1.0.

keepWalkingIntoWalls bool (default false)

If the player should keep walking into walls.

helpers.walk (x[, walkBackwards=false[, speedMultiplier=1.0[, keepWalkingIntoWalls=false]]])

Player walks x pixels from current position.

x number

X offset for where player should walk.

walkBackwards bool (default false)

If the player should visually be walking backwards.

speedMultiplier number (default 1.0)

How fast the player should move. Walking is considered a speed multiplier of 1.0.

keepWalkingIntoWalls bool (default false)

If the player should keep walking into walls.

helpers.runTo (x, fastAnimation)

Player runs to the given X coordinate. This is in pixels and uses map based coordinates.

x number

X coordinate to run to.

fastAnimation bool

Whether this should use the fast animation or not.

helpers.run (x, fastAnimation)

Player runs x pixels from current position.

x number

X offset for where player should run.

fastAnimation bool

Whether this should use the fast animation or not.

helpers.die ([direction={0⸴ 0}[, evenIfInvincible=false[, registerDeathInStats=true]]])

Kills the player.

direction table (default {0⸴ 0})

The direction the player dies from.

evenIfInvincible bool (default false)

If the player should die even if they are invincible (assist mode).

registerDeathInStats bool (default true)

If it should count as a death in journal.

helpers.setPlayerState (state[, locked=false])

Sets the current player state.

state

Name of the state or the state number.

locked bool (default false)

If this should prevent the player for changing state afterwards.

helpers.getPlayerState ()

Gets the current state of the player.

helpers.disableMovement ()

Disable player movement.

helpers.enableMovement ()

Enable player movement.

helpers.jump ([duration=2.0])

Make the player jump.

duration number (default 2.0)

How long the "jump button" would be held (in seconds).

helpers.waitUntilOnGround ()

Waits until the player is on the ground.

helpers.changeRoom (name[, spawnX[, spawnY]])

Changes the room the game thinks the player is in.

name string

Room name.

spawnX string (optional)

X coordinate for new spawn point, by default it uses bottom left of room.

spawnY string (optional)

Y coordinate for new spawn point, by default it uses bottom left of room.

helpers.teleportTo (x, y[, room[, introType]])

Sets the player position to the absolute coordinates.

x number

Target x coordinate.

y number

Target y coordinate.

room string (optional)

What room the game should attempt to load. If room is specified player will land at closest spawnpoint to target location.

introType any (optional)

intro type to use, can be either a #Celeste.Player.IntroTypes enum or a string

helpers.teleport (x, y[, room[, introType]])

Teleport the player to (x, y) pixels from current position.

x number

X offset on X axis.

y number

Y offset on Y axis.

room string (optional)

What room the game should attempt to load. If room is specified player will land at closest spawnpoint to target location.

introType any (optional)

intro type to use, can be either a #Celeste.Player.IntroTypes enum or a string. Only applies if room is specified.

helpers.instantTeleportTo (x, y[, room])

Instantly teleport the player seamlessly. Teleport player to (x, y) position, in pixels. Room name as only argument will seamlessly teleport to that room at the same relative position.

x any

X offset on X axis if number. Target room if string.

y number

Y offset on Y axis.

room string (optional)

What room the game should attempt to load. By default same room.

helpers.instantTeleport (x, y[, room])

Instantly teleport the player to the same coordinates in another room seamlessly. Teleport player (x, y) pixels from current position. Room name as only argument will seamlessly teleport to that room at the same relative position.

x any

X offset on X axis if number. Target room if string.

y number

Y offset on Y axis.

room string (optional)

What room the game should attempt to load. By default same room.

helpers.completeArea ([spotlightWipe=false[, skipScreenWipe=false[, skipCompleteScreen=false]]])

Completes the level and returns the player to the chapter screen.

spotlightWipe bool (default false)

Whether this should be a spotlight wipe or not.

skipScreenWipe bool (default false)

Whether this wipe is skipped or not.

skipCompleteScreen bool (default false)

Whether this skips the complete screen.

helpers.playSound (name[, position])

Plays a sound.

name string

Event for the song.

position table (optional)

Where the sound is played from.

Returns

#Celeste.Audio The audio instance of the sound.

helpers.getEntities (name[, prefix])

Gets all tracked entities by class name.

name string

Class name of the entity, relative to "Celeste." by default.

prefix string (optional)

Overrides the global class name prefix.

Returns

{#Monocle.Entity...} Tracked entities of given class.

helpers.getEntity (name[, prefix])

Gets the first tracked entity by class name.

name string

Class name of the entity, relative to "Celeste." by default.

prefix string (optional)

Overrides the global class name prefix.

Returns

#Monocle.Entity First entity of given class.

helpers.getAllEntities (name[, prefix])

Gets all entities by class name.

name string

Class name of the entity, relative to "Celeste." by default.

prefix string (optional)

Overrides the global class name prefix.

Returns

{#Monocle.Entity...} Tracked entities of given class.

helpers.getFirstEntity (name[, prefix])

Gets the first entity by class name.

name string

Class name of the entity, relative to "Celeste." by default.

prefix string (optional)

Overrides the global class name prefix.

Returns

#Monocle.Entity First entity of given class.

helpers.giveFeather ()

Puts player in feather state.

helpers.deathsInCurrentRoom ()

Get amount of deaths in current room.

Returns

number Current deaths in room.

helpers.playMusic (track, progress)

Play and update the current music track.

track string

Name of song, same as in Ahorn's room window.

progress number

[opt] Which progress level the music should be at. Leave empty for no change.

helpers.getMusic ()

Get the current music track name.

Returns

string Music track name.

helpers.setMusicProgression (progress)

Sets music progression.

progress number

The new progress level.

helpers.getMusicProgression ()

Gets the current music progression.

Returns

number Music progress level.

helpers.setMusicLayer (layer, value)

Set music layer on/off.

layer any

number or table of numbers to set.

value bool

The state of the layer.

helpers.setSpawnPoint ([target={0⸴ 0}[, absolute=false]])

Attempt to set the player spawnpoint.

target table (default {0⸴ 0})

Where it should attempt to set the spawnpoint from.

absolute bool (default false)

If set uses absolute coordinates from target, otherwise it offsets from the center of the cutscene trigger.

helpers.shake (Direction[, duration])

Shakes the camera.

Direction direction

the screen should shake from.

duration bool (optional)

How long the screen should shake.

helpers.setInventory (name)

Set player inventory

name

Inventory to use. If name is string look it up in valid inventories, otherwise use the inventory.

helpers.getInventory ([inventory])

Get player inventory

inventory string (optional)

If name is given get inventory by name, otherwise the current player inventory

helpers.setCameraOffset (x[, y])

Offset the camera by x and y like in camera offset trigger.

x

X coordinate or table of coordinates to offset by.

y number (optional)

Y coordinate to offset by.

helpers.getCameraOffset ()

Get the current offset struct.

Returns

{number⸴ number} The camera offset.

helpers.getRoomCoordinates ()

Get the current room coordinates.

Returns

{number⸴ number} The camera offset.

helpers.getRoomCoordinatesOffset (x[, y])

Get the current room coordinates offset by x and y.

x

X coordinate or table of coordinates to offset by.

y number (optional)

Y coordinate to offset by.

Returns

{number, number} The camera offset.

helpers.setFlag (flag, value)

Set session flag.

flag string

Flag to set.

value bool

State of flag.

helpers.getFlag (flag)

Get session flag.

flag string

Flag to get.

Returns

bool The state of the flag.

helpers.endCutscene ()

Ends the current cutscene.

helpers.setBloomStrength (amount)

Sets the current bloom strength.

amount number

New bloom strength.

helpers.getBloomStrength ()

Returns the current bloom strength.

Returns

number Bloom strength.

helpers.setDarkness (amount)

Sets the current darkness (bloom) strength.

amount number

New bloom strength.

helpers.getDarkness ()

Returns the current darkness (bloom) strength.

Returns

number Bloom strength.

helpers.setCoreMode (mode)

Sets the current core mode.

mode

String name for mode or Core Mode enum.

helpers.getCoreMode ()

Returns the current core mode.

Returns

#Celeste.Session.CoreMode.

helpers.setColorGrade (colorGrade[, instant=false])

Changes the current colorgrade to the new one.

colorGrade string

Name of the color grade

instant bool (default false)

Wheter the color grade should instantly change or gradually change

helpers.cassetteFlyTo (endX, endY[, controllX=endX[, controllY=endY]])

Bubble flies (cassette collection) to the target. This is in pixels and uses map based coordinates.

endX number

X coordinate for end point.

endY number

Y coordinate for end point.

controllX number (default endX)

X coordinate for controll point.

controllY number (default endY)

coordinate for controll.

helpers.cassetteFly (endX, endY[, controllX=endX[, controllY=endY]])

Bubble flies (cassette collection) to the target relative to player. Values are in pixels and not tiles.

endX number

X offset for end point.

endY number

Y offset for end point.

controllX number (default endX)

X offset for controll point.

controllY number (default endY)

offset for controll.

helpers.giveKey ()

Gives the player a key.

helpers.makeUnskippable ()

Disables skip cutscene from menu.

helpers.enableRetry ()

Enables retrying from menu.

helpers.disableRetry ()

Disables retrying from menu.

helpers.disablePause ()

Prevents the player from even accessing the pause menu.

helpers.enablePause ()

Reenables the player to pause the game.