BlueGit

timfa questward

Expand scripts plan: waypoints, visible find, station inventory rules.

timfa Tim Falken · pushed by timfa

Authored 2026-08-27 · 2 months ago

Hash
910159562bc8dfd87d53650e0b162bbae39f05a7
Parent
7d167316
2 files changed +762 −601
docs/FEATURES.md +2 −2
@@ -259,7 +259,7 @@ Each entry is a short note on behaviour and where the code lives. Update this fi
259 259 ## Crafting stations
260 260
261 261 **Status:** partial (furnace, anvil, woodworking, crafting, spinning wheel, loom, tailor bench live)
262 **Spec:** Furnace / anvil / woodworking-bench / crafting-bench / spinning-wheel / loom / tailor-bench blocks + adjacency craft panel. Recipes in `stationRecipes.js`. Furnace/anvil/woodworking/crafting craft timer = `smeltingDurationMs` (`rank × 2s`) when `xpMaterial` is set; other stations still use `CRAFT_DURATION_MS` (2s) / UI/dev only (`__craftDev`). Woodworking shapes components (handles); crafting bench joins finished parts (pickaxe/axe head + handle). Spinning wheel / loom / tailor use Tailoring. **Anvil**, **woodworking**, and **tailor** craft UIs use a material dropdown so tier variants share one recipe cell (plant clippers = 1 bar per metal tier).
262 **Spec:** Furnace / anvil / woodworking-bench / crafting-bench / spinning-wheel / loom / tailor-bench blocks + adjacency craft panel. Recipes in `stationRecipes.js`. Furnace/anvil/woodworking/crafting craft timer = `smeltingDurationMs` (`rank × 2s`) when `xpMaterial` is set; other stations still use `CRAFT_DURATION_MS` (2s) / UI/dev only (`__craftDev`). Woodworking shapes components (handles); crafting bench joins finished parts (pickaxe/axe head + handle). Spinning wheel / loom / tailor use Tailoring. **Anvil**, **woodworking**, and **tailor** craft UIs use a material dropdown so tier variants share one recipe cell (plant clippers = 1 bar per metal tier). **Hard rule (all stations + cauldron, player and scripts):** items in station slots are never committed out of the inventory — slots are a reservation/view over the bag. Materials are consumed only when the craft/brew **succeeds**. Closing the UI, cancelling, or dying mid-craft/brew cannot destroy reserved mats. Station progress is **per player**, not tile-global.
263 263 **TODO:** oven/campfire burn; dedicated station sprites where still placeholder.
264 264 **Code:** `shared/definitions/craftingStations.js`, `shared/definitions/tiles.js`, `server/src/crafting/service.js`, `client/src/play/crafting.js`
265 265
@@ -353,5 +353,5 @@ Use later when deciding which ingredients fit which potions. Tiers: **2 / 3 / 3
353 353 ## Player scripting (AFK / offline)
354 354
355 355 **Status:** not implemented
356 **Spec:** Full language + UI + online/AFK/offline behaviour is documented in [`docs/SCRIPTS.md`](SCRIPTS.md). Scripts are a sandboxed, server-interpreted language that emits normal player intents (gather, craft/alchemy, combat, bank/cheques/market, spells, courier, chat, …). `go` and gather/craft block until done; `wait until` covers every `if` condition. Death while scripting stops the script and fully logs the instance out (respawn UI on next login). Friends/barber/follow/graphics/editor are out of scope. Architecture hooks remain in design doc §18.
356 **Spec:** Full language + UI + online/AFK/offline behaviour is documented in [`docs/SCRIPTS.md`](SCRIPTS.md). Scripts are a sandboxed, server-interpreted language that emits normal player intents. Names match **exactly** (case-insensitive). `find` / nearest only searches the **visible 3×3** chunks (what a player sees). `@` variables + `set` hold targets/coords for waypoints; `go` fails beyond **2 chunks** (`Too far away.`). Universal `can <action>` dry-runs any verb. Station/cauldron state is **per player**; station slots never commit items out of the bag until craft/brew succeeds. AFK auto-start after **30 minutes** idle. Death while scripting stops the script and fully logs the instance out. Friends/barber/follow/graphics/editor are out of scope. Architecture hooks remain in design doc §18.
357 357 **Code:** — (planned: `shared/scripts/`, `server/src/scripts/`, `client/src/play/scripts.js`, state DB script rows)
@@ -259,7 +259,7 @@ Each entry is a short note on behaviour and where the code lives. Update this fi
259## Crafting stations
259## Crafting stations
260
260
261**Status:** partial (furnace, anvil, woodworking, crafting, spinning wheel, loom, tailor bench live)
261**Status:** partial (furnace, anvil, woodworking, crafting, spinning wheel, loom, tailor bench live)
262**Spec:** Furnace / anvil / woodworking-bench / crafting-bench / spinning-wheel / loom / tailor-bench blocks + adjacency craft panel. Recipes in `stationRecipes.js`. Furnace/anvil/woodworking/crafting craft timer = `smeltingDurationMs` (`rank × 2s`) when `xpMaterial` is set; other stations still use `CRAFT_DURATION_MS` (2s) / UI/dev only (`__craftDev`). Woodworking shapes components (handles); crafting bench joins finished parts (pickaxe/axe head + handle). Spinning wheel / loom / tailor use Tailoring. **Anvil**, **woodworking**, and **tailor** craft UIs use a material dropdown so tier variants share one recipe cell (plant clippers = 1 bar per metal tier).
262**Spec:** Furnace / anvil / woodworking-bench / crafting-bench / spinning-wheel / loom / tailor-bench blocks + adjacency craft panel. Recipes in `stationRecipes.js`. Furnace/anvil/woodworking/crafting craft timer = `smeltingDurationMs` (`rank × 2s`) when `xpMaterial` is set; other stations still use `CRAFT_DURATION_MS` (2s) / UI/dev only (`__craftDev`). Woodworking shapes components (handles); crafting bench joins finished parts (pickaxe/axe head + handle). Spinning wheel / loom / tailor use Tailoring. **Anvil**, **woodworking**, and **tailor** craft UIs use a material dropdown so tier variants share one recipe cell (plant clippers = 1 bar per metal tier). **Hard rule (all stations + cauldron, player and scripts):** items in station slots are never committed out of the inventory — slots are a reservation/view over the bag. Materials are consumed only when the craft/brew **succeeds**. Closing the UI, cancelling, or dying mid-craft/brew cannot destroy reserved mats. Station progress is **per player**, not tile-global.
263**TODO:** oven/campfire burn; dedicated station sprites where still placeholder.
263**TODO:** oven/campfire burn; dedicated station sprites where still placeholder.
264**Code:** `shared/definitions/craftingStations.js`, `shared/definitions/tiles.js`, `server/src/crafting/service.js`, `client/src/play/crafting.js`
264**Code:** `shared/definitions/craftingStations.js`, `shared/definitions/tiles.js`, `server/src/crafting/service.js`, `client/src/play/crafting.js`
265
265
@@ -353,5 +353,5 @@ Use later when deciding which ingredients fit which potions. Tiers: **2 / 3 / 3
353## Player scripting (AFK / offline)
353## Player scripting (AFK / offline)
354
354
355**Status:** not implemented
355**Status:** not implemented
356**Spec:** Full language + UI + online/AFK/offline behaviour is documented in [`docs/SCRIPTS.md`](SCRIPTS.md). Scripts are a sandboxed, server-interpreted language that emits normal player intents (gather, craft/alchemy, combat, bank/cheques/market, spells, courier, chat, …). `go` and gather/craft block until done; `wait until` covers every `if` condition. Death while scripting stops the script and fully logs the instance out (respawn UI on next login). Friends/barber/follow/graphics/editor are out of scope. Architecture hooks remain in design doc §18.
356**Spec:** Full language + UI + online/AFK/offline behaviour is documented in [`docs/SCRIPTS.md`](SCRIPTS.md). Scripts are a sandboxed, server-interpreted language that emits normal player intents. Names match **exactly** (case-insensitive). `find` / nearest only searches the **visible 3×3** chunks (what a player sees). `@` variables + `set` hold targets/coords for waypoints; `go` fails beyond **2 chunks** (`Too far away.`). Universal `can <action>` dry-runs any verb. Station/cauldron state is **per player**; station slots never commit items out of the bag until craft/brew succeeds. AFK auto-start after **30 minutes** idle. Death while scripting stops the script and fully logs the instance out. Friends/barber/follow/graphics/editor are out of scope. Architecture hooks remain in design doc §18.
357**Code:** — (planned: `shared/scripts/`, `server/src/scripts/`, `client/src/play/scripts.js`, state DB script rows)
357**Code:** — (planned: `shared/scripts/`, `server/src/scripts/`, `client/src/play/scripts.js`, state DB script rows)
docs/SCRIPTS.md +760 −599
@@ -1,599 +1,760 @@
1 # Player scripts (AFK / offline)
2
3 **Status:** not implemented (design only)
4 **Related:** `tile_mmo_server_technical_design_v0.6.md` §18 (controller abstraction, offline entity, sandbox rules)
5
6 Scripts are a **sandboxed language** interpreted on the **server**. They never mutate world state directly; they emit the same player **intents** as a human client (`moveTo`, gather, craft, attack, shop, equip, …). The server validates every step.
7
8 This document is the product + language spec for implementation.
9
10 ---
11
12 ## 1. Goals
13
14 - Automate simple loops: gather → bank/craft → fight → recover.
15 - Run **while online** (watch + stop bar), **while AFK** (idle 5+ minutes), or **while offline** (character stays in the world, max 1 hour).
16 - Keep the language **small**, readable, and hard to misuse.
17 - Fail loudly: toast (online) or pigeon letter (offline), with line + operation + reason.
18
19 ---
20
21 ## 2. Player UI
22
23 ### 2.1 Scripts button
24
25 - HUD control **Scripts** opens the Scripts panel.
26 - Panel lists the player’s saved scripts (name + badges for Offline / AFK flags).
27 - Actions per script: **Edit**, **Delete**, **Run** (online).
28 - **New script** creates an empty script and opens the editor.
29
30 ### 2.2 Script editor
31
32 - Name field.
33 - Text area with **syntax highlighting** (keywords, strings, numbers, comments, labels).
34 - Flags (mutually independent; at most one script should be marked for each role — marking one clears that flag on others):
35 - **Run this while offline** — eligible on logout confirmation.
36 - **Run while AFK** — auto-starts after 5 minutes with no player actions.
37 - **Save** / **Cancel**.
38
39 ### 2.3 Online run bar
40
41 When a script is running (started manually, AFK auto-start, or resumed after re-login onto an offline script):
42
43 - Fixed bar at the **bottom** of the screen.
44 - Shows: script name, **current line** (number + source text), **Stop**.
45 - Manual player intents (move, attack, gather, …) **stop** the script (treat as cancel), except pure camera/UI (open bag, zoom, settings).
46
47 ### 2.4 Logout confirmation
48
49 On logout while in the world:
50
51 1. Modal: **Are you sure you want to log out?**
52 - **No** — stay.
53 - **Yes** — log out.
54 - Checkbox (default **unchecked**): **Run offline script**
55 - Enabled only if the player has a script marked **Run this while offline**.
56 2. If the checkbox is checked, show an extra **red** line:
57 **Running a script means your character remains in the world and can still be attacked!**
58 3. Confirming with the checkbox checked starts/continues the offline script on that character (see §4).
59
60 ---
61
62 ## 3. Modes
63
64 | Mode | How it starts | Character in world | Client |
65 |------|---------------|--------------------|--------|
66 | **Online** | Scripts panel → Run | Yes | Connected; run bar visible |
67 | **AFK** | No gameplay intents for **5 minutes**, and an AFK-marked script exists | Yes | Still connected; run bar appears when script starts |
68 | **Offline** | Logout with offline checkbox | Yes (no NetworkIdentity; keeps ChunkLoader) | Disconnected |
69
70 **AFK timer:** reset on any **gameplay intent** sent by the player (move, attack, gather, craft, shop, equip, cast, pickup, talk, …). Opening UI / scrolling chat does not reset AFK if those are not intents; prefer resetting on any outbound play command for simplicity.
71
72 **Offline duration:** max **1 hour** from offline-script start (or remaining time after restart rehydrate). Then: stop script, despawn character, persist as a normal logout.
73
74 **Re-login during offline script:** attach the client to the existing entity; keep the script running; show the run bar so the player can Stop.
75
76 ---
77
78 ## 4. Errors
79
80 ### 4.1 Message shape
81
82 Always:
83
84 ```text
85 Line <n>: <operation> — <reason>
86 ```
87
88 Example:
89
90 ```text
91 Line 12: mine — No reachable iron ore nearby.
92 ```
93
94 ### 4.2 Online / AFK (client connected)
95
96 - Stop the script.
97 - Show a **persistent toast** (stays until the player dismisses it) with the error message.
98
99 ### 4.3 Offline (no client)
100
101 - Stop the script.
102 - Remove the character from the world (normal offline persist).
103 - Queue a **pigeon letter**:
104 - Author display name: **Frederick**
105 - Role flavour: manager of Idle Gaming (author line / signature as other system letters do)
106 - Body:
107 `Unfortunately, your script encountered an error.`
108 then a blank line, then the error message from §4.1.
109
110 ---
111
112 ## 5. Language overview
113
114 - Line-oriented, case-insensitive **keywords**.
115 - One statement per line (blank lines and comments allowed).
116 - Comments: `# ...` to end of line.
117 - Strings: `"double quotes"` (names of blocks, mobs, items). Matching is **case-insensitive** display-name match unless noted.
118 - Numbers: integers (`10`, `100`).
119 - Labels: `label name_here` — name is letters, digits, underscore.
120 - No variables in v1 except **implicit targets** (current block / mob / ground item) and loop counters internal to `for` / `while`.
121 - No user-defined functions in v1.
122 - Sandbox: **not** JavaScript; custom interpreter only (§18.7 design doc).
123
124 ### 5.1 Implicit targets
125
126 The script keeps three optional targets (cleared when a new target of that kind is set, or on error/stop):
127
128 | Target | Set by | Used by |
129 |--------|--------|---------|
130 | **Block** | `find block "..."` | `go`, `mine`, `chop`, `harvest`, `craft`, `in range block` |
131 | **Mob** | `find mob "..."` | `go`, `attack`, `buy`, `sell`, `in range mob` |
132 | **Ground** | `find ground "..."` | `go`, `take`, `use`, `in range ground` |
133
134 `go` without a kind uses the **most recently set** target. Prefer explicit forms when ambiguous: `go block`, `go mob`, `go ground`.
135
136 ---
137
138 ## 6. Statements (v1)
139
140 ### 6.1 Targeting
141
142 | Statement | Meaning |
143 |-----------|---------|
144 | `find block "Iron ore"` | Closest **reachable** block whose display name matches. Sets block target. Fails if none. |
145 | `find mob "Shopkeeper"` | Closest living mob/NPC whose name matches. Sets mob target. Fails if none. |
146 | `find ground "Log"` | Closest ground item whose display name matches. Sets ground target. Fails if none. |
147
148 “Closest” = Chebyshev distance from the player, then path-reachable. Unreachable candidates are skipped.
149
150 ### 6.2 Movement
151
152 | Statement | Meaning |
153 |-----------|---------|
154 | `go` | Path to the last set target (block / mob / ground). **Blocks** until arrived or fails (blocked / lost / unreachable). |
155 | `go block` / `go mob` / `go ground` | Same, explicit target kind. Also **blocks** until arrival. |
156 | `run on` / `run off` | Toggle run gait (same rules as player: needs stamina). |
157
158 Arrival = standing on the tile (ground item / interactable) or adjacent where the game requires adjacency (stations, melee, gather nodes). Any other `move`-style path the script starts uses the same **wait-until-arrived** rule.
159
160 ### 6.3 Gathering & world interact
161
162 | Statement | Meaning |
163 |-----------|---------|
164 | `mine` | Gather/mine the targeted **block** (ore boulder, etc.). **Blocks** until finished or fails. |
165 | `chop` | Fell the targeted tree block. **Blocks** until finished. |
166 | `harvest` | Pick/harvest the targeted plant/herb/flower/cotton block. **Blocks** until finished. |
167 | `take` | Pick up the targeted **ground** item into the bag. |
168 | `use` | Interact with the targeted **ground** item if it has a use (e.g. light a log). |
169
170 Exact gather verb must match what the block supports; wrong verb → error (`chop — That is not a tree.`).
171
172 ### 6.4 Crafting stations & alchemy
173
174 **Principle:** script steps mirror what a player does in the UI. No free shortcuts that skip materials, skill, adjacency, or recipe knowledge.
175
176 #### Crafting stations (furnace, anvil, woodworking, bench, spinning wheel, loom, tailor, leatherworking, …)
177
178 | Statement | Meaning |
179 |-----------|---------|
180 | `craft "Bronze bar"` | At the targeted station **block**, start the same craft the player would (one product). **Blocks** until finished or fails (not at station, unknown recipe, missing mats, skill too low). |
181 | `can craft "Bronze bar"` | Condition only. True if that craft would succeed **right now**. |
182 | `craft "Cotton sweater" dye` | **Tailor only:** craft with dyeing on. Uses a **random** dye charge from the bag (no colour picker). **Fails** if dyeing is requested and the bag has no dye uses left. |
183 | `craft "Cotton sweater"` | Tailor (or other station) **without** dyeing. |
184
185 #### Alchemy cauldron — manual steps (1:1 with UI)
186
187 Require a targeted cauldron (find + go / adjacency), same as opening the cauldron as a player.
188
189 | Statement | Meaning |
190 |-----------|---------|
191 | `cauldron insert "Thyme"` | Insert that ingredient from the bag. |
192 | `cauldron heat` | Heat. |
193 | `cauldron stir` | Stir. |
194 | `cauldron cool` | Cool. |
195 | `cauldron bottle` | Bottle into an empty glass bottle. **Blocks** until done. |
196 | `cauldron clear` | Clear/abandon the brew if the UI allows it. |
197
198 Step order and outcomes match humans: correct sequence → potion (with Alchemy skill roll); wrong sequence → unstable brew. Scripts get **no** easier success path.
199
200 Example (same steps a player would click):
201
202 ```text
203 find block "Cauldron"
204 go block
205 cauldron insert "Thyme"
206 cauldron heat
207 cauldron insert "Mint"
208 cauldron stir
209 cauldron bottle
210 ```
211
212 #### Named `brew` — only with a recipe paper in the bag
213
214 | Statement | Meaning |
215 |-----------|---------|
216 | `brew "Lesser health tonic"` | Allowed **only** if the inventory contains a **recipe paper** for that potion. Then run that paper’s recorded steps and bottle (consume herbs, bottle, skill checks as usual). **Fails immediately** if no matching recipe is in the bag (`brew — No recipe for that in your bag.`). |
217
218 Without a recipe item, authors must write the `cauldron …` steps themselves. `brew` is “follow this paper,” not free knowledge of the recipe.
219
220 #### Dyes (flower list, same as dye tab)
221
222 | Statement | Meaning |
223 |-----------|---------|
224 | `cauldron dye ["White flower", "Yellow flower", "Yellow flower"]` | Make dye from that multiset of flowers (here: 1 white + 2 yellow). List order = insert order; repeat a name for more of the same flower. Consumes flowers from the bag; colour/yield rules match the normal dye UI. Fails if flowers missing, not at cauldron, or bottling not possible. |
225
226 List syntax: `[ "...", "..." ]`.
227
228 ### 6.5 Combat & shops
229
230 | Statement | Meaning |
231 |-----------|---------|
232 | `attack` | Attack the targeted mob (player Attack intent). Does **not** wait for the kill by itself — use `wait until target dead or 60` (§6.12). |
233 | `stop attack` | Cancel the current attack engage (player cancel-attack). |
234 | `buy "Feather" 10` | Buy quantity from targeted shop mob. Fails if no shop, not in range, can’t afford, or not stocked. |
235 | `sell "Soft leather" 5` | Sell quantity to targeted shop mob (if it buys). |
236
237 **Follow** is intentionally **not** supported.
238
239 ### 6.6 Inventory, gear & vitals
240
241 | Statement | Meaning |
242 |-----------|---------|
243 | `equip "Bronze pickaxe"` | Equip a matching item from the bag into its proper slot. Fails if missing or not equippable. |
244 | `unequip weapon` | Clear that equipment **slot** into the bag. Slots: `head`, `chest`, `legs`, `boots`, `weapon`, `offhand` (same as game). **Fails if the bag has no free space.** |
245 | `drink "Lesser health tonic"` | Drink a matching consumable from the bag. |
246 | `eat "Apple"` | Eat a matching food from the bag. |
247 | `drop "Tin ore" 5` | Drop quantity from the bag onto the ground. |
248 | `read "Spark spellbook"` | Read a spellbook from the bag to learn its spell (same as player). Fails if missing, already known, or requirements not met. |
249 | `if health below 30` … | See control flow. |
250 | `if stamina below 5` … | See control flow. |
251
252 ### 6.7 Range checks & queries
253
254 | Statement | Meaning |
255 |-----------|---------|
256 | `if in range block "Furnace"` | True if a matching block exists within interaction/path range. |
257 | `if in range mob "Deer"` | True if a matching living mob is within **15 tiles** Chebyshev. |
258 | `if in range ground "Bones"` | True if a matching ground item is within **15 tiles**. |
259 | `if in range item "Bronze bar"` | True if the bag contains that item (quantity ≥ 1). |
260 | `if bag has "Tin ore" at least 10` | Bag quantity check. |
261 | `if bag has "Tin ore" below 10` | Bag quantity check. |
262 | `if target health below 20` | Targeted **mob** current HP below N. Fails the condition (false) if no mob target; does not hard-error. |
263 | `if target dead` | Targeted mob is gone or at 0 HP. |
264
265 ### 6.8 Bank, cheques, market, social economy
266
267 Requires being at / having path-interacted with the right block where the game requires it (bank counter, bounty office, marketplace).
268
269 | Statement | Meaning |
270 |-----------|---------|
271 | `bank deposit "Tin ore" 20` | Move quantity from bag → vault. |
272 | `bank withdraw "Tin ore" 20` | Move quantity from vault → bag. |
273 | `write cheque "Tin ore" 50` | Write a cheque reserving that item+qty from the **bank (vault)**. Fails if the vault lacks enough. |
274 | `redeem cheque` | Redeem a written cheque from the bag at a bank (goods → vault), same as player. |
275 | `market sell "Tin ore" 10 for 8` | Place sell order (qty, min unit price). Escrows goods + listing fee like the UI. |
276 | `market buy "Tin ore" 10 for 12` | Place buy order (qty, max unit price). Escrows coins like the UI. |
277 | `market cancel sell` / `market cancel buy` | Cancel the character’s open order of that side (or nearest matching — prefer cancelling by item name if multiple: `market cancel sell "Tin ore"`). |
278 | `raise bounty on "Ada Worker" 100` | Raise bounty (near bounty office, pays from bag). |
279 | `send pigeon to bank` | Courier cargo to own bank (same rules as UI). |
280 | `send pigeon to "Ada Worker"` | Courier to that character; payload prefers a written letter, else a cheque (§13). |
281 | `write letter "..."` | Write body onto a **blank letter** in the bag (fails if none); does not send. |
282 | `say "hello"` | Local chat say. |
283
284 ### 6.9 Spells
285
286 | Statement | Meaning |
287 |-----------|---------|
288 | `cast "Light"` | Cast on the targeted **block** tile (tile-target spells). Approaches into range if needed (same as player cast). **Blocks** until cast attempt resolves; **fizzle is not an error** (line completes). |
289 | `cast "Spark" on mob` | Cast entity-target spell on the mob target. |
290 | `cast "Light" on block` | Explicit tile target = targeted block’s tile. |
291
292 Fails if unknown spell, not learned, on cooldown, out of range with no path, or wrong target kind.
293
294 ### 6.10 Labels & jumps
295
296 | Statement | Meaning |
297 |-----------|---------|
298 | `label camp` | Declare label `camp`. |
299 | `goto camp` | Jump to that label. |
300
301 Forward and backward jumps allowed. Jumping into/out of loops is **disallowed** (error if attempted).
302
303 ### 6.11 Control flow
304
305 ```text
306 if health below 30
307 goto heal
308 end
309
310 if stamina below 5
311 run off
312 end
313
314 if can craft "Bronze bar"
315 craft "Bronze bar"
316 end
317
318 if in range item "Bronze pickaxe"
319 equip "Bronze pickaxe"
320 end
321
322 for 10
323 find block "Tin ore"
324 go block
325 mine
326 end
327
328 while in range mob "Rat"
329 find mob "Rat"
330 go mob
331 attack
332 wait until target dead or 60
333 end
334 ```
335
336 Rules:
337
338 - Blocks end with `end`.
339 - `if` body runs when the condition is true; no `else` (use a second `if` / `goto`).
340 - `for N` — repeat body **N** times (N ≥ 1, max **1000**).
341 - `while <condition>` — repeat while condition true; **max 1000** iterations per `while` then error (`while — Too many repeats.`).
342 - Conditions:
343 `health below N` · `stamina below N` · `can craft "..."` · `in range block|mob|ground|item "..."` · `bag has "..." at least|below N` · `target health below N` · `target dead`
344
345 ### 6.12 Waiting (`wait` / `wait until`)
346
347 | Statement | Meaning |
348 |-----------|---------|
349 | `wait 2` | Pause **2 seconds** (server time). Max **60** per wait. |
350 | `wait until arrived or 30` | Block until the current path finishes (usually redundant after `go`, which already waits). |
351 | `wait until gathered or 120` | Block until the active mine/chop/harvest completes. |
352 | `wait until crafted or 120` | Block until the active station craft / `brew` / `cauldron bottle` completes. |
353 | `wait until target dead or 60` | Block until the mob target is dead or despawned. Fails if no mob target. |
354 | `wait until health at least 50 or 120` | Block until own HP ≥ N. |
355 | `wait until stamina at least 5 or 60` | Block until stamina ≥ N. |
356 | `wait until in range item "Bronze bar" or 60` | Block until bag has that item. |
357 | `wait until in range mob "Deer" or 30` | Block until such a mob is in range. |
358 | `wait until bag has "Tin ore" at least 10 or 300` | Block until quantity met. |
359 | `wait until can craft "Bronze bar" or 60` | Block until craft would succeed at current station target. |
360
361 **Principle:** every boolean condition usable in `if` / `while` is also valid after `wait until`. Extend this set whenever new conditions ship.
362
363 **Timeout is mandatory:** every `wait until` must end with `or <seconds>` (1–300). Bare `wait until …` without `or N` is a **parse error**. On timeout → script error (`wait until — Timed out.`).
364
365 `go` / gather / `craft` / `brew` already **block** like a built-in wait for their own completion (they have natural end conditions; no separate `or N` on those verbs).
366
367 ### 6.13 Utility
368
369 | Statement | Meaning |
370 |-----------|---------|
371 | `stop` | End the script successfully (no error letter). |
372
373 ---
374
375 ## 7. Death while a script is running
376
377 If the character **dies** for any reason while a script is active (online, AFK, or offline):
378
379 1. **Stop** the script immediately (not an “error letter” unless death was caused mid-op failure — death itself is a clean stop).
380 2. **Fully log the instance out** of the world (despawn entity, persist dead flag / position as normal death logout).
381 3. When the player next connects, they see the normal **respawn** screen — no auto-respawn from scripts.
382
383 There is **no** `respawn` script command.
384
385 ---
386
387 ## 8. Example script
388
389 ```text
390 # Tin loop with panic flee
391 label start
392 equip "Bronze pickaxe"
393 run on
394
395 for 20
396 if health below 25
397 goto flee
398 end
399 find block "Tin ore"
400 go block
401 mine
402 if in range ground "Tin ore"
403 find ground "Tin ore"
404 go ground
405 take
406 end
407 end
408 stop
409
410 label flee
411 run on
412 drink "Lesser health tonic"
413 stop attack
414 find block "Bank"
415 go block
416 bank deposit "Tin ore" 999
417 stop
418 ```
419
420 ---
421
422 ## 9. Syntax highlighting (editor)
423
424 Highlight at least:
425
426 | Class | Examples |
427 |-------|----------|
428 | Keyword | `find`, `go`, `mine`, `chop`, `harvest`, `craft`, `brew`, `cauldron`, `attack`, `buy`, `sell`, `equip`, `unequip`, `drink`, `eat`, `drop`, `read`, `cast`, `bank`, `market`, `write`, `redeem`, `raise`, `send`, `say`, `label`, `goto`, `if`, `end`, `for`, `while`, `wait`, `stop`, `run`, `take`, `use`, `can` |
429 | Subkeyword | `block`, `mob`, `ground`, `item`, `health`, `stamina`, `below`, `at`, `least`, `in`, `range`, `on`, `off`, `until`, `or`, `arrived`, `gathered`, `crafted`, `target`, `dead`, `deposit`, `withdraw`, `cheque`, `pigeon`, `bounty`, `sell`, `buy`, `cancel`, `insert`, `heat`, `stir`, `cool`, `bottle`, `clear`, `dye` |
430 | String | `"..."` |
431 | List | `[ "...", "..." ]` (flower lists for `cauldron dye`) |
432 | Number | `10`, `30` |
433 | Comment | `# ...` |
434 | Label name | after `label` / `goto` |
435 | Slot name | after `unequip` (`weapon`, `head`, …) |
436
437 Invalid lines can be marked with a subtle error underline on Save (optional v1).
438
439 ---
440
441 ## 10. Persistence & limits
442
443 - Scripts stored per character in state DB (name, source text, flags, updatedAt).
444 - Soft caps (suggested): **20** scripts / character, **200** lines / script, **4 KB** source.
445 - Offline script runtime state: program counter, targets, loop stack, `offlineUntil` timestamp — rehydrated on server restart (§18.6).
446 - Instruction budget: small per simulation tick (at most one **blocking** wait/path/gather/craft at a time; non-blocking lines burst with a low cap).
447
448 ---
449
450 ## 11. Authority & safety (implementation notes)
451
452 - Interpreter runs only on the server.
453 - Every gameplay effect goes through existing command handlers.
454 - No filesystem, network, `eval`, or shared mutable globals across characters.
455 - Name matching uses the same display names players see in tooltips / shops.
456 - Script controller and client controller: only one produces intents at a time; **any manual gameplay intent stops** the script.
457 - Offline `say` / pigeon / bounty: same validation as players; add rate limits if abused.
458
459 ---
460
461 ## 12. Implementation plan (phased)
462
463 1. **Data + UI shell** — CRUD scripts, flags, editor with highlighting, no execution.
464 2. **Online runner** — interpreter + run bar + stop; `find` / `go` (blocking) / `wait` / `wait until` / `label` / `goto` / `stop`.
465 3. **Gather + gear + vitals** — `mine` / `chop` / `harvest` / `equip` / `unequip` / `drink` / `eat` / `if health|stamina`.
466 4. **Combat + shops + craft/alchemy** — stations via `craft` (tailor `dye` flag); cauldron via step verbs + recipe-gated `brew` + `cauldron dye [...]`.
467 5. **Loops + range + bag/target queries**.
468 6. **Bank, cheques, market, spells, pigeon, chat, bounty, spellbooks**.
469 7. **AFK auto-start** — 5-minute idle.
470 8. **Offline logout flow** — modal, entity retention, 1-hour cap, re-login attach, error pigeon, **death → full logout**.
471
472 ---
473
474 ## 13. Open choices (resolve during implementation)
475
476 Resolved defaults (change only with a good reason):
477
478 | Topic | Decision |
479 |-------|----------|
480 | `in range mob/ground` radius | **15** tiles Chebyshev |
481 | AFK timer vs Scripts panel | Opening the panel does **not** reset idle |
482 | Name collisions | **Closest** reachable/living match wins |
483 | `wait until` timeout | **Required** form: `wait until <cond> or <seconds>` (max 300). Bare `wait until` without `or N` is a **parse error** so offline scripts cannot hang forever |
484 | `cast` fizzle | **Not** a script error — line completes; use `if` / skill checks if you care |
485 | Quantity overflow (`bank deposit "Tin ore" 999` with only 5) | Deposit/withdraw/sell/buy **as many as possible up to N**; error only if **zero** moved |
486 | `redeem cheque` with several cheques | Redeem the **first** written cheque in bag order |
487 | `market cancel sell "Tin ore"` | Cancel the **oldest** open sell order for that item name |
488 | `send pigeon to "Name"` | Payload = **one** selected bag item: prefer a written **letter** if present, else a **cheque**, else fail asking for a letter/cheque (`send pigeon — Carry a letter or cheque to send.`) |
489 | `write letter "..."` | Writes onto a **blank letter** in the bag (fails if none); does not send |
490 | Editing a script while it runs | Save applies next **Run** only; running copy is a snapshot |
491 | AFK start while a script already runs | Do **not** start a second script |
492 | Offline logout while a script already runs online | Offline flag continues **that** run (same PC); do not restart from line 1 |
493
494 Still soft:
495
496 - Exact flower **display names** in `cauldron dye` must match item defs (document in editor autocomplete later).
497
498 ---
499
500 ## 14. Out of scope
501
502 | Area | Reason |
503 |------|--------|
504 | **Follow** | Not needed for scripts |
505 | **Friends** | Social; low AFK value |
506 | **Barber / hair** | Cosmetics |
507 | **Inspect / social panel** | Not needed for AFK |
508 | **Graphics settings** | Client-only |
509 | **World editor** | Admin |
510 | **`respawn` command** | Death always full-logout; player uses respawn UI on next login |
511 | **User variables / functions** | v1 stays line+label only; revisit if scripts become unreadable |
512
513 Script steps should stay aligned with player UI actions; never add a verb that skips a check the human UI enforces (recipe paper for `brew`, random dye only for tailor, etc.).
514
515 ### Still fine to add later if play gains new intents
516
517 Inheritance claim, blank-cheque get/return — add a matching verb when useful.
518
519 When a new player-facing intent ships, add a matching script statement in the same feature commit.
520
521 ---
522
523 ## 15. Runtime edge cases (resolved in plan)
524
525 ### 15.1 Targeting & names
526
527 - `find` uses **display names** (case-insensitive). Ore nodes, trees, and dyed clothing must match what tooltips show.
528 - After `find`, if the world changes (ore depleted, mob died, item picked up) before `go`/`mine` completes → **fail** that op with a clear reason (`mine — Target is gone.`).
529 - Block vs ground vs bag: verbs decide the namespace (`mine` always uses **block** target; `take` uses **ground**; `in range item` uses bag).
530
531 ### 15.2 Blocking ops interrupted
532
533 - If the player is **shoved**, loses the gather, or combat cancels a path while `go`/`mine`/… is blocking → treat as **script error** for that line (not silent continue).
534 - `run on` with 0 stamina: gait falls back to walk (same as player); **not** an error.
535 - Full bag on `take` / gather loot / `unequip` → error for that line.
536
537 ### 15.3 Combat & waits
538
539 - `wait until target dead or 60`: success when target entity is despawned or HP ≤ 0; if the script never had a mob target → immediate error.
540 - `attack` then `wait until target dead` while the mob flees out of chase range: wait hits **timeout** → error (script must re-`find`).
541 - Town guards / retaliation killing the character → §7 death logout (clean stop, no Frederick letter).
542
543 ### 15.4 Stations & cauldron
544
545 - `craft` / `brew` / `cauldron *` require adjacency to the targeted station block like the UI.
546 - `brew` with a recipe paper: if the cauldron already has leftover steps, **clear first** automatically only if the UI’s “start fresh” equivalent exists; otherwise **fail** (`brew — Cauldron is busy.`). Prefer fail-safe: scripts should `cauldron clear` before `brew`.
547 - `cauldron dye [...]` fails if the alchemy brew tab is mid-potion (busy cauldron).
548 - Unstable potion from wrong manual steps is **success of bottling**, not a script error (player can get unstable too).
549
550 ### 15.5 Mode switches
551
552 - Disconnect while online script running **without** offline checkbox → stop script + normal logout (entity despawn).
553 - Disconnect **with** offline already running → keep offline run.
554 - Re-login onto offline script: restore run bar; PC unchanged.
555 - Server restart: persist PC, targets (by tile + name + entityId if still valid), wait deadline, `offlineUntil`; invalid target after rehydrate → error letter.
556
557 ### 15.6 Safety / abuse
558
559 - Rate-limit offline `say` and pigeon sends (e.g. max 1 say / 10s, max 3 pigeons / hour) — same spirit as anti-spam, documented in implementation.
560 - Cap concurrent **offline-scripting** characters per server (suggested **50** initially) to protect ChunkLoader cost; further logouts with offline checked fail with toast if at cap.
561
562 ---
563
564 ## 16. Known weaknesses & open problems
565
566 Issues that remain hard or only partly specified — fix in implementation or revisit the design:
567
568 1. **No variables** — scripts cannot remember “the furnace at (x,y)” or a count beyond `for`. Complex AFK loops get long `goto` spaghetti. *Mitigation:* keep v1; add optional `set`/`$name` later if needed.
569 2. **Display-name fragility** — renames in item/block defs break scripts. *Mitigation:* prefer stable ids in a later “advanced” mode; v1 stays names-for-humans.
570 3. **Recipe paper ↔ `brew "Name"` matching** — papers may store potion keys/hashes, not display strings. *Must* define a canonical match (displayName on the paper instance). If ambiguous, fail.
571 4. **Pigeon cargo model** — real UI may allow more than letter/cheque; script support may lag the UI until cargo selection is unified.
572 5. **Marketplace disambiguation** — multiple sell orders same item at different prices; “oldest” may surprise players. Acceptable v1; later allow `market cancel sell "Tin ore" for 8`.
573 6. **Tailor random dye** — non-deterministic scripts (harder to test). Intentional per design; document it.
574 7. **`goto` vs loops** — statically forbidding jump into/`out of` `for`/`while` needs a clear compiler pass; easy to get wrong with nested `if`. *Must* implement a block-stack checker at save/run.
575 8. **Offline ChunkLoader cost** — many offline miners keep regions hot; the concurrency cap helps but economy/world load can still spike. Needs live metrics after ship.
576 9. **Partial command surface** — any new play feature without a script verb creates parity drift (§14 reminder). Process discipline, not a technical guarantee.
577 10. **Cauldron multiplayer contention** — two characters cannot share one cauldron entity easily; if cauldrons are tile-global state, scripts may race with humans. *Clarify in impl:* cauldron state is per-tile; fail if another session holds it.
578 11. **Death vs error letter** — dying mid-`brew` after consuming herbs: items are already gone; no rollback. Same as player death mid-craft — acceptable but harsh; mention in player-facing script help.
579 12. **AFK false positives** — idle 5 minutes in a menu reading skills still starts AFK script. Acceptable; players can Stop or unmark AFK.
580
581 ---
582
583 ## 17. Feasibility & stability (assessment)
584
585 **Feasibility: high for a phased build; medium-high for “full parity.”**
586 The architecture already assumes a script controller emitting the same intents (§18). Online runner + gather/`go`/`wait until` is straightforward. Offline + ChunkLoader + re-login + restart rehydrate is the hard part but is sketched in the design doc. Full verb parity (market, cauldron, pigeons) is mostly glue once the interpreter and blocking scheduler exist — estimate **several milestones**, not one dump.
587
588 **Stability in use: good if timeouts and fail-loud rules hold; fragile if name-matching and waits are sloppy.**
589
590 | Area | Outlook |
591 |------|---------|
592 | Online scripts | Stable: same validation as players; run bar + Stop; manual intent cancels script |
593 | AFK auto-start | Stable with clear Stop; occasional surprise starts (§16.12) |
594 | Offline hour | Stable for gameplay; **ops risk** on region load — needs caps + metrics |
595 | Long `wait until` | Stable **only** with mandatory `or N` timeouts |
596 | Economy bots | Will exist (shops/market/gather); rate limits and normal game costs are the balance knobs |
597 | Player trust | Death→logout and Frederick letters are clear; herb loss on death mid-brew must be documented |
598
599 **Bottom line:** the concept is **implementable and can be sturdy** for gather/bank/fight loops. Treat name matching, mandatory wait timeouts, offline concurrency caps, and cauldron/recipe matching as **non-negotiable** for stability. Full “every button in the game” parity is **achievable over phases**, not day one — the plan is strongest when each new UI action ships with its script verb in the same commit.
1 # Player scripts (AFK / offline)
2
3 **Status:** not implemented (design only)
4 **Related:** `tile_mmo_server_technical_design_v0.6.md` §18 (controller abstraction, offline entity, sandbox rules)
5
6 Scripts are a **sandboxed language** interpreted on the **server**. They never mutate world state directly; they emit the same player **intents** as a human client (`moveTo`, gather, craft, attack, shop, equip, …). The server validates every step.
7
8 This document is the product + language spec for implementation.
9
10 ---
11
12 ## 1. Goals
13
14 - Automate simple loops: gather → bank/craft → fight → recover.
15 - Run **while online** (watch + stop bar), **while AFK** (idle 30+ minutes), or **while offline** (character stays in the world, max 1 hour).
16 - Keep the language **small**, readable, and hard to misuse.
17 - Fail loudly: toast (online) or pigeon letter (offline), with line + operation + reason.
18
19 ---
20
21 ## 2. Player UI
22
23 ### 2.1 Scripts button
24
25 - HUD control **Scripts** opens the Scripts panel.
26 - Panel lists the player’s saved scripts (name + badges for Offline / AFK flags).
27 - Actions per script: **Edit**, **Delete**, **Run** (online).
28 - **New script** creates an empty script and opens the editor.
29
30 ### 2.2 Script editor
31
32 - Name field.
33 - Text area with **syntax highlighting** (keywords, strings, numbers, comments, labels, `@` vars).
34 - Flags (mutually independent; at most one script should be marked for each role — marking one clears that flag on others):
35 - **Run this while offline** — eligible on logout confirmation.
36 - **Run while AFK** — auto-starts after **30 minutes** with no player actions.
37 - **Live world coordinates** at the **bottom** of the editor (player’s current tile, e.g. `Position: (5, 18)`), updating as the character moves while the panel is open — so authors can copy values into `set @waypoint (5, 18)`.
38 - Optional: a small **Copy** control that copies `set @here (x, y)` (or just `(x, y)`) to the clipboard.
39 - **Save** / **Cancel**.
40
41 ### 2.3 Online run bar
42
43 When a script is running (started manually, AFK auto-start, or resumed after re-login onto an offline script):
44
45 - Fixed bar at the **bottom** of the screen.
46 - Shows: script name, **current line** (number + source text), **Stop**.
47 - Manual player intents (move, attack, gather, …) **stop** the script (treat as cancel), except pure camera/UI (open bag, zoom, settings).
48
49 ### 2.4 Logout confirmation
50
51 On logout while in the world:
52
53 1. Modal: **Are you sure you want to log out?**
54 - **No** — stay.
55 - **Yes** — log out.
56 - Checkbox (default **unchecked**): **Run offline script**
57 - Enabled only if the player has a script marked **Run this while offline**.
58 2. If the checkbox is checked, show an extra **red** line:
59 **Running a script means your character remains in the world and can still be attacked!**
60 3. Confirming with the checkbox checked starts/continues the offline script on that character (see §4).
61
62 ---
63
64 ## 3. Modes
65
66 | Mode | How it starts | Character in world | Client |
67 |------|---------------|--------------------|--------|
68 | **Online** | Scripts panel → Run | Yes | Connected; run bar visible |
69 | **AFK** | No gameplay intents for **30 minutes**, and an AFK-marked script exists | Yes | Still connected; run bar appears when script starts |
70 | **Offline** | Logout with offline checkbox | Yes (no NetworkIdentity; keeps ChunkLoader) | Disconnected |
71
72 **AFK timer:** reset on any **gameplay intent** sent by the player (move, attack, gather, craft, shop, equip, cast, pickup, talk, …). Opening UI / scrolling chat does not reset AFK if those are not intents; prefer resetting on any outbound play command for simplicity.
73
74 **Offline duration:** max **1 hour** from offline-script start (or remaining time after restart rehydrate). Then: stop script, despawn character, persist as a normal logout.
75
76 **Re-login during offline script:** attach the client to the existing entity; keep the script running; show the run bar so the player can Stop.
77
78 ---
79
80 ## 4. Errors
81
82 ### 4.1 Message shape
83
84 Always:
85
86 ```text
87 Line <n>: <operation> — <reason>
88 ```
89
90 Example:
91
92 ```text
93 Line 12: mine — No reachable iron ore nearby.
94 ```
95
96 ### 4.2 Online / AFK (client connected)
97
98 - Stop the script.
99 - Show a **persistent toast** (stays until the player dismisses it) with the error message.
100
101 ### 4.3 Offline (no client)
102
103 - Stop the script.
104 - Remove the character from the world (normal offline persist).
105 - Queue a **pigeon letter**:
106 - Author display name: **Frederick**
107 - Role flavour: manager of Idle Gaming (author line / signature as other system letters do)
108 - Body:
109 `Unfortunately, your script encountered an error.`
110 then a blank line, then the error message from §4.1.
111
112 ---
113
114 ## 5. Language overview
115
116 - Line-oriented, case-insensitive **keywords**.
117 - One statement per line (blank lines and comments allowed).
118 - Comments: `# ...` to end of line.
119 - Strings: `"double quotes"` (names of blocks, mobs, items).
120 - **Name matching is exact** (full display name), **case-insensitive**, never fuzzy / substring / “closest spelling”. `"Tin"` does **not** match `"Tin ore"`.
121 - Numbers: integers (`10`, `100`).
122 - Labels: `label name_here` — name is letters, digits, underscore.
123 - **Variables:** `@name` (letters, digits, underscore after `@`). Set with `set` (§5.2). Hold a **target**, a **tile coordinate**, or (later) a number if needed.
124 - Implicit targets (block / mob / ground) still exist alongside `@` vars.
125 - No user-defined functions in v1.
126 - Sandbox: **not** JavaScript; custom interpreter only (§18.7 design doc).
127
128 ### 5.1 Implicit targets
129
130 The script keeps three optional targets (cleared when a new target of that kind is set, or on error/stop):
131
132 | Target | Set by | Used by |
133 |--------|--------|---------|
134 | **Block** | `find block "..."` | `go`, `mine`, `chop`, `harvest`, `craft`, `in range block` |
135 | **Mob** | `find mob "..."` | `go`, `attack`, `buy`, `sell`, `in range mob` |
136 | **Ground** | `find ground "..."` | `go`, `take`, `use`, `in range ground` |
137
138 `go` without a kind uses the **most recently set** target. Prefer explicit forms when ambiguous: `go block`, `go mob`, `go ground`.
139
140 ### 5.2 Variables (`@` + `set`)
141
142 | Statement | Meaning |
143 |-----------|---------|
144 | `set @tree target` | Copy the **most recently set** implicit target (block / mob / ground) into `@tree`. |
145 | `set @tree block` / `set @tree mob` / `set @tree ground` | Copy that specific implicit target kind into `@tree`. |
146 | `set @furnace here` | Store the player’s **current tile** as coordinates in `@furnace`. |
147 | `set @waypoint (5, 18)` | Store absolute tile coordinates `(5, 18)` in `@waypoint`. Preferred literal form. |
148 | `set @furnace 512 128` | Same as `(512, 128)` — space-separated form also accepted. |
149 | `go @furnace` | Path to the stored **coords** or to the stored **target** (same rules as `go`). |
150 | `go block @tree` | If `@tree` holds a block target, path to it (explicit kind). |
151
152 Rules:
153
154 - Soft cap: **32** variables per running script.
155 - Variables live in **runtime state** (persisted across offline rehydrate / re-login for that run). They are **not** saved with the script source.
156 - Using an unset `@name` → error (`go — @furnace is not set.`).
157 - Storing a target keeps enough identity to re-resolve (tile + kind + name / entityId). If the world object is gone when used → error (`go — Target is gone.`).
158
159 Waypoints: because `go` only works within **2 chunks** (§6.2), authors manually chain coordinate variables for long trips (e.g. mine → mid → furnace).
160
161 ---
162
163 ## 6. Statements (v1)
164
165 ### 6.1 Targeting
166
167 | Statement | Meaning |
168 |-----------|---------|
169 | `find block "Iron ore"` | Closest **reachable** block whose display name equals (case-insensitive). Search = **visible chunk neighbourhood only** (player’s chunk + **8** surrounding = Chebyshev chunk distance ≤ **1**, same as `VISIBLE_CHUNK_RADIUS`). Sets block target. Fails if none. |
170 | `find mob "Shopkeeper"` | Closest living mob/NPC with exact name match in that same **3×3** chunk window. Sets mob target. Fails if none. |
171 | `find ground "Log"` | Closest ground item with exact name match in that same **3×3** chunk window. Sets ground target. Fails if none. |
172
173 “Closest” = Chebyshev tile distance, then path-reachable. Unreachable candidates are skipped. Multiple exact name matches → closest wins. Scripts must **not** see farther than a connected player would for entity/block discovery — never scan the full 2-chunk map ring.
174
175 ### 6.2 Movement
176
177 | Statement | Meaning |
178 |-----------|---------|
179 | `go` | Path to the last set target (block / mob / ground). **Blocks** until arrived or fails. |
180 | `go block` / `go mob` / `go ground` | Same, explicit target kind. |
181 | `go @name` | Path to a variable (coords or stored target). |
182 | `run on` / `run off` | Toggle run gait (same rules as player: needs stamina). |
183
184 **Range hard rule:** the destination tile (target or `@` coords) must lie within **2 chunks** of the player (Chebyshev chunk distance ≤ 2; with `CHUNK_SIZE` 16 that is ≤ **32** tiles in chunk metric). Otherwise the op fails immediately:
185
186 ```text
187 go — Too far away.
188 ```
189
190 There is **no** automatic multi-hop pathing across the world. Use coordinate waypoints (`set @mid …` / `go @mid` / `go @furnace`) for longer trips.
191
192 Arrival = standing on the tile (ground item / interactable) or adjacent where the game requires adjacency (stations, melee, gather nodes).
193
194 ### 6.3 Gathering & world interact
195
196 | Statement | Meaning |
197 |-----------|---------|
198 | `mine` | Gather/mine the targeted **block** (ore boulder, etc.). **Blocks** until finished or fails. |
199 | `chop` | Fell the targeted tree block. **Blocks** until finished. |
200 | `harvest` | Pick/harvest the targeted plant/herb/flower/cotton block. **Blocks** until finished. |
201 | `take` | Pick up the targeted **ground** item into the bag. |
202 | `use` | Interact with the targeted **ground** item if it has a use (e.g. light a log). |
203
204 Exact gather verb must match what the block supports; wrong verb → error (`chop — That is not a tree.`).
205
206 ### 6.4 Crafting stations & alchemy
207
208 **Principle:** script steps mirror what a player does in the UI. No free shortcuts that skip materials, skill, adjacency, or recipe knowledge.
209
210 **Station state hard rule:** cauldron / furnace / anvil / every craft station progress is **per player**, never shared on the tile. Many characters may use the “same” station block at once without interfering. Scripts and the UI obey the same rule — this applies to **all current and future** crafting stations.
211
212 **Inventory hard rule (stations — script and player):** an item is **never committed** into a station. Slots in craft/brew UIs are a **view / reservation** over the bag only — materials do not leave the inventory when placed in a station slot. Therefore:
213
214 - Closing the station UI, cancelling, `cauldron clear`, script stop/error, logout, or **death mid-craft / mid-brew** must leave the bag unchanged for those materials (or immediately show them back — there was nothing to return from the station itself).
215 - Item loss due to closed UI or death while using a station is **impossible**.
216 - Materials are consumed only when the craft/brew **successfully completes** (same moment the product is created), never earlier.
217
218 This is a gameplay rule for humans and scripts alike; the script layer must not invent a different consume-on-insert path.
219
220 #### Crafting stations (furnace, anvil, woodworking, bench, spinning wheel, loom, tailor, leatherworking, …)
221
222 | Statement | Meaning |
223 |-----------|---------|
224 | `craft "Bronze bar"` | At the targeted station **block**, start the same craft the player would (one product). **Blocks** until finished or fails (not at station, unknown recipe, missing mats, skill too low). Mats stay in the bag until success (§6.4). |
225 | `craft "Cotton sweater" dye` | **Tailor only:** craft with dyeing on. Uses a **random** dye charge from the bag (no colour picker). **Fails** if dyeing is requested and the bag has no dye uses left. |
226 | `craft "Cotton sweater"` | Tailor (or other station) **without** dyeing. |
227
228 #### Alchemy cauldron — manual steps (1:1 with UI)
229
230 Require adjacency to a cauldron block (find + go), same as opening the cauldron as a player. Brew progress is **this character’s** cauldron state only.
231
232 | Statement | Meaning |
233 |-----------|---------|
234 | `cauldron insert "Thyme"` | Select/reserve that ingredient from the bag for the brew UI (does **not** remove it from inventory — §6.4 inventory hard rule). |
235 | `cauldron heat` | Heat. |
236 | `cauldron stir` | Stir. |
237 | `cauldron cool` | Cool. |
238 | `cauldron bottle` | Bottle into an empty glass bottle. **Blocks** until done. On success, reserved mats + bottle are consumed and the potion is granted. |
239 | `cauldron clear` | Clear/abandon the brew UI selection; bag unchanged. |
240
241 Step order and outcomes match humans: correct sequence → potion (with Alchemy skill roll); wrong sequence → unstable brew. Scripts get **no** easier success path.
242
243 Example (same steps a player would click):
244
245 ```text
246 find block "Cauldron"
247 go block
248 cauldron insert "Thyme"
249 cauldron heat
250 cauldron insert "Mint"
251 cauldron stir
252 cauldron bottle
253 ```
254
255 #### Named `brew` — only with a recipe paper in the bag
256
257 | Statement | Meaning |
258 |-----------|---------|
259 | `brew "Lesser health tonic"` | Allowed **only** if the inventory contains a **recipe paper** for that potion. Then run that paper’s recorded steps and bottle (skill checks as usual). Mats are reserved until success, then consumed with the bottle — never lost on interrupt. **Fails immediately** if no matching recipe is in the bag (`brew — No recipe for that in your bag.`). |
260
261 Without a recipe item, authors must write the `cauldron …` steps themselves. `brew` is “follow this paper,” not free knowledge of the recipe.
262
263 #### Dyes (flower list, same as dye tab)
264
265 | Statement | Meaning |
266 |-----------|---------|
267 | `cauldron dye ["White flower", "Yellow flower", "Yellow flower"]` | Make dye from that multiset of flowers (here: 1 white + 2 yellow). List order = insert order; repeat a name for more of the same flower. Flowers are reserved from the bag until the dye brew completes successfully; colour/yield rules match the normal dye UI. Fails if flowers missing, not at cauldron, or bottling not possible. |
268
269 List syntax: `[ "...", "..." ]`. Exact flower display names only.
270
271 ### 6.5 Dry-run: `can` before any action
272
273 `can` prefixes **any action statement** and returns whether that exact line would succeed **right now**, without mutating world state (no path start, no craft start, no item move).
274
275 Forms:
276
277 - Standalone is not used — always in conditions: `if can …` / `while can …` / `wait until can … or N`
278 - Syntax: `can` + the same tokens as the action line (including args and `@` vars)
279
280 Examples:
281
282 | Condition | True when… |
283 |-----------|------------|
284 | `can craft "Bronze bar"` | At station, recipe known, mats + skill OK |
285 | `can mine` | Block target set, in gather range, tool/skill OK, node still there |
286 | `can go` / `can go @furnace` | Destination set/resolvable, **≤ 2 chunks**, path exists |
287 | `can bank deposit "Tin ore" 20` | At bank, at least 1 Tin ore movable (qty overflow rules still apply) |
288 | `can buy "Feather" 10` | Shop mob targeted, in range, stock + coins OK |
289 | `can cast "Spark" on mob` | Spell known, valid target, not on CD, in approach range or pathable within 2 chunks |
290 | `can brew "Lesser health tonic"` | Matching recipe paper in bag, at cauldron, mats OK |
291 | `can find block "Tin ore"` | Exact name exists in the visible **3×3** chunk window (and reachable if `find` requires it) |
292 | `can cauldron bottle` | Per-player brew ready to bottle + empty bottle |
293
294 **Not** actions (no `can`): pure control (`label`, `goto`, `if`, `end`, `for`, `while`, `wait`, `stop`, `set`, `run on`/`off`). `find` **is** an action for `can find block "Tin ore"` (true if such a find would succeed).
295
296 Implementation: share the same validation path as the real command; skip the mutate/apply step.
297
298 ### 6.6 Combat & shops
299
300 | Statement | Meaning |
301 |-----------|---------|
302 | `attack` | Attack the targeted mob (player Attack intent). Does **not** wait for the kill by itself — use `wait until target dead or 60` (§6.13). |
303 | `stop attack` | Cancel the current attack engage (player cancel-attack). |
304 | `buy "Feather" 10` | Buy quantity from targeted shop mob. Fails if no shop, not in range, can’t afford, or not stocked. |
305 | `sell "Soft leather" 5` | Sell quantity to targeted shop mob (if it buys). |
306
307 **Follow** is intentionally **not** supported.
308
309 ### 6.7 Inventory, gear & vitals
310
311 | Statement | Meaning |
312 |-----------|---------|
313 | `equip "Bronze pickaxe"` | Equip a matching item from the bag into its proper slot. Fails if missing or not equippable. |
314 | `unequip weapon` | Clear that equipment **slot** into the bag. Slots: `head`, `chest`, `legs`, `boots`, `weapon`, `offhand` (same as game). **Fails if the bag has no free space.** |
315 | `drink "Lesser health tonic"` | Drink a matching consumable from the bag. |
316 | `eat "Apple"` | Eat a matching food from the bag. |
317 | `drop "Tin ore" 5` | Drop quantity from the bag onto the ground. |
318 | `read "Spark spellbook"` | Read a spellbook from the bag to learn its spell (same as player). Fails if missing, already known, or requirements not met. |
319 | `if health below 30` … | See control flow. |
320 | `if stamina below 5` … | See control flow. |
321
322 ### 6.8 Range checks & queries
323
324 | Statement | Meaning |
325 |-----------|---------|
326 | `if in range block "Furnace"` | True if a matching block exists in the **visible 3×3** chunk window (same as `find`) and is within interaction/path rules. |
327 | `if in range mob "Deer"` | True if a matching living mob is within **15 tiles** Chebyshev **and** inside the visible 3×3 chunk window. |
328 | `if in range ground "Bones"` | True if a matching ground item is within **15 tiles** **and** inside the visible 3×3 chunk window. |
329 | `if in range item "Bronze bar"` | True if the bag contains that item (quantity ≥ 1). |
330 | `if bag has "Tin ore" at least 10` | Bag quantity check. |
331 | `if bag has "Tin ore" below 10` | Bag quantity check. |
332 | `if target health below 20` | Targeted **mob** current HP below N. Fails the condition (false) if no mob target; does not hard-error. |
333 | `if target dead` | Targeted mob is gone or at 0 HP. |
334
335 ### 6.9 Bank, cheques, market, social economy
336
337 Requires being at / having path-interacted with the right block where the game requires it (bank counter, bounty office, marketplace).
338
339 | Statement | Meaning |
340 |-----------|---------|
341 | `bank deposit "Tin ore" 20` | Move quantity from bag → vault. |
342 | `bank withdraw "Tin ore" 20` | Move quantity from vault → bag. |
343 | `write cheque "Tin ore" 50` | Write a cheque reserving that item+qty from the **bank (vault)**. Fails if the vault lacks enough. |
344 | `redeem cheque` | Redeem a written cheque from the bag at a bank (goods → vault), same as player. |
345 | `market sell "Tin ore" 10 for 8` | Place sell order (qty, min unit price). Escrows goods + listing fee like the UI. |
346 | `market buy "Tin ore" 10 for 12` | Place buy order (qty, max unit price). Escrows coins like the UI. |
347 | `market cancel sell` / `market cancel buy` | Cancel the character’s open order of that side (or nearest matching — prefer cancelling by item name if multiple: `market cancel sell "Tin ore"`). |
348 | `raise bounty on "Ada Worker" 100` | Raise bounty (near bounty office, pays from bag). |
349 | `send pigeon to bank` | Courier cargo to own bank (same rules as UI). |
350 | `send pigeon to "Ada Worker"` | Courier to that character; payload prefers a written letter, else a cheque (§13). |
351 | `write letter "..."` | Write body onto a **blank letter** in the bag (fails if none); does not send. |
352 | `say "hello"` | Local chat say. |
353
354 ### 6.10 Spells
355
356 | Statement | Meaning |
357 |-----------|---------|
358 | `cast "Light"` | Cast on the targeted **block** tile (tile-target spells). Approaches into range if needed (same as player cast). **Blocks** until cast attempt resolves; **fizzle is not an error** (line completes). Approach still obeys the **2-chunk** `go` limit. |
359 | `cast "Spark" on mob` | Cast entity-target spell on the mob target. |
360 | `cast "Light" on block` | Explicit tile target = targeted block’s tile. |
361
362 Fails if unknown spell, not learned, on cooldown, out of range with no path, or wrong target kind.
363
364 ### 6.11 Labels & jumps
365
366 | Statement | Meaning |
367 |-----------|---------|
368 | `label camp` | Declare label `camp`. |
369 | `goto camp` | Jump to that label. |
370
371 Forward and backward jumps allowed. Jumping into/out of loops is **disallowed** (error if attempted).
372
373 ### 6.12 Control flow
374
375 ```text
376 if health below 30
377 goto heal
378 end
379
380 if stamina below 5
381 run off
382 end
383
384 if can craft "Bronze bar"
385 craft "Bronze bar"
386 end
387
388 if can go @furnace
389 go @furnace
390 end
391
392 if in range item "Bronze pickaxe"
393 equip "Bronze pickaxe"
394 end
395
396 for 10
397 find block "Tin ore"
398 go block
399 mine
400 end
401
402 while in range mob "Rat"
403 find mob "Rat"
404 go mob
405 attack
406 wait until target dead or 60
407 end
408 ```
409
410 Rules:
411
412 - Blocks end with `end`.
413 - `if` body runs when the condition is true; no `else` (use a second `if` / `goto`).
414 - `for N` — repeat body **N** times (N ≥ 1, max **1000**).
415 - `while <condition>` — repeat while condition true; **max 1000** iterations per `while` then error (`while — Too many repeats.`).
416 - Conditions:
417 `health below N` · `stamina below N` · `can <action…>` (§6.5) · `in range block|mob|ground|item "..."` · `bag has "..." at least|below N` · `target health below N` · `target dead`
418
419 ### 6.13 Waiting (`wait` / `wait until`)
420
421 | Statement | Meaning |
422 |-----------|---------|
423 | `wait 2` | Pause **2 seconds** (server time). Max **60** per wait. |
424 | `wait until arrived or 30` | Block until the current path finishes (usually redundant after `go`, which already waits). |
425 | `wait until gathered or 120` | Block until the active mine/chop/harvest completes. |
426 | `wait until crafted or 120` | Block until the active station craft / `brew` / `cauldron bottle` completes. |
427 | `wait until target dead or 60` | Block until the mob target is dead or despawned. Fails if no mob target. |
428 | `wait until health at least 50 or 120` | Block until own HP ≥ N. |
429 | `wait until stamina at least 5 or 60` | Block until stamina ≥ N. |
430 | `wait until in range item "Bronze bar" or 60` | Block until bag has that item. |
431 | `wait until in range mob "Deer" or 30` | Block until such a mob is in range. |
432 | `wait until bag has "Tin ore" at least 10 or 300` | Block until quantity met. |
433 | `wait until can craft "Bronze bar" or 60` | Block until that dry-run would succeed. |
434 | `wait until can go @furnace or 60` | Block until the destination is ≤ 2 chunks and pathable (e.g. after walking a midpoint waypoint). |
435
436 **Principle:** every boolean condition usable in `if` / `while` is also valid after `wait until`. Extend this set whenever new conditions ship. `can <action>` is valid anywhere a condition is.
437
438 **Timeout is mandatory:** every `wait until` must end with `or <seconds>` (1–300). Bare `wait until …` without `or N` is a **parse error**. On timeout → script error (`wait until — Timed out.`).
439
440 `go` / gather / `craft` / `brew` already **block** like a built-in wait for their own completion (they have natural end conditions; no separate `or N` on those verbs).
441
442 ### 6.14 Utility
443
444 | Statement | Meaning |
445 |-----------|---------|
446 | `stop` | End the script successfully (no error letter). |
447
448 ---
449
450 ## 7. Death while a script is running
451
452 If the character **dies** for any reason while a script is active (online, AFK, or offline):
453
454 1. **Stop** the script immediately (not an “error letter” unless death was caused mid-op failure — death itself is a clean stop).
455 2. Cancel any in-progress station/cauldron UI state for that player; **bag contents for reserved station mats are unchanged** (§6.4 inventory hard rule).
456 3. **Fully log the instance out** of the world (despawn entity, persist dead flag / position as normal death logout).
457 4. When the player next connects, they see the normal **respawn** screen — no auto-respawn from scripts.
458
459 There is **no** `respawn` script command.
460
461 ---
462
463 ## 8. Example scripts
464
465 ### 8.1 Tin loop with panic flee
466
467 ```text
468 # Tin loop with panic flee
469 label start
470 equip "Bronze pickaxe"
471 run on
472
473 for 20
474 if health below 25
475 goto flee
476 end
477 find block "Tin ore"
478 go block
479 mine
480 if in range ground "Tin ore"
481 find ground "Tin ore"
482 go ground
483 take
484 end
485 end
486 stop
487
488 label flee
489 run on
490 drink "Lesser health tonic"
491 stop attack
492 find block "Bank"
493 go block
494 bank deposit "Tin ore" 999
495 stop
496 ```
497
498 ### 8.2 Bronze mining bot (equal tin/copper → smelt → bank)
499
500 Furnace is ~4 chunks from the mine (beyond the 2-chunk `go` limit), so the author pre-saves waypoints by standing on tiles and using `set @… here`, or by writing coordinates. Bank is near the furnace here; bronze goes to the vault via `bank deposit` (or `send pigeon to bank` if preferred).
501
502 Smelting consumes tin and copper in pairs, so the loop mines whichever ore is missing first — stock stays balanced.
503
504 ```text
505 # Waypoints (edit coords to your world; mid is ~2 chunks from mine toward furnace)
506 # Tip: open the script editor and read Position: (x, y) at the bottom while standing on each tile
507 set @mine (800, 400)
508 set @mid (800, 432)
509 set @furnace (800, 464)
510 set @bank (804, 464)
511
512 equip "Bronze pickaxe"
513 run on
514
515 label loop
516 # Equal ores: mine whichever is missing; smelting consumes pairs so stock stays balanced
517 if bag has "Tin ore" below 1
518 goto mine_tin
519 end
520 if bag has "Copper ore" below 1
521 goto mine_copper
522 end
523 goto smelt
524
525 label mine_tin
526 go @mid
527 go @mine
528 find block "Tin ore"
529 if can go block
530 go block
531 mine
532 end
533 if in range ground "Tin ore"
534 find ground "Tin ore"
535 go ground
536 take
537 end
538 goto loop
539
540 label mine_copper
541 go @mid
542 go @mine
543 find block "Copper ore"
544 if can go block
545 go block
546 mine
547 end
548 if in range ground "Copper ore"
549 find ground "Copper ore"
550 go ground
551 take
552 end
553 goto loop
554
555 label smelt
556 go @mid
557 go @furnace
558 find block "Furnace"
559 go block
560 while can craft "Bronze bar"
561 craft "Bronze bar"
562 end
563 go @bank
564 find block "Bank"
565 go block
566 bank deposit "Bronze bar" 999
567 goto loop
568 ```
569
570 ---
571
572 ## 9. Syntax highlighting (editor)
573
574 Highlight at least:
575
576 | Class | Examples |
577 |-------|----------|
578 | Keyword | `find`, `go`, `mine`, `chop`, `harvest`, `craft`, `brew`, `cauldron`, `attack`, `buy`, `sell`, `equip`, `unequip`, `drink`, `eat`, `drop`, `read`, `cast`, `bank`, `market`, `write`, `redeem`, `raise`, `send`, `say`, `label`, `goto`, `if`, `end`, `for`, `while`, `wait`, `stop`, `run`, `take`, `use`, `can`, `set` |
579 | Subkeyword | `block`, `mob`, `ground`, `item`, `health`, `stamina`, `below`, `at`, `least`, `in`, `range`, `on`, `off`, `until`, `or`, `arrived`, `gathered`, `crafted`, `target`, `dead`, `here`, `deposit`, `withdraw`, `cheque`, `pigeon`, `bounty`, `sell`, `buy`, `cancel`, `insert`, `heat`, `stir`, `cool`, `bottle`, `clear`, `dye` |
580 | String | `"..."` |
581 | List | `[ "...", "..." ]` (flower lists for `cauldron dye`) |
582 | Number | `10`, `30` |
583 | Comment | `# ...` |
584 | Label name | after `label` / `goto` |
585 | Slot name | after `unequip` (`weapon`, `head`, …) |
586
587 | Variable | `@furnace`, `@mid` |
588 | Coord pair | `(5, 18)` or `512 128` after `set @name` |
589
590 Invalid lines can be marked with a subtle error underline on Save (optional v1).
591
592 ---
593
594 ## 10. Persistence & limits
595
596 - Scripts stored per character in state DB (name, source text, flags, updatedAt).
597 - Soft caps (suggested): **20** scripts / character, **200** lines / script, **4 KB** source.
598 - Offline script runtime state: program counter, targets, `@` variables, loop stack, `offlineUntil` timestamp — rehydrated on server restart (§18.6).
599 - Instruction budget: small per simulation tick (at most one **blocking** wait/path/gather/craft at a time; non-blocking lines burst with a low cap).
600
601 ---
602
603 ## 11. Authority & safety (implementation notes)
604
605 - Interpreter runs only on the server.
606 - Every gameplay effect goes through existing command handlers.
607 - No filesystem, network, `eval`, or shared mutable globals across characters.
608 - Name matching uses the same display names players see in tooltips / shops — **exact**, case-insensitive, never fuzzy.
609 - Script controller and client controller: only one produces intents at a time; **any manual gameplay intent stops** the script.
610 - Offline `say` / pigeon / bounty: same validation as players; add rate limits if abused.
611
612 ---
613
614 ## 12. Implementation plan (phased)
615
616 1. **Data + UI shell** — CRUD scripts, flags, editor with highlighting + **live position readout**, no execution.
617 2. **Online runner** — interpreter + run bar + stop; `find` / `go` (blocking, **2-chunk** cap) / `set` / `@` vars / `wait` / `wait until` / `label` / `goto` / `stop` / universal `can`.
618 3. **Gather + gear + vitals** — `mine` / `chop` / `harvest` / `equip` / `unequip` / `drink` / `eat` / `if health|stamina`.
619 4. **Combat + shops + craft/alchemy** — stations via `craft` (tailor `dye` flag); cauldron via step verbs + recipe-gated `brew` + `cauldron dye [...]`; per-player station state.
620 5. **Loops + range + bag/target queries**.
621 6. **Bank, cheques, market, spells, pigeon, chat, bounty, spellbooks**.
622 7. **AFK auto-start** — 30-minute idle.
623 8. **Offline logout flow** — modal, entity retention, 1-hour cap, re-login attach, error pigeon, **death → full logout**.
624
625 ---
626
627 ## 13. Open choices (resolve during implementation)
628
629 Resolved defaults (change only with a good reason):
630
631 | Topic | Decision |
632 |-------|----------|
633 | `in range mob/ground` radius | **15** tiles Chebyshev |
634 | AFK timer vs Scripts panel | Opening the panel does **not** reset idle |
635 | Name matching | **Exact** display name, case-insensitive; never fuzzy. Multiple exact matches → **closest** in the visible **3×3** chunk window |
636 | `find` / nearest search | Player chunk + 8 neighbours only (`VISIBLE_CHUNK_RADIUS` = 1) — what a real player would see |
637 | `go` max distance | Destination must be within **2 chunks** or fail `Too far away.` |
638 | AFK idle duration | **30 minutes** |
639 | `wait until` timeout | **Required** form: `wait until <cond> or <seconds>` (max 300). Bare `wait until` without `or N` is a **parse error** so offline scripts cannot hang forever |
640 | `cast` fizzle | **Not** a script error — line completes; use `if` / skill checks if you care |
641 | Quantity overflow (`bank deposit "Tin ore" 999` with only 5) | Deposit/withdraw/sell/buy **as many as possible up to N**; error only if **zero** moved |
642 | `redeem cheque` with several cheques | Redeem the **first** written cheque in bag order |
643 | `market cancel sell "Tin ore"` | Cancel the **oldest** open sell order for that item name |
644 | `send pigeon to "Name"` | Payload = **one** selected bag item: prefer a written **letter** if present, else a **cheque**, else fail asking for a letter/cheque (`send pigeon — Carry a letter or cheque to send.`) |
645 | `write letter "..."` | Writes onto a **blank letter** in the bag (fails if none); does not send |
646 | Editing a script while it runs | Save applies next **Run** only; running copy is a snapshot |
647 | AFK start while a script already runs | Do **not** start a second script |
648 | Offline logout while a script already runs online | Offline flag continues **that** run (same PC); do not restart from line 1 |
649 | Station inventory | Mats **never leave** the bag until craft/brew **succeeds**; death/UI close cannot destroy them |
650
651 Still soft:
652
653 - Flower **display names** in `cauldron dye` must match item defs exactly (document in editor autocomplete later).
654
655 ---
656
657 ## 14. Out of scope
658
659 | Area | Reason |
660 |------|--------|
661 | **Follow** | Not needed for scripts |
662 | **Friends** | Social; low AFK value |
663 | **Barber / hair** | Cosmetics |
664 | **Inspect / social panel** | Not needed for AFK |
665 | **Graphics settings** | Client-only |
666 | **World editor** | Admin |
667 | **`respawn` command** | Death always full-logout; player uses respawn UI on next login |
668 | **User-defined functions** | v1 stays line+label+`@` vars only |
669
670 Script steps should stay aligned with player UI actions; never add a verb that skips a check the human UI enforces (recipe paper for `brew`, random dye only for tailor, etc.).
671
672 ### Still fine to add later if play gains new intents
673
674 Inheritance claim, blank-cheque get/return — add a matching verb when useful.
675
676 When a new player-facing intent ships, add a matching script statement in the same feature commit.
677
678 ---
679
680 ## 15. Runtime edge cases (resolved in plan)
681
682 ### 15.1 Targeting & names
683
684 - `find` uses **exact** display names (case-insensitive). Ore nodes, trees, and dyed clothing must match tooltips character-for-character aside from case.
685 - `find` / `in range` world searches only the **visible 3×3** chunks (current + 8 surrounding). `go` may still path up to **2 chunks**; farther → `Too far away.` Use `@` coordinate waypoints for long trips.
686 - After `find`, if the world changes (ore depleted, mob died, item picked up) before `go`/`mine` completes → **fail** that op with a clear reason (`mine — Target is gone.`).
687 - Block vs ground vs bag: verbs decide the namespace (`mine` always uses **block** target; `take` uses **ground**; `in range item` uses bag).
688 - `@` vars holding targets re-resolve on use; gone → error. Coords always valid geometrically but still need path + 2-chunk proximity at `go` time.
689
690 ### 15.2 Blocking ops interrupted
691
692 - If the player is **shoved**, loses the gather, or combat cancels a path while `go`/`mine`/… is blocking → treat as **script error** for that line (not silent continue).
693 - `run on` with 0 stamina: gait falls back to walk (same as player); **not** an error.
694 - Full bag on `take` / gather loot / `unequip` → error for that line.
695
696 ### 15.3 Combat & waits
697
698 - `wait until target dead or 60`: success when target entity is despawned or HP ≤ 0; if the script never had a mob target → immediate error.
699 - `attack` then `wait until target dead` while the mob flees out of chase range: wait hits **timeout** → error (script must re-`find`).
700 - Town guards / retaliation killing the character → §7 death logout (clean stop, no Frederick letter).
701
702 ### 15.4 Stations & cauldron
703
704 - `craft` / `brew` / `cauldron *` require adjacency to the targeted station block like the UI.
705 - Station / cauldron progress is **per player** — never tile-global. Concurrent users at the same block do not share or corrupt each other’s brew/craft.
706 - Materials in station slots are **never removed from the bag** until a craft/brew **succeeds**; close UI / clear / death / script stop cannot destroy those items (§6.4).
707 - `brew` with a recipe paper: if **this player’s** cauldron already has leftover steps, **fail** (`brew — Cauldron is busy.`) unless cleared. Prefer: scripts `cauldron clear` before `brew` (clear is safe — bag unchanged).
708 - `cauldron dye [...]` fails if **this player’s** alchemy brew is mid-potion.
709 - Unstable potion from wrong manual steps is **success of bottling**, not a script error (player can get unstable too) — only then are reserved mats consumed.
710
711 ### 15.5 Mode switches
712
713 - Disconnect while online script running **without** offline checkbox → stop script + normal logout (entity despawn).
714 - Disconnect **with** offline already running → keep offline run.
715 - Re-login onto offline script: restore run bar; PC unchanged.
716 - Server restart: persist PC, targets (by tile + name + entityId if still valid), wait deadline, `offlineUntil`; invalid target after rehydrate → error letter.
717
718 ### 15.6 Safety / abuse
719
720 - Rate-limit offline `say` and pigeon sends (e.g. max 1 say / 10s, max 3 pigeons / hour) — same spirit as anti-spam, documented in implementation.
721 - Cap concurrent **offline-scripting** characters per server (suggested **50** initially) to protect ChunkLoader cost; further logouts with offline checked fail with toast if at cap.
722
723 ---
724
725 ## 16. Known weaknesses & open problems
726
727 Issues that remain hard or only partly specified — fix in implementation or revisit the design:
728
729 1. **Display-name fragility** — renames in item/block defs break scripts (exact match). *Mitigation:* editor autocomplete from live defs; optional stable ids later.
730 2. **Manual waypoints** — long trips need author-maintained `@` coords; wrong midpoints → `Too far away.` *Mitigation:* document hop spacing (≤ 2 chunks); later optional `go via @a @b @c` sugar.
731 3. **Equal ore without bag-vs-bag compare** — scripts approximate balance with thresholds (`below 5`), not true `Tin < Copper`. *Mitigation:* add `if bag "Tin ore" below bag "Copper ore"` later if needed.
732 4. **Recipe paper ↔ `brew "Name"` matching** — papers may store potion keys/hashes, not display strings. *Must* define a canonical match (displayName on the paper instance). If ambiguous, fail.
733 5. **Pigeon cargo model** — real UI may allow more than letter/cheque; script support may lag the UI until cargo selection is unified.
734 6. **Marketplace disambiguation** — multiple sell orders same item at different prices; “oldest” may surprise players. Acceptable v1; later allow `market cancel sell "Tin ore" for 8`.
735 7. **Tailor random dye** — non-deterministic scripts (harder to test). Intentional per design; document it.
736 8. **`goto` vs loops** — statically forbidding jump into/`out of` `for`/`while` needs a clear compiler pass; easy to get wrong with nested `if`. *Must* implement a block-stack checker at save/run.
737 9. **Offline ChunkLoader cost** — many offline miners keep regions hot; the concurrency cap helps but economy/world load can still spike. Needs live metrics after ship.
738 10. **Partial command surface** — any new play feature without a script verb creates parity drift (§14 reminder). Process discipline, not a technical guarantee.
739 11. **Universal `can` cost** — dry-running every action (esp. pathfinding) each `while can` tick must be cheap or cached. *Must* budget path checks.
740 12. **AFK false positives** — idle 30 minutes in a menu reading skills still starts AFK script. Acceptable; players can Stop or unmark AFK.
741
742 ---
743
744 ## 17. Feasibility & stability (assessment)
745
746 **Feasibility: high for a phased build; medium-high for “full parity.”**
747 The architecture already assumes a script controller emitting the same intents (§18). Online runner + gather/`go`/`wait until` is straightforward. Offline + ChunkLoader + re-login + restart rehydrate is the hard part but is sketched in the design doc. Full verb parity (market, cauldron, pigeons) is mostly glue once the interpreter and blocking scheduler exist — estimate **several milestones**, not one dump.
748
749 **Stability in use: good if timeouts and fail-loud rules hold; fragile if name-matching and waits are sloppy.**
750
751 | Area | Outlook |
752 |------|---------|
753 | Online scripts | Stable: same validation as players; run bar + Stop; manual intent cancels script |
754 | AFK auto-start | Stable with clear Stop; occasional surprise starts (§16.12) |
755 | Offline hour | Stable for gameplay; **ops risk** on region load — needs caps + metrics |
756 | Long `wait until` | Stable **only** with mandatory `or N` timeouts |
757 | Economy bots | Will exist (shops/market/gather); rate limits and normal game costs are the balance knobs |
758 | Player trust | Death→logout and Frederick letters are clear; station mats cannot be lost on death/UI close (§6.4) |
759
760 **Bottom line:** the concept is **implementable and can be sturdy** for gather/bank/fight loops. Treat **exact** name matching, **visible-only** `find` (3×3 chunks), the **2-chunk** `go` cap, mandatory wait timeouts, offline concurrency caps, per-player station state, **non-committing station inventory**, and recipe matching as **non-negotiable** for stability. Full “every button in the game” parity is **achievable over phases**, not day one — the plan is strongest when each new UI action ships with its script verb in the same commit.
@@ -1,599 +1,760 @@
1# Player scripts (AFK / offline)
1# Player scripts (AFK / offline)
2
2
3**Status:** not implemented (design only)
3**Status:** not implemented (design only)
4**Related:** `tile_mmo_server_technical_design_v0.6.md` §18 (controller abstraction, offline entity, sandbox rules)
4**Related:** `tile_mmo_server_technical_design_v0.6.md` §18 (controller abstraction, offline entity, sandbox rules)
5
5
6Scripts are a **sandboxed language** interpreted on the **server**. They never mutate world state directly; they emit the same player **intents** as a human client (`moveTo`, gather, craft, attack, shop, equip, …). The server validates every step.
6Scripts are a **sandboxed language** interpreted on the **server**. They never mutate world state directly; they emit the same player **intents** as a human client (`moveTo`, gather, craft, attack, shop, equip, …). The server validates every step.
7
7
8This document is the product + language spec for implementation.
8This document is the product + language spec for implementation.
9
9
10---
10---
11
11
12## 1. Goals
12## 1. Goals
13
13
14- Automate simple loops: gather → bank/craft → fight → recover.
14- Automate simple loops: gather → bank/craft → fight → recover.
15- Run **while online** (watch + stop bar), **while AFK** (idle 5+ minutes), or **while offline** (character stays in the world, max 1 hour).
15- Run **while online** (watch + stop bar), **while AFK** (idle 30+ minutes), or **while offline** (character stays in the world, max 1 hour).
16- Keep the language **small**, readable, and hard to misuse.
16- Keep the language **small**, readable, and hard to misuse.
17- Fail loudly: toast (online) or pigeon letter (offline), with line + operation + reason.
17- Fail loudly: toast (online) or pigeon letter (offline), with line + operation + reason.
18
18
19---
19---
20
20
21## 2. Player UI
21## 2. Player UI
22
22
23### 2.1 Scripts button
23### 2.1 Scripts button
24
24
25- HUD control **Scripts** opens the Scripts panel.
25- HUD control **Scripts** opens the Scripts panel.
26- Panel lists the player’s saved scripts (name + badges for Offline / AFK flags).
26- Panel lists the player’s saved scripts (name + badges for Offline / AFK flags).
27- Actions per script: **Edit**, **Delete**, **Run** (online).
27- Actions per script: **Edit**, **Delete**, **Run** (online).
28- **New script** creates an empty script and opens the editor.
28- **New script** creates an empty script and opens the editor.
29
29
30### 2.2 Script editor
30### 2.2 Script editor
31
31
32- Name field.
32- Name field.
33- Text area with **syntax highlighting** (keywords, strings, numbers, comments, labels).
33- Text area with **syntax highlighting** (keywords, strings, numbers, comments, labels, `@` vars).
34- Flags (mutually independent; at most one script should be marked for each role — marking one clears that flag on others):
34- Flags (mutually independent; at most one script should be marked for each role — marking one clears that flag on others):
35 - **Run this while offline** — eligible on logout confirmation.
35 - **Run this while offline** — eligible on logout confirmation.
36 - **Run while AFK** — auto-starts after 5 minutes with no player actions.
36 - **Run while AFK** — auto-starts after **30 minutes** with no player actions.
37- **Save** / **Cancel**.
37- **Live world coordinates** at the **bottom** of the editor (player’s current tile, e.g. `Position: (5, 18)`), updating as the character moves while the panel is open — so authors can copy values into `set @waypoint (5, 18)`.
38
38- Optional: a small **Copy** control that copies `set @here (x, y)` (or just `(x, y)`) to the clipboard.
39### 2.3 Online run bar
39- **Save** / **Cancel**.
40
40
41When a script is running (started manually, AFK auto-start, or resumed after re-login onto an offline script):
41### 2.3 Online run bar
42
42
43- Fixed bar at the **bottom** of the screen.
43When a script is running (started manually, AFK auto-start, or resumed after re-login onto an offline script):
44- Shows: script name, **current line** (number + source text), **Stop**.
44
45- Manual player intents (move, attack, gather, …) **stop** the script (treat as cancel), except pure camera/UI (open bag, zoom, settings).
45- Fixed bar at the **bottom** of the screen.
46
46- Shows: script name, **current line** (number + source text), **Stop**.
47### 2.4 Logout confirmation
47- Manual player intents (move, attack, gather, …) **stop** the script (treat as cancel), except pure camera/UI (open bag, zoom, settings).
48
48
49On logout while in the world:
49### 2.4 Logout confirmation
50
50
511. Modal: **Are you sure you want to log out?**
51On logout while in the world:
52 - **No** — stay.
52
53 - **Yes** — log out.
531. Modal: **Are you sure you want to log out?**
54 - Checkbox (default **unchecked**): **Run offline script**
54 - **No** — stay.
55 - Enabled only if the player has a script marked **Run this while offline**.
55 - **Yes** — log out.
562. If the checkbox is checked, show an extra **red** line:
56 - Checkbox (default **unchecked**): **Run offline script**
57 **Running a script means your character remains in the world and can still be attacked!**
57 - Enabled only if the player has a script marked **Run this while offline**.
583. Confirming with the checkbox checked starts/continues the offline script on that character (see §4).
582. If the checkbox is checked, show an extra **red** line:
59
59 **Running a script means your character remains in the world and can still be attacked!**
60---
603. Confirming with the checkbox checked starts/continues the offline script on that character (see §4).
61
61
62## 3. Modes
62---
63
63
64| Mode | How it starts | Character in world | Client |
64## 3. Modes
65|------|---------------|--------------------|--------|
65
66| **Online** | Scripts panel → Run | Yes | Connected; run bar visible |
66| Mode | How it starts | Character in world | Client |
67| **AFK** | No gameplay intents for **5 minutes**, and an AFK-marked script exists | Yes | Still connected; run bar appears when script starts |
67|------|---------------|--------------------|--------|
68| **Offline** | Logout with offline checkbox | Yes (no NetworkIdentity; keeps ChunkLoader) | Disconnected |
68| **Online** | Scripts panel → Run | Yes | Connected; run bar visible |
69
69| **AFK** | No gameplay intents for **30 minutes**, and an AFK-marked script exists | Yes | Still connected; run bar appears when script starts |
70**AFK timer:** reset on any **gameplay intent** sent by the player (move, attack, gather, craft, shop, equip, cast, pickup, talk, …). Opening UI / scrolling chat does not reset AFK if those are not intents; prefer resetting on any outbound play command for simplicity.
70| **Offline** | Logout with offline checkbox | Yes (no NetworkIdentity; keeps ChunkLoader) | Disconnected |
71
71
72**Offline duration:** max **1 hour** from offline-script start (or remaining time after restart rehydrate). Then: stop script, despawn character, persist as a normal logout.
72**AFK timer:** reset on any **gameplay intent** sent by the player (move, attack, gather, craft, shop, equip, cast, pickup, talk, …). Opening UI / scrolling chat does not reset AFK if those are not intents; prefer resetting on any outbound play command for simplicity.
73
73
74**Re-login during offline script:** attach the client to the existing entity; keep the script running; show the run bar so the player can Stop.
74**Offline duration:** max **1 hour** from offline-script start (or remaining time after restart rehydrate). Then: stop script, despawn character, persist as a normal logout.
75
75
76---
76**Re-login during offline script:** attach the client to the existing entity; keep the script running; show the run bar so the player can Stop.
77
77
78## 4. Errors
78---
79
79
80### 4.1 Message shape
80## 4. Errors
81
81
82Always:
82### 4.1 Message shape
83
83
84```text
84Always:
85Line <n>: <operation> — <reason>
85
86```
86```text
87
87Line <n>: <operation> — <reason>
88Example:
88```
89
89
90```text
90Example:
91Line 12: mine — No reachable iron ore nearby.
91
92```
92```text
93
93Line 12: mine — No reachable iron ore nearby.
94### 4.2 Online / AFK (client connected)
94```
95
95
96- Stop the script.
96### 4.2 Online / AFK (client connected)
97- Show a **persistent toast** (stays until the player dismisses it) with the error message.
97
98
98- Stop the script.
99### 4.3 Offline (no client)
99- Show a **persistent toast** (stays until the player dismisses it) with the error message.
100
100
101- Stop the script.
101### 4.3 Offline (no client)
102- Remove the character from the world (normal offline persist).
102
103- Queue a **pigeon letter**:
103- Stop the script.
104 - Author display name: **Frederick**
104- Remove the character from the world (normal offline persist).
105 - Role flavour: manager of Idle Gaming (author line / signature as other system letters do)
105- Queue a **pigeon letter**:
106 - Body:
106 - Author display name: **Frederick**
107 `Unfortunately, your script encountered an error.`
107 - Role flavour: manager of Idle Gaming (author line / signature as other system letters do)
108 then a blank line, then the error message from §4.1.
108 - Body:
109
109 `Unfortunately, your script encountered an error.`
110---
110 then a blank line, then the error message from §4.1.
111
111
112## 5. Language overview
112---
113
113
114- Line-oriented, case-insensitive **keywords**.
114## 5. Language overview
115- One statement per line (blank lines and comments allowed).
115
116- Comments: `# ...` to end of line.
116- Line-oriented, case-insensitive **keywords**.
117- Strings: `"double quotes"` (names of blocks, mobs, items). Matching is **case-insensitive** display-name match unless noted.
117- One statement per line (blank lines and comments allowed).
118- Numbers: integers (`10`, `100`).
118- Comments: `# ...` to end of line.
119- Labels: `label name_here` — name is letters, digits, underscore.
119- Strings: `"double quotes"` (names of blocks, mobs, items).
120- No variables in v1 except **implicit targets** (current block / mob / ground item) and loop counters internal to `for` / `while`.
120- **Name matching is exact** (full display name), **case-insensitive**, never fuzzy / substring / “closest spelling”. `"Tin"` does **not** match `"Tin ore"`.
121- No user-defined functions in v1.
121- Numbers: integers (`10`, `100`).
122- Sandbox: **not** JavaScript; custom interpreter only (§18.7 design doc).
122- Labels: `label name_here` — name is letters, digits, underscore.
123
123- **Variables:** `@name` (letters, digits, underscore after `@`). Set with `set` (§5.2). Hold a **target**, a **tile coordinate**, or (later) a number if needed.
124### 5.1 Implicit targets
124- Implicit targets (block / mob / ground) still exist alongside `@` vars.
125
125- No user-defined functions in v1.
126The script keeps three optional targets (cleared when a new target of that kind is set, or on error/stop):
126- Sandbox: **not** JavaScript; custom interpreter only (§18.7 design doc).
127
127
128| Target | Set by | Used by |
128### 5.1 Implicit targets
129|--------|--------|---------|
129
130| **Block** | `find block "..."` | `go`, `mine`, `chop`, `harvest`, `craft`, `in range block` |
130The script keeps three optional targets (cleared when a new target of that kind is set, or on error/stop):
131| **Mob** | `find mob "..."` | `go`, `attack`, `buy`, `sell`, `in range mob` |
131
132| **Ground** | `find ground "..."` | `go`, `take`, `use`, `in range ground` |
132| Target | Set by | Used by |
133
133|--------|--------|---------|
134`go` without a kind uses the **most recently set** target. Prefer explicit forms when ambiguous: `go block`, `go mob`, `go ground`.
134| **Block** | `find block "..."` | `go`, `mine`, `chop`, `harvest`, `craft`, `in range block` |
135
135| **Mob** | `find mob "..."` | `go`, `attack`, `buy`, `sell`, `in range mob` |
136---
136| **Ground** | `find ground "..."` | `go`, `take`, `use`, `in range ground` |
137
137
138## 6. Statements (v1)
138`go` without a kind uses the **most recently set** target. Prefer explicit forms when ambiguous: `go block`, `go mob`, `go ground`.
139
139
140### 6.1 Targeting
140### 5.2 Variables (`@` + `set`)
141
141
142| Statement | Meaning |
142| Statement | Meaning |
143|-----------|---------|
143|-----------|---------|
144| `find block "Iron ore"` | Closest **reachable** block whose display name matches. Sets block target. Fails if none. |
144| `set @tree target` | Copy the **most recently set** implicit target (block / mob / ground) into `@tree`. |
145| `find mob "Shopkeeper"` | Closest living mob/NPC whose name matches. Sets mob target. Fails if none. |
145| `set @tree block` / `set @tree mob` / `set @tree ground` | Copy that specific implicit target kind into `@tree`. |
146| `find ground "Log"` | Closest ground item whose display name matches. Sets ground target. Fails if none. |
146| `set @furnace here` | Store the player’s **current tile** as coordinates in `@furnace`. |
147
147| `set @waypoint (5, 18)` | Store absolute tile coordinates `(5, 18)` in `@waypoint`. Preferred literal form. |
148“Closest” = Chebyshev distance from the player, then path-reachable. Unreachable candidates are skipped.
148| `set @furnace 512 128` | Same as `(512, 128)` — space-separated form also accepted. |
149
149| `go @furnace` | Path to the stored **coords** or to the stored **target** (same rules as `go`). |
150### 6.2 Movement
150| `go block @tree` | If `@tree` holds a block target, path to it (explicit kind). |
151
151
152| Statement | Meaning |
152Rules:
153|-----------|---------|
153
154| `go` | Path to the last set target (block / mob / ground). **Blocks** until arrived or fails (blocked / lost / unreachable). |
154- Soft cap: **32** variables per running script.
155| `go block` / `go mob` / `go ground` | Same, explicit target kind. Also **blocks** until arrival. |
155- Variables live in **runtime state** (persisted across offline rehydrate / re-login for that run). They are **not** saved with the script source.
156| `run on` / `run off` | Toggle run gait (same rules as player: needs stamina). |
156- Using an unset `@name` → error (`go — @furnace is not set.`).
157
157- Storing a target keeps enough identity to re-resolve (tile + kind + name / entityId). If the world object is gone when used → error (`go — Target is gone.`).
158Arrival = standing on the tile (ground item / interactable) or adjacent where the game requires adjacency (stations, melee, gather nodes). Any other `move`-style path the script starts uses the same **wait-until-arrived** rule.
158
159
159Waypoints: because `go` only works within **2 chunks** (§6.2), authors manually chain coordinate variables for long trips (e.g. mine → mid → furnace).
160### 6.3 Gathering & world interact
160
161
161---
162| Statement | Meaning |
162
163|-----------|---------|
163## 6. Statements (v1)
164| `mine` | Gather/mine the targeted **block** (ore boulder, etc.). **Blocks** until finished or fails. |
164
165| `chop` | Fell the targeted tree block. **Blocks** until finished. |
165### 6.1 Targeting
166| `harvest` | Pick/harvest the targeted plant/herb/flower/cotton block. **Blocks** until finished. |
166
167| `take` | Pick up the targeted **ground** item into the bag. |
167| Statement | Meaning |
168| `use` | Interact with the targeted **ground** item if it has a use (e.g. light a log). |
168|-----------|---------|
169
169| `find block "Iron ore"` | Closest **reachable** block whose display name equals (case-insensitive). Search = **visible chunk neighbourhood only** (player’s chunk + **8** surrounding = Chebyshev chunk distance ≤ **1**, same as `VISIBLE_CHUNK_RADIUS`). Sets block target. Fails if none. |
170Exact gather verb must match what the block supports; wrong verb → error (`chop — That is not a tree.`).
170| `find mob "Shopkeeper"` | Closest living mob/NPC with exact name match in that same **3×3** chunk window. Sets mob target. Fails if none. |
171
171| `find ground "Log"` | Closest ground item with exact name match in that same **3×3** chunk window. Sets ground target. Fails if none. |
172### 6.4 Crafting stations & alchemy
172
173
173“Closest” = Chebyshev tile distance, then path-reachable. Unreachable candidates are skipped. Multiple exact name matches → closest wins. Scripts must **not** see farther than a connected player would for entity/block discovery — never scan the full 2-chunk map ring.
174**Principle:** script steps mirror what a player does in the UI. No free shortcuts that skip materials, skill, adjacency, or recipe knowledge.
174
175
175### 6.2 Movement
176#### Crafting stations (furnace, anvil, woodworking, bench, spinning wheel, loom, tailor, leatherworking, …)
176
177
177| Statement | Meaning |
178| Statement | Meaning |
178|-----------|---------|
179|-----------|---------|
179| `go` | Path to the last set target (block / mob / ground). **Blocks** until arrived or fails. |
180| `craft "Bronze bar"` | At the targeted station **block**, start the same craft the player would (one product). **Blocks** until finished or fails (not at station, unknown recipe, missing mats, skill too low). |
180| `go block` / `go mob` / `go ground` | Same, explicit target kind. |
181| `can craft "Bronze bar"` | Condition only. True if that craft would succeed **right now**. |
181| `go @name` | Path to a variable (coords or stored target). |
182| `craft "Cotton sweater" dye` | **Tailor only:** craft with dyeing on. Uses a **random** dye charge from the bag (no colour picker). **Fails** if dyeing is requested and the bag has no dye uses left. |
182| `run on` / `run off` | Toggle run gait (same rules as player: needs stamina). |
183| `craft "Cotton sweater"` | Tailor (or other station) **without** dyeing. |
183
184
184**Range hard rule:** the destination tile (target or `@` coords) must lie within **2 chunks** of the player (Chebyshev chunk distance ≤ 2; with `CHUNK_SIZE` 16 that is ≤ **32** tiles in chunk metric). Otherwise the op fails immediately:
185#### Alchemy cauldron — manual steps (1:1 with UI)
185
186
186```text
187Require a targeted cauldron (find + go / adjacency), same as opening the cauldron as a player.
187go — Too far away.
188
188```
189| Statement | Meaning |
189
190|-----------|---------|
190There is **no** automatic multi-hop pathing across the world. Use coordinate waypoints (`set @mid …` / `go @mid` / `go @furnace`) for longer trips.
191| `cauldron insert "Thyme"` | Insert that ingredient from the bag. |
191
192| `cauldron heat` | Heat. |
192Arrival = standing on the tile (ground item / interactable) or adjacent where the game requires adjacency (stations, melee, gather nodes).
193| `cauldron stir` | Stir. |
193
194| `cauldron cool` | Cool. |
194### 6.3 Gathering & world interact
195| `cauldron bottle` | Bottle into an empty glass bottle. **Blocks** until done. |
195
196| `cauldron clear` | Clear/abandon the brew if the UI allows it. |
196| Statement | Meaning |
197
197|-----------|---------|
198Step order and outcomes match humans: correct sequence → potion (with Alchemy skill roll); wrong sequence → unstable brew. Scripts get **no** easier success path.
198| `mine` | Gather/mine the targeted **block** (ore boulder, etc.). **Blocks** until finished or fails. |
199
199| `chop` | Fell the targeted tree block. **Blocks** until finished. |
200Example (same steps a player would click):
200| `harvest` | Pick/harvest the targeted plant/herb/flower/cotton block. **Blocks** until finished. |
201
201| `take` | Pick up the targeted **ground** item into the bag. |
202```text
202| `use` | Interact with the targeted **ground** item if it has a use (e.g. light a log). |
203find block "Cauldron"
203
204go block
204Exact gather verb must match what the block supports; wrong verb → error (`chop — That is not a tree.`).
205cauldron insert "Thyme"
205
206cauldron heat
206### 6.4 Crafting stations & alchemy
207cauldron insert "Mint"
207
208cauldron stir
208**Principle:** script steps mirror what a player does in the UI. No free shortcuts that skip materials, skill, adjacency, or recipe knowledge.
209cauldron bottle
209
210```
210**Station state hard rule:** cauldron / furnace / anvil / every craft station progress is **per player**, never shared on the tile. Many characters may use the “same” station block at once without interfering. Scripts and the UI obey the same rule — this applies to **all current and future** crafting stations.
211
211
212#### Named `brew` — only with a recipe paper in the bag
212**Inventory hard rule (stations — script and player):** an item is **never committed** into a station. Slots in craft/brew UIs are a **view / reservation** over the bag only — materials do not leave the inventory when placed in a station slot. Therefore:
213
213
214| Statement | Meaning |
214- Closing the station UI, cancelling, `cauldron clear`, script stop/error, logout, or **death mid-craft / mid-brew** must leave the bag unchanged for those materials (or immediately show them back — there was nothing to return from the station itself).
215|-----------|---------|
215- Item loss due to closed UI or death while using a station is **impossible**.
216| `brew "Lesser health tonic"` | Allowed **only** if the inventory contains a **recipe paper** for that potion. Then run that paper’s recorded steps and bottle (consume herbs, bottle, skill checks as usual). **Fails immediately** if no matching recipe is in the bag (`brew — No recipe for that in your bag.`). |
216- Materials are consumed only when the craft/brew **successfully completes** (same moment the product is created), never earlier.
217
217
218Without a recipe item, authors must write the `cauldron …` steps themselves. `brew` is “follow this paper,” not free knowledge of the recipe.
218This is a gameplay rule for humans and scripts alike; the script layer must not invent a different consume-on-insert path.
219
219
220#### Dyes (flower list, same as dye tab)
220#### Crafting stations (furnace, anvil, woodworking, bench, spinning wheel, loom, tailor, leatherworking, …)
221
221
222| Statement | Meaning |
222| Statement | Meaning |
223|-----------|---------|
223|-----------|---------|
224| `cauldron dye ["White flower", "Yellow flower", "Yellow flower"]` | Make dye from that multiset of flowers (here: 1 white + 2 yellow). List order = insert order; repeat a name for more of the same flower. Consumes flowers from the bag; colour/yield rules match the normal dye UI. Fails if flowers missing, not at cauldron, or bottling not possible. |
224| `craft "Bronze bar"` | At the targeted station **block**, start the same craft the player would (one product). **Blocks** until finished or fails (not at station, unknown recipe, missing mats, skill too low). Mats stay in the bag until success (§6.4). |
225
225| `craft "Cotton sweater" dye` | **Tailor only:** craft with dyeing on. Uses a **random** dye charge from the bag (no colour picker). **Fails** if dyeing is requested and the bag has no dye uses left. |
226List syntax: `[ "...", "..." ]`.
226| `craft "Cotton sweater"` | Tailor (or other station) **without** dyeing. |
227
227
228### 6.5 Combat & shops
228#### Alchemy cauldron — manual steps (1:1 with UI)
229
229
230| Statement | Meaning |
230Require adjacency to a cauldron block (find + go), same as opening the cauldron as a player. Brew progress is **this character’s** cauldron state only.
231|-----------|---------|
231
232| `attack` | Attack the targeted mob (player Attack intent). Does **not** wait for the kill by itself — use `wait until target dead or 60` (§6.12). |
232| Statement | Meaning |
233| `stop attack` | Cancel the current attack engage (player cancel-attack). |
233|-----------|---------|
234| `buy "Feather" 10` | Buy quantity from targeted shop mob. Fails if no shop, not in range, can’t afford, or not stocked. |
234| `cauldron insert "Thyme"` | Select/reserve that ingredient from the bag for the brew UI (does **not** remove it from inventory — §6.4 inventory hard rule). |
235| `sell "Soft leather" 5` | Sell quantity to targeted shop mob (if it buys). |
235| `cauldron heat` | Heat. |
236
236| `cauldron stir` | Stir. |
237**Follow** is intentionally **not** supported.
237| `cauldron cool` | Cool. |
238
238| `cauldron bottle` | Bottle into an empty glass bottle. **Blocks** until done. On success, reserved mats + bottle are consumed and the potion is granted. |
239### 6.6 Inventory, gear & vitals
239| `cauldron clear` | Clear/abandon the brew UI selection; bag unchanged. |
240
240
241| Statement | Meaning |
241Step order and outcomes match humans: correct sequence → potion (with Alchemy skill roll); wrong sequence → unstable brew. Scripts get **no** easier success path.
242|-----------|---------|
242
243| `equip "Bronze pickaxe"` | Equip a matching item from the bag into its proper slot. Fails if missing or not equippable. |
243Example (same steps a player would click):
244| `unequip weapon` | Clear that equipment **slot** into the bag. Slots: `head`, `chest`, `legs`, `boots`, `weapon`, `offhand` (same as game). **Fails if the bag has no free space.** |
244
245| `drink "Lesser health tonic"` | Drink a matching consumable from the bag. |
245```text
246| `eat "Apple"` | Eat a matching food from the bag. |
246find block "Cauldron"
247| `drop "Tin ore" 5` | Drop quantity from the bag onto the ground. |
247go block
248| `read "Spark spellbook"` | Read a spellbook from the bag to learn its spell (same as player). Fails if missing, already known, or requirements not met. |
248cauldron insert "Thyme"
249| `if health below 30` … | See control flow. |
249cauldron heat
250| `if stamina below 5` … | See control flow. |
250cauldron insert "Mint"
251
251cauldron stir
252### 6.7 Range checks & queries
252cauldron bottle
253
253```
254| Statement | Meaning |
254
255|-----------|---------|
255#### Named `brew` — only with a recipe paper in the bag
256| `if in range block "Furnace"` | True if a matching block exists within interaction/path range. |
256
257| `if in range mob "Deer"` | True if a matching living mob is within **15 tiles** Chebyshev. |
257| Statement | Meaning |
258| `if in range ground "Bones"` | True if a matching ground item is within **15 tiles**. |
258|-----------|---------|
259| `if in range item "Bronze bar"` | True if the bag contains that item (quantity ≥ 1). |
259| `brew "Lesser health tonic"` | Allowed **only** if the inventory contains a **recipe paper** for that potion. Then run that paper’s recorded steps and bottle (skill checks as usual). Mats are reserved until success, then consumed with the bottle — never lost on interrupt. **Fails immediately** if no matching recipe is in the bag (`brew — No recipe for that in your bag.`). |
260| `if bag has "Tin ore" at least 10` | Bag quantity check. |
260
261| `if bag has "Tin ore" below 10` | Bag quantity check. |
261Without a recipe item, authors must write the `cauldron …` steps themselves. `brew` is “follow this paper,” not free knowledge of the recipe.
262| `if target health below 20` | Targeted **mob** current HP below N. Fails the condition (false) if no mob target; does not hard-error. |
262
263| `if target dead` | Targeted mob is gone or at 0 HP. |
263#### Dyes (flower list, same as dye tab)
264
264
265### 6.8 Bank, cheques, market, social economy
265| Statement | Meaning |
266
266|-----------|---------|
267Requires being at / having path-interacted with the right block where the game requires it (bank counter, bounty office, marketplace).
267| `cauldron dye ["White flower", "Yellow flower", "Yellow flower"]` | Make dye from that multiset of flowers (here: 1 white + 2 yellow). List order = insert order; repeat a name for more of the same flower. Flowers are reserved from the bag until the dye brew completes successfully; colour/yield rules match the normal dye UI. Fails if flowers missing, not at cauldron, or bottling not possible. |
268
268
269| Statement | Meaning |
269List syntax: `[ "...", "..." ]`. Exact flower display names only.
270|-----------|---------|
270
271| `bank deposit "Tin ore" 20` | Move quantity from bag → vault. |
271### 6.5 Dry-run: `can` before any action
272| `bank withdraw "Tin ore" 20` | Move quantity from vault → bag. |
272
273| `write cheque "Tin ore" 50` | Write a cheque reserving that item+qty from the **bank (vault)**. Fails if the vault lacks enough. |
273`can` prefixes **any action statement** and returns whether that exact line would succeed **right now**, without mutating world state (no path start, no craft start, no item move).
274| `redeem cheque` | Redeem a written cheque from the bag at a bank (goods → vault), same as player. |
274
275| `market sell "Tin ore" 10 for 8` | Place sell order (qty, min unit price). Escrows goods + listing fee like the UI. |
275Forms:
276| `market buy "Tin ore" 10 for 12` | Place buy order (qty, max unit price). Escrows coins like the UI. |
276
277| `market cancel sell` / `market cancel buy` | Cancel the character’s open order of that side (or nearest matching — prefer cancelling by item name if multiple: `market cancel sell "Tin ore"`). |
277- Standalone is not used — always in conditions: `if can …` / `while can …` / `wait until can … or N`
278| `raise bounty on "Ada Worker" 100` | Raise bounty (near bounty office, pays from bag). |
278- Syntax: `can` + the same tokens as the action line (including args and `@` vars)
279| `send pigeon to bank` | Courier cargo to own bank (same rules as UI). |
279
280| `send pigeon to "Ada Worker"` | Courier to that character; payload prefers a written letter, else a cheque (§13). |
280Examples:
281| `write letter "..."` | Write body onto a **blank letter** in the bag (fails if none); does not send. |
281
282| `say "hello"` | Local chat say. |
282| Condition | True when… |
283
283|-----------|------------|
284### 6.9 Spells
284| `can craft "Bronze bar"` | At station, recipe known, mats + skill OK |
285
285| `can mine` | Block target set, in gather range, tool/skill OK, node still there |
286| Statement | Meaning |
286| `can go` / `can go @furnace` | Destination set/resolvable, **≤ 2 chunks**, path exists |
287|-----------|---------|
287| `can bank deposit "Tin ore" 20` | At bank, at least 1 Tin ore movable (qty overflow rules still apply) |
288| `cast "Light"` | Cast on the targeted **block** tile (tile-target spells). Approaches into range if needed (same as player cast). **Blocks** until cast attempt resolves; **fizzle is not an error** (line completes). |
288| `can buy "Feather" 10` | Shop mob targeted, in range, stock + coins OK |
289| `cast "Spark" on mob` | Cast entity-target spell on the mob target. |
289| `can cast "Spark" on mob` | Spell known, valid target, not on CD, in approach range or pathable within 2 chunks |
290| `cast "Light" on block` | Explicit tile target = targeted block’s tile. |
290| `can brew "Lesser health tonic"` | Matching recipe paper in bag, at cauldron, mats OK |
291
291| `can find block "Tin ore"` | Exact name exists in the visible **3×3** chunk window (and reachable if `find` requires it) |
292Fails if unknown spell, not learned, on cooldown, out of range with no path, or wrong target kind.
292| `can cauldron bottle` | Per-player brew ready to bottle + empty bottle |
293
293
294### 6.10 Labels & jumps
294**Not** actions (no `can`): pure control (`label`, `goto`, `if`, `end`, `for`, `while`, `wait`, `stop`, `set`, `run on`/`off`). `find` **is** an action for `can find block "Tin ore"` (true if such a find would succeed).
295
295
296| Statement | Meaning |
296Implementation: share the same validation path as the real command; skip the mutate/apply step.
297|-----------|---------|
297
298| `label camp` | Declare label `camp`. |
298### 6.6 Combat & shops
299| `goto camp` | Jump to that label. |
299
300
300| Statement | Meaning |
301Forward and backward jumps allowed. Jumping into/out of loops is **disallowed** (error if attempted).
301|-----------|---------|
302
302| `attack` | Attack the targeted mob (player Attack intent). Does **not** wait for the kill by itself — use `wait until target dead or 60` (§6.13). |
303### 6.11 Control flow
303| `stop attack` | Cancel the current attack engage (player cancel-attack). |
304
304| `buy "Feather" 10` | Buy quantity from targeted shop mob. Fails if no shop, not in range, can’t afford, or not stocked. |
305```text
305| `sell "Soft leather" 5` | Sell quantity to targeted shop mob (if it buys). |
306if health below 30
306
307 goto heal
307**Follow** is intentionally **not** supported.
308end
308
309
309### 6.7 Inventory, gear & vitals
310if stamina below 5
310
311 run off
311| Statement | Meaning |
312end
312|-----------|---------|
313
313| `equip "Bronze pickaxe"` | Equip a matching item from the bag into its proper slot. Fails if missing or not equippable. |
314if can craft "Bronze bar"
314| `unequip weapon` | Clear that equipment **slot** into the bag. Slots: `head`, `chest`, `legs`, `boots`, `weapon`, `offhand` (same as game). **Fails if the bag has no free space.** |
315 craft "Bronze bar"
315| `drink "Lesser health tonic"` | Drink a matching consumable from the bag. |
316end
316| `eat "Apple"` | Eat a matching food from the bag. |
317
317| `drop "Tin ore" 5` | Drop quantity from the bag onto the ground. |
318if in range item "Bronze pickaxe"
318| `read "Spark spellbook"` | Read a spellbook from the bag to learn its spell (same as player). Fails if missing, already known, or requirements not met. |
319 equip "Bronze pickaxe"
319| `if health below 30` … | See control flow. |
320end
320| `if stamina below 5` … | See control flow. |
321
321
322for 10
322### 6.8 Range checks & queries
323 find block "Tin ore"
323
324 go block
324| Statement | Meaning |
325 mine
325|-----------|---------|
326end
326| `if in range block "Furnace"` | True if a matching block exists in the **visible 3×3** chunk window (same as `find`) and is within interaction/path rules. |
327
327| `if in range mob "Deer"` | True if a matching living mob is within **15 tiles** Chebyshev **and** inside the visible 3×3 chunk window. |
328while in range mob "Rat"
328| `if in range ground "Bones"` | True if a matching ground item is within **15 tiles** **and** inside the visible 3×3 chunk window. |
329 find mob "Rat"
329| `if in range item "Bronze bar"` | True if the bag contains that item (quantity ≥ 1). |
330 go mob
330| `if bag has "Tin ore" at least 10` | Bag quantity check. |
331 attack
331| `if bag has "Tin ore" below 10` | Bag quantity check. |
332 wait until target dead or 60
332| `if target health below 20` | Targeted **mob** current HP below N. Fails the condition (false) if no mob target; does not hard-error. |
333end
333| `if target dead` | Targeted mob is gone or at 0 HP. |
334```
334
335
335### 6.9 Bank, cheques, market, social economy
336Rules:
336
337
337Requires being at / having path-interacted with the right block where the game requires it (bank counter, bounty office, marketplace).
338- Blocks end with `end`.
338
339- `if` body runs when the condition is true; no `else` (use a second `if` / `goto`).
339| Statement | Meaning |
340- `for N` — repeat body **N** times (N ≥ 1, max **1000**).
340|-----------|---------|
341- `while <condition>` — repeat while condition true; **max 1000** iterations per `while` then error (`while — Too many repeats.`).
341| `bank deposit "Tin ore" 20` | Move quantity from bag → vault. |
342- Conditions:
342| `bank withdraw "Tin ore" 20` | Move quantity from vault → bag. |
343 `health below N` · `stamina below N` · `can craft "..."` · `in range block|mob|ground|item "..."` · `bag has "..." at least|below N` · `target health below N` · `target dead`
343| `write cheque "Tin ore" 50` | Write a cheque reserving that item+qty from the **bank (vault)**. Fails if the vault lacks enough. |
344
344| `redeem cheque` | Redeem a written cheque from the bag at a bank (goods → vault), same as player. |
345### 6.12 Waiting (`wait` / `wait until`)
345| `market sell "Tin ore" 10 for 8` | Place sell order (qty, min unit price). Escrows goods + listing fee like the UI. |
346
346| `market buy "Tin ore" 10 for 12` | Place buy order (qty, max unit price). Escrows coins like the UI. |
347| Statement | Meaning |
347| `market cancel sell` / `market cancel buy` | Cancel the character’s open order of that side (or nearest matching — prefer cancelling by item name if multiple: `market cancel sell "Tin ore"`). |
348|-----------|---------|
348| `raise bounty on "Ada Worker" 100` | Raise bounty (near bounty office, pays from bag). |
349| `wait 2` | Pause **2 seconds** (server time). Max **60** per wait. |
349| `send pigeon to bank` | Courier cargo to own bank (same rules as UI). |
350| `wait until arrived or 30` | Block until the current path finishes (usually redundant after `go`, which already waits). |
350| `send pigeon to "Ada Worker"` | Courier to that character; payload prefers a written letter, else a cheque (§13). |
351| `wait until gathered or 120` | Block until the active mine/chop/harvest completes. |
351| `write letter "..."` | Write body onto a **blank letter** in the bag (fails if none); does not send. |
352| `wait until crafted or 120` | Block until the active station craft / `brew` / `cauldron bottle` completes. |
352| `say "hello"` | Local chat say. |
353| `wait until target dead or 60` | Block until the mob target is dead or despawned. Fails if no mob target. |
353
354| `wait until health at least 50 or 120` | Block until own HP ≥ N. |
354### 6.10 Spells
355| `wait until stamina at least 5 or 60` | Block until stamina ≥ N. |
355
356| `wait until in range item "Bronze bar" or 60` | Block until bag has that item. |
356| Statement | Meaning |
357| `wait until in range mob "Deer" or 30` | Block until such a mob is in range. |
357|-----------|---------|
358| `wait until bag has "Tin ore" at least 10 or 300` | Block until quantity met. |
358| `cast "Light"` | Cast on the targeted **block** tile (tile-target spells). Approaches into range if needed (same as player cast). **Blocks** until cast attempt resolves; **fizzle is not an error** (line completes). Approach still obeys the **2-chunk** `go` limit. |
359| `wait until can craft "Bronze bar" or 60` | Block until craft would succeed at current station target. |
359| `cast "Spark" on mob` | Cast entity-target spell on the mob target. |
360
360| `cast "Light" on block` | Explicit tile target = targeted block’s tile. |
361**Principle:** every boolean condition usable in `if` / `while` is also valid after `wait until`. Extend this set whenever new conditions ship.
361
362
362Fails if unknown spell, not learned, on cooldown, out of range with no path, or wrong target kind.
363**Timeout is mandatory:** every `wait until` must end with `or <seconds>` (1–300). Bare `wait until …` without `or N` is a **parse error**. On timeout → script error (`wait until — Timed out.`).
363
364
364### 6.11 Labels & jumps
365`go` / gather / `craft` / `brew` already **block** like a built-in wait for their own completion (they have natural end conditions; no separate `or N` on those verbs).
365
366
366| Statement | Meaning |
367### 6.13 Utility
367|-----------|---------|
368
368| `label camp` | Declare label `camp`. |
369| Statement | Meaning |
369| `goto camp` | Jump to that label. |
370|-----------|---------|
370
371| `stop` | End the script successfully (no error letter). |
371Forward and backward jumps allowed. Jumping into/out of loops is **disallowed** (error if attempted).
372
372
373---
373### 6.12 Control flow
374
374
375## 7. Death while a script is running
375```text
376
376if health below 30
377If the character **dies** for any reason while a script is active (online, AFK, or offline):
377 goto heal
378
378end
3791. **Stop** the script immediately (not an “error letter” unless death was caused mid-op failure — death itself is a clean stop).
379
3802. **Fully log the instance out** of the world (despawn entity, persist dead flag / position as normal death logout).
380if stamina below 5
3813. When the player next connects, they see the normal **respawn** screen — no auto-respawn from scripts.
381 run off
382
382end
383There is **no** `respawn` script command.
383
384
384if can craft "Bronze bar"
385---
385 craft "Bronze bar"
386
386end
387## 8. Example script
387
388
388if can go @furnace
389```text
389 go @furnace
390# Tin loop with panic flee
390end
391label start
391
392equip "Bronze pickaxe"
392if in range item "Bronze pickaxe"
393run on
393 equip "Bronze pickaxe"
394
394end
395for 20
395
396 if health below 25
396for 10
397 goto flee
397 find block "Tin ore"
398 end
398 go block
399 find block "Tin ore"
399 mine
400 go block
400end
401 mine
401
402 if in range ground "Tin ore"
402while in range mob "Rat"
403 find ground "Tin ore"
403 find mob "Rat"
404 go ground
404 go mob
405 take
405 attack
406 end
406 wait until target dead or 60
407end
407end
408stop
408```
409
409
410label flee
410Rules:
411run on
411
412drink "Lesser health tonic"
412- Blocks end with `end`.
413stop attack
413- `if` body runs when the condition is true; no `else` (use a second `if` / `goto`).
414find block "Bank"
414- `for N` — repeat body **N** times (N ≥ 1, max **1000**).
415go block
415- `while <condition>` — repeat while condition true; **max 1000** iterations per `while` then error (`while — Too many repeats.`).
416bank deposit "Tin ore" 999
416- Conditions:
417stop
417 `health below N` · `stamina below N` · `can <action…>` (§6.5) · `in range block|mob|ground|item "..."` · `bag has "..." at least|below N` · `target health below N` · `target dead`
418```
418
419
419### 6.13 Waiting (`wait` / `wait until`)
420---
420
421
421| Statement | Meaning |
422## 9. Syntax highlighting (editor)
422|-----------|---------|
423
423| `wait 2` | Pause **2 seconds** (server time). Max **60** per wait. |
424Highlight at least:
424| `wait until arrived or 30` | Block until the current path finishes (usually redundant after `go`, which already waits). |
425
425| `wait until gathered or 120` | Block until the active mine/chop/harvest completes. |
426| Class | Examples |
426| `wait until crafted or 120` | Block until the active station craft / `brew` / `cauldron bottle` completes. |
427|-------|----------|
427| `wait until target dead or 60` | Block until the mob target is dead or despawned. Fails if no mob target. |
428| Keyword | `find`, `go`, `mine`, `chop`, `harvest`, `craft`, `brew`, `cauldron`, `attack`, `buy`, `sell`, `equip`, `unequip`, `drink`, `eat`, `drop`, `read`, `cast`, `bank`, `market`, `write`, `redeem`, `raise`, `send`, `say`, `label`, `goto`, `if`, `end`, `for`, `while`, `wait`, `stop`, `run`, `take`, `use`, `can` |
428| `wait until health at least 50 or 120` | Block until own HP ≥ N. |
429| Subkeyword | `block`, `mob`, `ground`, `item`, `health`, `stamina`, `below`, `at`, `least`, `in`, `range`, `on`, `off`, `until`, `or`, `arrived`, `gathered`, `crafted`, `target`, `dead`, `deposit`, `withdraw`, `cheque`, `pigeon`, `bounty`, `sell`, `buy`, `cancel`, `insert`, `heat`, `stir`, `cool`, `bottle`, `clear`, `dye` |
429| `wait until stamina at least 5 or 60` | Block until stamina ≥ N. |
430| String | `"..."` |
430| `wait until in range item "Bronze bar" or 60` | Block until bag has that item. |
431| List | `[ "...", "..." ]` (flower lists for `cauldron dye`) |
431| `wait until in range mob "Deer" or 30` | Block until such a mob is in range. |
432| Number | `10`, `30` |
432| `wait until bag has "Tin ore" at least 10 or 300` | Block until quantity met. |
433| Comment | `# ...` |
433| `wait until can craft "Bronze bar" or 60` | Block until that dry-run would succeed. |
434| Label name | after `label` / `goto` |
434| `wait until can go @furnace or 60` | Block until the destination is ≤ 2 chunks and pathable (e.g. after walking a midpoint waypoint). |
435| Slot name | after `unequip` (`weapon`, `head`, …) |
435
436
436**Principle:** every boolean condition usable in `if` / `while` is also valid after `wait until`. Extend this set whenever new conditions ship. `can <action>` is valid anywhere a condition is.
437Invalid lines can be marked with a subtle error underline on Save (optional v1).
437
438
438**Timeout is mandatory:** every `wait until` must end with `or <seconds>` (1–300). Bare `wait until …` without `or N` is a **parse error**. On timeout → script error (`wait until — Timed out.`).
439---
439
440
440`go` / gather / `craft` / `brew` already **block** like a built-in wait for their own completion (they have natural end conditions; no separate `or N` on those verbs).
441## 10. Persistence & limits
441
442
442### 6.14 Utility
443- Scripts stored per character in state DB (name, source text, flags, updatedAt).
443
444- Soft caps (suggested): **20** scripts / character, **200** lines / script, **4 KB** source.
444| Statement | Meaning |
445- Offline script runtime state: program counter, targets, loop stack, `offlineUntil` timestamp — rehydrated on server restart (§18.6).
445|-----------|---------|
446- Instruction budget: small per simulation tick (at most one **blocking** wait/path/gather/craft at a time; non-blocking lines burst with a low cap).
446| `stop` | End the script successfully (no error letter). |
447
447
448---
448---
449
449
450## 11. Authority & safety (implementation notes)
450## 7. Death while a script is running
451
451
452- Interpreter runs only on the server.
452If the character **dies** for any reason while a script is active (online, AFK, or offline):
453- Every gameplay effect goes through existing command handlers.
453
454- No filesystem, network, `eval`, or shared mutable globals across characters.
4541. **Stop** the script immediately (not an “error letter” unless death was caused mid-op failure — death itself is a clean stop).
455- Name matching uses the same display names players see in tooltips / shops.
4552. Cancel any in-progress station/cauldron UI state for that player; **bag contents for reserved station mats are unchanged** (§6.4 inventory hard rule).
456- Script controller and client controller: only one produces intents at a time; **any manual gameplay intent stops** the script.
4563. **Fully log the instance out** of the world (despawn entity, persist dead flag / position as normal death logout).
457- Offline `say` / pigeon / bounty: same validation as players; add rate limits if abused.
4574. When the player next connects, they see the normal **respawn** screen — no auto-respawn from scripts.
458
458
459---
459There is **no** `respawn` script command.
460
460
461## 12. Implementation plan (phased)
461---
462
462
4631. **Data + UI shell** — CRUD scripts, flags, editor with highlighting, no execution.
463## 8. Example scripts
4642. **Online runner** — interpreter + run bar + stop; `find` / `go` (blocking) / `wait` / `wait until` / `label` / `goto` / `stop`.
464
4653. **Gather + gear + vitals** — `mine` / `chop` / `harvest` / `equip` / `unequip` / `drink` / `eat` / `if health|stamina`.
465### 8.1 Tin loop with panic flee
4664. **Combat + shops + craft/alchemy** — stations via `craft` (tailor `dye` flag); cauldron via step verbs + recipe-gated `brew` + `cauldron dye [...]`.
466
4675. **Loops + range + bag/target queries**.
467```text
4686. **Bank, cheques, market, spells, pigeon, chat, bounty, spellbooks**.
468# Tin loop with panic flee
4697. **AFK auto-start** — 5-minute idle.
469label start
4708. **Offline logout flow** — modal, entity retention, 1-hour cap, re-login attach, error pigeon, **death → full logout**.
470equip "Bronze pickaxe"
471
471run on
472---
472
473
473for 20
474## 13. Open choices (resolve during implementation)
474 if health below 25
475
475 goto flee
476Resolved defaults (change only with a good reason):
476 end
477
477 find block "Tin ore"
478| Topic | Decision |
478 go block
479|-------|----------|
479 mine
480| `in range mob/ground` radius | **15** tiles Chebyshev |
480 if in range ground "Tin ore"
481| AFK timer vs Scripts panel | Opening the panel does **not** reset idle |
481 find ground "Tin ore"
482| Name collisions | **Closest** reachable/living match wins |
482 go ground
483| `wait until` timeout | **Required** form: `wait until <cond> or <seconds>` (max 300). Bare `wait until` without `or N` is a **parse error** so offline scripts cannot hang forever |
483 take
484| `cast` fizzle | **Not** a script error — line completes; use `if` / skill checks if you care |
484 end
485| Quantity overflow (`bank deposit "Tin ore" 999` with only 5) | Deposit/withdraw/sell/buy **as many as possible up to N**; error only if **zero** moved |
485end
486| `redeem cheque` with several cheques | Redeem the **first** written cheque in bag order |
486stop
487| `market cancel sell "Tin ore"` | Cancel the **oldest** open sell order for that item name |
487
488| `send pigeon to "Name"` | Payload = **one** selected bag item: prefer a written **letter** if present, else a **cheque**, else fail asking for a letter/cheque (`send pigeon — Carry a letter or cheque to send.`) |
488label flee
489| `write letter "..."` | Writes onto a **blank letter** in the bag (fails if none); does not send |
489run on
490| Editing a script while it runs | Save applies next **Run** only; running copy is a snapshot |
490drink "Lesser health tonic"
491| AFK start while a script already runs | Do **not** start a second script |
491stop attack
492| Offline logout while a script already runs online | Offline flag continues **that** run (same PC); do not restart from line 1 |
492find block "Bank"
493
493go block
494Still soft:
494bank deposit "Tin ore" 999
495
495stop
496- Exact flower **display names** in `cauldron dye` must match item defs (document in editor autocomplete later).
496```
497
497
498---
498### 8.2 Bronze mining bot (equal tin/copper → smelt → bank)
499
499
500## 14. Out of scope
500Furnace is ~4 chunks from the mine (beyond the 2-chunk `go` limit), so the author pre-saves waypoints by standing on tiles and using `set @… here`, or by writing coordinates. Bank is near the furnace here; bronze goes to the vault via `bank deposit` (or `send pigeon to bank` if preferred).
501
501
502| Area | Reason |
502Smelting consumes tin and copper in pairs, so the loop mines whichever ore is missing first — stock stays balanced.
503|------|--------|
503
504| **Follow** | Not needed for scripts |
504```text
505| **Friends** | Social; low AFK value |
505# Waypoints (edit coords to your world; mid is ~2 chunks from mine toward furnace)
506| **Barber / hair** | Cosmetics |
506# Tip: open the script editor and read Position: (x, y) at the bottom while standing on each tile
507| **Inspect / social panel** | Not needed for AFK |
507set @mine (800, 400)
508| **Graphics settings** | Client-only |
508set @mid (800, 432)
509| **World editor** | Admin |
509set @furnace (800, 464)
510| **`respawn` command** | Death always full-logout; player uses respawn UI on next login |
510set @bank (804, 464)
511| **User variables / functions** | v1 stays line+label only; revisit if scripts become unreadable |
511
512
512equip "Bronze pickaxe"
513Script steps should stay aligned with player UI actions; never add a verb that skips a check the human UI enforces (recipe paper for `brew`, random dye only for tailor, etc.).
513run on
514
514
515### Still fine to add later if play gains new intents
515label loop
516
516# Equal ores: mine whichever is missing; smelting consumes pairs so stock stays balanced
517Inheritance claim, blank-cheque get/return — add a matching verb when useful.
517if bag has "Tin ore" below 1
518
518 goto mine_tin
519When a new player-facing intent ships, add a matching script statement in the same feature commit.
519end
520
520if bag has "Copper ore" below 1
521---
521 goto mine_copper
522
522end
523## 15. Runtime edge cases (resolved in plan)
523goto smelt
524
524
525### 15.1 Targeting & names
525label mine_tin
526
526go @mid
527- `find` uses **display names** (case-insensitive). Ore nodes, trees, and dyed clothing must match what tooltips show.
527go @mine
528- After `find`, if the world changes (ore depleted, mob died, item picked up) before `go`/`mine` completes → **fail** that op with a clear reason (`mine — Target is gone.`).
528find block "Tin ore"
529- Block vs ground vs bag: verbs decide the namespace (`mine` always uses **block** target; `take` uses **ground**; `in range item` uses bag).
529if can go block
530
530 go block
531### 15.2 Blocking ops interrupted
531 mine
532
532end
533- If the player is **shoved**, loses the gather, or combat cancels a path while `go`/`mine`/… is blocking → treat as **script error** for that line (not silent continue).
533if in range ground "Tin ore"
534- `run on` with 0 stamina: gait falls back to walk (same as player); **not** an error.
534 find ground "Tin ore"
535- Full bag on `take` / gather loot / `unequip` → error for that line.
535 go ground
536
536 take
537### 15.3 Combat & waits
537end
538
538goto loop
539- `wait until target dead or 60`: success when target entity is despawned or HP ≤ 0; if the script never had a mob target → immediate error.
539
540- `attack` then `wait until target dead` while the mob flees out of chase range: wait hits **timeout** → error (script must re-`find`).
540label mine_copper
541- Town guards / retaliation killing the character → §7 death logout (clean stop, no Frederick letter).
541go @mid
542
542go @mine
543### 15.4 Stations & cauldron
543find block "Copper ore"
544
544if can go block
545- `craft` / `brew` / `cauldron *` require adjacency to the targeted station block like the UI.
545 go block
546- `brew` with a recipe paper: if the cauldron already has leftover steps, **clear first** automatically only if the UI’s “start fresh” equivalent exists; otherwise **fail** (`brew — Cauldron is busy.`). Prefer fail-safe: scripts should `cauldron clear` before `brew`.
546 mine
547- `cauldron dye [...]` fails if the alchemy brew tab is mid-potion (busy cauldron).
547end
548- Unstable potion from wrong manual steps is **success of bottling**, not a script error (player can get unstable too).
548if in range ground "Copper ore"
549
549 find ground "Copper ore"
550### 15.5 Mode switches
550 go ground
551
551 take
552- Disconnect while online script running **without** offline checkbox → stop script + normal logout (entity despawn).
552end
553- Disconnect **with** offline already running → keep offline run.
553goto loop
554- Re-login onto offline script: restore run bar; PC unchanged.
554
555- Server restart: persist PC, targets (by tile + name + entityId if still valid), wait deadline, `offlineUntil`; invalid target after rehydrate → error letter.
555label smelt
556
556go @mid
557### 15.6 Safety / abuse
557go @furnace
558
558find block "Furnace"
559- Rate-limit offline `say` and pigeon sends (e.g. max 1 say / 10s, max 3 pigeons / hour) — same spirit as anti-spam, documented in implementation.
559go block
560- Cap concurrent **offline-scripting** characters per server (suggested **50** initially) to protect ChunkLoader cost; further logouts with offline checked fail with toast if at cap.
560while can craft "Bronze bar"
561
561 craft "Bronze bar"
562---
562end
563
563go @bank
564## 16. Known weaknesses & open problems
564find block "Bank"
565
565go block
566Issues that remain hard or only partly specified — fix in implementation or revisit the design:
566bank deposit "Bronze bar" 999
567
567goto loop
5681. **No variables** — scripts cannot remember “the furnace at (x,y)” or a count beyond `for`. Complex AFK loops get long `goto` spaghetti. *Mitigation:* keep v1; add optional `set`/`$name` later if needed.
568```
5692. **Display-name fragility** — renames in item/block defs break scripts. *Mitigation:* prefer stable ids in a later “advanced” mode; v1 stays names-for-humans.
569
5703. **Recipe paper ↔ `brew "Name"` matching** — papers may store potion keys/hashes, not display strings. *Must* define a canonical match (displayName on the paper instance). If ambiguous, fail.
570---
5714. **Pigeon cargo model** — real UI may allow more than letter/cheque; script support may lag the UI until cargo selection is unified.
571
5725. **Marketplace disambiguation** — multiple sell orders same item at different prices; “oldest” may surprise players. Acceptable v1; later allow `market cancel sell "Tin ore" for 8`.
572## 9. Syntax highlighting (editor)
5736. **Tailor random dye** — non-deterministic scripts (harder to test). Intentional per design; document it.
573
5747. **`goto` vs loops** — statically forbidding jump into/`out of` `for`/`while` needs a clear compiler pass; easy to get wrong with nested `if`. *Must* implement a block-stack checker at save/run.
574Highlight at least:
5758. **Offline ChunkLoader cost** — many offline miners keep regions hot; the concurrency cap helps but economy/world load can still spike. Needs live metrics after ship.
575
5769. **Partial command surface** — any new play feature without a script verb creates parity drift (§14 reminder). Process discipline, not a technical guarantee.
576| Class | Examples |
57710. **Cauldron multiplayer contention** — two characters cannot share one cauldron entity easily; if cauldrons are tile-global state, scripts may race with humans. *Clarify in impl:* cauldron state is per-tile; fail if another session holds it.
577|-------|----------|
57811. **Death vs error letter** — dying mid-`brew` after consuming herbs: items are already gone; no rollback. Same as player death mid-craft — acceptable but harsh; mention in player-facing script help.
578| Keyword | `find`, `go`, `mine`, `chop`, `harvest`, `craft`, `brew`, `cauldron`, `attack`, `buy`, `sell`, `equip`, `unequip`, `drink`, `eat`, `drop`, `read`, `cast`, `bank`, `market`, `write`, `redeem`, `raise`, `send`, `say`, `label`, `goto`, `if`, `end`, `for`, `while`, `wait`, `stop`, `run`, `take`, `use`, `can`, `set` |
57912. **AFK false positives** — idle 5 minutes in a menu reading skills still starts AFK script. Acceptable; players can Stop or unmark AFK.
579| Subkeyword | `block`, `mob`, `ground`, `item`, `health`, `stamina`, `below`, `at`, `least`, `in`, `range`, `on`, `off`, `until`, `or`, `arrived`, `gathered`, `crafted`, `target`, `dead`, `here`, `deposit`, `withdraw`, `cheque`, `pigeon`, `bounty`, `sell`, `buy`, `cancel`, `insert`, `heat`, `stir`, `cool`, `bottle`, `clear`, `dye` |
580
580| String | `"..."` |
581---
581| List | `[ "...", "..." ]` (flower lists for `cauldron dye`) |
582
582| Number | `10`, `30` |
583## 17. Feasibility & stability (assessment)
583| Comment | `# ...` |
584
584| Label name | after `label` / `goto` |
585**Feasibility: high for a phased build; medium-high for “full parity.”**
585| Slot name | after `unequip` (`weapon`, `head`, …) |
586The architecture already assumes a script controller emitting the same intents (§18). Online runner + gather/`go`/`wait until` is straightforward. Offline + ChunkLoader + re-login + restart rehydrate is the hard part but is sketched in the design doc. Full verb parity (market, cauldron, pigeons) is mostly glue once the interpreter and blocking scheduler exist — estimate **several milestones**, not one dump.
586
587
587| Variable | `@furnace`, `@mid` |
588**Stability in use: good if timeouts and fail-loud rules hold; fragile if name-matching and waits are sloppy.**
588| Coord pair | `(5, 18)` or `512 128` after `set @name` |
589
589
590| Area | Outlook |
590Invalid lines can be marked with a subtle error underline on Save (optional v1).
591|------|---------|
591
592| Online scripts | Stable: same validation as players; run bar + Stop; manual intent cancels script |
592---
593| AFK auto-start | Stable with clear Stop; occasional surprise starts (§16.12) |
593
594| Offline hour | Stable for gameplay; **ops risk** on region load — needs caps + metrics |
594## 10. Persistence & limits
595| Long `wait until` | Stable **only** with mandatory `or N` timeouts |
595
596| Economy bots | Will exist (shops/market/gather); rate limits and normal game costs are the balance knobs |
596- Scripts stored per character in state DB (name, source text, flags, updatedAt).
597| Player trust | Death→logout and Frederick letters are clear; herb loss on death mid-brew must be documented |
597- Soft caps (suggested): **20** scripts / character, **200** lines / script, **4 KB** source.
598
598- Offline script runtime state: program counter, targets, `@` variables, loop stack, `offlineUntil` timestamp — rehydrated on server restart (§18.6).
599**Bottom line:** the concept is **implementable and can be sturdy** for gather/bank/fight loops. Treat name matching, mandatory wait timeouts, offline concurrency caps, and cauldron/recipe matching as **non-negotiable** for stability. Full “every button in the game” parity is **achievable over phases**, not day one — the plan is strongest when each new UI action ships with its script verb in the same commit.
599- Instruction budget: small per simulation tick (at most one **blocking** wait/path/gather/craft at a time; non-blocking lines burst with a low cap).
600
601---
602
603## 11. Authority & safety (implementation notes)
604
605- Interpreter runs only on the server.
606- Every gameplay effect goes through existing command handlers.
607- No filesystem, network, `eval`, or shared mutable globals across characters.
608- Name matching uses the same display names players see in tooltips / shops — **exact**, case-insensitive, never fuzzy.
609- Script controller and client controller: only one produces intents at a time; **any manual gameplay intent stops** the script.
610- Offline `say` / pigeon / bounty: same validation as players; add rate limits if abused.
611
612---
613
614## 12. Implementation plan (phased)
615
6161. **Data + UI shell** — CRUD scripts, flags, editor with highlighting + **live position readout**, no execution.
6172. **Online runner** — interpreter + run bar + stop; `find` / `go` (blocking, **2-chunk** cap) / `set` / `@` vars / `wait` / `wait until` / `label` / `goto` / `stop` / universal `can`.
6183. **Gather + gear + vitals** — `mine` / `chop` / `harvest` / `equip` / `unequip` / `drink` / `eat` / `if health|stamina`.
6194. **Combat + shops + craft/alchemy** — stations via `craft` (tailor `dye` flag); cauldron via step verbs + recipe-gated `brew` + `cauldron dye [...]`; per-player station state.
6205. **Loops + range + bag/target queries**.
6216. **Bank, cheques, market, spells, pigeon, chat, bounty, spellbooks**.
6227. **AFK auto-start** — 30-minute idle.
6238. **Offline logout flow** — modal, entity retention, 1-hour cap, re-login attach, error pigeon, **death → full logout**.
624
625---
626
627## 13. Open choices (resolve during implementation)
628
629Resolved defaults (change only with a good reason):
630
631| Topic | Decision |
632|-------|----------|
633| `in range mob/ground` radius | **15** tiles Chebyshev |
634| AFK timer vs Scripts panel | Opening the panel does **not** reset idle |
635| Name matching | **Exact** display name, case-insensitive; never fuzzy. Multiple exact matches → **closest** in the visible **3×3** chunk window |
636| `find` / nearest search | Player chunk + 8 neighbours only (`VISIBLE_CHUNK_RADIUS` = 1) — what a real player would see |
637| `go` max distance | Destination must be within **2 chunks** or fail `Too far away.` |
638| AFK idle duration | **30 minutes** |
639| `wait until` timeout | **Required** form: `wait until <cond> or <seconds>` (max 300). Bare `wait until` without `or N` is a **parse error** so offline scripts cannot hang forever |
640| `cast` fizzle | **Not** a script error — line completes; use `if` / skill checks if you care |
641| Quantity overflow (`bank deposit "Tin ore" 999` with only 5) | Deposit/withdraw/sell/buy **as many as possible up to N**; error only if **zero** moved |
642| `redeem cheque` with several cheques | Redeem the **first** written cheque in bag order |
643| `market cancel sell "Tin ore"` | Cancel the **oldest** open sell order for that item name |
644| `send pigeon to "Name"` | Payload = **one** selected bag item: prefer a written **letter** if present, else a **cheque**, else fail asking for a letter/cheque (`send pigeon — Carry a letter or cheque to send.`) |
645| `write letter "..."` | Writes onto a **blank letter** in the bag (fails if none); does not send |
646| Editing a script while it runs | Save applies next **Run** only; running copy is a snapshot |
647| AFK start while a script already runs | Do **not** start a second script |
648| Offline logout while a script already runs online | Offline flag continues **that** run (same PC); do not restart from line 1 |
649| Station inventory | Mats **never leave** the bag until craft/brew **succeeds**; death/UI close cannot destroy them |
650
651Still soft:
652
653- Flower **display names** in `cauldron dye` must match item defs exactly (document in editor autocomplete later).
654
655---
656
657## 14. Out of scope
658
659| Area | Reason |
660|------|--------|
661| **Follow** | Not needed for scripts |
662| **Friends** | Social; low AFK value |
663| **Barber / hair** | Cosmetics |
664| **Inspect / social panel** | Not needed for AFK |
665| **Graphics settings** | Client-only |
666| **World editor** | Admin |
667| **`respawn` command** | Death always full-logout; player uses respawn UI on next login |
668| **User-defined functions** | v1 stays line+label+`@` vars only |
669
670Script steps should stay aligned with player UI actions; never add a verb that skips a check the human UI enforces (recipe paper for `brew`, random dye only for tailor, etc.).
671
672### Still fine to add later if play gains new intents
673
674Inheritance claim, blank-cheque get/return — add a matching verb when useful.
675
676When a new player-facing intent ships, add a matching script statement in the same feature commit.
677
678---
679
680## 15. Runtime edge cases (resolved in plan)
681
682### 15.1 Targeting & names
683
684- `find` uses **exact** display names (case-insensitive). Ore nodes, trees, and dyed clothing must match tooltips character-for-character aside from case.
685- `find` / `in range` world searches only the **visible 3×3** chunks (current + 8 surrounding). `go` may still path up to **2 chunks**; farther → `Too far away.` Use `@` coordinate waypoints for long trips.
686- After `find`, if the world changes (ore depleted, mob died, item picked up) before `go`/`mine` completes → **fail** that op with a clear reason (`mine — Target is gone.`).
687- Block vs ground vs bag: verbs decide the namespace (`mine` always uses **block** target; `take` uses **ground**; `in range item` uses bag).
688- `@` vars holding targets re-resolve on use; gone → error. Coords always valid geometrically but still need path + 2-chunk proximity at `go` time.
689
690### 15.2 Blocking ops interrupted
691
692- If the player is **shoved**, loses the gather, or combat cancels a path while `go`/`mine`/… is blocking → treat as **script error** for that line (not silent continue).
693- `run on` with 0 stamina: gait falls back to walk (same as player); **not** an error.
694- Full bag on `take` / gather loot / `unequip` → error for that line.
695
696### 15.3 Combat & waits
697
698- `wait until target dead or 60`: success when target entity is despawned or HP ≤ 0; if the script never had a mob target → immediate error.
699- `attack` then `wait until target dead` while the mob flees out of chase range: wait hits **timeout** → error (script must re-`find`).
700- Town guards / retaliation killing the character → §7 death logout (clean stop, no Frederick letter).
701
702### 15.4 Stations & cauldron
703
704- `craft` / `brew` / `cauldron *` require adjacency to the targeted station block like the UI.
705- Station / cauldron progress is **per player** — never tile-global. Concurrent users at the same block do not share or corrupt each other’s brew/craft.
706- Materials in station slots are **never removed from the bag** until a craft/brew **succeeds**; close UI / clear / death / script stop cannot destroy those items (§6.4).
707- `brew` with a recipe paper: if **this player’s** cauldron already has leftover steps, **fail** (`brew — Cauldron is busy.`) unless cleared. Prefer: scripts `cauldron clear` before `brew` (clear is safe — bag unchanged).
708- `cauldron dye [...]` fails if **this player’s** alchemy brew is mid-potion.
709- Unstable potion from wrong manual steps is **success of bottling**, not a script error (player can get unstable too) — only then are reserved mats consumed.
710
711### 15.5 Mode switches
712
713- Disconnect while online script running **without** offline checkbox → stop script + normal logout (entity despawn).
714- Disconnect **with** offline already running → keep offline run.
715- Re-login onto offline script: restore run bar; PC unchanged.
716- Server restart: persist PC, targets (by tile + name + entityId if still valid), wait deadline, `offlineUntil`; invalid target after rehydrate → error letter.
717
718### 15.6 Safety / abuse
719
720- Rate-limit offline `say` and pigeon sends (e.g. max 1 say / 10s, max 3 pigeons / hour) — same spirit as anti-spam, documented in implementation.
721- Cap concurrent **offline-scripting** characters per server (suggested **50** initially) to protect ChunkLoader cost; further logouts with offline checked fail with toast if at cap.
722
723---
724
725## 16. Known weaknesses & open problems
726
727Issues that remain hard or only partly specified — fix in implementation or revisit the design:
728
7291. **Display-name fragility** — renames in item/block defs break scripts (exact match). *Mitigation:* editor autocomplete from live defs; optional stable ids later.
7302. **Manual waypoints** — long trips need author-maintained `@` coords; wrong midpoints → `Too far away.` *Mitigation:* document hop spacing (≤ 2 chunks); later optional `go via @a @b @c` sugar.
7313. **Equal ore without bag-vs-bag compare** — scripts approximate balance with thresholds (`below 5`), not true `Tin < Copper`. *Mitigation:* add `if bag "Tin ore" below bag "Copper ore"` later if needed.
7324. **Recipe paper ↔ `brew "Name"` matching** — papers may store potion keys/hashes, not display strings. *Must* define a canonical match (displayName on the paper instance). If ambiguous, fail.
7335. **Pigeon cargo model** — real UI may allow more than letter/cheque; script support may lag the UI until cargo selection is unified.
7346. **Marketplace disambiguation** — multiple sell orders same item at different prices; “oldest” may surprise players. Acceptable v1; later allow `market cancel sell "Tin ore" for 8`.
7357. **Tailor random dye** — non-deterministic scripts (harder to test). Intentional per design; document it.
7368. **`goto` vs loops** — statically forbidding jump into/`out of` `for`/`while` needs a clear compiler pass; easy to get wrong with nested `if`. *Must* implement a block-stack checker at save/run.
7379. **Offline ChunkLoader cost** — many offline miners keep regions hot; the concurrency cap helps but economy/world load can still spike. Needs live metrics after ship.
73810. **Partial command surface** — any new play feature without a script verb creates parity drift (§14 reminder). Process discipline, not a technical guarantee.
73911. **Universal `can` cost** — dry-running every action (esp. pathfinding) each `while can` tick must be cheap or cached. *Must* budget path checks.
74012. **AFK false positives** — idle 30 minutes in a menu reading skills still starts AFK script. Acceptable; players can Stop or unmark AFK.
741
742---
743
744## 17. Feasibility & stability (assessment)
745
746**Feasibility: high for a phased build; medium-high for “full parity.”**
747The architecture already assumes a script controller emitting the same intents (§18). Online runner + gather/`go`/`wait until` is straightforward. Offline + ChunkLoader + re-login + restart rehydrate is the hard part but is sketched in the design doc. Full verb parity (market, cauldron, pigeons) is mostly glue once the interpreter and blocking scheduler exist — estimate **several milestones**, not one dump.
748
749**Stability in use: good if timeouts and fail-loud rules hold; fragile if name-matching and waits are sloppy.**
750
751| Area | Outlook |
752|------|---------|
753| Online scripts | Stable: same validation as players; run bar + Stop; manual intent cancels script |
754| AFK auto-start | Stable with clear Stop; occasional surprise starts (§16.12) |
755| Offline hour | Stable for gameplay; **ops risk** on region load — needs caps + metrics |
756| Long `wait until` | Stable **only** with mandatory `or N` timeouts |
757| Economy bots | Will exist (shops/market/gather); rate limits and normal game costs are the balance knobs |
758| Player trust | Death→logout and Frederick letters are clear; station mats cannot be lost on death/UI close (§6.4) |
759
760**Bottom line:** the concept is **implementable and can be sturdy** for gather/bank/fight loops. Treat **exact** name matching, **visible-only** `find` (3×3 chunks), the **2-chunk** `go` cap, mandatory wait timeouts, offline concurrency caps, per-player station state, **non-committing station inventory**, and recipe matching as **non-negotiable** for stability. Full “every button in the game” parity is **achievable over phases**, not day one — the plan is strongest when each new UI action ships with its script verb in the same commit.