path: root/worldbuilding_guide/behaviors.md

## Behaviors

### Gather (mining, fishing, woodcutting)

Mining — per-drop depletion:
```yaml
id: mine_copper
type: gather
skill: mining
level: 1
xp: 17                        # XP awarded per successful gather
base_wait: 8                   # ticks between attempts
tool: pickaxe                  # requires item with tool_type: pickaxe
success:
  base: 0.40                   # 40% base chance
  per_level: 0.01              # +1% per level above requirement
  cap: 0.95                    # 95% max
gather_message: "You swing your pickaxe at the rock..."
fail_message: "You chip away but get nothing useful."
drops:
  - item_id: copper_ore
    weight: 90                 # 90% chance when roll succeeds
    depletes: true             # rock becomes depleted after this drop
    message: "You manage to mine some {178}copper ore{/}."
  - table: gem_table           # reference a shared drop table
    weight: 10
    depletes: false            # gem drops don't deplete the rock
    message: "You spot a glint of something valuable!"
respawn_timer: 50              # ticks until rock respawns
respawn_message: "You see more ore in the rock."
respawn_broadcast: "A glint of copper catches your eye from some {name}."
```

Drop messages support inline color tags: `{<0-255>}text{/}`. Use the item's color index to match its display color. Gradients also work: `{g:196,82}text{/}`.

Non-depleting gather (fishing):
```yaml
id: fish_trout
type: gather
skill: fishing
level: 1
xp: 10
base_wait: 4
tool: fishing_rod
success:
  base: 0.30
  per_level: 0.01
  cap: 0.90
gather_message: "You cast your line into the water..."
fail_message: "Nothing seems to bite."
drops:
  - item_id: raw_trout
    weight: 100
    depletes: false            # never depletes
    message: "You catch a {69}raw trout{/}!"
```

Woodcutting with shared depletion and bird's nests:
```yaml
id: chop_oak
type: gather
skill: woodcutting
level: 15
xp: 37
base_wait: 6
tool: axe
success:
  base: 0.40
  per_level: 0.01
  cap: 0.90
gather_message: "You swing your axe at the oak tree..."
fail_message: "You swing but get no logs."
drops:
  - item_id: oak_logs
    weight: 100
    depletes: false            # depletion is timer-based (deplete_timer)
    message: "You get some {113}oak logs{/}."
respawn_timer: 14              # ticks until tree respawns after being cut down
deplete_timer: 45             # max ticks before next gather depletes (counts down while chopping)
nest_chance: 256               # 1/256 chance for a bird's nest on each successful gather
respawn_message: "A new oak sapling grows in its place."
respawn_broadcast: "An {name} grows back."
```

Regular tree — always depletes on first gather, no shared timer, no nests:
```yaml
id: chop_tree
type: gather
skill: woodcutting
level: 1
xp: 25
base_wait: 4
tool: axe
success:
  base: 0.50
  per_level: 0.01
  cap: 0.95
gather_message: "You swing your axe at the tree..."
fail_message: "You swing but get no logs."
drops:
  - item_id: logs
    weight: 100
    depletes: true             # regular tree depletes on first successful gather
    message: "You get some {107}logs{/}."
respawn_timer: 80
respawn_message: "A new tree grows in its place."
respawn_broadcast: "A {name} grows back."
```

#### Shared depletion explained

When `deplete_timer > 0`, the tree has a shared despawn timer:
- The timer starts at `deplete_timer` max when the first player begins chopping.
- Each tick, if anyone is chopping, the timer counts down.
- When the timer reaches 0, the NEXT successful gather depletes the tree.
- If no one is chopping and the tree isn't depleted, the timer ticks back UP.
- All players chopping the same tree are interrupted when it depletes.

Use `deplete_timer` for trees. Use `depletes: true` on individual drops for rocks.

#### Bird's nests

When `nest_chance > 0`, each successful gather has a 1/N independent chance to also drop
a bird's nest. The nest goes to inventory (or to the ground if inventory is full).
Use the `search` command to open nests — they roll on the `birds_nest_drop` table.

#### XP drops

When `xp > 0`, the gather awards XP on each successful drop. If the player's `xpdrops`
toggle is on, the output includes the XP gain: `(+37xp wct)`.

### Talk (dialog trees)

Full conversation with conditions, actions, and player flag tracking:
```yaml
id: guard_talk
type: talk
nodes:
  start:
    message: "\"Halt! This area is restricted.\""
    options:
      - text: "\"What's behind that gate?\""
        goto: about_gate
      - text: "\"I have copper ore.\""            # only shows if player has ore
        goto: trade_ore
        condition:
          has_item: copper_ore
      - text: "\"I have a pass.\""                # only shows if player earned a pass
        goto: has_pass
        condition:
          player_flag: got_pass
          value: true
      - text: "\"Goodbye.\""
        end: true

  about_gate:
    message: "\"Bring me some copper ore and I'll stamp you a pass.\""
    action:
      set_player_flags:                           # player-local: only this player
        talked_to_guard: true
    options:
      - text: "\"I'll be back.\""
        end: true
      - text: "\"I have some right here.\""
        goto: trade_ore
        condition:
          has_item: copper_ore

  trade_ore:
    message: "\"Good quality ore.\" He stamps a pass and hands it to you."
    action:
      take_item: copper_ore                       # removes 1 copper ore
      give_item: pass_stub                        # gives pass stub
      set_player_flags:
        got_pass: true                            # player now "has a pass"
    options:
      - text: "\"Thanks.\""
        end: true

  has_pass:
    message: "\"Alright, I'll open the gate for you.\""
    action:
      set_flags:                                  # WORLD flag: gate opens for everyone
        gate_open: true
    options:
      - text: "\"Thanks.\""
        end: true
```

#### 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) |

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:
```yaml
action:
  take_item: dragon_head
  give_item: dragon_slayer_medal
  set_player_flags:
    dragon_quest: complete
    dragon_slain: true
  heal: 99
  teleport: 1                                     # return to town
```

#### 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:

```yaml
action:
  shop:
    message: "What would you like to buy or sell?"
    items:
      - item_id: fishing_rod
        buy_price: 10
        sell_price: 2
      - item_id: fishing_bait
        buy_price: 2
        sell_price: 0
```

| 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.

Full example — General Store:
```yaml
id: general_store
type: talk
nodes:
  start:
    message: "\"Welcome to the General Store!\""
    options:
      - text: "\"I'd like to browse.\""
        goto: shop
      - text: "\"Goodbye.\""
        end: true
  shop:
    message: "\"Take your time.\""
    action:
      shop:
        message: "What would you like to buy or sell?"
        items:
          - item_id: fishing_rod
            buy_price: 10
            sell_price: 2
          - item_id: hammer
            buy_price: 20
            sell_price: 5
    options:
      - text: "\"I'm done.\""
        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.

### Toggle (levers, switches, gates)

Simple toggle that sets a world flag:
```yaml
id: iron_gate_toggle
type: toggle
message: "You push the heavy iron gate open."
set_flags:
  gate_open: true
check:                                            # only works when gate is closed
  flag: gate_open
  value: true
  not: true
```

Lever that toggles between two states:
```yaml
id: bridge_lever
type: toggle
message: "You pull the lever. Mechanisms groan somewhere in the distance."
set_flags:
  bridge_extended: true
check:
  flag: bridge_extended
  value: true
  not: true
```

### Use (crafting stations)

```yaml
id: smelt_copper
type: use
message: "You place the ore in the furnace..."
wait: 4                          # ticks between crafts
consume:                         # items consumed per craft
  copper_ore: 1
reward:                          # item produced
  item_id: copper_bar
  quantity: 1
fail_message: "The ore crumbles to dust."
success:
  base: 0.60
  per_level: 0.01
  cap: 0.95
skill: smithing
level: 1
xp: 15                           # XP awarded per successful craft
```

---