From 3102525d97aa6f1ad152c74b2ccfbd4b3a9b83f5 Mon Sep 17 00:00:00 2001 From: historia <[not public]> Date: Fri, 26 Jun 2026 02:52:31 -0400 Subject: feat: simplified conversation trees and output won't overwrite prompts now --- building_guide/behaviors.md | 85 +++++++++++++++++++++++++++++++++++++++----- building_guide/conditions.md | 5 +-- building_guide/mobs.md | 32 +++++++++++++---- 3 files changed, 106 insertions(+), 16 deletions(-) (limited to 'building_guide') diff --git a/building_guide/behaviors.md b/building_guide/behaviors.md index a2c1f89..60428d6 100644 --- a/building_guide/behaviors.md +++ b/building_guide/behaviors.md @@ -244,9 +244,11 @@ talk: | Field | Type | Description | |---|---|---| | `message` | string or list | NPC dialogue. May be a single string or a list of strings (pick one at random). | +| `sequence` | []string | NPC monologue — each message shown one at a time, player presses enter to advance. Options appear after the last message. Takes priority over `message` if both present. | +| `condition` | Condition | Optional. If the condition fails, the node is skipped entirely — its message, action, and options are not shown. Use with `goto` to auto-advance to a different node. | | `action` | NodeAction | Fires when the node is entered (give items, set flags, etc). | -| `options` | []TalkOption | Player choices. If empty and `next` is set, auto-advances. | -| `next` | string | Node ID to auto-advance to when there are no visible options. | +| `options` | []TalkOption | Player choices. If empty and `goto` is set, auto-advances. | +| `goto` | string | Node ID to auto-advance to when there are no visible options OR when the node condition fails. | #### TalkOption fields @@ -322,6 +324,32 @@ nodes: If an option has both an `action` and a `goto`, the action runs first, then the player navigates to the target node (which may also have its own action, fired on entry). +#### Sequences + +`sequence` is a flat list of NPC messages shown one at a time. The player presses +enter to advance through each message. After the last message, the node's options +(if any) are displayed. This is the preferred way to deliver NPC monologues — no +named nodes or `goto` chains needed: + +```yaml +nodes: + sign_reminder: + sequence: + - "\"Yeah, just us two! Not a lot of people heading into the belt these days.\"" + - "\"But we'll be landing shortly! Please look at the information sign.\"" + options: + - text: "\"Okay, thanks.\"" + - text: "\"Goodbye.\"" +``` + +Each `[enter to continue]` prompt is automatic. The node's action fires once on +entry, before the first sequence message. Node conditions still work normally — +if the condition fails, the entire sequence is skipped via `goto`. + +If a sequence node has no options after the last message and `goto` is set, it +auto-advances to the target node. Non-empty input during a sequence cancels the +conversation (just like invalid input does during option selection). + #### Randomized messages `message` accepts either a plain string or a list. A list picks one entry at random each @@ -341,7 +369,7 @@ nodes: #### Linear auto-advance -When a node has no options (or all its options are hidden by conditions) and `next` is set, +When a node has no options (or all its options are hidden by conditions) and `goto` is set, the conversation automatically advances to the target node. This creates dialogue chains without prompting the player: @@ -349,13 +377,13 @@ without prompting the player: nodes: monologue_1: message: "The elder clears his throat and begins..." - next: monologue_2 + goto: monologue_2 monologue_2: message: "\"Long ago, before the asteroid was settled...\"" - next: monologue_3 + goto: monologue_3 monologue_3: message: "\"...a great darkness fell upon these halls.\" He pauses." - next: choice_point + goto: choice_point choice_point: message: "\"Do you understand the weight of what I'm telling you?\"" options: @@ -363,8 +391,49 @@ nodes: - text: "\"Not really.\"" ``` -If a node has both `next` and options, the options take priority — `next` is only used -when no options are visible. A node with a shop action ignores `next` entirely. +If a node has both `goto` and options, the options take priority — `goto` is only used +when no options are visible. A node with a shop action ignores `goto` entirely. + +#### Conditional nodes + +A node can have its own `condition` that gates the entire node — message, action, +and options. When the condition fails, the node is skipped and the conversation +automatically advances to `goto` (if set). This lets you build branching first +messages or entire mutually-exclusive conversation paths based on player flags, +items, or any other condition: + +```yaml +nodes: + start: + condition: + player_flag: finished_tutorial + not: true + message: "\"Welcome, newcomer! Need any help getting started?\"" + goto: returning_player + options: + - text: "\"Yes, where do I go?\"" + goto: directions + - text: "\"I'll figure it out.\"" + returning_player: + message: "\"Ah, you're back! I heard you handled that raid beautifully.\"" + options: + - text: "\"The loot was worth it.\"" + - text: "\"Barely made it out alive.\"" + directions: + message: "\"Head north through the gate and follow the road.\"" + options: + - text: "\"Thanks!\"" +``` + +When `finished_tutorial` is set, the `start` node's condition fails, so the player +never sees "Welcome, newcomer" — it jumps straight to `returning_player`. When the +flag is unset, the condition passes and the player sees the newcomer message and its +options. + +Node conditions compose cleanly with option conditions. When the node condition +passes, each option's own condition is then checked independently to determine +visibility — exactly as option conditions always work. When the node condition +fails, the node (and all its options) are skipped entirely. #### Shop (buy/sell interface) diff --git a/building_guide/conditions.md b/building_guide/conditions.md index d58b35c..853518b 100644 --- a/building_guide/conditions.md +++ b/building_guide/conditions.md @@ -1,7 +1,8 @@ ## Conditions Reference -Conditions are used in talk options, exit gates, on-enter scripts, use_interactions -checks, room descriptions, object descriptions, and trigger value matching. +Conditions are used in talk option guards, talk node conditions, exit gates, +on-enter scripts, use_interactions checks, room descriptions, object +descriptions, and trigger value matching. ### Simple conditions diff --git a/building_guide/mobs.md b/building_guide/mobs.md index 32ee408..c7331da 100644 --- a/building_guide/mobs.md +++ b/building_guide/mobs.md @@ -95,17 +95,37 @@ idle_descriptions: talk: # inline talk config nodes: start: - message: "\"Welcome aboard!\"" + condition: # only show this node when flag is NOT set + player_flag: 1001_look_sign + not: true + message: "\"How can I help you?\"" + goto: thanks # auto-advance here if condition fails options: - - text: "\"What should I do?\"" - goto: check_sign + - text: "\"Oh, nothing...\"" + goto: sign_reminder - text: "\"Goodbye.\"" - check_sign: - message: "\"Review the safety information.\"" + thanks: + message: "\"Thank you for flying with us. Be careful on the stairs.\"" options: - - text: "\"Will do.\"" + - text: "\"Thanks!\"" + sign_reminder: + sequence: + - "\"Yeah, just us two! Not a lot of people heading into the belt these days.\"" + - "\"But we'll be landing shortly! Look at the information sign so you'll know what to do.\"" + options: + - text: "\"Okay, I'll take a look.\"" ``` +When the player has `1001_look_sign` set, the `start` node's condition fails, so +it skips directly to `thanks` ("Thank you for flying..."). When the flag is unset, +the player sees "How can I help you?" and can choose to be reminded about the sign +or say goodbye. The `sign_reminder` node uses a `sequence` so the flight attendant +delivers two lines, pausing for the player to press enter between them, before +showing the "Okay" option. + +See the [Talk section of behaviors](behaviors.md#talk-dialog-trees) for the full +dialog tree format, including sequences and conditional nodes. + Protected mob with combat stats (for internal testing or debug purposes): ```yaml name: "Guard" -- cgit v1.2.3