BlueGit

timfa questward

Harden scripts plan: mandatory wait timeouts and edge-case review.

timfa Tim Falken · pushed by timfa

Authored 2026-08-27 · 2 months ago

Hash
7d16731631e1c544e93b19379af909aa4c98312f
Parent
437ae08f
1 file changed +122 −26
docs/SCRIPTS.md +122 −26
@@ -229,7 +229,7 @@ List syntax: `[ "...", "..." ]`.
229 229
230 230 | Statement | Meaning |
231 231 |-----------|---------|
232 | `attack` | Attack the targeted mob (player Attack intent). Does **not** wait for the kill by itself — use `wait until target dead` (§6.11). |
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 233 | `stop attack` | Cancel the current attack engage (player cancel-attack). |
234 234 | `buy "Feather" 10` | Buy quantity from targeted shop mob. Fails if no shop, not in range, can’t afford, or not stocked. |
235 235 | `sell "Soft leather" 5` | Sell quantity to targeted shop mob (if it buys). |
@@ -277,15 +277,15 @@ Requires being at / having path-interacted with the right block where the game r
277 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 278 | `raise bounty on "Ada Worker" 100` | Raise bounty (near bounty office, pays from bag). |
279 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. |
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 282 | `say "hello"` | Local chat say. |
283 283
284 284 ### 6.9 Spells
285 285
286 286 | Statement | Meaning |
287 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). |
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 289 | `cast "Spark" on mob` | Cast entity-target spell on the mob target. |
290 290 | `cast "Light" on block` | Explicit tile target = targeted block’s tile. |
291 291
@@ -329,7 +329,7 @@ while in range mob "Rat"
329 329 find mob "Rat"
330 330 go mob
331 331 attack
332 wait until target dead
332 wait until target dead or 60
333 333 end
334 334 ```
335 335
@@ -347,22 +347,22 @@ Rules:
347 347 | Statement | Meaning |
348 348 |-----------|---------|
349 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. |
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 360
361 361 **Principle:** every boolean condition usable in `if` / `while` is also valid after `wait until`. Extend this set whenever new conditions ship.
362 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.
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 364
365 `go` / gather / `craft` / `brew` already **block** like a built-in `wait until` for their own completion.
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 366
367 367 ### 6.13 Utility
368 368
@@ -426,7 +426,7 @@ Highlight at least:
426 426 | Class | Examples |
427 427 |-------|----------|
428 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` |
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 430 | String | `"..."` |
431 431 | List | `[ "...", "..." ]` (flower lists for `cauldron dye`) |
432 432 | Number | `10`, `30` |
@@ -473,12 +473,27 @@ Invalid lines can be marked with a subtle error underline on Save (optional v1).
473 473
474 474 ## 13. Open choices (resolve during implementation)
475 475
476 - Exact radius for `in range mob/ground` (proposed **15**).
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.
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).
482 497
483 498 ---
484 499
@@ -493,11 +508,92 @@ Invalid lines can be marked with a subtle error underline on Save (optional v1).
493 508 | **Graphics settings** | Client-only |
494 509 | **World editor** | Admin |
495 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 |
496 512
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.).
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.).
498 514
499 515 ### Still fine to add later if play gains new intents
500 516
501 Dye-clothing-from-bag (if not covered by cauldron), inheritance claim, blank-cheque get/return — add a matching verb when useful.
517 Inheritance claim, blank-cheque get/return — add a matching verb when useful.
502 518
503 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.
@@ -229,7 +229,7 @@ List syntax: `[ "...", "..." ]`.
229
229
230| Statement | Meaning |
230| Statement | Meaning |
231|-----------|---------|
231|-----------|---------|
232| `attack` | Attack the targeted mob (player Attack intent). Does **not** wait for the kill by itself — use `wait until target dead` (§6.11). |
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). |
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. |
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). |
235| `sell "Soft leather" 5` | Sell quantity to targeted shop mob (if it buys). |
@@ -277,15 +277,15 @@ Requires being at / having path-interacted with the right block where the game r
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| `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). |
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). |
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). |
280| `send pigeon to "Ada Worker"` | Courier to that character; payload prefers a written letter, else a cheque (§13). |
281| `write letter "..."` | Write letter body onto a blank letter/cheque flow as the game allows. |
281| `write letter "..."` | Write body onto a **blank letter** in the bag (fails if none); does not send. |
282| `say "hello"` | Local chat say. |
282| `say "hello"` | Local chat say. |
283
283
284### 6.9 Spells
284### 6.9 Spells
285
285
286| Statement | Meaning |
286| Statement | Meaning |
287|-----------|---------|
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). |
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. |
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. |
290| `cast "Light" on block` | Explicit tile target = targeted block’s tile. |
291
291
@@ -329,7 +329,7 @@ while in range mob "Rat"
329 find mob "Rat"
329 find mob "Rat"
330 go mob
330 go mob
331 attack
331 attack
332 wait until target dead
332 wait until target dead or 60
333end
333end
334```
334```
335
335
@@ -347,22 +347,22 @@ Rules:
347| Statement | Meaning |
347| Statement | Meaning |
348|-----------|---------|
348|-----------|---------|
349| `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). |
350| `wait until arrived or 30` | 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. |
351| `wait until gathered or 120` | Block until the active mine/chop/harvest completes. |
352| `wait until crafted` | Block until the active station craft / `brew` / `cauldron bottle` completes. |
352| `wait until crafted or 120` | 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. |
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` | Block until own HP ≥ N (or timeout — see below). |
354| `wait until health at least 50 or 120` | Block until own HP ≥ N. |
355| `wait until stamina at least 5` | Block until stamina ≥ N. |
355| `wait until stamina at least 5 or 60` | Block until stamina ≥ N. |
356| `wait until in range item "Bronze bar"` | Block until bag has that item. |
356| `wait until in range item "Bronze bar" or 60` | Block until bag has that item. |
357| `wait until in range mob "Deer"` | Block until such a mob is in range. |
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` | Block until quantity met. |
358| `wait until bag has "Tin ore" at least 10 or 300` | Block until quantity met. |
359| `wait until can craft "Bronze bar"` | Block until craft would succeed at current station target. |
359| `wait until can craft "Bronze bar" or 60` | Block until craft would succeed at current station target. |
360
360
361**Principle:** every boolean condition usable in `if` / `while` is also valid after `wait until`. Extend this set whenever new conditions ship.
361**Principle:** every boolean condition usable in `if` / `while` is also valid after `wait until`. Extend this set whenever new conditions ship.
362
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.
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
364
365`go` / gather / `craft` / `brew` already **block** like a built-in `wait until` for their own completion.
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
366
367### 6.13 Utility
367### 6.13 Utility
368
368
@@ -426,7 +426,7 @@ Highlight at least:
426| Class | Examples |
426| Class | Examples |
427|-------|----------|
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` |
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` |
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 | `"..."` |
430| String | `"..."` |
431| List | `[ "...", "..." ]` (flower lists for `cauldron dye`) |
431| List | `[ "...", "..." ]` (flower lists for `cauldron dye`) |
432| Number | `10`, `30` |
432| Number | `10`, `30` |
@@ -473,12 +473,27 @@ Invalid lines can be marked with a subtle error underline on Save (optional v1).
473
473
474## 13. Open choices (resolve during implementation)
474## 13. Open choices (resolve during implementation)
475
475
476- Exact radius for `in range mob/ground` (proposed **15**).
476Resolved defaults (change only with a good reason):
477- AFK timer: opening Scripts panel does **not** reset idle (only gameplay intents).
477
478- Display-name collisions: **closest** wins.
478| Topic | Decision |
479- `send pigeon to "Name"` payload: letter only, or also item/cheque from bag — match the pigeon UI’s current options.
479|-------|----------|
480- `wait until … or N` timeout syntax — recommended for all `wait until` forms.
480| `in range mob/ground` radius | **15** tiles Chebyshev |
481- `market cancel` when multiple orders exist: require item name disambiguation.
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
494Still soft:
495
496- Exact flower **display names** in `cauldron dye` must match item defs (document in editor autocomplete later).
482
497
483---
498---
484
499
@@ -493,11 +508,92 @@ Invalid lines can be marked with a subtle error underline on Save (optional v1).
493| **Graphics settings** | Client-only |
508| **Graphics settings** | Client-only |
494| **World editor** | Admin |
509| **World editor** | Admin |
495| **`respawn` command** | Death always full-logout; player uses respawn UI on next login |
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 |
496
512
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.).
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.).
498
514
499### Still fine to add later if play gains new intents
515### Still fine to add later if play gains new intents
500
516
501Dye-clothing-from-bag (if not covered by cauldron), inheritance claim, blank-cheque get/return — add a matching verb when useful.
517Inheritance claim, blank-cheque get/return — add a matching verb when useful.
502
518
503When a new player-facing intent ships, add a matching script statement in the same feature commit.
519When 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
566Issues that remain hard or only partly specified — fix in implementation or revisit the design:
567
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.
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.
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.
5714. **Pigeon cargo model** — real UI may allow more than letter/cheque; script support may lag the UI until cargo selection is unified.
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`.
5736. **Tailor random dye** — non-deterministic scripts (harder to test). Intentional per design; document it.
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.
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.
5769. **Partial command surface** — any new play feature without a script verb creates parity drift (§14 reminder). Process discipline, not a technical guarantee.
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.
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.
57912. **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.”**
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.
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.