From 5ed62a5d66588220ed9ac6a7c6542ffaa7022592 Mon Sep 17 00:00:00 2001 From: 4ian <1280130+4ian@users.noreply.github.com> Date: Fri, 27 Mar 2026 10:27:56 +0000 Subject: [PATCH] [Auto] [Improve] Add typewriter effect, branch tags, visited branches, and state save/load to dialogue-tree docs --- automated_updates_data.json | 4 ++ .../all-features/dialogue-tree/index.md | 65 +++++++++++++++++++ 2 files changed, 69 insertions(+) diff --git a/automated_updates_data.json b/automated_updates_data.json index 8a7b974c5c0..c37d9fc01d0 100644 --- a/automated_updates_data.json +++ b/automated_updates_data.json @@ -84,6 +84,10 @@ { "date": "2026-03-24", "summary": "Fixed device-sensors docs (typo in gamma rotation description, wrong units deg/s vs m/s² for rotation values, clarified Is Absolute expression, added gravity note to acceleration) and fixed broken wiki URL in advanced-conditions OR condition" + }, + { + "date": "2026-03-27", + "summary": "Improved dialogue-tree docs: added typewriter effect, branch tags, visited-branch tracking, options display helpers, dialogue state variables, and save/load state sections; documented CommandParameter(-1) and CommandParametersCount" } ] } diff --git a/docs/gdevelop5/all-features/dialogue-tree/index.md b/docs/gdevelop5/all-features/dialogue-tree/index.md index 2643b897bb2..a442216b144 100644 --- a/docs/gdevelop5/all-features/dialogue-tree/index.md +++ b/docs/gdevelop5/all-features/dialogue-tree/index.md @@ -65,6 +65,9 @@ An example of that in the demo project is the way the animated avatar is changed **<>** when the command **avatar** is triggered, the avatar's sprite object is set to change its animation to the word after it - CommandParameter(0) (**ant**) +- **`DialogueTree::CommandParameter(index)`** — returns the parameter at position `index` (0-based). Pass `-1` to get the command name itself. +- **`DialogueTree::CommandParametersCount`** — the number of parameters (not counting the command name). + !!! tip If you are using the extension's built in scrolling functionality, you can insert pauses between text/other commands with the built in <> command. 1000 in this case is equal to 1 second, but can be anything you choose. <> will for example pause the text scrolling for half a second, then continue. If you have another command after it, it won't get triggered before that half second is over. So wait can be used to insert pauses between a chain of custom commands too - similar to rpg maker :) @@ -198,6 +201,68 @@ Ok kids we're gonna go with... ---- +## Displaying options to the player + +When the current line type is `options`, you have several ways to display the choices: + +- **`DialogueTree::Option(index)`** — get the text of the option at position `index` (0-based). Use `DialogueTree::OptionsCount` to know how many options exist. +- **`DialogueTree::HorizontalOptionsList(cursor)`** — returns all options concatenated in one line, with the `cursor` string placed before the currently selected option (useful for a compact single-line display). +- **`DialogueTree::VerticalOptionsList(cursor)`** — same, but each option is on its own line. + +Use the `Select next option` / `Select previous option` actions to move the highlighted choice (wraps around), or `Select option` to jump to a specific index. `DialogueTree::SelectedOptionIndex` gives the index of the highlighted option. Confirm the choice with `Confirm selected option`. + +## Built-in typewriter effect + +The extension includes a built-in **typewriter (text scrolling) effect** that reveals the current line one character at a time. + +- Call **`Scroll clipped text`** action every frame (e.g., on every game tick) to advance by one character. +- Use **`DialogueTree::ClippedLineText()`** as the expression for your text object (instead of `DialogueTree::LineText()`). +- Use **`Complete clipped text scrolling`** to instantly reveal the full line (useful when the player presses a button to skip the animation). +- The condition **`Clipped text scrolling has completed`** becomes true when all characters are visible. + +!!! tip + + The `<>` command integrates with the scrolling: it pauses the reveal for the given number of milliseconds before continuing, which is useful for dramatic pauses mid-sentence. + +## Branch tags + +Yarn nodes can carry **tags** in their header: `--- MyNode #emotion #mood(sad) ---`. These tags let you attach metadata to a branch that your game can act on without adding visible dialogue text or commands. + +- **`DialogueTree::BranchTags()`** — returns all tags of the current branch as a comma-separated string. +- **`DialogueTree::BranchTag(index)`** — returns the tag at position `index` (0-based). +- The condition **`Current branch contains tag`** checks whether a specific tag is present. If the tag has a parameter (e.g., `#mood(sad)`), the matched parameter is accessible via **`DialogueTree::TagParameter(index)`**. + +A common use case is triggering animations or music changes when a branch starts, by checking its tags. + +## Tracking visited branches + +The extension automatically remembers which branches the player has visited during the current session. + +- The condition **`Branch was visited`** checks whether a specific branch title has been seen before. +- **`DialogueTree::VisitedBranchTitles()`** returns a comma-separated string of all visited branch names. + +This is useful for letting NPCs react differently to repeat conversations, or for preventing the player from re-reading items they have already picked up. + +## Dialogue state variables + +Yarn's `<>` syntax stores values inside the dialogue engine. You can read and write these from GDevelop events too: + +- **`DialogueTree::VariableString(name)`** and **`DialogueTree::Variable(name)`** — get a dialogue variable as a string or number. +- Actions **`Set dialogue state string/number/boolean variable`** — set a dialogue variable directly from an event. +- Conditions **`Compare dialogue state string/number/boolean variable`** — check a dialogue variable's value. + +This lets you synchronise Yarn variables with GDevelop variables (e.g., copy them to a scene variable before saving). + +## Saving and loading dialogue state + +Use the actions **`Save dialogue state to variable`** and **`Load dialogue state from variable`** to preserve the player's dialogue progress (which branches were visited and what Yarn variables are set) across sessions. + +- These actions serialise/deserialise into a **scene or global variable**, which you can then persist to device storage using the regular Storage or Save State extension. +- **Important:** the state includes Yarn variables and visited-branch history, but **not** the current position in the active dialogue. After loading, you still need to call `Start dialogue from branch` to resume at the right place. +- The action **`Clear dialogue state`** resets all Yarn variables and visited-branch history (use it when starting a New Game). + +---- + ## Known issues: * Using a -> shortcut crashes my game - This is a known bug in bondage.js - the library that the dialogue tree extension is using to parse yarn files. See [https://github.com/hylyh/bondage.js/issues/31](https://github.com/hylyh/bondage.js/issues/31) to check if that has been fixed. The reason it happens is that bondagejs expects you to indent any linked text with tabs, otherwise its seen as a syntax error. If you want to use the shortcut syntax, please refer to this example json file as to howto do it without crashing the parser [https://github.com/hylyh/bondage.js/blob/master/tests/yarn_files/shortcuts.json](https://github.com/hylyh/bondage.js/blob/master/tests/yarn_files/shortcuts.json)