BlueGit

timfa questward

Expand scripts plan: parity verbs, alchemy steps, wait-until, death logout.

Document unequip/slots, cancel attack, bank/cheques/market, recipe-gated brew, flower-list dyes, tailor random-dye flag, blocking go, and death-stops-script full logout. Update FEATURES.md pointer.

timfa Tim Falken · pushed by timfa

Authored 2026-08-27 · 2 months ago

Hash
437ae08f16d910e71e21b55c1da218c957ff24ac
Parent
da7a0e39
2 files changed +199 −44
docs/FEATURES.md +1 −1
@@ -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. Players manage scripts in a Scripts panel (create/edit/delete, Run, Offline/AFK flags), see a bottom run bar while a script executes, confirm logout with an optional offline-script checkbox and danger line, auto-start an AFK script after 5 minutes idle, and get persistent toast or Frederick (Idle Gaming) pigeon letters on errors. Offline scripts keep the character in the world up to 1 hour; re-login attaches to the same instance. 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 (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.
357 357 **Code:** — (planned: `shared/scripts/`, `server/src/scripts/`, `client/src/play/scripts.js`, state DB script rows)
@@ -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. Players manage scripts in a Scripts panel (create/edit/delete, Run, Offline/AFK flags), see a bottom run bar while a script executes, confirm logout with an optional offline-script checkbox and danger line, auto-start an AFK script after 5 minutes idle, and get persistent toast or Frederick (Idle Gaming) pigeon letters on errors. Offline scripts keep the character in the world up to 1 hour; re-login attaches to the same instance. 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 (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.
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 +198 −43
@@ -151,66 +151,156 @@ The script keeps three optional targets (cleared when a new target of that kind
151 151
152 152 | Statement | Meaning |
153 153 |-----------|---------|
154 | `go` | Path to the last set target (block / mob / ground). Waits until arrived or fails (blocked / lost). |
155 | `go block` / `go mob` / `go ground` | Same, explicit target kind. |
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 156 | `run on` / `run off` | Toggle run gait (same rules as player: needs stamina). |
157 157
158 Arrival = standing on the tile (ground item / interactable) or adjacent where the game requires adjacency (stations, melee, gather nodes).
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 159
160 160 ### 6.3 Gathering & world interact
161 161
162 162 | Statement | Meaning |
163 163 |-----------|---------|
164 | `mine` | Gather/mine the targeted **block** (ore boulder, etc.). Waits for finish or fails. |
165 | `chop` | Fell the targeted tree block. |
166 | `harvest` | Pick/harvest the targeted plant/herb/flower/cotton block. |
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 167 | `take` | Pick up the targeted **ground** item into the bag. |
168 168 | `use` | Interact with the targeted **ground** item if it has a use (e.g. light a log). |
169 169
170 170 Exact gather verb must match what the block supports; wrong verb → error (`chop — That is not a tree.`).
171 171
172 ### 6.4 Crafting
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.
173 188
174 189 | Statement | Meaning |
175 190 |-----------|---------|
176 | `craft "Bronze bar"` | At the targeted crafting **block** (station), try to craft one of that recipe output (or recipe display name). Fails if not at station, recipe unknown, missing mats, or skill too low. |
177 | `can craft "Bronze bar"` | Does **not** craft. Used only inside `if` (see §6.9). True if the targeted station can craft it **right now** with current bag + skills. |
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: `[ "...", "..." ]`.
178 227
179 228 ### 6.5 Combat & shops
180 229
181 230 | Statement | Meaning |
182 231 |-----------|---------|
183 | `attack` | Attack the targeted mob (same as player Attack intent). Does not wait for kill; continues next line. Optional later: `wait until dead` — **not in v1**. |
232 | `attack` | Attack the targeted mob (player Attack intent). Does **not** wait for the kill by itself — use `wait until target dead` (§6.11). |
233 | `stop attack` | Cancel the current attack engage (player cancel-attack). |
184 234 | `buy "Feather" 10` | Buy quantity from targeted shop mob. Fails if no shop, not in range, can’t afford, or not stocked. |
185 235 | `sell "Soft leather" 5` | Sell quantity to targeted shop mob (if it buys). |
186 236
187 ### 6.6 Inventory & vitals
237 **Follow** is intentionally **not** supported.
238
239 ### 6.6 Inventory, gear & vitals
188 240
189 241 | Statement | Meaning |
190 242 |-----------|---------|
191 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. |
192 249 | `if health below 30` … | See control flow. |
193 250 | `if stamina below 5` … | See control flow. |
194 251
195 ### 6.7 Range checks
252 ### 6.7 Range checks & queries
196 253
197 254 | Statement | Meaning |
198 255 |-----------|---------|
199 | `if in range block "Furnace"` | True if a matching block exists within interaction/path range (same rules as find + adjacent/interact). |
200 | `if in range mob "Deer"` | True if a matching living mob is within a small radius (e.g. combat/script range, document as **15 tiles** Chebyshev). |
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. |
201 258 | `if in range ground "Bones"` | True if a matching ground item is within **15 tiles**. |
202 | `if in range item "Bronze bar"` | True if the bag contains that item (any quantity ≥ 1). |
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
203 266
204 ### 6.8 Labels & jumps
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 from current letter/cheque/item selection rules — see open choices). |
281 | `write letter "..."` | Write letter body onto a blank letter/cheque flow as the game allows. |
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 (success or fizzle still continues unless you `wait until` something else). |
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
205 295
206 296 | Statement | Meaning |
207 297 |-----------|---------|
208 298 | `label camp` | Declare label `camp`. |
209 299 | `goto camp` | Jump to that label. |
210 300
211 Forward and backward jumps allowed. Jumping into/out of loops is **disallowed** in v1 (error if attempted).
301 Forward and backward jumps allowed. Jumping into/out of loops is **disallowed** (error if attempted).
212 302
213 ### 6.9 Control flow
303 ### 6.11 Control flow
214 304
215 305 ```text
216 306 if health below 30
@@ -239,28 +329,62 @@ while in range mob "Rat"
239 329 find mob "Rat"
240 330 go mob
241 331 attack
332 wait until target dead
242 333 end
243 334 ```
244 335
245 336 Rules:
246 337
247 338 - Blocks end with `end`.
248 - `if` body runs when the condition is true; no `else` in v1 (use a second `if` / `goto`).
339 - `if` body runs when the condition is true; no `else` (use a second `if` / `goto`).
249 340 - `for N` — repeat body **N** times (N ≥ 1, max **1000**).
250 341 - `while <condition>` — repeat while condition true; **max 1000** iterations per `while` then error (`while — Too many repeats.`).
251 - Conditions for `while` / `if`:
252 `health below N` · `stamina below N` · `can craft "..."` · `in range block|mob|ground|item "..."`
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`
253 344
254 ### 6.10 Utility
345 ### 6.12 Waiting (`wait` / `wait until`)
255 346
256 347 | Statement | Meaning |
257 348 |-----------|---------|
258 349 | `wait 2` | Pause **2 seconds** (server time). Max **60** per wait. |
350 | `wait until arrived` | Block until the current path finishes (usually redundant after `go`, which already waits). |
351 | `wait until gathered` | Block until the active mine/chop/harvest completes. |
352 | `wait until crafted` | Block until the active station craft / `brew` / `cauldron bottle` completes. |
353 | `wait until target dead` | Block until the mob target is dead or despawned. Fails if no mob target. |
354 | `wait until health at least 50` | Block until own HP ≥ N (or timeout — see below). |
355 | `wait until stamina at least 5` | Block until stamina ≥ N. |
356 | `wait until in range item "Bronze bar"` | Block until bag has that item. |
357 | `wait until in range mob "Deer"` | Block until such a mob is in range. |
358 | `wait until bag has "Tin ore" at least 10` | Block until quantity met. |
359 | `wait until can craft "Bronze bar"` | 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 Optional timeout (recommended): `wait until target dead or 60` — fail with timeout error after N seconds so offline scripts cannot hang forever on one line.
364
365 `go` / gather / `craft` / `brew` already **block** like a built-in `wait until` for their own completion.
366
367 ### 6.13 Utility
368
369 | Statement | Meaning |
370 |-----------|---------|
259 371 | `stop` | End the script successfully (no error letter). |
260 372
261 373 ---
262 374
263 ## 7. Example script
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
264 388
265 389 ```text
266 390 # Tin loop with panic flee
@@ -285,64 +409,95 @@ stop
285 409
286 410 label flee
287 411 run on
288 find mob "Town Guard"
289 go mob
412 drink "Lesser health tonic"
413 stop attack
414 find block "Bank"
415 go block
416 bank deposit "Tin ore" 999
290 417 stop
291 418 ```
292 419
293 420 ---
294 421
295 ## 8. Syntax highlighting (editor)
422 ## 9. Syntax highlighting (editor)
296 423
297 424 Highlight at least:
298 425
299 426 | Class | Examples |
300 427 |-------|----------|
301 | Keyword | `find`, `go`, `mine`, `chop`, `harvest`, `craft`, `attack`, `buy`, `sell`, `equip`, `label`, `goto`, `if`, `end`, `for`, `while`, `wait`, `stop`, `run`, `take`, `use`, `can` |
302 | Subkeyword | `block`, `mob`, `ground`, `item`, `health`, `stamina`, `below`, `in`, `range`, `on`, `off`, `craft` (in `can craft`) |
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`, `arrived`, `gathered`, `crafted`, `target`, `dead`, `deposit`, `withdraw`, `cheque`, `pigeon`, `bounty`, `sell`, `buy`, `cancel`, `insert`, `heat`, `stir`, `cool`, `bottle`, `clear`, `dye` |
303 430 | String | `"..."` |
431 | List | `[ "...", "..." ]` (flower lists for `cauldron dye`) |
304 432 | Number | `10`, `30` |
305 433 | Comment | `# ...` |
306 434 | Label name | after `label` / `goto` |
435 | Slot name | after `unequip` (`weapon`, `head`, …) |
307 436
308 437 Invalid lines can be marked with a subtle error underline on Save (optional v1).
309 438
310 439 ---
311 440
312 ## 9. Persistence & limits
441 ## 10. Persistence & limits
313 442
314 443 - Scripts stored per character in state DB (name, source text, flags, updatedAt).
315 444 - Soft caps (suggested): **20** scripts / character, **200** lines / script, **4 KB** source.
316 445 - Offline script runtime state: program counter, targets, loop stack, `offlineUntil` timestamp — rehydrated on server restart (§18.6).
317 - Instruction budget: small per simulation tick (e.g. advance at most one **blocking** wait/path/gather at a time; non-blocking lines burst with a low cap).
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).
318 447
319 448 ---
320 449
321 ## 10. Authority & safety (implementation notes)
450 ## 11. Authority & safety (implementation notes)
322 451
323 452 - Interpreter runs only on the server.
324 453 - Every gameplay effect goes through existing command handlers.
325 454 - No filesystem, network, `eval`, or shared mutable globals across characters.
326 455 - Name matching uses the same display names players see in tooltips / shops.
327 - Script controller and client controller: only one produces intents at a time; starting a script disables manual gameplay intents until Stop (or manual intent cancels script — pick one policy and stick to it; **recommended:** any manual gameplay intent **stops** the script).
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.
328 458
329 459 ---
330 460
331 ## 11. Implementation plan (phased)
461 ## 12. Implementation plan (phased)
332 462
333 463 1. **Data + UI shell** — CRUD scripts, flags, editor with highlighting, no execution.
334 2. **Online runner** — interpreter + run bar + stop; subset: `find` / `go` / `wait` / `label` / `goto` / `stop`.
335 3. **Gather + equip + vitals if** — `mine` / `chop` / `harvest` / `equip` / `if health|stamina`.
336 4. **Combat + shops + craft** — `attack` / `buy` / `sell` / `craft` / `can craft`.
337 5. **Loops + range checks** — `for` / `while` / `in range *`.
338 6. **AFK auto-start** — 5-minute idle.
339 7. **Offline logout flow** — modal, entity retention, 1-hour cap, re-login attach, error pigeon.
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**.
340 471
341 472 ---
342 473
343 ## 12. Open choices (resolve during implementation)
474 ## 13. Open choices (resolve during implementation)
344 475
345 476 - Exact radius for `in range mob/ground` (proposed **15**).
346 - Whether `attack` should block until the mob dies (v1: **no**).
347 - Whether opening the Scripts panel resets the AFK timer (proposed: **no**, only gameplay intents).
348 - Display-name collisions (multiple “Humanoid”): always **closest** wins.
477 - AFK timer: opening Scripts panel does **not** reset idle (only gameplay intents).
478 - Display-name collisions: **closest** wins.
479 - `send pigeon to "Name"` payload: letter only, or also item/cheque from bag — match the pigeon UI’s current options.
480 - `wait until … or N` timeout syntax — recommended for all `wait until` forms.
481 - `market cancel` when multiple orders exist: require item name disambiguation.
482
483 ---
484
485 ## 14. Out of scope
486
487 | Area | Reason |
488 |------|--------|
489 | **Follow** | Not needed for scripts |
490 | **Friends** | Social; low AFK value |
491 | **Barber / hair** | Cosmetics |
492 | **Inspect / social panel** | Not needed for AFK |
493 | **Graphics settings** | Client-only |
494 | **World editor** | Admin |
495 | **`respawn` command** | Death always full-logout; player uses respawn UI on next login |
496
497 - 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.).
498
499 ### Still fine to add later if play gains new intents
500
501 Dye-clothing-from-bag (if not covered by cauldron), inheritance claim, blank-cheque get/return — add a matching verb when useful.
502
503 When a new player-facing intent ships, add a matching script statement in the same feature commit.
@@ -151,66 +151,156 @@ The script keeps three optional targets (cleared when a new target of that kind
151
151
152| Statement | Meaning |
152| Statement | Meaning |
153|-----------|---------|
153|-----------|---------|
154| `go` | Path to the last set target (block / mob / ground). Waits until arrived or fails (blocked / lost). |
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. |
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). |
156| `run on` / `run off` | Toggle run gait (same rules as player: needs stamina). |
157
157
158Arrival = standing on the tile (ground item / interactable) or adjacent where the game requires adjacency (stations, melee, gather nodes).
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.
159
159
160### 6.3 Gathering & world interact
160### 6.3 Gathering & world interact
161
161
162| Statement | Meaning |
162| Statement | Meaning |
163|-----------|---------|
163|-----------|---------|
164| `mine` | Gather/mine the targeted **block** (ore boulder, etc.). Waits for finish or fails. |
164| `mine` | Gather/mine the targeted **block** (ore boulder, etc.). **Blocks** until finished or fails. |
165| `chop` | Fell the targeted tree block. |
165| `chop` | Fell the targeted tree block. **Blocks** until finished. |
166| `harvest` | Pick/harvest the targeted plant/herb/flower/cotton block. |
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. |
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). |
168| `use` | Interact with the targeted **ground** item if it has a use (e.g. light a log). |
169
169
170Exact gather verb must match what the block supports; wrong verb → error (`chop — That is not a tree.`).
170Exact gather verb must match what the block supports; wrong verb → error (`chop — That is not a tree.`).
171
171
172### 6.4 Crafting
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
187Require a targeted cauldron (find + go / adjacency), same as opening the cauldron as a player.
173
188
174| Statement | Meaning |
189| Statement | Meaning |
175|-----------|---------|
190|-----------|---------|
176| `craft "Bronze bar"` | At the targeted crafting **block** (station), try to craft one of that recipe output (or recipe display name). Fails if not at station, recipe unknown, missing mats, or skill too low. |
191| `cauldron insert "Thyme"` | Insert that ingredient from the bag. |
177| `can craft "Bronze bar"` | Does **not** craft. Used only inside `if` (see §6.9). True if the targeted station can craft it **right now** with current bag + skills. |
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
198Step order and outcomes match humans: correct sequence → potion (with Alchemy skill roll); wrong sequence → unstable brew. Scripts get **no** easier success path.
199
200Example (same steps a player would click):
201
202```text
203find block "Cauldron"
204go block
205cauldron insert "Thyme"
206cauldron heat
207cauldron insert "Mint"
208cauldron stir
209cauldron 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
218Without 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
226List syntax: `[ "...", "..." ]`.
178
227
179### 6.5 Combat & shops
228### 6.5 Combat & shops
180
229
181| Statement | Meaning |
230| Statement | Meaning |
182|-----------|---------|
231|-----------|---------|
183| `attack` | Attack the targeted mob (same as player Attack intent). Does not wait for kill; continues next line. Optional later: `wait until dead` — **not in v1**. |
232| `attack` | Attack the targeted mob (player Attack intent). Does **not** wait for the kill by itself — use `wait until target dead` (§6.11). |
233| `stop attack` | Cancel the current attack engage (player cancel-attack). |
184| `buy "Feather" 10` | Buy quantity from targeted shop mob. Fails if no shop, not in range, can’t afford, or not stocked. |
234| `buy "Feather" 10` | Buy quantity from targeted shop mob. Fails if no shop, not in range, can’t afford, or not stocked. |
185| `sell "Soft leather" 5` | Sell quantity to targeted shop mob (if it buys). |
235| `sell "Soft leather" 5` | Sell quantity to targeted shop mob (if it buys). |
186
236
187### 6.6 Inventory & vitals
237**Follow** is intentionally **not** supported.
238
239### 6.6 Inventory, gear & vitals
188
240
189| Statement | Meaning |
241| Statement | Meaning |
190|-----------|---------|
242|-----------|---------|
191| `equip "Bronze pickaxe"` | Equip a matching item from the bag into its proper slot. Fails if missing or not equippable. |
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. |
192| `if health below 30` … | See control flow. |
249| `if health below 30` … | See control flow. |
193| `if stamina below 5` … | See control flow. |
250| `if stamina below 5` … | See control flow. |
194
251
195### 6.7 Range checks
252### 6.7 Range checks & queries
196
253
197| Statement | Meaning |
254| Statement | Meaning |
198|-----------|---------|
255|-----------|---------|
199| `if in range block "Furnace"` | True if a matching block exists within interaction/path range (same rules as find + adjacent/interact). |
256| `if in range block "Furnace"` | True if a matching block exists within interaction/path range. |
200| `if in range mob "Deer"` | True if a matching living mob is within a small radius (e.g. combat/script range, document as **15 tiles** Chebyshev). |
257| `if in range mob "Deer"` | True if a matching living mob is within **15 tiles** Chebyshev. |
201| `if in range ground "Bones"` | True if a matching ground item is within **15 tiles**. |
258| `if in range ground "Bones"` | True if a matching ground item is within **15 tiles**. |
202| `if in range item "Bronze bar"` | True if the bag contains that item (any quantity ≥ 1). |
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
203
266
204### 6.8 Labels & jumps
267Requires 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 from current letter/cheque/item selection rules — see open choices). |
281| `write letter "..."` | Write letter body onto a blank letter/cheque flow as the game allows. |
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 (success or fizzle still continues unless you `wait until` something else). |
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
292Fails if unknown spell, not learned, on cooldown, out of range with no path, or wrong target kind.
293
294### 6.10 Labels & jumps
205
295
206| Statement | Meaning |
296| Statement | Meaning |
207|-----------|---------|
297|-----------|---------|
208| `label camp` | Declare label `camp`. |
298| `label camp` | Declare label `camp`. |
209| `goto camp` | Jump to that label. |
299| `goto camp` | Jump to that label. |
210
300
211Forward and backward jumps allowed. Jumping into/out of loops is **disallowed** in v1 (error if attempted).
301Forward and backward jumps allowed. Jumping into/out of loops is **disallowed** (error if attempted).
212
302
213### 6.9 Control flow
303### 6.11 Control flow
214
304
215```text
305```text
216if health below 30
306if health below 30
@@ -239,28 +329,62 @@ while in range mob "Rat"
239 find mob "Rat"
329 find mob "Rat"
240 go mob
330 go mob
241 attack
331 attack
332 wait until target dead
242end
333end
243```
334```
244
335
245Rules:
336Rules:
246
337
247- Blocks end with `end`.
338- Blocks end with `end`.
248- `if` body runs when the condition is true; no `else` in v1 (use a second `if` / `goto`).
339- `if` body runs when the condition is true; no `else` (use a second `if` / `goto`).
249- `for N` — repeat body **N** times (N ≥ 1, max **1000**).
340- `for N` — repeat body **N** times (N ≥ 1, max **1000**).
250- `while <condition>` — repeat while condition true; **max 1000** iterations per `while` then error (`while — Too many repeats.`).
341- `while <condition>` — repeat while condition true; **max 1000** iterations per `while` then error (`while — Too many repeats.`).
251- Conditions for `while` / `if`:
342- Conditions:
252 `health below N` · `stamina below N` · `can craft "..."` · `in range block|mob|ground|item "..."`
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`
253
344
254### 6.10 Utility
345### 6.12 Waiting (`wait` / `wait until`)
255
346
256| Statement | Meaning |
347| Statement | Meaning |
257|-----------|---------|
348|-----------|---------|
258| `wait 2` | Pause **2 seconds** (server time). Max **60** per wait. |
349| `wait 2` | Pause **2 seconds** (server time). Max **60** per wait. |
350| `wait until arrived` | Block until the current path finishes (usually redundant after `go`, which already waits). |
351| `wait until gathered` | Block until the active mine/chop/harvest completes. |
352| `wait until crafted` | Block until the active station craft / `brew` / `cauldron bottle` completes. |
353| `wait until target dead` | Block until the mob target is dead or despawned. Fails if no mob target. |
354| `wait until health at least 50` | Block until own HP ≥ N (or timeout — see below). |
355| `wait until stamina at least 5` | Block until stamina ≥ N. |
356| `wait until in range item "Bronze bar"` | Block until bag has that item. |
357| `wait until in range mob "Deer"` | Block until such a mob is in range. |
358| `wait until bag has "Tin ore" at least 10` | Block until quantity met. |
359| `wait until can craft "Bronze bar"` | 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
363Optional timeout (recommended): `wait until target dead or 60` — fail with timeout error after N seconds so offline scripts cannot hang forever on one line.
364
365`go` / gather / `craft` / `brew` already **block** like a built-in `wait until` for their own completion.
366
367### 6.13 Utility
368
369| Statement | Meaning |
370|-----------|---------|
259| `stop` | End the script successfully (no error letter). |
371| `stop` | End the script successfully (no error letter). |
260
372
261---
373---
262
374
263## 7. Example script
375## 7. Death while a script is running
376
377If the character **dies** for any reason while a script is active (online, AFK, or offline):
378
3791. **Stop** the script immediately (not an “error letter” unless death was caused mid-op failure — death itself is a clean stop).
3802. **Fully log the instance out** of the world (despawn entity, persist dead flag / position as normal death logout).
3813. When the player next connects, they see the normal **respawn** screen — no auto-respawn from scripts.
382
383There is **no** `respawn` script command.
384
385---
386
387## 8. Example script
264
388
265```text
389```text
266# Tin loop with panic flee
390# Tin loop with panic flee
@@ -285,64 +409,95 @@ stop
285
409
286label flee
410label flee
287run on
411run on
288find mob "Town Guard"
412drink "Lesser health tonic"
289go mob
413stop attack
414find block "Bank"
415go block
416bank deposit "Tin ore" 999
290stop
417stop
291```
418```
292
419
293---
420---
294
421
295## 8. Syntax highlighting (editor)
422## 9. Syntax highlighting (editor)
296
423
297Highlight at least:
424Highlight at least:
298
425
299| Class | Examples |
426| Class | Examples |
300|-------|----------|
427|-------|----------|
301| Keyword | `find`, `go`, `mine`, `chop`, `harvest`, `craft`, `attack`, `buy`, `sell`, `equip`, `label`, `goto`, `if`, `end`, `for`, `while`, `wait`, `stop`, `run`, `take`, `use`, `can` |
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` |
302| Subkeyword | `block`, `mob`, `ground`, `item`, `health`, `stamina`, `below`, `in`, `range`, `on`, `off`, `craft` (in `can craft`) |
429| Subkeyword | `block`, `mob`, `ground`, `item`, `health`, `stamina`, `below`, `at`, `least`, `in`, `range`, `on`, `off`, `until`, `arrived`, `gathered`, `crafted`, `target`, `dead`, `deposit`, `withdraw`, `cheque`, `pigeon`, `bounty`, `sell`, `buy`, `cancel`, `insert`, `heat`, `stir`, `cool`, `bottle`, `clear`, `dye` |
303| String | `"..."` |
430| String | `"..."` |
431| List | `[ "...", "..." ]` (flower lists for `cauldron dye`) |
304| Number | `10`, `30` |
432| Number | `10`, `30` |
305| Comment | `# ...` |
433| Comment | `# ...` |
306| Label name | after `label` / `goto` |
434| Label name | after `label` / `goto` |
435| Slot name | after `unequip` (`weapon`, `head`, …) |
307
436
308Invalid lines can be marked with a subtle error underline on Save (optional v1).
437Invalid lines can be marked with a subtle error underline on Save (optional v1).
309
438
310---
439---
311
440
312## 9. Persistence & limits
441## 10. Persistence & limits
313
442
314- Scripts stored per character in state DB (name, source text, flags, updatedAt).
443- Scripts stored per character in state DB (name, source text, flags, updatedAt).
315- Soft caps (suggested): **20** scripts / character, **200** lines / script, **4 KB** source.
444- Soft caps (suggested): **20** scripts / character, **200** lines / script, **4 KB** source.
316- Offline script runtime state: program counter, targets, loop stack, `offlineUntil` timestamp — rehydrated on server restart (§18.6).
445- Offline script runtime state: program counter, targets, loop stack, `offlineUntil` timestamp — rehydrated on server restart (§18.6).
317- Instruction budget: small per simulation tick (e.g. advance at most one **blocking** wait/path/gather at a time; non-blocking lines burst with a low cap).
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).
318
447
319---
448---
320
449
321## 10. Authority & safety (implementation notes)
450## 11. Authority & safety (implementation notes)
322
451
323- Interpreter runs only on the server.
452- Interpreter runs only on the server.
324- Every gameplay effect goes through existing command handlers.
453- Every gameplay effect goes through existing command handlers.
325- No filesystem, network, `eval`, or shared mutable globals across characters.
454- No filesystem, network, `eval`, or shared mutable globals across characters.
326- Name matching uses the same display names players see in tooltips / shops.
455- Name matching uses the same display names players see in tooltips / shops.
327- Script controller and client controller: only one produces intents at a time; starting a script disables manual gameplay intents until Stop (or manual intent cancels script — pick one policy and stick to it; **recommended:** any manual gameplay intent **stops** the script).
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.
328
458
329---
459---
330
460
331## 11. Implementation plan (phased)
461## 12. Implementation plan (phased)
332
462
3331. **Data + UI shell** — CRUD scripts, flags, editor with highlighting, no execution.
4631. **Data + UI shell** — CRUD scripts, flags, editor with highlighting, no execution.
3342. **Online runner** — interpreter + run bar + stop; subset: `find` / `go` / `wait` / `label` / `goto` / `stop`.
4642. **Online runner** — interpreter + run bar + stop; `find` / `go` (blocking) / `wait` / `wait until` / `label` / `goto` / `stop`.
3353. **Gather + equip + vitals if** — `mine` / `chop` / `harvest` / `equip` / `if health|stamina`.
4653. **Gather + gear + vitals** — `mine` / `chop` / `harvest` / `equip` / `unequip` / `drink` / `eat` / `if health|stamina`.
3364. **Combat + shops + craft** — `attack` / `buy` / `sell` / `craft` / `can craft`.
4664. **Combat + shops + craft/alchemy** — stations via `craft` (tailor `dye` flag); cauldron via step verbs + recipe-gated `brew` + `cauldron dye [...]`.
3375. **Loops + range checks** — `for` / `while` / `in range *`.
4675. **Loops + range + bag/target queries**.
3386. **AFK auto-start** — 5-minute idle.
4686. **Bank, cheques, market, spells, pigeon, chat, bounty, spellbooks**.
3397. **Offline logout flow** — modal, entity retention, 1-hour cap, re-login attach, error pigeon.
4697. **AFK auto-start** — 5-minute idle.
4708. **Offline logout flow** — modal, entity retention, 1-hour cap, re-login attach, error pigeon, **death → full logout**.
340
471
341---
472---
342
473
343## 12. Open choices (resolve during implementation)
474## 13. Open choices (resolve during implementation)
344
475
345- Exact radius for `in range mob/ground` (proposed **15**).
476- Exact radius for `in range mob/ground` (proposed **15**).
346- Whether `attack` should block until the mob dies (v1: **no**).
477- AFK timer: opening Scripts panel does **not** reset idle (only gameplay intents).
347- Whether opening the Scripts panel resets the AFK timer (proposed: **no**, only gameplay intents).
478- Display-name collisions: **closest** wins.
348- Display-name collisions (multiple “Humanoid”): always **closest** wins.
479- `send pigeon to "Name"` payload: letter only, or also item/cheque from bag — match the pigeon UI’s current options.
480- `wait until … or N` timeout syntax — recommended for all `wait until` forms.
481- `market cancel` when multiple orders exist: require item name disambiguation.
482
483---
484
485## 14. Out of scope
486
487| Area | Reason |
488|------|--------|
489| **Follow** | Not needed for scripts |
490| **Friends** | Social; low AFK value |
491| **Barber / hair** | Cosmetics |
492| **Inspect / social panel** | Not needed for AFK |
493| **Graphics settings** | Client-only |
494| **World editor** | Admin |
495| **`respawn` command** | Death always full-logout; player uses respawn UI on next login |
496
497- 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.).
498
499### Still fine to add later if play gains new intents
500
501Dye-clothing-from-bag (if not covered by cauldron), inheritance claim, blank-cheque get/return — add a matching verb when useful.
502
503When a new player-facing intent ships, add a matching script statement in the same feature commit.