BlueGit

timfa questward

Files

questward / docs / SCRIPTS.md

SCRIPTS.md

SCRIPTS.md 29.7 KiB Download Raw

Player scripts (AFK / offline)

Status: not implemented (design only) Related: tile_mmo_server_technical_design_v0.6.md §18 (controller abstraction, offline entity, sandbox rules)

Scripts are a sandboxed language interpreted on the server. They never mutate world state directly; they emit the same player intents as a human client (moveTo, gather, craft, attack, shop, equip, …). The server validates every step.

This document is the product + language spec for implementation.

---

1. Goals

  • Automate simple loops: gather → bank/craft → fight → recover.
  • Run while online (watch + stop bar), while AFK (idle 5+ minutes), or while offline (character stays in the world, max 1 hour).
  • Keep the language small, readable, and hard to misuse.
  • Fail loudly: toast (online) or pigeon letter (offline), with line + operation + reason.

---

2. Player UI

2.1 Scripts button

  • HUD control Scripts opens the Scripts panel.
  • Panel lists the player’s saved scripts (name + badges for Offline / AFK flags).
  • Actions per script: Edit, Delete, Run (online).
  • New script creates an empty script and opens the editor.

2.2 Script editor

  • Name field.
  • Text area with syntax highlighting (keywords, strings, numbers, comments, labels).
  • Flags (mutually independent; at most one script should be marked for each role — marking one clears that flag on others):
  • Run this while offline — eligible on logout confirmation.
  • Run while AFK — auto-starts after 5 minutes with no player actions.
  • Save / Cancel.

2.3 Online run bar

When a script is running (started manually, AFK auto-start, or resumed after re-login onto an offline script):

  • Fixed bar at the bottom of the screen.
  • Shows: script name, current line (number + source text), Stop.
  • Manual player intents (move, attack, gather, …) stop the script (treat as cancel), except pure camera/UI (open bag, zoom, settings).

2.4 Logout confirmation

On logout while in the world:

1. Modal: Are you sure you want to log out?

  • No — stay.
  • Yes — log out.
  • Checkbox (default unchecked): Run offline script
  • Enabled only if the player has a script marked Run this while offline.

2. If the checkbox is checked, show an extra red line: Running a script means your character remains in the world and can still be attacked! 3. Confirming with the checkbox checked starts/continues the offline script on that character (see §4).

---

3. Modes

ModeHow it startsCharacter in worldClient
OnlineScripts panel → RunYesConnected; run bar visible
AFKNo gameplay intents for 5 minutes, and an AFK-marked script existsYesStill connected; run bar appears when script starts
OfflineLogout with offline checkboxYes (no NetworkIdentity; keeps ChunkLoader)Disconnected

AFK timer: reset on any gameplay intent sent by the player (move, attack, gather, craft, shop, equip, cast, pickup, talk, …). Opening UI / scrolling chat does not reset AFK if those are not intents; prefer resetting on any outbound play command for simplicity.

Offline duration: max 1 hour from offline-script start (or remaining time after restart rehydrate). Then: stop script, despawn character, persist as a normal logout.

Re-login during offline script: attach the client to the existing entity; keep the script running; show the run bar so the player can Stop.

---

4. Errors

4.1 Message shape

Always:

Line <n>: <operation> — <reason>

Example:

Line 12: mine — No reachable iron ore nearby.

4.2 Online / AFK (client connected)

  • Stop the script.
  • Show a persistent toast (stays until the player dismisses it) with the error message.

4.3 Offline (no client)

  • Stop the script.
  • Remove the character from the world (normal offline persist).
  • Queue a pigeon letter:
  • Author display name: Frederick
  • Role flavour: manager of Idle Gaming (author line / signature as other system letters do)
  • Body:

Unfortunately, your script encountered an error. then a blank line, then the error message from §4.1.

---

5. Language overview

  • Line-oriented, case-insensitive keywords.
  • One statement per line (blank lines and comments allowed).
  • Comments: # ... to end of line.
  • Strings: "double quotes" (names of blocks, mobs, items). Matching is case-insensitive display-name match unless noted.
  • Numbers: integers (10, 100).
  • Labels: label name_here — name is letters, digits, underscore.
  • No variables in v1 except implicit targets (current block / mob / ground item) and loop counters internal to for / while.
  • No user-defined functions in v1.
  • Sandbox: not JavaScript; custom interpreter only (§18.7 design doc).

5.1 Implicit targets

The script keeps three optional targets (cleared when a new target of that kind is set, or on error/stop):

TargetSet byUsed by
Blockfind block "..."go, mine, chop, harvest, craft, in range block
Mobfind mob "..."go, attack, buy, sell, in range mob
Groundfind ground "..."go, take, use, in range ground

go without a kind uses the most recently set target. Prefer explicit forms when ambiguous: go block, go mob, go ground.

---

6. Statements (v1)

6.1 Targeting

StatementMeaning
find block "Iron ore"Closest reachable block whose display name matches. Sets block target. Fails if none.
find mob "Shopkeeper"Closest living mob/NPC whose name matches. Sets mob target. Fails if none.
find ground "Log"Closest ground item whose display name matches. Sets ground target. Fails if none.

“Closest” = Chebyshev distance from the player, then path-reachable. Unreachable candidates are skipped.

6.2 Movement

StatementMeaning
goPath to the last set target (block / mob / ground). Blocks until arrived or fails (blocked / lost / unreachable).
go block / go mob / go groundSame, explicit target kind. Also blocks until arrival.
run on / run offToggle run gait (same rules as player: needs stamina).

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.

6.3 Gathering & world interact

StatementMeaning
mineGather/mine the targeted block (ore boulder, etc.). Blocks until finished or fails.
chopFell the targeted tree block. Blocks until finished.
harvestPick/harvest the targeted plant/herb/flower/cotton block. Blocks until finished.
takePick up the targeted ground item into the bag.
useInteract with the targeted ground item if it has a use (e.g. light a log).

Exact gather verb must match what the block supports; wrong verb → error (chop — That is not a tree.).

6.4 Crafting stations & alchemy

Principle: script steps mirror what a player does in the UI. No free shortcuts that skip materials, skill, adjacency, or recipe knowledge.

Crafting stations (furnace, anvil, woodworking, bench, spinning wheel, loom, tailor, leatherworking, …)

StatementMeaning
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).
can craft "Bronze bar"Condition only. True if that craft would succeed right now.
craft "Cotton sweater" dyeTailor 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.
craft "Cotton sweater"Tailor (or other station) without dyeing.

Alchemy cauldron — manual steps (1:1 with UI)

Require a targeted cauldron (find + go / adjacency), same as opening the cauldron as a player.

StatementMeaning
cauldron insert "Thyme"Insert that ingredient from the bag.
cauldron heatHeat.
cauldron stirStir.
cauldron coolCool.
cauldron bottleBottle into an empty glass bottle. Blocks until done.
cauldron clearClear/abandon the brew if the UI allows it.

Step order and outcomes match humans: correct sequence → potion (with Alchemy skill roll); wrong sequence → unstable brew. Scripts get no easier success path.

Example (same steps a player would click):

find block "Cauldron"
go block
cauldron insert "Thyme"
cauldron heat
cauldron insert "Mint"
cauldron stir
cauldron bottle

Named brew — only with a recipe paper in the bag

StatementMeaning
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.).

Without a recipe item, authors must write the cauldron … steps themselves. brew is “follow this paper,” not free knowledge of the recipe.

Dyes (flower list, same as dye tab)

StatementMeaning
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.

List syntax: [ "...", "..." ].

6.5 Combat & shops

StatementMeaning
attackAttack the targeted mob (player Attack intent). Does not wait for the kill by itself — use wait until target dead or 60 (§6.12).
stop attackCancel the current attack engage (player cancel-attack).
buy "Feather" 10Buy quantity from targeted shop mob. Fails if no shop, not in range, can’t afford, or not stocked.
sell "Soft leather" 5Sell quantity to targeted shop mob (if it buys).

Follow is intentionally not supported.

6.6 Inventory, gear & vitals

StatementMeaning
equip "Bronze pickaxe"Equip a matching item from the bag into its proper slot. Fails if missing or not equippable.
unequip weaponClear that equipment slot into the bag. Slots: head, chest, legs, boots, weapon, offhand (same as game). Fails if the bag has no free space.
drink "Lesser health tonic"Drink a matching consumable from the bag.
eat "Apple"Eat a matching food from the bag.
drop "Tin ore" 5Drop quantity from the bag onto the ground.
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.
if health below 30 …See control flow.
if stamina below 5 …See control flow.

6.7 Range checks & queries

StatementMeaning
if in range block "Furnace"True if a matching block exists within interaction/path range.
if in range mob "Deer"True if a matching living mob is within 15 tiles Chebyshev.
if in range ground "Bones"True if a matching ground item is within 15 tiles.
if in range item "Bronze bar"True if the bag contains that item (quantity ≥ 1).
if bag has "Tin ore" at least 10Bag quantity check.
if bag has "Tin ore" below 10Bag quantity check.
if target health below 20Targeted mob current HP below N. Fails the condition (false) if no mob target; does not hard-error.
if target deadTargeted mob is gone or at 0 HP.

6.8 Bank, cheques, market, social economy

Requires being at / having path-interacted with the right block where the game requires it (bank counter, bounty office, marketplace).

StatementMeaning
bank deposit "Tin ore" 20Move quantity from bag → vault.
bank withdraw "Tin ore" 20Move quantity from vault → bag.
write cheque "Tin ore" 50Write a cheque reserving that item+qty from the bank (vault). Fails if the vault lacks enough.
redeem chequeRedeem a written cheque from the bag at a bank (goods → vault), same as player.
market sell "Tin ore" 10 for 8Place sell order (qty, min unit price). Escrows goods + listing fee like the UI.
market buy "Tin ore" 10 for 12Place buy order (qty, max unit price). Escrows coins like the UI.
market cancel sell / market cancel buyCancel the character’s open order of that side (or nearest matching — prefer cancelling by item name if multiple: market cancel sell "Tin ore").
raise bounty on "Ada Worker" 100Raise bounty (near bounty office, pays from bag).
send pigeon to bankCourier cargo to own bank (same rules as UI).
send pigeon to "Ada Worker"Courier to that character; payload prefers a written letter, else a cheque (§13).
write letter "..."Write body onto a blank letter in the bag (fails if none); does not send.
say "hello"Local chat say.

6.9 Spells

StatementMeaning
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).
cast "Spark" on mobCast entity-target spell on the mob target.
cast "Light" on blockExplicit tile target = targeted block’s tile.

Fails if unknown spell, not learned, on cooldown, out of range with no path, or wrong target kind.

6.10 Labels & jumps

StatementMeaning
label campDeclare label camp.
goto campJump to that label.

Forward and backward jumps allowed. Jumping into/out of loops is disallowed (error if attempted).

6.11 Control flow

if health below 30
  goto heal
end

if stamina below 5
  run off
end

if can craft "Bronze bar"
  craft "Bronze bar"
end

if in range item "Bronze pickaxe"
  equip "Bronze pickaxe"
end

for 10
  find block "Tin ore"
  go block
  mine
end

while in range mob "Rat"
  find mob "Rat"
  go mob
  attack
  wait until target dead or 60
end

Rules:

  • Blocks end with end.
  • if body runs when the condition is true; no else (use a second if / goto).
  • for N — repeat body N times (N ≥ 1, max 1000).
  • while <condition> — repeat while condition true; max 1000 iterations per while then error (while — Too many repeats.).
  • Conditions:

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

6.12 Waiting (wait / wait until)

StatementMeaning
wait 2Pause 2 seconds (server time). Max 60 per wait.
wait until arrived or 30Block until the current path finishes (usually redundant after go, which already waits).
wait until gathered or 120Block until the active mine/chop/harvest completes.
wait until crafted or 120Block until the active station craft / brew / cauldron bottle completes.
wait until target dead or 60Block until the mob target is dead or despawned. Fails if no mob target.
wait until health at least 50 or 120Block until own HP ≥ N.
wait until stamina at least 5 or 60Block until stamina ≥ N.
wait until in range item "Bronze bar" or 60Block until bag has that item.
wait until in range mob "Deer" or 30Block until such a mob is in range.
wait until bag has "Tin ore" at least 10 or 300Block until quantity met.
wait until can craft "Bronze bar" or 60Block until craft would succeed at current station target.

Principle: every boolean condition usable in if / while is also valid after wait until. Extend this set whenever new conditions ship.

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.).

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).

6.13 Utility

StatementMeaning
stopEnd the script successfully (no error letter).

---

7. Death while a script is running

If the character dies for any reason while a script is active (online, AFK, or offline):

1. Stop the script immediately (not an “error letter” unless death was caused mid-op failure — death itself is a clean stop). 2. Fully log the instance out of the world (despawn entity, persist dead flag / position as normal death logout). 3. When the player next connects, they see the normal respawn screen — no auto-respawn from scripts.

There is no respawn script command.

---

8. Example script

# Tin loop with panic flee
label start
equip "Bronze pickaxe"
run on

for 20
  if health below 25
    goto flee
  end
  find block "Tin ore"
  go block
  mine
  if in range ground "Tin ore"
    find ground "Tin ore"
    go ground
    take
  end
end
stop

label flee
run on
drink "Lesser health tonic"
stop attack
find block "Bank"
go block
bank deposit "Tin ore" 999
stop

---

9. Syntax highlighting (editor)

Highlight at least:

ClassExamples
Keywordfind, 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
Subkeywordblock, 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
String"..."
List[ "...", "..." ] (flower lists for cauldron dye)
Number10, 30
Comment# ...
Label nameafter label / goto
Slot nameafter unequip (weapon, head, …)

Invalid lines can be marked with a subtle error underline on Save (optional v1).

---

10. Persistence & limits

  • Scripts stored per character in state DB (name, source text, flags, updatedAt).
  • Soft caps (suggested): 20 scripts / character, 200 lines / script, 4 KB source.
  • Offline script runtime state: program counter, targets, loop stack, offlineUntil timestamp — rehydrated on server restart (§18.6).
  • 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).

---

11. Authority & safety (implementation notes)

  • Interpreter runs only on the server.
  • Every gameplay effect goes through existing command handlers.
  • No filesystem, network, eval, or shared mutable globals across characters.
  • Name matching uses the same display names players see in tooltips / shops.
  • Script controller and client controller: only one produces intents at a time; any manual gameplay intent stops the script.
  • Offline say / pigeon / bounty: same validation as players; add rate limits if abused.

---

12. Implementation plan (phased)

1. Data + UI shell — CRUD scripts, flags, editor with highlighting, no execution. 2. Online runner — interpreter + run bar + stop; find / go (blocking) / wait / wait until / label / goto / stop. 3. Gather + gear + vitals — mine / chop / harvest / equip / unequip / drink / eat / if health|stamina. 4. Combat + shops + craft/alchemy — stations via craft (tailor dye flag); cauldron via step verbs + recipe-gated brew + cauldron dye [...]. 5. Loops + range + bag/target queries. 6. Bank, cheques, market, spells, pigeon, chat, bounty, spellbooks. 7. AFK auto-start — 5-minute idle. 8. Offline logout flow — modal, entity retention, 1-hour cap, re-login attach, error pigeon, death → full logout.

---

13. Open choices (resolve during implementation)

Resolved defaults (change only with a good reason):

TopicDecision
in range mob/ground radius15 tiles Chebyshev
AFK timer vs Scripts panelOpening the panel does not reset idle
Name collisionsClosest reachable/living match wins
wait until timeoutRequired form: wait until <cond> or <seconds> (max 300). Bare wait until without or N is a parse error so offline scripts cannot hang forever
cast fizzleNot a script error — line completes; use if / skill checks if you care
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
redeem cheque with several chequesRedeem the first written cheque in bag order
market cancel sell "Tin ore"Cancel the oldest open sell order for that item name
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.)
write letter "..."Writes onto a blank letter in the bag (fails if none); does not send
Editing a script while it runsSave applies next Run only; running copy is a snapshot
AFK start while a script already runsDo not start a second script
Offline logout while a script already runs onlineOffline flag continues that run (same PC); do not restart from line 1

Still soft:

  • Exact flower display names in cauldron dye must match item defs (document in editor autocomplete later).

---

14. Out of scope

AreaReason
FollowNot needed for scripts
FriendsSocial; low AFK value
Barber / hairCosmetics
Inspect / social panelNot needed for AFK
Graphics settingsClient-only
World editorAdmin
respawn commandDeath always full-logout; player uses respawn UI on next login
User variables / functionsv1 stays line+label only; revisit if scripts become unreadable

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.).

Still fine to add later if play gains new intents

Inheritance claim, blank-cheque get/return — add a matching verb when useful.

When a new player-facing intent ships, add a matching script statement in the same feature commit.

---

15. Runtime edge cases (resolved in plan)

15.1 Targeting & names

  • find uses display names (case-insensitive). Ore nodes, trees, and dyed clothing must match what tooltips show.
  • 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.).
  • Block vs ground vs bag: verbs decide the namespace (mine always uses block target; take uses ground; in range item uses bag).

15.2 Blocking ops interrupted

  • 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).
  • run on with 0 stamina: gait falls back to walk (same as player); not an error.
  • Full bag on take / gather loot / unequip → error for that line.

15.3 Combat & waits

  • 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.
  • attack then wait until target dead while the mob flees out of chase range: wait hits timeout → error (script must re-find).
  • Town guards / retaliation killing the character → §7 death logout (clean stop, no Frederick letter).

15.4 Stations & cauldron

  • craft / brew / cauldron * require adjacency to the targeted station block like the UI.
  • 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.
  • cauldron dye [...] fails if the alchemy brew tab is mid-potion (busy cauldron).
  • Unstable potion from wrong manual steps is success of bottling, not a script error (player can get unstable too).

15.5 Mode switches

  • Disconnect while online script running without offline checkbox → stop script + normal logout (entity despawn).
  • Disconnect with offline already running → keep offline run.
  • Re-login onto offline script: restore run bar; PC unchanged.
  • Server restart: persist PC, targets (by tile + name + entityId if still valid), wait deadline, offlineUntil; invalid target after rehydrate → error letter.

15.6 Safety / abuse

  • 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.
  • 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.

---

16. Known weaknesses & open problems

Issues that remain hard or only partly specified — fix in implementation or revisit the design:

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. 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. 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. 4. Pigeon cargo model — real UI may allow more than letter/cheque; script support may lag the UI until cargo selection is unified. 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. 6. Tailor random dye — non-deterministic scripts (harder to test). Intentional per design; document it. 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. 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. 9. Partial command surface — any new play feature without a script verb creates parity drift (§14 reminder). Process discipline, not a technical guarantee. 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. 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. 12. AFK false positives — idle 5 minutes in a menu reading skills still starts AFK script. Acceptable; players can Stop or unmark AFK.

---

17. Feasibility & stability (assessment)

Feasibility: high for a phased build; medium-high for “full parity.” 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.

Stability in use: good if timeouts and fail-loud rules hold; fragile if name-matching and waits are sloppy.

AreaOutlook
Online scriptsStable: same validation as players; run bar + Stop; manual intent cancels script
AFK auto-startStable with clear Stop; occasional surprise starts (§16.12)
Offline hourStable for gameplay; ops risk on region load — needs caps + metrics
Long wait untilStable only with mandatory or N timeouts
Economy botsWill exist (shops/market/gather); rate limits and normal game costs are the balance knobs
Player trustDeath→logout and Frederick letters are clear; herb loss on death mid-brew must be documented

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.

Source
1# Player scripts (AFK / offline)
2
3**Status:** not implemented (design only)
4**Related:** `tile_mmo_server_technical_design_v0.6.md` §18 (controller abstraction, offline entity, sandbox rules)
5
6Scripts are a **sandboxed language** interpreted on the **server**. They never mutate world state directly; they emit the same player **intents** as a human client (`moveTo`, gather, craft, attack, shop, equip, …). The server validates every step.
7
8This document is the product + language spec for implementation.
9
10---
11
12## 1. Goals
13
14- Automate simple loops: gather → bank/craft → fight → recover.
15- Run **while online** (watch + stop bar), **while AFK** (idle 5+ minutes), or **while offline** (character stays in the world, max 1 hour).
16- Keep the language **small**, readable, and hard to misuse.
17- Fail loudly: toast (online) or pigeon letter (offline), with line + operation + reason.
18
19---
20
21## 2. Player UI
22
23### 2.1 Scripts button
24
25- HUD control **Scripts** opens the Scripts panel.
26- Panel lists the player’s saved scripts (name + badges for Offline / AFK flags).
27- Actions per script: **Edit**, **Delete**, **Run** (online).
28- **New script** creates an empty script and opens the editor.
29
30### 2.2 Script editor
31
32- Name field.
33- Text area with **syntax highlighting** (keywords, strings, numbers, comments, labels).
34- Flags (mutually independent; at most one script should be marked for each role — marking one clears that flag on others):
35 - **Run this while offline** — eligible on logout confirmation.
36 - **Run while AFK** — auto-starts after 5 minutes with no player actions.
37- **Save** / **Cancel**.
38
39### 2.3 Online run bar
40
41When a script is running (started manually, AFK auto-start, or resumed after re-login onto an offline script):
42
43- Fixed bar at the **bottom** of the screen.
44- Shows: script name, **current line** (number + source text), **Stop**.
45- Manual player intents (move, attack, gather, …) **stop** the script (treat as cancel), except pure camera/UI (open bag, zoom, settings).
46
47### 2.4 Logout confirmation
48
49On logout while in the world:
50
511. Modal: **Are you sure you want to log out?**
52 - **No** — stay.
53 - **Yes** — log out.
54 - Checkbox (default **unchecked**): **Run offline script**
55 - Enabled only if the player has a script marked **Run this while offline**.
562. If the checkbox is checked, show an extra **red** line:
57 **Running a script means your character remains in the world and can still be attacked!**
583. Confirming with the checkbox checked starts/continues the offline script on that character (see §4).
59
60---
61
62## 3. Modes
63
64| Mode | How it starts | Character in world | Client |
65|------|---------------|--------------------|--------|
66| **Online** | Scripts panel → Run | Yes | Connected; run bar visible |
67| **AFK** | No gameplay intents for **5 minutes**, and an AFK-marked script exists | Yes | Still connected; run bar appears when script starts |
68| **Offline** | Logout with offline checkbox | Yes (no NetworkIdentity; keeps ChunkLoader) | Disconnected |
69
70**AFK timer:** reset on any **gameplay intent** sent by the player (move, attack, gather, craft, shop, equip, cast, pickup, talk, …). Opening UI / scrolling chat does not reset AFK if those are not intents; prefer resetting on any outbound play command for simplicity.
71
72**Offline duration:** max **1 hour** from offline-script start (or remaining time after restart rehydrate). Then: stop script, despawn character, persist as a normal logout.
73
74**Re-login during offline script:** attach the client to the existing entity; keep the script running; show the run bar so the player can Stop.
75
76---
77
78## 4. Errors
79
80### 4.1 Message shape
81
82Always:
83
84```text
85Line <n>: <operation> — <reason>
86```
87
88Example:
89
90```text
91Line 12: mine — No reachable iron ore nearby.
92```
93
94### 4.2 Online / AFK (client connected)
95
96- Stop the script.
97- Show a **persistent toast** (stays until the player dismisses it) with the error message.
98
99### 4.3 Offline (no client)
100
101- Stop the script.
102- Remove the character from the world (normal offline persist).
103- Queue a **pigeon letter**:
104 - Author display name: **Frederick**
105 - Role flavour: manager of Idle Gaming (author line / signature as other system letters do)
106 - Body:
107 `Unfortunately, your script encountered an error.`
108 then a blank line, then the error message from §4.1.
109
110---
111
112## 5. Language overview
113
114- Line-oriented, case-insensitive **keywords**.
115- One statement per line (blank lines and comments allowed).
116- Comments: `# ...` to end of line.
117- Strings: `"double quotes"` (names of blocks, mobs, items). Matching is **case-insensitive** display-name match unless noted.
118- Numbers: integers (`10`, `100`).
119- Labels: `label name_here` — name is letters, digits, underscore.
120- No variables in v1 except **implicit targets** (current block / mob / ground item) and loop counters internal to `for` / `while`.
121- No user-defined functions in v1.
122- Sandbox: **not** JavaScript; custom interpreter only (§18.7 design doc).
123
124### 5.1 Implicit targets
125
126The script keeps three optional targets (cleared when a new target of that kind is set, or on error/stop):
127
128| Target | Set by | Used by |
129|--------|--------|---------|
130| **Block** | `find block "..."` | `go`, `mine`, `chop`, `harvest`, `craft`, `in range block` |
131| **Mob** | `find mob "..."` | `go`, `attack`, `buy`, `sell`, `in range mob` |
132| **Ground** | `find ground "..."` | `go`, `take`, `use`, `in range ground` |
133
134`go` without a kind uses the **most recently set** target. Prefer explicit forms when ambiguous: `go block`, `go mob`, `go ground`.
135
136---
137
138## 6. Statements (v1)
139
140### 6.1 Targeting
141
142| Statement | Meaning |
143|-----------|---------|
144| `find block "Iron ore"` | Closest **reachable** block whose display name matches. Sets block target. Fails if none. |
145| `find mob "Shopkeeper"` | Closest living mob/NPC whose name matches. Sets mob target. Fails if none. |
146| `find ground "Log"` | Closest ground item whose display name matches. Sets ground target. Fails if none. |
147
148“Closest” = Chebyshev distance from the player, then path-reachable. Unreachable candidates are skipped.
149
150### 6.2 Movement
151
152| Statement | Meaning |
153|-----------|---------|
154| `go` | Path to the last set target (block / mob / ground). **Blocks** until arrived or fails (blocked / lost / unreachable). |
155| `go block` / `go mob` / `go ground` | Same, explicit target kind. Also **blocks** until arrival. |
156| `run on` / `run off` | Toggle run gait (same rules as player: needs stamina). |
157
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
160### 6.3 Gathering & world interact
161
162| Statement | Meaning |
163|-----------|---------|
164| `mine` | Gather/mine the targeted **block** (ore boulder, etc.). **Blocks** until finished or fails. |
165| `chop` | Fell the targeted tree block. **Blocks** until finished. |
166| `harvest` | Pick/harvest the targeted plant/herb/flower/cotton block. **Blocks** until finished. |
167| `take` | Pick up the targeted **ground** item into the bag. |
168| `use` | Interact with the targeted **ground** item if it has a use (e.g. light a log). |
169
170Exact gather verb must match what the block supports; wrong verb → error (`chop — That is not a tree.`).
171
172### 6.4 Crafting stations & alchemy
173
174**Principle:** script steps mirror what a player does in the UI. No free shortcuts that skip materials, skill, adjacency, or recipe knowledge.
175
176#### Crafting stations (furnace, anvil, woodworking, bench, spinning wheel, loom, tailor, leatherworking, …)
177
178| Statement | Meaning |
179|-----------|---------|
180| `craft "Bronze bar"` | At the targeted station **block**, start the same craft the player would (one product). **Blocks** until finished or fails (not at station, unknown recipe, missing mats, skill too low). |
181| `can craft "Bronze bar"` | Condition only. True if that craft would succeed **right now**. |
182| `craft "Cotton sweater" dye` | **Tailor only:** craft with dyeing on. Uses a **random** dye charge from the bag (no colour picker). **Fails** if dyeing is requested and the bag has no dye uses left. |
183| `craft "Cotton sweater"` | Tailor (or other station) **without** dyeing. |
184
185#### Alchemy cauldron — manual steps (1:1 with UI)
186
187Require a targeted cauldron (find + go / adjacency), same as opening the cauldron as a player.
188
189| Statement | Meaning |
190|-----------|---------|
191| `cauldron insert "Thyme"` | Insert that ingredient from the bag. |
192| `cauldron heat` | Heat. |
193| `cauldron stir` | Stir. |
194| `cauldron cool` | Cool. |
195| `cauldron bottle` | Bottle into an empty glass bottle. **Blocks** until done. |
196| `cauldron clear` | Clear/abandon the brew if the UI allows it. |
197
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: `[ "...", "..." ]`.
227
228### 6.5 Combat & shops
229
230| Statement | Meaning |
231|-----------|---------|
232| `attack` | Attack the targeted mob (player Attack intent). Does **not** wait for the kill by itself — use `wait until target dead or 60` (§6.12). |
233| `stop attack` | Cancel the current attack engage (player cancel-attack). |
234| `buy "Feather" 10` | Buy quantity from targeted shop mob. Fails if no shop, not in range, can’t afford, or not stocked. |
235| `sell "Soft leather" 5` | Sell quantity to targeted shop mob (if it buys). |
236
237**Follow** is intentionally **not** supported.
238
239### 6.6 Inventory, gear & vitals
240
241| Statement | Meaning |
242|-----------|---------|
243| `equip "Bronze pickaxe"` | Equip a matching item from the bag into its proper slot. Fails if missing or not equippable. |
244| `unequip weapon` | Clear that equipment **slot** into the bag. Slots: `head`, `chest`, `legs`, `boots`, `weapon`, `offhand` (same as game). **Fails if the bag has no free space.** |
245| `drink "Lesser health tonic"` | Drink a matching consumable from the bag. |
246| `eat "Apple"` | Eat a matching food from the bag. |
247| `drop "Tin ore" 5` | Drop quantity from the bag onto the ground. |
248| `read "Spark spellbook"` | Read a spellbook from the bag to learn its spell (same as player). Fails if missing, already known, or requirements not met. |
249| `if health below 30` … | See control flow. |
250| `if stamina below 5` … | See control flow. |
251
252### 6.7 Range checks & queries
253
254| Statement | Meaning |
255|-----------|---------|
256| `if in range block "Furnace"` | True if a matching block exists within interaction/path range. |
257| `if in range mob "Deer"` | True if a matching living mob is within **15 tiles** Chebyshev. |
258| `if in range ground "Bones"` | True if a matching ground item is within **15 tiles**. |
259| `if in range item "Bronze bar"` | True if the bag contains that item (quantity ≥ 1). |
260| `if bag has "Tin ore" at least 10` | Bag quantity check. |
261| `if bag has "Tin ore" below 10` | Bag quantity check. |
262| `if target health below 20` | Targeted **mob** current HP below N. Fails the condition (false) if no mob target; does not hard-error. |
263| `if target dead` | Targeted mob is gone or at 0 HP. |
264
265### 6.8 Bank, cheques, market, social economy
266
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 prefers a written letter, else a cheque (§13). |
281| `write letter "..."` | Write body onto a **blank letter** in the bag (fails if none); does not send. |
282| `say "hello"` | Local chat say. |
283
284### 6.9 Spells
285
286| Statement | Meaning |
287|-----------|---------|
288| `cast "Light"` | Cast on the targeted **block** tile (tile-target spells). Approaches into range if needed (same as player cast). **Blocks** until cast attempt resolves; **fizzle is not an error** (line completes). |
289| `cast "Spark" on mob` | Cast entity-target spell on the mob target. |
290| `cast "Light" on block` | Explicit tile target = targeted block’s tile. |
291
292Fails if unknown spell, not learned, on cooldown, out of range with no path, or wrong target kind.
293
294### 6.10 Labels & jumps
295
296| Statement | Meaning |
297|-----------|---------|
298| `label camp` | Declare label `camp`. |
299| `goto camp` | Jump to that label. |
300
301Forward and backward jumps allowed. Jumping into/out of loops is **disallowed** (error if attempted).
302
303### 6.11 Control flow
304
305```text
306if health below 30
307 goto heal
308end
309
310if stamina below 5
311 run off
312end
313
314if can craft "Bronze bar"
315 craft "Bronze bar"
316end
317
318if in range item "Bronze pickaxe"
319 equip "Bronze pickaxe"
320end
321
322for 10
323 find block "Tin ore"
324 go block
325 mine
326end
327
328while in range mob "Rat"
329 find mob "Rat"
330 go mob
331 attack
332 wait until target dead or 60
333end
334```
335
336Rules:
337
338- Blocks end with `end`.
339- `if` body runs when the condition is true; no `else` (use a second `if` / `goto`).
340- `for N` — repeat body **N** times (N ≥ 1, max **1000**).
341- `while <condition>` — repeat while condition true; **max 1000** iterations per `while` then error (`while — Too many repeats.`).
342- Conditions:
343 `health below N` · `stamina below N` · `can craft "..."` · `in range block|mob|ground|item "..."` · `bag has "..." at least|below N` · `target health below N` · `target dead`
344
345### 6.12 Waiting (`wait` / `wait until`)
346
347| Statement | Meaning |
348|-----------|---------|
349| `wait 2` | Pause **2 seconds** (server time). Max **60** per wait. |
350| `wait until arrived or 30` | Block until the current path finishes (usually redundant after `go`, which already waits). |
351| `wait until gathered or 120` | Block until the active mine/chop/harvest completes. |
352| `wait until crafted or 120` | Block until the active station craft / `brew` / `cauldron bottle` completes. |
353| `wait until target dead or 60` | Block until the mob target is dead or despawned. Fails if no mob target. |
354| `wait until health at least 50 or 120` | Block until own HP ≥ N. |
355| `wait until stamina at least 5 or 60` | Block until stamina ≥ N. |
356| `wait until in range item "Bronze bar" or 60` | Block until bag has that item. |
357| `wait until in range mob "Deer" or 30` | Block until such a mob is in range. |
358| `wait until bag has "Tin ore" at least 10 or 300` | Block until quantity met. |
359| `wait until can craft "Bronze bar" or 60` | Block until craft would succeed at current station target. |
360
361**Principle:** every boolean condition usable in `if` / `while` is also valid after `wait until`. Extend this set whenever new conditions ship.
362
363**Timeout is mandatory:** every `wait until` must end with `or <seconds>` (1–300). Bare `wait until …` without `or N` is a **parse error**. On timeout → script error (`wait until — Timed out.`).
364
365`go` / gather / `craft` / `brew` already **block** like a built-in wait for their own completion (they have natural end conditions; no separate `or N` on those verbs).
366
367### 6.13 Utility
368
369| Statement | Meaning |
370|-----------|---------|
371| `stop` | End the script successfully (no error letter). |
372
373---
374
375## 7. Death while a script is running
376
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
388
389```text
390# Tin loop with panic flee
391label start
392equip "Bronze pickaxe"
393run on
394
395for 20
396 if health below 25
397 goto flee
398 end
399 find block "Tin ore"
400 go block
401 mine
402 if in range ground "Tin ore"
403 find ground "Tin ore"
404 go ground
405 take
406 end
407end
408stop
409
410label flee
411run on
412drink "Lesser health tonic"
413stop attack
414find block "Bank"
415go block
416bank deposit "Tin ore" 999
417stop
418```
419
420---
421
422## 9. Syntax highlighting (editor)
423
424Highlight at least:
425
426| Class | Examples |
427|-------|----------|
428| Keyword | `find`, `go`, `mine`, `chop`, `harvest`, `craft`, `brew`, `cauldron`, `attack`, `buy`, `sell`, `equip`, `unequip`, `drink`, `eat`, `drop`, `read`, `cast`, `bank`, `market`, `write`, `redeem`, `raise`, `send`, `say`, `label`, `goto`, `if`, `end`, `for`, `while`, `wait`, `stop`, `run`, `take`, `use`, `can` |
429| Subkeyword | `block`, `mob`, `ground`, `item`, `health`, `stamina`, `below`, `at`, `least`, `in`, `range`, `on`, `off`, `until`, `or`, `arrived`, `gathered`, `crafted`, `target`, `dead`, `deposit`, `withdraw`, `cheque`, `pigeon`, `bounty`, `sell`, `buy`, `cancel`, `insert`, `heat`, `stir`, `cool`, `bottle`, `clear`, `dye` |
430| String | `"..."` |
431| List | `[ "...", "..." ]` (flower lists for `cauldron dye`) |
432| Number | `10`, `30` |
433| Comment | `# ...` |
434| Label name | after `label` / `goto` |
435| Slot name | after `unequip` (`weapon`, `head`, …) |
436
437Invalid lines can be marked with a subtle error underline on Save (optional v1).
438
439---
440
441## 10. Persistence & limits
442
443- Scripts stored per character in state DB (name, source text, flags, updatedAt).
444- Soft caps (suggested): **20** scripts / character, **200** lines / script, **4 KB** source.
445- Offline script runtime state: program counter, targets, loop stack, `offlineUntil` timestamp — rehydrated on server restart (§18.6).
446- Instruction budget: small per simulation tick (at most one **blocking** wait/path/gather/craft at a time; non-blocking lines burst with a low cap).
447
448---
449
450## 11. Authority & safety (implementation notes)
451
452- Interpreter runs only on the server.
453- Every gameplay effect goes through existing command handlers.
454- No filesystem, network, `eval`, or shared mutable globals across characters.
455- Name matching uses the same display names players see in tooltips / shops.
456- Script controller and client controller: only one produces intents at a time; **any manual gameplay intent stops** the script.
457- Offline `say` / pigeon / bounty: same validation as players; add rate limits if abused.
458
459---
460
461## 12. Implementation plan (phased)
462
4631. **Data + UI shell** — CRUD scripts, flags, editor with highlighting, no execution.
4642. **Online runner** — interpreter + run bar + stop; `find` / `go` (blocking) / `wait` / `wait until` / `label` / `goto` / `stop`.
4653. **Gather + gear + vitals** — `mine` / `chop` / `harvest` / `equip` / `unequip` / `drink` / `eat` / `if health|stamina`.
4664. **Combat + shops + craft/alchemy** — stations via `craft` (tailor `dye` flag); cauldron via step verbs + recipe-gated `brew` + `cauldron dye [...]`.
4675. **Loops + range + bag/target queries**.
4686. **Bank, cheques, market, spells, pigeon, chat, bounty, spellbooks**.
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**.
471
472---
473
474## 13. Open choices (resolve during implementation)
475
476Resolved 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
494Still soft:
495
496- Exact flower **display names** in `cauldron dye` must match item defs (document in editor autocomplete later).
497
498---
499
500## 14. Out of scope
501
502| Area | Reason |
503|------|--------|
504| **Follow** | Not needed for scripts |
505| **Friends** | Social; low AFK value |
506| **Barber / hair** | Cosmetics |
507| **Inspect / social panel** | Not needed for AFK |
508| **Graphics settings** | Client-only |
509| **World editor** | Admin |
510| **`respawn` command** | Death always full-logout; player uses respawn UI on next login |
511| **User variables / functions** | v1 stays line+label only; revisit if scripts become unreadable |
512
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.).
514
515### Still fine to add later if play gains new intents
516
517Inheritance claim, blank-cheque get/return — add a matching verb when useful.
518
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.