From a6f0ad79e2e3a5b7c11eef1ffc3233f3a2766f77 Mon Sep 17 00:00:00 2001
From: historia <[not public]>
Date: Sun, 14 Jun 2026 22:38:23 -0400
Subject: feat: fractional ticks and server game_speed implemented. potentially
 insanely janky.

---
 data/help/actions.yaml                | 35 +++++++++++++++++++++++++++++++++++
 data/help/left-tinymap.yaml           | 11 -----------
 data/help/left_tinymap.yaml           | 11 +++++++++++
 data/help/queue_actions_silently.yaml | 15 +++++++++++++++
 data/help/queued.yaml                 | 17 +++++++++++++++++
 data/help/search.yaml                 | 17 ++++++++++++-----
 data/help/ticks.yaml                  | 24 ++++++++++++++++++++++++
 7 files changed, 114 insertions(+), 16 deletions(-)
 create mode 100644 data/help/actions.yaml
 delete mode 100644 data/help/left-tinymap.yaml
 create mode 100644 data/help/left_tinymap.yaml
 create mode 100644 data/help/queue_actions_silently.yaml
 create mode 100644 data/help/queued.yaml
 create mode 100644 data/help/ticks.yaml

(limited to 'data/help')

diff --git a/data/help/actions.yaml b/data/help/actions.yaml
new file mode 100644
index 0000000..7a2cbd3
--- /dev/null
+++ b/data/help/actions.yaml
@@ -0,0 +1,35 @@
+name: "actions"
+category: "General"
+description: |
+  The action queue system resolves all gameplay commands on the 600ms game tick
+  instead of instantly. Commands fall into three classes:
+
+  Instant actions — execute immediately, bypassing the tick queue entirely:
+    say, score, inventory, equipment, look, exits, help, map, option,
+    alias, unalias, description, queued
+
+  Free actions — stackable, all execute before active actions:
+    wear, wield, remove, unwear, unwield, style
+    You can queue multiple free actions. They execute in the order you typed them.
+
+  Active actions — only the most recent survives:
+    All other commands (move, attack, mine, chop, fish, cut, use, talk,
+    pull, push, burn, stoke, get, drop, search, quit)
+    If you queue two active actions, the newer one replaces the older one.
+
+  Order of execution each tick:
+    1. Free actions (per player, in order)
+    2. Active actions (globally, sorted by real-time timestamp)
+
+  This means free actions always take effect before active actions, even if
+  you typed the active one first. For example, "attack goblin" then "style
+  aggressive" in the same tick means style applies first, then combat starts.
+
+  Conflict resolution:
+    - If two players attack the same mob on the same tick, the first to
+      queue the command gets the kill.
+    - If multiple players successfully harvest a shared-resource object on
+      the same tick, ALL players get their drops.
+    - If two players try to pick up the same item, the first queued gets it.
+
+  See also: help queued
diff --git a/data/help/left-tinymap.yaml b/data/help/left-tinymap.yaml
deleted file mode 100644
index 689aa89..0000000
--- a/data/help/left-tinymap.yaml
+++ /dev/null
@@ -1,11 +0,0 @@
-name: "left-tinymap"
-category: "Options"
-description: |
-  Show the mini-map on the left side of room descriptions.
-
-  Type:    boolean (on/off)
-  Default: off
-
-  When both tinymap and left-tinymap are enabled, the
-  mini-map appears on the left side of the room description
-  rather than the right.
diff --git a/data/help/left_tinymap.yaml b/data/help/left_tinymap.yaml
new file mode 100644
index 0000000..6810dd1
--- /dev/null
+++ b/data/help/left_tinymap.yaml
@@ -0,0 +1,11 @@
+name: "left_tinymap"
+category: "Options"
+description: |
+  Show the mini-map on the left side of room descriptions.
+
+  Type:    boolean (on/off)
+  Default: off
+
+  When both tinymap and left_tinymap are enabled, the
+  mini-map appears on the left side of the room description
+  rather than the right.
diff --git a/data/help/queue_actions_silently.yaml b/data/help/queue_actions_silently.yaml
new file mode 100644
index 0000000..8101c5c
--- /dev/null
+++ b/data/help/queue_actions_silently.yaml
@@ -0,0 +1,15 @@
+name: "queue_actions_silently"
+category: "Options"
+description: |
+  Controls whether queued game actions produce confirmation messages.
+
+  When on (default): No message is shown when you queue an action. The action
+  simply executes on the next game tick without fanfare.
+
+  When off: A brief "You prepare to X." message is shown for each queued
+  action, confirming that it has been added to the queue.
+
+  Usage: option queue_actions_silently on
+         option queue_actions_silently off
+
+  See also: help queued, help actions, help option
diff --git a/data/help/queued.yaml b/data/help/queued.yaml
new file mode 100644
index 0000000..6859b65
--- /dev/null
+++ b/data/help/queued.yaml
@@ -0,0 +1,17 @@
+name: "queued"
+category: "General"
+description: |
+  Shows your pending actions that will execute on the next game tick.
+
+  Usage: queued
+
+  All gameplay actions are resolved once per tick (600ms). Free actions
+  stack (you can queue several), while active actions replace each other.
+  Instant actions execute immediately.
+
+  The queued command shows:
+    - Free actions you've stacked up (e.g. wear, remove, style)
+    - Your active action that will execute after all free actions
+    - Your position in the global active action queue (for conflict resolution)
+
+  See also: help actions
diff --git a/data/help/search.yaml b/data/help/search.yaml
index 42eec52..96bd008 100644
--- a/data/help/search.yaml
+++ b/data/help/search.yaml
@@ -1,12 +1,19 @@
 name: "search"
 category: "Items"
 description: |
-  Search an item in your inventory.
+  Search a searchable item in your inventory.
 
   Usage: search <item>
 
-  Example: search nest, search birds nest
+  Example: search nest, search cracker
 
-  Opens a searchable item (currently only bird's nests) and rolls on its
-  drop table for loot. The item is consumed in the process. Items found
-  go to inventory or fall to the ground if full.
+  Searching takes a few game ticks to complete. On each tick, you will
+  see progress messages until the action finishes and you receive your
+  reward. If you are interrupted during a search (by combat, movement,
+  or another action), the item is NOT consumed.
+
+  Currently searchable items:
+    bird's nest       - Credits (various amounts)
+    christmas cracker - Random party hat + bonus item
+
+  Items found go to inventory or fall to the ground if full.
diff --git a/data/help/ticks.yaml b/data/help/ticks.yaml
new file mode 100644
index 0000000..fd128c2
--- /dev/null
+++ b/data/help/ticks.yaml
@@ -0,0 +1,24 @@
+name: "ticks"
+category: "General"
+description: |
+  All timed game actions use a tick-based system. Each game tick runs at a
+  configurable interval (default 600ms). Actions like gathering, combat, and
+  crafting advance on each tick.
+
+  Fractional ticks allow tool speeds and timers to be non-integer values.
+  For example, a tool with speed 4.5 has a 50% chance of taking 4 ticks
+  and a 50% chance of taking 5 ticks per action cycle. The average
+  converges to 4.5 over many actions. This applies to:
+
+    - Tool speed (gathering, firemaking)
+    - Weapon speed (combat)
+    - Production wait timers (use behaviors)
+    - Search timers
+    - Depletion and respawn timers
+
+  The game_speed config option scales ALL tick timers proportionally.
+  A game_speed of 2.0 makes everything resolve twice as fast; 0.5 makes
+  everything twice as slow.
+
+  Use the "option" command to configure tick-related display settings.
+  Use "help option" for a list of all player options.
-- 
cgit v1.2.3