From ab2597b22ccdb71116992aec78080d9858358d04 Mon Sep 17 00:00:00 2001
From: historia <[not public]>
Date: Tue, 7 Jul 2026 16:24:27 -0400
Subject: rename flags to global_flags (differentiate from player_flags)

---
 building_guide/admin.md          |  6 +++---
 building_guide/behaviors.md      |  8 +++----
 building_guide/conditions.md     |  6 +++---
 building_guide/doors.md          |  4 ++--
 building_guide/hidden_objects.md |  2 +-
 building_guide/objects.md        | 12 +++++------
 building_guide/rooms.md          | 10 ++++-----
 building_guide/state.md          |  2 +-
 building_guide/tips.md           |  2 +-
 building_guide/triggers.md       | 46 ++++++++++++++++++++--------------------
 10 files changed, 49 insertions(+), 49 deletions(-)

(limited to 'building_guide')

diff --git a/building_guide/admin.md b/building_guide/admin.md
index fe940e3..f5ddcd1 100644
--- a/building_guide/admin.md
+++ b/building_guide/admin.md
@@ -171,7 +171,7 @@ are never saved to disk.
 ```
 setflag <flag_name> [value]
 ```
-Sets a world flag. World flags are shared by all players and stored in memory (lost on
+Sets a global flag. Global flags are shared by all players and stored in memory (lost on
 server restart). Setting a flag fires any triggers watching that flag. Values default to
 `true` if omitted. Accepted value types: `true`/`false` (bool), integer, or string.
 
@@ -222,7 +222,7 @@ Dumps detailed diagnostic information about your current room:
 - Mobs with wander intervals
 - Item spawns with respawn timers
 - On-enter step and trigger counts
-- All world flags
+- All global flags
 - Your player flags
 - Connected players in the room
 - Live mob instances with HP
@@ -259,7 +259,7 @@ the game server and is configured in `config.yaml` under `admin_http` (plain HTT
 | Courses | `/editor/courses` | CRUD for agility courses (obstacle sequences, XP, fail damage). |
 | Modules | `/editor/modules` | CRUD for science modules (combat/utility/transport/enchant/processing). |
 | Players | `/editor/players` | Browse character YAML files and view player state. |
-| Flags | `/editor/flags` | View and edit world flags in real time. |
+| Flags | `/editor/flags` | View and edit global flags in real time. |
 | Files | `/editor/files` | Raw file tree browser for all YAML files under `data/`. |
 
 All CRUD editors support undo/redo (persisted to `data/.admin_history.json`), so changes can be reverted
diff --git a/building_guide/behaviors.md b/building_guide/behaviors.md
index 8030d3d..1857681 100644
--- a/building_guide/behaviors.md
+++ b/building_guide/behaviors.md
@@ -230,7 +230,7 @@ talk:
             messages:
                 - "\"Alright, I'll open the gate.\""
             action:
-                set_flags:
+                set_global_flags:
                     gate_open: true
             options:
                 - text: "\"Thanks.\""
@@ -259,7 +259,7 @@ talk:
 
 | Field | Effect |
 |---|---|
-| `set_flags` | Sets world flags (global, shared by all players). |
+| `set_global_flags` | Sets global 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. |
@@ -538,7 +538,7 @@ use_interactions:
       not: true
     message: "You push the heavy iron gate open."
     action:
-      set_flags:
+      set_global_flags:
         gate_open: true
 ```
 
@@ -549,7 +549,7 @@ use_interactions:
   - item_id: dusty_tome
     message: "The bookshelf slides aside, revealing a secret passage!"
     action:
-      set_flags:
+      set_global_flags:
         secret_passage_open: true
 ```
 
diff --git a/building_guide/conditions.md b/building_guide/conditions.md
index 853518b..acfdf57 100644
--- a/building_guide/conditions.md
+++ b/building_guide/conditions.md
@@ -6,17 +6,17 @@ descriptions, and trigger value matching.
 
 ### Simple conditions
 
-A bare `flag:` / `player_flag:` check passes when the flag is **set to a truthy
+A bare `global_flag:` / `player_flag:` check passes when the flag is **set to a truthy
 value** (`true`, a non-zero number, a non-empty string). Add `value:` only when
 you need to match a specific value (e.g. a numeric quest stage). `not: true`
 inverts any check.
 
 ```yaml
-# Check a world flag is set
+# Check a global flag is set
 condition:
   flag: gate_open
 
-# Check a world flag is NOT set
+# Check a global flag is NOT set
 condition:
   flag: gate_open
   not: true
diff --git a/building_guide/doors.md b/building_guide/doors.md
index 3756a13..358001f 100644
--- a/building_guide/doors.md
+++ b/building_guide/doors.md
@@ -16,7 +16,7 @@ use_interactions:
       not: true
     message: "You press the stone button. You hear grinding stone in the distance."
     action:
-      set_flags:
+      set_global_flags:
         secret_door_open: true
 ```
 
@@ -87,7 +87,7 @@ spawns:
     respawn_ticks: 500
 ```
 
-Key difference: the button door uses `flag` (shared state — one player presses, everyone benefits), the key door uses `has_item` (per-player inventory check — each player needs their own key).
+Key difference: the button door uses `global_flag` (shared state — one player presses, everyone benefits), the key door uses `has_item` (per-player inventory check — each player needs their own key).
 
 ---
 
diff --git a/building_guide/hidden_objects.md b/building_guide/hidden_objects.md
index 0adb7d9..b1ed7b4 100644
--- a/building_guide/hidden_objects.md
+++ b/building_guide/hidden_objects.md
@@ -16,7 +16,7 @@ use_interactions:
       not: true
     message: "You pull the lever. A grinding sound echoes from the east."
     action:
-      set_flags:
+      set_global_flags:
         secret_passage_open: true
 ```
 
diff --git a/building_guide/objects.md b/building_guide/objects.md
index af693c4..d377f23 100644
--- a/building_guide/objects.md
+++ b/building_guide/objects.md
@@ -149,7 +149,7 @@ use_interactions:
       not: true
     message: "You push the heavy iron gate open."
     action:
-      set_flags:
+      set_global_flags:
         gate_open: true
 ```
 
@@ -183,7 +183,7 @@ on_look:
         read_sign: true
 ```
 `on_look` fires the action AFTER showing the object's description. It uses the same
-`NodeAction` type as talk nodes — supports `set_player_flags`, `set_flags`,
+`NodeAction` type as talk nodes — supports `set_player_flags`, `set_global_flags`,
 `give_item`, `take_item`, `teleport`, `heal`, `cost`, and everything else in the
 [node action reference](behaviors.md#node-action-reference).
 
@@ -220,7 +220,7 @@ use_interactions:
     message: "You insert the crystal key into the slot. It clicks into place."
     action:
       take_item: crystal_key
-      set_flags:
+      set_global_flags:
         crystal_inserted: true
 ```
 
@@ -235,7 +235,7 @@ use_interactions:
       take_item: ancient_scroll
       set_player_flags:
         quest_complete: true
-      set_flags:
+      set_global_flags:
         temple_door_open: true
 ```
 
@@ -252,7 +252,7 @@ use_interactions:
 
 | Field              | Type           | Description                        |
 | ------------------ | -------------- | ---------------------------------- |
-| `set_flags`        | map[string]any | Set world flags (shared)           |
+| `set_global_flags`        | map[string]any | Set global flags (shared)           |
 | `set_player_flags` | map[string]any | Set player flags (per-character)   |
 | `give_item`        | string         | Give an item to inventory          |
 | `take_item`        | string         | Remove an item from inventory      |
@@ -263,7 +263,7 @@ use_interactions:
 
 | Field         | Description                      |
 | ------------- | -------------------------------- |
-| `flag`        | World flag check                 |
+| `global_flag`        | Global flag check                 |
 | `player_flag` | Per-character flag check         |
 | `has_item`    | Inventory item check             |
 | `value`       | Expected value for flag checks   |
diff --git a/building_guide/rooms.md b/building_guide/rooms.md
index 35fd85a..f77aa42 100644
--- a/building_guide/rooms.md
+++ b/building_guide/rooms.md
@@ -46,7 +46,7 @@ exits:
   southeast: 4
 ```
 
-Conditional exit — blocked until a world flag is set:
+Conditional exit — blocked until a global flag is set:
 ```yaml
 exits:
   north:
@@ -66,7 +66,7 @@ exits:
     blocked_message: "The vault door is locked. You need a key."
 ```
 
-Conditional exit with compound condition — requires both a world flag AND a player flag:
+Conditional exit with compound condition — requires both a global flag AND a player flag:
 ```yaml
 exits:
   north:
@@ -78,7 +78,7 @@ exits:
     blocked_message: "The bridge is out, and the toll collector blocks the path."
 ```
 
-Exit that sets flags when used — `set_flags` / `set_player_flags` are applied
+Exit that sets flags when used — `set_global_flags` / `set_player_flags` are applied
 only when the player actually moves through the exit (not when it's blocked):
 ```yaml
 exits:
@@ -215,7 +215,7 @@ on_enter:
 ```
 
 **Timed sequences.** A step may also carry a `delay` (ticks to wait before it
-fires) and/or set flags (`set_flags` / `set_player_flags`). If any surviving step
+fires) and/or set flags (`set_global_flags` / `set_player_flags`). If any surviving step
 has a delay or sets a flag, the whole sequence runs as a scheduled enter sequence;
 plain message-only scripts still print instantly.
 
@@ -300,7 +300,7 @@ mobs:
 
 ### Room triggers — scripted events when flags change
 
-A room can carry a `triggers:` block. Each trigger watches a player or world flag
+A room can carry a `triggers:` block. Each trigger watches a player or global flag
 and fires a sequence of timed steps when that flag's value changes. See `triggers.md`
 for the full reference.
 
diff --git a/building_guide/state.md b/building_guide/state.md
index 2e0b5cc..fe526bf 100644
--- a/building_guide/state.md
+++ b/building_guide/state.md
@@ -1,6 +1,6 @@
 ## State: World vs Player
 
-**World flags** (`set_flags`, checked with `flag`) are shared by every player on the server. A door opened by one player is open for everyone. A lever pulled once changes the world for all. Stored in memory (`FlagStore`) — **lost on server restart**. Numeric values are compared by coercion (int/int64/float64 are normalized), so a YAML-decoded `3` matches a code-set `int(3)`.
+**Global flags** (`set_global_flags`, checked with `global_flag`) are shared by every player on the server. A door opened by one player is open for everyone. A lever pulled once changes the world for all. Stored in memory (`GlobalFlagStore`) — **lost on server restart**. Numeric values are compared by coercion (int/int64/float64 are normalized), so a YAML-decoded `3` matches a code-set `int(3)`.
 
 **Player flags** (`set_player_flags`, checked with `player_flag`) are per-character. Quest progress, "has read the sign," "paid the toll" — these are different for each player. Saved to the character YAML and persist across logins.
 
diff --git a/building_guide/tips.md b/building_guide/tips.md
index b4abeb9..61c595f 100644
--- a/building_guide/tips.md
+++ b/building_guide/tips.md
@@ -1,6 +1,6 @@
 ## Tips
 
-1. **Use player flags for quest progress, world flags for environmental state.** If a bridge is repaired, that's world state. If a player has read a sign, that's player state.
+1. **Use player flags for quest progress, global flags for environmental state.** If a bridge is repaired, that's world state. If a player has read a sign, that's player state.
 
 2. **Conditions on enter scripts** make rooms feel alive. A guard who only barks the first time, a room that changes after a quest completes.
 
diff --git a/building_guide/triggers.md b/building_guide/triggers.md
index b88f16d..0d227bd 100644
--- a/building_guide/triggers.md
+++ b/building_guide/triggers.md
@@ -8,7 +8,7 @@ value. They come in two flavors:
 - **Global triggers** — defined in `data/triggers/<id>.yaml`. These fire regardless
   of where the flag-setting player is, and can broadcast to all online players.
 
-A trigger watches one flag (`on_player_flag` or `on_flag`). When that flag's value
+A trigger watches one flag (`on_player_flag` or `on_global_flag`). When that flag's value
 actually changes (from unset/falsy to a truthy/new value), the trigger's steps
 begin executing. Setting a flag to the same value it already has does **not** re-fire
 the trigger.
@@ -61,7 +61,7 @@ elapses.
 | `message`          | player | Text sent to the triggering player only. Supports `%p` (player name) and `%v` (flag value) templates. |
 | `broadcast`        | room   | Text sent to everyone in the room. Inline color tags work; `\n` prefix is added automatically.        |
 | `broadcast_global` | world  | Text sent to every online player. Useful for server-wide announcements.                               |
-| `set_flags`        | world  | Mutates world flags (shared by all players).                                                          |
+| `set_global_flags`        | global | Mutates global flags (shared by all players).                                                          |
 | `set_player_flags` | player | Mutates player flags (per-character). Only valid for `on_player_flag` triggers.                       |
 | `spawn_mob`        | room   | Spawns a **transient** mob from a mob definition. See Transient Mobs below.                           |
 | `despawn_mob`      | room   | Removes all trigger-spawned mobs matching the given mob ID (and optionally owner).                    |
@@ -127,24 +127,24 @@ The final step uses both `broadcast` (everyone in the ritual room sees the flash
 and `teleport` + `message` (the triggering player is moved and sees a personal
 message).
 
-#### Example 3: World-flag room trigger — shared environmental event
+#### Example 3: Global-flag room trigger — shared environmental event
 
-A player pulls a lever (sets world flag `floodgate_open`). The room trigger
+A player pulls a lever (sets global flag `floodgate_open`). The room trigger
 broadcasts to everyone in the dam control room:
 
 ```yaml
 # data/rooms/wilderness/dam_control.yaml
 triggers:
-  - on_flag: floodgate_open
+  - on_global_flag: floodgate_open
     steps:
       - broadcast: "Ancient gears grind as the floodgate slowly opens..."
       - delay: 15
         broadcast: "Water thunders through the opening!"
-      - set_flags:
+      - set_global_flags:
           valley_flooded: true
 ```
 
-Because this watches a **world** flag (`on_flag`), it fires once globally when
+Because this watches a **global** flag (`on_global_flag`), it fires once globally when
 the flag is first set — not per-player. Everyone in the room sees the messages.
 
 #### Example 4: "Push button" — trigger that resets itself
@@ -189,26 +189,26 @@ PlayerName has reached level 99 attack!
 
 #### Example 6: World-first boss kill — global broadcast
 
-A boss mob's death sets world flag `world_boss_slain`. A global trigger
+A boss mob's death sets global flag `world_boss_slain`. A global trigger
 announces it to everyone:
 
 ```yaml
 # data/triggers/world_boss_slain.yaml
-on_flag: world_boss_slain
+on_global_flag: world_boss_slain
 steps:
   - broadcast_global: "The Ancient One has been vanquished! The land stirs with new life."
-  - set_flags:
+  - set_global_flags:
       ancient_lands_access: true      # opens a zone for everyone
 ```
 
 #### Example 7: Global trigger with room context
 
 A global trigger can specify a `room` for broadcasts and mob spawns. This is
-useful when a world flag should trigger effects in a specific location:
+useful when a global flag should trigger effects in a specific location:
 
 ```yaml
 # data/triggers/obelisk_activated.yaml
-on_flag: desert_obelisk_charged
+on_global_flag: desert_obelisk_charged
 room: 1200
 steps:
   - broadcast: "The obelisk hums with stored power."
@@ -310,7 +310,7 @@ triggers:
 ```
 
 `despawn_mob` with an owner only removes mobs spawned by that player. Without an
-owner (in world-flag triggers), it removes all matching mobs.
+owner (in global-flag triggers), it removes all matching mobs.
 
 #### Example 11: Fixed-lifetime mob
 
@@ -357,7 +357,7 @@ triggers:
     value: 3
     steps:
       - message: "Stage 3 begins — the temple doors swing open."
-      - set_flags:
+      - set_global_flags:
           temple_open: true
 ```
 
@@ -453,18 +453,18 @@ flag is already at that value.
 
 ### Full Scenario: Server-Wide World Event
 
-A server event progresses through stages. A global trigger chains world flags to
+A server event progresses through stages. A global trigger chains global flags to
 advance the event for everyone.
 
 **Phase 1 trigger:**
 
 ```yaml
 # data/triggers/event_phase1.yaml
-on_flag: event_phase1_start
+on_global_flag: event_phase1_start
 steps:
   - broadcast_global: "The sky darkens as an eclipse begins..."
   - delay: 100
-    set_flags:
+    set_global_flags:
       event_phase2_start: true
 ```
 
@@ -472,11 +472,11 @@ steps:
 
 ```yaml
 # data/triggers/event_phase2.yaml
-on_flag: event_phase2_start
+on_global_flag: event_phase2_start
 steps:
   - broadcast_global: "Monsters pour from the shadows across the land!"
   - delay: 300
-    set_flags:
+    set_global_flags:
       event_phase3_start: true
 ```
 
@@ -484,11 +484,11 @@ steps:
 
 ```yaml
 # data/triggers/event_phase3.yaml
-on_flag: event_phase3_start
+on_global_flag: event_phase3_start
 steps:
   - broadcast_global: "The eclipse passes. The monsters retreat."
   - delay: 50
-    set_flags:
+    set_global_flags:
       event_active: false
 ```
 
@@ -528,7 +528,7 @@ All of these paths activate triggers:
    the same trigger running simultaneously. Starting a new one replaces the old.
 
 4. **Player must be online.** Player-flag triggers only fire for connected
-   players. World-flag triggers fire regardless.
+   players. Global-flag triggers fire regardless.
 
 5. **Room triggers check room.** Room-level triggers only fire when the
    flag-setting player is in that room. This keeps local events local.
@@ -544,6 +544,6 @@ Startup validation checks that trigger `spawn_mob.id` references an existing mob
 definition, `give_item`/`take_item` reference existing items, `teleport` and
 `despawn_rooms` reference existing rooms, and that global trigger IDs are unique.
 
-Validation does NOT check that the watched flags (`on_player_flag` / `on_flag`)
+Validation does NOT check that the watched flags (`on_player_flag` / `on_global_flag`)
 are ever set — those are dynamic, set by runtime gameplay, and can't be statically
 verified.
-- 
cgit v1.2.3