Harden scripts plan: mandatory wait timeouts and edge-case review.
@@ -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 r277
| `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 Spells284
### 6.9 Spells285
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 mob330
go mob331
attack331
attack332
wait until target dead332
wait until target dead or 60333
end333
end334
```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
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
### 6.13 Utility367
### 6.13 Utility368
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**).476
Resolved 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
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
| **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.).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
### Still fine to add later if play gains new intents515
### Still fine to add later if play gains new intents500
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
When a new player-facing intent ships, add a matching script statement in the same feature commit.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 & names526
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 interrupted532
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 & waits538
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 & cauldron544
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 switches551
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 / abuse558
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 problems565
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.