# 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 | Mode | How it starts | Character in world | Client | |------|---------------|--------------------|--------| | **Online** | Scripts panel → Run | Yes | Connected; run bar visible | | **AFK** | No gameplay intents for **5 minutes**, and an AFK-marked script exists | Yes | Still connected; run bar appears when script starts | | **Offline** | Logout with offline checkbox | Yes (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: ```text Line : — ``` Example: ```text 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): | Target | Set by | Used by | |--------|--------|---------| | **Block** | `find block "..."` | `go`, `mine`, `chop`, `harvest`, `craft`, `in range block` | | **Mob** | `find mob "..."` | `go`, `attack`, `buy`, `sell`, `in range mob` | | **Ground** | `find 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 | Statement | Meaning | |-----------|---------| | `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 | Statement | Meaning | |-----------|---------| | `go` | Path to the last set target (block / mob / ground). Waits until arrived or fails (blocked / lost). | | `go block` / `go mob` / `go ground` | Same, explicit target kind. | | `run on` / `run off` | Toggle 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). ### 6.3 Gathering & world interact | Statement | Meaning | |-----------|---------| | `mine` | Gather/mine the targeted **block** (ore boulder, etc.). Waits for finish or fails. | | `chop` | Fell the targeted tree block. | | `harvest` | Pick/harvest the targeted plant/herb/flower/cotton block. | | `take` | Pick up the targeted **ground** item into the bag. | | `use` | Interact 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 | Statement | Meaning | |-----------|---------| | `craft "Bronze bar"` | At the targeted crafting **block** (station), try to craft one of that recipe output (or recipe display name). Fails if not at station, recipe unknown, missing mats, or skill too low. | | `can craft "Bronze bar"` | Does **not** craft. Used only inside `if` (see §6.9). True if the targeted station can craft it **right now** with current bag + skills. | ### 6.5 Combat & shops | Statement | Meaning | |-----------|---------| | `attack` | Attack the targeted mob (same as player Attack intent). Does not wait for kill; continues next line. Optional later: `wait until dead` — **not in v1**. | | `buy "Feather" 10` | Buy quantity from targeted shop mob. Fails if no shop, not in range, can’t afford, or not stocked. | | `sell "Soft leather" 5` | Sell quantity to targeted shop mob (if it buys). | ### 6.6 Inventory & vitals | Statement | Meaning | |-----------|---------| | `equip "Bronze pickaxe"` | Equip a matching item from the bag into its proper slot. Fails if missing or not equippable. | | `if health below 30` … | See control flow. | | `if stamina below 5` … | See control flow. | ### 6.7 Range checks | Statement | Meaning | |-----------|---------| | `if in range block "Furnace"` | True if a matching block exists within interaction/path range (same rules as find + adjacent/interact). | | `if in range mob "Deer"` | True if a matching living mob is within a small radius (e.g. combat/script range, document as **15 tiles** Chebyshev). | | `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 (any quantity ≥ 1). | ### 6.8 Labels & jumps | Statement | Meaning | |-----------|---------| | `label camp` | Declare label `camp`. | | `goto camp` | Jump to that label. | Forward and backward jumps allowed. Jumping into/out of loops is **disallowed** in v1 (error if attempted). ### 6.9 Control flow ```text 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 end ``` Rules: - Blocks end with `end`. - `if` body runs when the condition is true; no `else` in v1 (use a second `if` / `goto`). - `for N` — repeat body **N** times (N ≥ 1, max **1000**). - `while ` — repeat while condition true; **max 1000** iterations per `while` then error (`while — Too many repeats.`). - Conditions for `while` / `if`: `health below N` · `stamina below N` · `can craft "..."` · `in range block|mob|ground|item "..."` ### 6.10 Utility | Statement | Meaning | |-----------|---------| | `wait 2` | Pause **2 seconds** (server time). Max **60** per wait. | | `stop` | End the script successfully (no error letter). | --- ## 7. Example script ```text # 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 find mob "Town Guard" go mob stop ``` --- ## 8. Syntax highlighting (editor) Highlight at least: | Class | Examples | |-------|----------| | Keyword | `find`, `go`, `mine`, `chop`, `harvest`, `craft`, `attack`, `buy`, `sell`, `equip`, `label`, `goto`, `if`, `end`, `for`, `while`, `wait`, `stop`, `run`, `take`, `use`, `can` | | Subkeyword | `block`, `mob`, `ground`, `item`, `health`, `stamina`, `below`, `in`, `range`, `on`, `off`, `craft` (in `can craft`) | | String | `"..."` | | Number | `10`, `30` | | Comment | `# ...` | | Label name | after `label` / `goto` | Invalid lines can be marked with a subtle error underline on Save (optional v1). --- ## 9. 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 (e.g. advance at most one **blocking** wait/path/gather at a time; non-blocking lines burst with a low cap). --- ## 10. 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; starting a script disables manual gameplay intents until Stop (or manual intent cancels script — pick one policy and stick to it; **recommended:** any manual gameplay intent **stops** the script). --- ## 11. Implementation plan (phased) 1. **Data + UI shell** — CRUD scripts, flags, editor with highlighting, no execution. 2. **Online runner** — interpreter + run bar + stop; subset: `find` / `go` / `wait` / `label` / `goto` / `stop`. 3. **Gather + equip + vitals if** — `mine` / `chop` / `harvest` / `equip` / `if health|stamina`. 4. **Combat + shops + craft** — `attack` / `buy` / `sell` / `craft` / `can craft`. 5. **Loops + range checks** — `for` / `while` / `in range *`. 6. **AFK auto-start** — 5-minute idle. 7. **Offline logout flow** — modal, entity retention, 1-hour cap, re-login attach, error pigeon. --- ## 12. Open choices (resolve during implementation) - Exact radius for `in range mob/ground` (proposed **15**). - Whether `attack` should block until the mob dies (v1: **no**). - Whether opening the Scripts panel resets the AFK timer (proposed: **no**, only gameplay intents). - Display-name collisions (multiple “Humanoid”): always **closest** wins.