Project Mammut Wiki
projectmammut.com
Project Mammut is currently in open beta. The UI is being updated a lot during this time, and you may run into bugs. If you'd like to help develop the engine or suggest features, come find us on Bluesky or Discord.

Revealer

Written 18 Nov 2026 · Updated 19 Nov 2026 · Requires Mammut 0.9.22+

The Revealer types a chapter's text into a text element, one character at a time, and runs the actions in it. Your script reacts to what happens in the text by registering handlers for its events. It's only available while the Narrative module is turned on in Project Settings.

See Revealer for how a reveal works step by step, and Actions Reference for the [Action()] tags you can write in chapters.

Member Description
Init() Sets the element text is revealed into
StartRevealChapterByID() Loads a chapter and reveals its start node
StartRevealChapter() Reveals a chapter you've already loaded
StartRevealChapterByPath() Loads a chapter from a url and reveals it
RevealNode() Reveals one node of the current chapter
Register() Calls a handler for an event or action
Unregister() Removes a handler
unregisterAll() Removes every handler for an event
Pause() Freezes the reveal
Unpause() Carries on after Pause()
IsPaused() Whether the reveal is paused
GetHistory() The nodes revealed so far
Reveal controller Controls one node's reveal
Events Everything you can register for

Starting a reveal

Init

Revealer.Init(element: HTMLElement, options?: RevealerInitOptions): void

Sets the element that text is revealed into, and how fast it appears. Call it before revealing anything, usually in onStart().

Parameter Type Default Description
element HTMLElement The text element
options.clickTarget HTMLElement None An element the player clicks to continue, instead of anywhere on the screen
options.autoClick boolean true false turns off click handling completely
options.speed number 30 Milliseconds between characters. Lower is faster
options.commaDelay number 60 Extra milliseconds to wait after a comma
options.semicolonDelay number 120 Extra milliseconds to wait after a semicolon
options.colonDelay number 180 Extra milliseconds to wait after a colon
options.fullStopDelay number 250 Extra milliseconds to wait after a full stop

How it works

  • By default, an invisible layer inside the text element covers the whole screen while a node reveals, so a click anywhere continues. It's hidden between nodes and while the reveal is paused, so the rest of your UI can be clicked then.
  • With clickTarget, only clicks on that element continue. It's never hidden.
  • A click while text is still appearing shows the rest of it straight away. A click while the text waits at an [AwaitClick()] carries on.
  • Links in the text (see Formatting) jump to their node when clicked, unless autoClick is false.
  • With autoClick set to false, nothing continues past an [AwaitClick()], so only use it for chapters without them.
  • The speed and pauses apply from the next node that starts. [TextSpeed()] in a chapter changes the speed for the rest of a node.
  • Calling Init again replaces the earlier element and options.

Example

onStart() {
  const speed = SaveManager.GetGameSettings("textSpeed", 30); // the player's choice from the options menu
  Revealer.Init(this.dom.dialogue_text, { clickTarget: this.dom.next_button, speed });
  Revealer.StartRevealChapterByID("chapter_01");
},

StartRevealChapterByID

Revealer.StartRevealChapterByID(chapterId: ChapterName | AssetRef<"chapter">): Promise<RevealController | undefined>

Loads a chapter by its key, or a chapter picked in a File variable (an AssetRef), and reveals its start node.

Returns a promise of the start node's reveal controller. It's undefined, and an error is logged, if the chapter couldn't be loaded.

Example

async onStart() {
  Revealer.Init(this.dom.dialogue_text);
  const reveal = await Revealer.StartRevealChapterByID("intro");
  await reveal?.promise; // waits for the start node to finish
  log("The first node has finished");
},

StartRevealChapter

Revealer.StartRevealChapter(chapter: object): Promise<RevealController | undefined>

Reveals the start node of a chapter you've already loaded, for example with Assets.LoadFile.

Returns a promise of the start node's reveal controller. It's undefined, and an error is logged, if no chapter was passed or the chapter has no start node.

Example

async onStart() {
  const chapter = await Assets.LoadFile(Store.Get("currentChapter", "chapter_01"), "chapter");
  Revealer.Init(this.dom.dialogue_text);
  Revealer.StartRevealChapter(chapter);
},

StartRevealChapterByPath

Revealer.StartRevealChapterByPath(path: string): Promise<RevealController | undefined>

Loads a chapter file from a url and reveals its start node. Use StartRevealChapterByID for chapters in your project.

Returns the same as StartRevealChapterByID.

RevealNode

Revealer.RevealNode(id: string): RevealController | undefined

Stops the node that's revealing and reveals another node of the current chapter.

Returns the new node's reveal controller, or undefined, with an error logged, if the chapter has no node with that id.

How it works

  • It also unpauses the reveal and lets go of any click being waited for.
  • Use it to follow the player's choice from OptionsReady.

Example

onStart() {
  Revealer.Register("OptionsReady", this.showChoices, this);
},

showChoices(event: RevealerEvent) {
  this.dom.choices.replaceChildren();
  for (const option of event.options ?? []) {
    const button = document.createElement("button");
    button.textContent = option.text;
    button.onclick = () => {
      this.dom.choices.replaceChildren(); // remove the buttons
      Revealer.RevealNode(option.id);     // go to the node the option links to
    };
    this.dom.choices.appendChild(button);
  }
},

Handlers

Register

Revealer.Register(eventName: string, handler: (event: RevealerEvent) => void | Promise<void>, owner?: object): void

Calls handler each time an event fires: one of the built-in events, or a custom action like [OpenShop(sword, price=10)] in a chapter.

Parameter Type Default Description
eventName string The event's or action's name
handler (event) => void Called with the event object
owner object None Usually this. See The owner argument

How it works

  • If the handler returns a promise (an async handler does), the text waits until it resolves.
  • Handlers for the same event run one after another, in the order they were registered.
  • Arguments arrive as text, so convert numbers yourself.

Example

onStart() {
  Revealer.Register("OpenShop", this.openShop, this);
},

async openShop(event: RevealerEvent) {
  const item = event.args[0];               // "sword"
  const price = Number(event.kwargs.price); // 10
  await this.dom.shop.setState("open");     // the text waits for the shop to open
},

Unregister

Revealer.Unregister(eventName: string, handler: (event: RevealerEvent) => void | Promise<void>, owner?: object): void

Removes a handler added with Register. Pass the same function, not a bound copy. UnregisterScene(owner) removes every handler that owner registered.

unregisterAll

Revealer.unregisterAll(eventName: string): void

Removes every handler for one event, from every scene. Its name starts with a small u.

Pausing

Pause

Revealer.Pause(): void

Freezes the reveal where it is, until Unpause() is called. While it's paused, the click layer is hidden, so the rest of your UI can be clicked.

Example

onMenuOpened() {
  Revealer.Pause();
  this.dom.menu.show();
},

Unpause

Revealer.Unpause(): void

Carries on after Pause(). The SetCharacter, UnsetCharacter and UnsetCharacterAll actions pause the reveal, so their handlers must call this when they're done.

Example

onStart() {
  Revealer.Register("SetCharacter", this.setCharacter, this);
},

async setCharacter(event: RevealerEvent) {
  const variant = Assets.GetVariant(event.args[0], event.kwargs.variant ?? "");
  this.dom.speaker_image.src = variant?.image ?? Assets.GetCharacter(event.args[0])?.image ?? "";
  await this.dom.speaker_image.setState("enter");
  Revealer.Unpause(); // without this the text stays paused
},

IsPaused

Revealer.IsPaused(): boolean

Returns true while the reveal is paused.

History

GetHistory

Revealer.GetHistory(): RevealHistoryEntry[]

Returns the nodes revealed since the game started, oldest first, up to the last 1000. Each entry has:

Field Description
chapter The chapter's name
nodeId The node's id
time When it was revealed, in milliseconds, like Date.now()
text The first 120 characters of the node's text, including any markup

Example

onBacklogOpened() {
  const lines = Revealer.GetHistory().slice(-20); // the last 20 nodes
  this.dom.backlog.textContent = lines.map((entry) => entry.text).join("\n\n");
},

Reveal controller

StartRevealChapterByID, StartRevealChapter, StartRevealChapterByPath and RevealNode return a controller for the node they reveal. Each node has its own. When the text moves to another node, through a link, an [AutoLink()] or RevealNode, a new one is made.

Member Description
promise Resolves when the node has finished, after its NodeEnd and OptionsReady handlers
skip() Shows the rest of the text straight away
stop() Ends the node's reveal now
pause() Freezes this reveal
resume() Carries on after pause()

Example

reveal: null as RevealController | null,

async onStart() {
  Revealer.Init(this.dom.dialogue_text);
  this.reveal = (await Revealer.StartRevealChapterByID("intro")) ?? null;
  InputManager.Register("KeyDown", "Space", () => this.reveal?.skip(), this);
},

Events

The event object

Every handler receives one event object:

Field Description
name The event's name
args The action's positional arguments, as text. [SetCharacter(alice)] gives ["alice"]
kwargs The action's named arguments, as text. [Foo(mood=happy)] gives { mood: "happy" }
options OptionsReady only: the choices, each with an id and text
char OnTextCharPlace only: the character about to appear

Built-in events

Event When it fires
NodeStart A node starts revealing
SectionStart At the start of a node, and each time the text carries on after a click
SectionEnd Before the text waits for a click, and at the end of a node
WaitingForClick The text has reached an [AwaitClick()] or [ClickClear()] and is waiting
NodeEnd A node has finished
OptionsReady After NodeEnd, if the node had [LinkOption()] tags
OnTextCharPlace Before each character appears. Not while the text is being skipped
SetCharacter A [SetCharacter()] tag. The reveal pauses until you call Unpause()
UnsetCharacter An [UnsetCharacter()] tag. The reveal pauses until you call Unpause()
UnsetCharacterAll An [UnsetCharacterAll()] tag. The reveal pauses until you call Unpause()

Any other tag that isn't a built-in action fires an event with its own name.

Example

onStart() {
  Revealer.Register("WaitingForClick", () => this.dom.continue_arrow.show(), this);
  Revealer.Register("SectionStart", () => this.dom.continue_arrow.hide(), this);
  Revealer.Register("OnTextCharPlace", (event) => {
    if (event.char !== " ") AudioManager.PlaySFX("blip"); // a blip for each letter
  }, this);
},