CutsceneTrigger

Plays a cutscene when something happens, without writing the wiring: the scene entering play, the player reaching this entity, or a call from your own code.

-- the game opens on a cutscene
entity.spawn("Intro").component.add("CutsceneTrigger", {
    cutscene = "mygame.scenes.intro",
    trigger = "onPlay",
})

-- a cutscene when the player reaches the gate
entity.find("GateArea").component.add("CutsceneTrigger", {
    cutscene = "mygame.scenes.gate_opens",
    trigger = "onEnter",
    radius = 4,
})

The cutscene itself is a module returning a definition — see the cutscene module for its shape, and the topics/cutscenes guide for the whole picture.

Fields

Field	Default	Notes
cutscene	""	The module path a cutscene definition is returned from.
trigger	"onPlay"	onPlay as the scene enters play · onEnter when the local player comes within radius · manual only on a play() call.
radius	3	How close the local player has to get, for onEnter.
delay	0	Seconds to wait after the trigger before it starts.
once	true	Whether it plays only the first time it is triggered.
skippable	true	Whether the player can skip it, overriding the definition.
played	false	Whether it has already played. Local to this peer.

Methods

• play() — start the cutscene now, whatever trigger says. This is what trigger = "manual" is for.
• isPlaying() — whether the cutscene this trigger started is still running.

Notes

• played is NoSync on purpose: a cutscene is something each player watches for themselves, so one player having seen it is not a reason another player does not.
• Playing goes through cutscene.play, so only one cutscene is ever on screen — a trigger that fires while another cutscene runs ends that one first. The onEnter trigger holds off while any cutscene is playing rather than cutting across it.
• A trigger destroyed while its own cutscene is on screen ends the cutscene, so the player is never left looking through a camera nothing moves.