diff options
Diffstat (limited to 'building_guide/behaviors.md')
| -rw-r--r-- | building_guide/behaviors.md | 170 |
1 files changed, 129 insertions, 41 deletions
diff --git a/building_guide/behaviors.md b/building_guide/behaviors.md index 438e859..a2c1f89 100644 --- a/building_guide/behaviors.md +++ b/building_guide/behaviors.md @@ -3,7 +3,7 @@ Behaviors are **inline configs** placed directly inside object YAML (`gather:`, `talk:`, `use:`, `safespot:`) or mob YAML (`talk:`). Each section below shows the keys you can use under each behavior type. -The examples below are object/mob files; remember **the filename is the ID** — don't include an `id:` field (see `objects.md` / `mobs.md`). +The examples below are object/mob files; remember the filename is the ID for these. ### Gather (mining, fishing, woodcutting) @@ -183,15 +183,16 @@ toggle is on, the output includes the XP gain: `(+37xp wct)`. ### Talk (dialog trees) -Talk configs go under the `talk:` key on objects or mobs. Full conversation with -conditions, actions, and player flag tracking: +Talk configs go under the `talk:` key on objects or mobs. A conversation is a set of named +**nodes**, each with a message, optional action, optional auto-advance target, and choices +for the player. ```yaml name: Guard talk: nodes: start: - message: "\"Halt! This area is restricted.\"" + message: "\"Halt! This area is restricted.\" The guard eyes you suspiciously." options: - text: "\"What's behind that gate?\"" goto: about_gate @@ -205,16 +206,15 @@ talk: player_flag: got_pass value: true - text: "\"Goodbye.\"" - end: true + # no goto = end conversation about_gate: - message: "\"Bring me some copper ore and I'll stamp you a pass.\"" + message: "\"Supplies. Weapons.\" He shifts his weight. \"Bring me some copper ore and I'll stamp you a pass.\"" action: set_player_flags: talked_to_guard: true options: - text: "\"I'll be back.\"" - end: true - text: "\"I have some right here.\"" goto: trade_ore condition: @@ -229,40 +229,57 @@ talk: got_pass: true options: - text: "\"Thanks.\"" - end: true has_pass: - message: "\"Alright, I'll open the gate for you.\"" + message: "\"Alright, I'll open the gate.\"" action: set_flags: gate_open: true options: - text: "\"Thanks.\"" - end: true ``` +#### TalkNode fields + +| Field | Type | Description | +|---|---|---| +| `message` | string or list | NPC dialogue. May be a single string or a list of strings (pick one at random). | +| `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. | + +#### TalkOption fields + +| Field | Type | Description | +|---|---|---| +| `text` | string | Player-facing choice text. | +| `goto` | string | Node ID to navigate to if this choice is selected. Omit to end the conversation. | +| `condition` | Condition | Only show this option if the condition passes. | +| `action` | NodeAction | Fires when this option is selected, BEFORE navigating to `goto`. | + #### Node action reference | Field | Effect | |---|---| -| `set_flags` | Sets world flags (global, shared by all players) | -| `set_player_flags` | Sets player-local flags (per-character, quest progress) | -| `give_item` | Gives an item to the player's inventory | -| `take_item` | Removes an item from the player's inventory | -| `teleport` | Moves the player to a room ID | -| `heal` | Restores that many hitpoints | -| `cost` | Credits charged for the action | -| `shop` | Opens a buy/sell shop interface (see Shop section below) | -| `assign_task` | Assigns a random assassin task to the player based on their assassin level | -| `skip_task` | Cancels current assassin task, costs 30 reputation, resets streak | -| `extend_task` | Adds 50% more kills to current task, costs 30 reputation | -| `reputation_cost` | Deducts reputation from the player's `assassin_reputation` flag (fails node if insufficient) | -| `sawmill` | Opens sawmill plank conversion interface | - -All fields in a single action are processed together — you can give an item, take an item, -set flags, and heal all in one node. - -Example — quest completion: +| `set_flags` | Sets world flags (global, shared by all players). | +| `set_player_flags` | Sets player-local flags (per-character, quest progress). | +| `give_item` | Gives an item to the player's inventory. | +| `take_item` | Removes an item from the player's inventory. | +| `teleport` | Moves the player to a room ID. | +| `heal` | Restores that many hitpoints. | +| `cost` | Credits charged for the action. | +| `shop` | Opens a buy/sell shop interface. See Shop section below. | +| `assign_task` | Assigns a random assassin task based on assassin level. | +| `skip_task` | Cancels current assassin task, costs 30 reputation, resets streak. | +| `extend_task` | Adds 50% more kills to current task, costs 30 reputation. | +| `reputation_cost` | Deducts reputation from `assassin_reputation` flag before other actions. | +| `sawmill` | Opens sawmill plank conversion interface. | +| `aps_node` | Marks this room's APS node as unlocked. | + +All fields in a single action are processed together — give an item, take an item, set flags, +and heal in one node. + +Example — quest completion with multiple actions: ```yaml action: take_item: dragon_head @@ -274,10 +291,85 @@ action: teleport: 1 ``` +#### Option-level actions + +Actions can be placed directly on options. The action fires when the player selects that +choice, BEFORE navigating to `goto`. This eliminates needing a separate "action node" for +simple transactions: + +```yaml +nodes: + start: + message: "Welcome! Houses are 10 credits. Interested?" + options: + - text: "Yes, I'll buy one." + action: + cost: 10 + set_player_flags: + owns_house: true + goto: purchased + condition: + player_flag: owns_house + not: true + - text: "No thanks." + purchased: + message: "Excellent! The plot is yours." + options: + - text: "Thanks!" + goto: start +``` + +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). + +#### Randomized messages + +`message` accepts either a plain string or a list. A list picks one entry at random each +time the node is visited: + +```yaml +nodes: + greeting: + message: + - "\"Hello, traveller.\"" + - "\"Ah, you again.\"" + - "\"A visitor! Pull up a chair.\"" + - "\"Back so soon?\"" + options: + - text: "\"Hello.\"" +``` + +#### Linear auto-advance + +When a node has no options (or all its options are hidden by conditions) and `next` is set, +the conversation automatically advances to the target node. This creates dialogue chains +without prompting the player: + +```yaml +nodes: + monologue_1: + message: "The elder clears his throat and begins..." + next: monologue_2 + monologue_2: + message: "\"Long ago, before the asteroid was settled...\"" + next: monologue_3 + monologue_3: + message: "\"...a great darkness fell upon these halls.\" He pauses." + next: choice_point + choice_point: + message: "\"Do you understand the weight of what I'm telling you?\"" + options: + - text: "\"I think so.\"" + - 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. + #### Shop (buy/sell interface) -The `shop` node action opens a dedicated buy/sell interface. The player can browse -items, buy with credits, and sell items back. Define a shop on a talk node: +The `shop` node action opens a dedicated buy/sell interface. The player can browse items, buy +with credits, and sell items back. Define a shop on a talk node: ```yaml action: @@ -294,14 +386,11 @@ action: | Field | Description | |---|---| -| `shop.message` | Greeting shown when entering the shop | -| `shop.items` | List of items for sale | -| `item_id` | Item definition ID | -| `buy_price` | Credits to buy from shop | -| `sell_price` | Credits shop pays (0 = won't buy) | - -Typical shop flow: a talk node with a "Browse" option leads to a `shop` node. -When the player leaves the shop, they return to the talk node's options. +| `shop.message` | Greeting shown when entering the shop. | +| `shop.items` | List of items for sale. | +| `item_id` | Item definition ID. | +| `buy_price` | Credits to buy from shop. | +| `sell_price` | Credits shop pays (0 = won't buy). | Full example — General Store: ```yaml @@ -314,7 +403,6 @@ talk: - text: "\"I'd like to browse.\"" goto: shop - text: "\"Goodbye.\"" - end: true shop: message: "\"Take your time.\"" action: @@ -332,8 +420,8 @@ talk: goto: start ``` -Node options on the shop node are shown when the player leaves the shop. -Use `goto: start` to loop back to the main greeting. +When the player leaves the shop, the current node's options are shown (or auto-advance +fires if no options are visible). Use `goto: start` to loop back to the main greeting. ### Object Interactions (levers, switches, gates) |