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
autoClickisfalse. - With
autoClickset tofalse, 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
Initagain 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
asynchandler 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);
},