BlueGit

timfa questward

Files

questward / docs / FEATURES.md

FEATURES.md

FEATURES.md 58.0 KiB Download Raw

Feature implementation tracker

Living companion to tile_mmo_server_technical_design_v0.6.md. Statuses: not implemented · partial · full.

Each entry is a short note on behaviour and where the code lives. Update this file in the same commit as the feature it describes.

---

World coordinates and spatial hierarchy

Status: full Spec: World tile coordinates are canonical. Chunks are 16×16 tiles; regions are 4×4 chunks. Negative coordinates use true floor division. Positions are scoped by dimensionId (default overworld); chunk/region keys are dim|x,y. Code: server/src/world/coordinates.js, shared/world/dimensions.js, tests in server/tests/coordinates.test.js

Interior dimensions

Status: partial Spec: Besides the overworld, the world may contain named dimensions (caves, houses, …), each with its own chunk grid, default ground, open/closed map, lighting mode (dayNight / alwaysLit / alwaysDark), and season mode (auto / summer / spring / autumn / winter; autumn→fall art). Soft-delete marks a non-overworld dim unusable; after 7 days it is purged (chunks + metadata). Cancel deletion before purge. Doorway blocks (ladder / door / hole / cave) teleport the player to { targetDimensionId, tileX, tileY } (server-authoritative). Characters persist dimension_id + visits for quest conditions. Editor: searchable dim picker with inline create; per-dim settings while selected. Code: shared/world/dimensions.js, server/src/persistence/worldDb.js (world_dimensions), server/src/simulation/simulation.js (#relocateCharacterThroughDoorway), client/src/editor/dimensionCombobox.js, BlockType.doorway

Ground and block tile layers

Status: full Spec: Every tile has a visual ground type. An optional block supplies collision and behaviour. Unedited chunks are default grass with no blocks. Live ground types include grass, dirt (outdoor seasonal, soft-terrain blendable like grass), wood, water (passable, animated; wading clips the bottom of entity sprites), and deep water (impassable, darker, animated). In winter, shallow water uses a static water-winter ice overlay (no animation, no wade clip, no coast foam); deep water keeps coast foam on edges against ice or land. Fishing spots in shallow water are unavailable in winter (fishing TBD). Live block types include stone wall, torch, bank, church altar (respawn destination — see Player death and respawn), crafting stations, ore boulders, and pine tree (32×48 seasonal sprite). Mob spawners are not blocks: they are authored chunk markers (data.spawners[]), editor-visible only, invisible/non-blocking in play, and may share a tile with a real block. All sprite kinds (grounds, blocks, items, mobs, characters) use a per-type folder; base PNGs are visual states and companions (*-bloom, *-equip, *-equip-bloom) live in that same folder and are never placeable editor states. The client bakes immobile ≤16×16 ground/block tiles (plus bloom companions) into per-chunk atlases: one ground layer, per-row block strips for Y-sort, and one bloom layer. Oversized or animated blocks/grounds stay individual sprites so mobiles can Y-sort behind them / water can animate. Liquid water tiles use a coast-foam shader on edges against non-liquid neighbours; entity sprites use a wade clip+foam tint that respects night darkness. Grounds/blocks are marked outdoor or indoor (building walls and interior props are indoor). Only outdoor types may use calendar seasonal sprites (summer / fall / winter; grass also keeps legacy grass) or optional overlays (e.g. *-winter only); play picks those from server local calendar (spring+summer share summer: Mar–Aug; fall Sep–Nov; winter Dec–Feb) via worldTime.season. Indoor types never need seasonal variants. Code: server/src/world/chunkData.js, shared/definitions/tiles.js, shared/definitions/tileSprites.js, shared/world/season.js, server/src/assets/spriteCatalog.js, client/src/render/worldView.js, client/src/render/chunkBake.js

Open and closed chunks

Status: full Spec: Never-edited chunks are closed grass. Closed chunks can be replicated but cannot be entered; pathfinding treats them as impassable. Open chunks draw a red border on edges that touch a closed neighbour. Code: server/src/world/chunkData.js (open flag), server/src/world/chunkFlags.js, server/src/simulation/simulation.js (isEnterable, #walkableFor, closedEdges), client/src/render/worldView.js (#rebuildChunkEdges)

ECS registry and components

Status: full Spec: Entities are compositions of components with integer tile positions. Live components include position, movement, path, appearance, character, networkIdentity, chunkLoader, and persistent. Global EntityIds are used for storage, networking and transfer; each worker uses compact recycled EntityHandles for hot ECS arrays. Code: server/src/ecs/world.js, server/src/ecs/serialize.js, server/src/ecs/components.js

Simulation tick

Status: full Spec: Fixed tick from WorldSettings.simulationTickHz (default 20 Hz). Commands drain at tick boundaries, then activation, movement, transfers, and ghost exchange. Multiple isolated simulation workers. Code: server/src/simulation/simulation.js (step), server/src/index.js

Authored world and runtime state persistence

Status: full Spec: world.sqlite holds revisioned authored chunks, live world settings, and settings/chunk changelogs. state.sqlite holds accounts, characters, and runtime entity state. Databases live under server/data/ and use Node's SQLite binding. Code: server/src/persistence/database.js, worldDb.js, stateDb.js

World revisions and pending editor saves

Status: partial Spec: Editor chunk saves write a pending world revision. The running process stays pinned to the map revision loaded at startup until an admin Apply now (in-process reload). Live world settings do not use this path. Code updates use the midnight deploy path (see Midnight restart and Git deploy). Code: server/src/persistence/worldDb.js (ensurePendingRevision, promotePendingRevision)

World settings

Status: full Spec: Global cadence, timers, night darkness, bloom post-chain knobs, and chat max characters live in world_live_settings and apply as soon as an admin saves. The editor modal uses category tabs (Simulation, Graphics, Inventory, Economy, Base prices, Equipment Stats, Starter Equipment, …), marks dirty fields, writes only those fields, and shows a settings edit log (who/when/from/to). Base prices is a searchable, paginated item list for world itemSeedValues overrides (seed = base price); Market shows last-sale lerp when known, Shop shows the undiscounted catalog price from the current seed. Equipment Stats edits worn combat bonuses as piece×tier tables (category dropdown: metal armour, leather armour, melee/ranged weapons, magic staves, wizard armour, clothing); multi-stat cells (e.g. leather Agility+Defence) are independent inputs. Starter Equipment configures equipped slots and inventory stacks granted only to newly created characters. Editing night darkness snaps the Night preview to night so the effect is visible (day hours otherwise keep ambient darkening at 0). Chunk Apply now is not required. Some timers are stored before the systems that consume them exist. Code: shared/definitions/worldSettings.js, shared/definitions/equipmentStatCategories.js, shared/shop/pricing.js (effectiveSeedValue, itemPriceSnapshot), server/src/persistence/worldDb.js (world_live_settings, world_settings_edit_log), server/src/editor/service.js (loadSettings, saveSettings), client/src/editor/settingsModal.js

Baked lighting

Status: full Spec: On chunk save, raycast light from blocks with lightRangeTiles through tiles that do not occlude light, including across chunk borders. Occlusion defaults to !passable; set blocksLight: false on furniture (tables, marketplace counters, crafting stations, ore nodes, cauldron) to let light through while remaining impassable. Set blocksLight: "partial" on standing trees so the ray continues but each canopy tile adds +1 to falloff distance; tree stumps (*-stump state from woodcutting) clear that occlusion at runtime via live chunk snapshots (same dynamic path as torches, without rebaking). Store a 16×16 intensity map (0–255, smoothstep falloff by effective tile distance). Torch range is 8 tiles; furnace is 4. Code: server/src/lighting/baker.js, shared/lighting/raycast.js, shared/definitions/tiles.js (LightOcclusion / blocksLight), tests in server/tests/lighting.test.js

World editor (server)

Status: full Spec: Admin API to load/save a chunk, toggle open/closed, paint ground/blocks/spawners, write changelog bullets, edit live world settings, and apply the pending map revision. Central Exchange counters (BlockType.marketplace, neighbor-connect autotile), wooden tables (BlockType.table, magenta autotile 0–15 tinted per wood tier; joins only the same material), and Central Exchange staff spawners are placeable. Code: server/src/editor/service.js

World editor (client)

Status: full Spec: Separate /editor page. 3×3 chunk view with the selected chunk centred and outlined in red. Chunk-step navigation, paint only inside the selected chunk, hover preview of the selected tool, mouse-wheel zoom (centred on the selected chunk) and Shift+wheel to cycle visual states (for outdoor seasonal tiles: spring/summer/fall/winter, which also updates Season preview), open/closed, right-side Changelog / Console tabs (console streams live server output to admins), night preview slider, season preview dropdown, world-settings modal, Dimension settings… opens a modal (lighting / season / default ground / soft-delete), Quests and Dialogues buttons under Settings (see docs/QUESTS.md), save chunk and Apply now. Save chunk is disabled when clean and pulses when the draft is dirty; navigating N/S/E/W with unsaved edits opens a confirm modal (Cancel / Discard / Save). Bottom status bar shows hovered tile and chunk coordinates. Select block… opens a modal with auto-loaded tabs (Ground tiles / Blocks / Spawners — one entry per mob type with mob icon). Flower is a single palette entry; each paint rolls a random colour (same as harvest respawn). Hover shows a tooltip of tile/spawner config and highlights a spawner’s spawn range (cyan) and wander range (amber); right-click a spawner opens its config modal. Spawners render as mob icons in the editor only. Code: client/editor.html, client/src/editor/main.js, client/src/editor/paletteModal.js, client/src/editor/tileConfigModal.js, client/ui/editor.css

Per-chunk changelog

Status: full Spec: Each save stores who, when, and structured bullets of ground/block/spawner/open-closed diffs. Code: server/src/editor/service.js (diffChunks), server/src/persistence/worldDb.js (world_chunk_edit_log), tests in server/tests/editor-diff.test.js

WebSocket gateway

Status: full Spec: JSON WebSocket on /ws, HTTP static files for the client. Connections belong to the gateway. Clients send intentions that are queued onto the simulation tick. Editor messages are admin-only. Code: server/src/gateway/websocket.js, server/src/gateway/http.js, server/src/index.js

Stub authentication

Status: full Spec: Until auth.timfalken.com exists, each connection is admin-<n>. n starts at connected-count+1 and skips names already in use so two live sessions cannot share a stub id. Stub accounts are admins. Code: server/src/auth/stub.js

Characters

Status: full Spec: Unlimited characters per account, one in the world. First name is not globally unique; last name is globally unique per account; first+last unique per account, case-insensitive. Male/female body. Spawn requires an open tile. The login screen lists characters first; Create Character opens a modal (Appearance / Clothing tabs) and successful creation enters the world immediately. New characters receive Starter Equipment / inventory from live world settings (origin: “Received from the gods”), then creation clothing on top: cotton shirt + chosen cotton trousers/shorts/skirt, each with an HSL dye (same controls as hair). Existing characters are unaffected. Code: server/src/characters/service.js, server/src/persistence/stateDb.js, shared/items/starterLoadout.js, shared/items/createClothing.js, client/index.html, client/src/play/createClothingControls.js

Character deletion and inheritance

Status: full Spec: 24h delayed delete, cancellable. Notify via stub log (or email when present). Names and surname claims are freed on permanent delete. Inventory, equipment, carried coins, and vault move to the account inheritance tab, claimable at a bank into another character's vault. Code: server/src/characters/service.js, server/src/persistence/stateDb.js (account_inheritance)

3×3 chunk replication

Status: full Spec: Entity and ground-item replication uses the current chunk and eight neighbours. Map tiles (static snapshots) default to a 5×5 ring (STATIC_CHUNK_RADIUS = 2); clients may request Short viewing distance so the map ring matches the 3×3 entity ring. Closed chunks are still sent. Afterwards the gateway sends ENTITY_SPAWN, compact ENTITY_MOVE (tile + gait) and ENTITY_DESPAWN; appearance and path stay off the move payload. Tile deltas are not used yet because live tile edits wait for Apply now. Visible chunks may be owned by different workers; the gateway never reassigns regions for rendering. Code: server/src/simulation/simulation.js (snapshotsForView, snapshotChunk, drainReplication), server/src/gateway/websocket.js (syncSubscriptions, publishEntity), shared/graphics/settings.js

Click-to-move and A\* pathfinding

Status: full Spec: MOVE_TO runs A\ over the visible 3×3 using block passability and open-chunk bounds. Entities do not block each other’s movement (players and mobs pass through). Occupied tiles are still preferred-away for mob wander goals and required to be clear for melee attack stance. Client spreads stacked entities evenly on a circle (ENTITY_STACK_SPREAD_DIAMETER_PX, centred on the tile) with a short lerp into place; within-tile y-sort still uses each sprite’s visual Y. Server commits integer tiles on the movement cadence. Neighbour expansion prefers steps that most reduce Manhattan distance to the goal; remaining ties break by axis — players prefer vertical, mobs prefer horizontal — so mutual approaches are less likely to oscillate sideways. Code:* server/src/navigation/astar.js, server/src/simulation/workerWorld.js (#moveTo, #stepMovement, walkableFor, isClearStanding)

Global walk/run cadence

Status: full Spec: Walk 2 tiles/s, run double. Movement ticks at run rate. SetGait chooses every-other vs every movement tick. Code: server/src/simulation/workerWorld.js (#stepMovement, #setGait)

Client movement interpolation

Status: full Spec: Client lerps sprites between replicated tiles over the walk or run interval from world settings. Code: client/src/render/worldView.js (moveEntity, update)

Play viewport and camera

Status: full Spec: Camera stays centered on the local player. Scroll-wheel zoom is viewport-only (1×–4×) and does not change server visibility. Tiles and chunk atlases more than half a tile outside the screen (zoom-aware) are not drawn and skip per-frame lighting work. Hovering another player shows their first name; clicking them inspects instead of issuing move. Code: client/src/render/worldView.js (#cullOffscreenDrawables, #drawBounds), client/src/play/main.js, client/index.html

Client graphics settings

Status: full Spec: Gear button (top-right) opens a client settings panel persisted in localStorage. Viewing distance Long (default) keeps the 5×5 map ring; Short limits map subscriptions to the 3×3 around the player (SET_GRAPHICS_SETTINGS). Lighting Soft (default) uses corner-blended lightmaps; Simple fills each tile flat. Bloom On/Off toggles the bloom render layer. Soft terrain On/Off (default On) edge-blends blendable ground tiles (grass, dirt) into differing neighbours along cardinal edges only: outer edge pixel 50% neighbour, next pixel 25% (softer 40%/20% when both sides are blendable); baked at chunk atlas time. The settings panel blocks world clicks while open. Code: shared/graphics/settings.js, client/src/play/graphicsSettings.js, client/src/render/worldView.js (setGraphicsPrefs), client/src/render/chunkBake.js, shared/render/softTerrain.js, server/src/gateway/websocket.js

Night shading

Status: full Spec: World time is server time minus 1200 years. At night, unlit tiles are darkened by nightDarkness (a live world setting) and reachable tiles use the baked 0–255 intensity so a torch fades tile-by-tile instead of a hard circle. With Soft lighting, baked ground/block atlases sample a per-chunk lightmap with neighbour blending; Simple lighting uses a flat per-tile intensity (no corner blend). Animated liquid water uses the same lit values via shader uniforms. Light-occluding tiles (blocksLight / impassable ground) stay flat and contribute 0 into open neighbours (and diagonals need both cardinals clear), so a torch beside a wall does not soft-light the far side. Oversized/animated blocks and mobiles still use a uniform darkness for their standing tile (entities lerp shade while moving). worldTime also carries the real server-local calendar season (spring / summer / fall / winter) for seasonal tile visuals (types without a spring sprite fall back to summer). Code: client/src/render/worldView.js (nightFactor, #updateShade, #writeChunkLightmap, #placeSpriteShade, setWorldSeason), server/src/simulation/simulation.js (worldTime), shared/world/season.js

FrameworkV3 client bootstrap

Status: full Spec: FrameworkV3 is a git submodule at client/frameworkv3, built first via npm run build:client. Game code lives in client/src. Server does not import it. Code: .gitmodules, client/frameworkv3, client/scripts/build-framework.mjs

Sprite size, pivot and Y-sort

Status: full Spec: World sprites may be any pixel size. Pivot is horizontal centre and 8px from the sprite bottom, placed on the tile centre. Blocks and mobiles are Y-sorted (north behind south). Ground/block definitions set frames, framesPerRow, and animationSpeed for sprite sheets. Immobile ≤16×16 blocks bake into per-row chunk strips; taller sprites stay individually Y-sorted. Code: shared/render/pivot.js, shared/definitions/tiles.js, client/src/render/worldView.js, client/src/render/chunkBake.js, tests in server/tests/pivot.test.js

Visual tile states

Status: full Spec: Each ground and block type has a folder of PNG states. Non-seasonal types use the first alphabetical file as the default; outdoor seasonal types prefer summer (or legacy grass). States are visual only; the game may set a named state (for example a door or ore). For outdoor types that expose summer/fall/winter (optional spring), calendar season overrides authored state in play — spring uses spring when present, otherwise summer; the editor Season preview (and Shift+wheel on seasonal tools) chooses which seasonal look to show while editing. Indoor types (floors, walls, furniture) do not need seasonal art. The editor wheel cycles states; hover previews the selected tool on the target tile. Code: server/src/assets/spriteCatalog.js, shared/definitions/tileSprites.js, shared/world/season.js, client/src/editor/main.js, client/src/render/worldView.js, tests in server/tests/tile-states.test.js, server/tests/season.test.js

Region workers and cross-worker transfer

Status: full Spec: Isolated simulation workers own regions. Default is two in-process workers behind a clone-on-boundary protocol (SIMULATION_WORKER_MODE=thread uses worker_threads). Neighbour-sticky assignment; an entity that steps into a foreign region is frozen, accepted on the destination, then removed from the source (one authoritative copy). Ghost occupancy is visible for pathfinding. Dynamic load rebalance is later. Code: server/src/simulation/simulation.js, workerWorld.js, inProcessWorker.js, threadWorker.js, tests in server/tests/worker-*.test.js

ChunkLoader activation and unload persistence

Status: full Spec: Players carry ChunkLoader (3×3 simulating chunks, 3×3 resident regions). Chunks with no simulation refs stay dormant in memory. Regions with no residency refs unload after regionUnloadGracePeriodMs. Persistent entities are written on unload and restored on the next load; non-persistent entities are discarded. Code: server/src/simulation/chunkLoader.js, server/src/simulation/simulation.js, server/src/persistence/stateDb.js (persistent_entities)

Midnight restart and Git deploy

Status: full Spec: The live process periodically git fetches and compares HEAD to origin/<branch> (default master). When the remote is ahead, a graceful restart is scheduled for the next server-local midnight. From 3 hours before midnight, every connected player gets a permanent toast with a live countdown. At midnight the server writes server/data/restart-request.json, force-logs out sessions, unloads/persists the world, and exits. systemd (Restart=always) relaunches via deploy/start-server.sh, which always hard-resets to origin/<branch>, pulls, runs npm install, then starts Node — including after crashes or power loss (intentional, so a fixed commit can recover a bad build). Install with sudo ./deploy/install-service.sh. World editor Console tab streams live server stdout to admins. Code: shared/deploy/schedule.js, server/src/deploy/, server/src/index.js, server/src/logging/consoleCapture.js, deploy/start-server.sh, deploy/install-service.sh, deploy/tile-mmo.service, client/src/play/toasts.js, client/src/editor/main.js, tests in server/tests/deploy.test.js

Spawners

Status: full Spec: Authored chunk spawners (data.spawners[]) with mob type, max alive, spawn range, and max wander range (≥ spawn range). Legacy BlockType.spawner tiles migrate into this array on decode. They fire only in open, simulating chunks. When a chunk first becomes simulating, spawners pre-heat and place up to maxAlive immediately so the area looks populated. Spawned mobs get SpawnOrigin (origin tile + wander range); idle wander goals must stay inside max wander range, while combat chase / approach may leave the area. Persistence follows the mob definition (deer are not persistent). In play, spawners are invisible and non-blocking; players may place real blocks on the same tile. Wildlife options include deer, rats, and chickens (white deer-shaped placeholder sprite); the editor lists every mob definition as a placeable spawner. Hovering a spawner in the world editor highlights spawn range (cyan) and wander range (amber). Pigeons are not ambient wildlife. Living mobs (deer, rats, chickens, etc.) can always fight back when attacked (retaliate on first swing); rats are aggressive and auto-engage players within 5 tiles with line of sight. Humanoid spawners (incl. town guards / exchange) have an editor Aggressive flag for the same in-range aggro; Aggressive forces Bounty to 0. Spawner Level sets skills/HP and spell cast chance % (= level, capped 1–100; shown as a label, not editable).; courier pigeons cannot. Code: server/src/simulation/spawners.js, server/src/simulation/workerWorld.js, server/src/world/chunkData.js, shared/definitions/mobs.js, shared/definitions/mobCombat.js, client/src/editor/tileConfigModal.js, client/assets/mobs/deer/, client/assets/mobs/rat/, client/assets/mobs/chicken/

Mob definitions (content schema)

Status: partial Spec: Target mob content shape: displayName, maxHealth, attackSkill, drops, sells. Drops support chance, fixed quantity, or inclusive quantityMin/quantityMax. Chicken always drops 1–3 feathers and has a 20% chance of an egg. Dialogue trees are world-scoped assets (Dialogues editor); humanoid spawners assign config.dialogueId. See docs/QUESTS.md. Code: shared/definitions/mobs.js, shared/definitions/mobCombat.js, server/src/combat/service.js (rollDropQuantity)

Quests

Status: partial Spec: Full design in docs/QUESTS.md. World editor Quests / Dialogues buttons (under Settings) author world-scoped defs. Spawners link dialogueId; unique dialogues require one spawner with maxAlive: 1. Shared ConditionSet (AND + per-clause NOT). Play Quests UI + step-complete toast “Quest objectives achieved”. Progress / journal / dialogueHeard in state.sqlite. Code: shared/quests/, server/src/quests/, server/src/persistence/worldDb.js, server/src/persistence/stateDb.js, client/src/editor/questsModal.js, client/src/editor/dialoguesModal.js, client/src/play/quests.js, client/src/play/dialogue.js

Character logout resume

Status: full Spec: Despawning a character (logout / disconnect) writes their live tile to characters. The next login reloads that row after despawn and resumes there (or the nearest free enterable tile within a short spiral if blocked), instead of jumping to a distant world spawn. Code: server/src/simulation/simulation.js (spawnCharacter, despawnCharacter), tests in server/tests/character-resume.test.js

Combat resolution (rolls)

Status: partial Spec: Authoritative server rolls; clients only show outcomes. Melee & ranged (physical): roll hit skill vs defender Dexterity (agility) — miss if attack roll < agility roll, hit on tie or higher; on hit roll damage skill (Strength for melee, Dexterity for ranged) for baseDamage + roll − 1; on hit defender rolls Defence — block if defence roll > attacker's to-hit roll; otherwise apply damage. Effective combat levels add worn equipment tier bonuses to damage/agility/defence rolls (e.g. Strength 10 + bronze weapon +1 → damage roll uses 11). Hit skills (Club/Sword fighting, Archery) use base skill only. XP only on damage hits. Attack types (slashing / piercing / blunt) are defined on weapons; mob weak/resist multipliers remain later. Magic: roll Magic vs per-spell difficulty (contest, tie or higher succeeds); on success roll Mind for damage; multiply by elemental weak ×2 / neutral ×1 / resistant ×0.5; non-damage spells only need a successful cast roll then apply an effect. Spell defs + live cast/impact in shared/definitions/spells.js / server/src/spells/ (starter Light + Spark). More spells and LOS polish remain later. Code: shared/combat/rolls.js, shared/combat/magic.js, shared/definitions/spells.js, shared/definitions/attackTypes.js, shared/equipment/stats.js, server/src/combat/service.js, server/src/spells/service.js, tests in server/tests/combatRolls.test.js, server/tests/magic.test.js, server/tests/spells.test.js, server/tests/equipment.test.js

Combat, skills, groups, pigeons

Status: partial (melee + ranged bows + starter spells live; groups later) Spec: Melee auto-attack with stick (Clubfighting + Strength), LMB/RMB targeting and context menu (including Follow \<name\> / Attack \<name\>), engage/retaliate, swipe VFX, shove animation, damage flash, HP bars above mobs and players when below max HP, and client dynamic-light hooks. Fightable mobs retaliate on the first resolved swing (hit or miss), not when Attack is merely clicked. Players likewise auto-retaliate when a mob’s first swing resolves against them (clears follow/gather). Melee requires Chebyshev distance 1 (diagonals allowed) while the attacker stands alone on their tile; if stacked with others they path to the nearest clear adjacent stance. Approach pathfinding may pass through entities but prefers clear goal tiles. Aggressive mobs (e.g. rats: aggressive + aggroRangeTiles, default 5) auto-engage player characters in Chebyshev range with line of sight through enterable tiles; passive wildlife (deer, chickens) does not. Engaged mobs keep pursuing if the player cancels attack. Physical combat uses skill rolls (see Combat resolution). Ranged: bow in weapon + arrows in offhand; Archery hit / Dexterity damage; arrow projectiles lerp toward the target’s live client visual pose (misses use a fixed fly-by tile). Server resolves the hit immediately; HP bar / flash / damage numbers wait until the projectile lands on each client. Magic: cast UI + Light/Spark; spell projectiles likewise track moving targets; spell impacts are delayed on the server to match travel time. Health skill sets max HP; taking damage awards Health XP equal to damage taken (lethal hits grant none). Reaching 0 HP is player death (see Player death and respawn). Follow reuses the target's vacated trail and remaining path (stop one tile short, wait for vacancy, walkability each step); catch-up A only when no shared trail yet. Break beyond one chunk width. Carrier pigeons dispatch money or one inventory stack to Bank or Player. Skills: persistent XP, 50 XP to level 2 then double each level, cap 99; Health starts at 10, others at 1; login enforces those minima (raises and persists under-leveled skills). Skills panel. Groups and broader non-combat skill XP remain later. Code:* shared/combat/rolls.js, shared/skills/progression.js, shared/skills/state.js, shared/definitions/skills.js, shared/definitions/mobCombat.js, shared/definitions/mobs.js, shared/definitions/rangedItems.js, server/src/skills/service.js, server/src/combat/service.js, server/src/spells/service.js, client/src/play/skills.js, client/src/play/main.js, client/src/render/worldView.js, tests in server/tests/combatRolls.test.js, server/tests/skills.test.js, server/tests/mobCombat.test.js, server/tests/ranged.test.js (+ combat/follow/courier/spells tests)

Player death and respawn

Status: full Spec: When a player reaches 0 HP, they die immediately (authoritative on the server):

1. Corpse drops on the death tile: a bones ground item and a skull ground item (new item definitions + sprites). These use normal ground-item rules (pickup, despawn timer). Inventory/equipment are not dropped by default (death penalty is the corpse markers + travel to church — revisit if PK/loot rules are added later). 2. Combat ends for the dead player and anyone targeting them (clear engage both ways). The dead player cannot move, attack, follow, pick up, bank, chat-actions that affect the world, or otherwise act until they respawn. 3. Death modal (client): a blocking modal that is the only interactable UI while dead (world clicks, hotkeys, bag, etc. are ignored). Copy states that the player is dead; primary action is Respawn. Closing the tab/disconnect while dead keeps them dead until they log in and respawn (or auto-prompt the same modal on re-enter). 4. Respawn: server moves the character to the nearest church altar block (Chebyshev / path distance TBD — prefer enterable tile adjacent to the altar if the altar tile itself is impassable). New block type: church altar (BlockType + editor placeable + sprite folder), passable or adjacent-use like bank (exact interaction: respawn destination only for now, not a usable station). 5. After respawn the player is restored to full Health and full Stamina (max from skills), cleared of death state, and may fight again.

TODO: Revisit player-loot penalties if PK rules are added. Code: shared/definitions/items.js, shared/definitions/tiles.js, shared/protocol/constants.js, server/src/combat/service.js, server/src/simulation/simulation.js, server/src/simulation/workerWorld.js, server/src/persistence/stateDb.js, server/src/gateway/websocket.js, client/src/play/death.js, tests in server/tests/death.test.js

Equipment tiers and worn stat bonuses

Status: partial Spec: Metal gear exists in seven material tiers (lowest → highest): Bronze, Iron, Steel, Mithril, Adamantium, Orichalcum, Dragon. Each has a rank (1–7), display tint, and equip min skill: 1 / 10 / 20 / 35 / 50 / 70 / 90. Mining a material requires half of that equip gate (ceil); smelting requires 75% (ceil). Worn combat bonuses come from live world setting equipmentStatBonuses (editor Equipment Stats tab); defaults seed from TIER_STAT_BONUS (full helms +1 Defence). Leather armour can grant Agility and Defence independently; wizard armour Magic and Defence; clothing Defence. Magic casting uses worn Magic/Mind gear bonuses the same way physical combat uses Strength/Agility/Defence. Tools (pickaxes) gate on Mining and do not use the bonus tables. Tin and copper ores (no bronze ore) and coal use their associated bar tier for mine/smelt timing and gates (tin/copper → bronze, coal → steel). Silver and Gold are precious-only (ore + bars, no tools; silver mine/smelt like iron rank 2 / skill 10, gold like steel rank 3 / skill 20). Wood tiers (same gates/ranks): Pine, Birch, Oak, Ebony, Lignum, Heartwood, Elder (match metal ranks for hafts). Cloth tiers (same gates/ranks): Cotton, Wool, Linen, Cashmere, Silk, Fairy silk, Dragonweave. Logs/handles tint from shared wood sprites; pine trees are chopable resource nodes (more tree tiers later) — axe sprites (items/axe) match pickaxe style for woodcutting. Armour pieces share one set of overlays under items/armour/ tinted per metal tier (no per-tier icon copies). Shared sprites + magenta tint: one base sprite per shape under items/metal (ore, bar), items/pickaxe, items/axe (axe, axe-head, axe-equip), items/wood (log, handle), items/cloth (wool, yarn, cloth), items/clothing (shirt, shorts, skirt, trousers, sweater), boulder-ore, and tables (blocks/table/0–15); tintable pixels use magenta rules in shared/render/tint.js. Dual-channel tint (red = shaft/wood, blue = tip/string; white unchanged): arrows, hafted tools, bows / unstrung bows under items/bow/ (bow, unstrung-bow, bowstring magenta, bow-equip). Boulder ore states are catalog aliases of boulder-ore.png with per-material tint. Table states are ${woodTier}-${mask} aliases of mask PNGs with wood-tier tint; tables autotile only with the same wood. Trees use per-season live + -stump PNGs (mandatory for every tree type). TODO: full combat gear catalog; more tree tiers / fishing / herbs; silver/gold jewelry / other precious recipes; cloth sources beyond cotton. Code: shared/definitions/materialTiers.js, shared/definitions/equipmentStatCategories.js, shared/render/tint.js, shared/definitions/metalItems.js, shared/definitions/woodItems.js, shared/definitions/rangedItems.js, shared/definitions/tierFamilies.js, shared/equipment/stats.js, tests in server/tests/equipment.test.js, server/tests/mining.test.js, server/tests/tint.test.js, server/tests/ranged.test.js

Gathering, crafting, and production skills

Status: partial (mining + smelting + pickaxe/axe/bow craft chains + pine woodcutting + cotton/flower/herb herbalism live) Spec: Mining: LMB/RMB on ore boulder (states tin-ore, copper-ore, iron-ore, silver-ore, gold-ore … dragon-ore, coal). Uses the best usable pickaxe in inventory (or weapon slot) — tools need not be equipped. Tool rank ≥ associated bar rank and Mining ≥ mine gate; otherwise toast "You need a pickaxe to mine this!". Duration (rank×8s) − (toolRank×3s) (min 0.5s). Attack shove animation, no swipe FX; while swinging, the gather tool's equip sprite is shown in the weapon overlay (even if a different weapon is equipped). Awards Mining XP (rank×5). On success the node becomes exhausted (plain boulder sprite, not mineable) for 10s × associated bar rank, then restores its ore state via runtime CHUNK_DELTA. Hovering an active ore/tree/plant node shows a cursor tooltip (resourceNodeDisplayName). Outdoor blocks may also use optional seasonal overlays (e.g. boulder / ore *-winter only — other seasons keep the base sprite). Woodcutting: LMB/RMB / Chop on outdoor tree blocks (pine today). Best usable axe in inventory/weapon; Woodcutting + axe tier gates match mining (pine = rank 1). Same duration/exhaust curves. Success grants a pine log, stamps Felled by <name>, awards Woodcutting XP, and sets a seasonal stump (summer-stump / fall-stump / winter-stump — required for every tree type). Calendar season still drives stump look while exhausted; after exhaust the live tree returns. Tree / flower / herb regrow uses the four-way growth season (spring Mar–May, summer Jun–Aug, fall Sep–Nov, winter Dec–Feb): summer & fall keep base exhaust time, winter doubles it, spring is 25% faster (×0.75). Herbalism (plants): Flower nodes need no tool (~1s); each flower block carries a fixed colour tint (chosen on respawn / editor place) and picking yields that colour, stamps Picked by <name>. Cotton plant needs no tool (RMB Pick / LMB); yields cotton fibre. Both exhaust ~15s then respawn. Smelting: furnace block opens craft UI; duration rank×2s by output bar tier. Recipes 1 ore → 1 bar except bronze = 1 tin + 1 copper, steel = 1 iron ore + 1 coal, adamantium = 1 ore + 1 coal, orichalcum = 1 ore + 3 coal, dragon = 1 ore + 5 coal. Smithing XP on success. Pickaxe / axe craft: woodworking bench shapes 1 log → 1 handle; anvil smiths 1 bar → 1 pickaxe head or axe head; crafting bench assembles matching-tier handle + head → pickaxe or axe (pine↔bronze … elder↔dragon). Ranged craft: woodworking → arrow shafts / unstrung bows; anvil → arrow tips; spinning wheel → bowstring from yarn; crafting bench → feather + shaft + tip → arrow, and unstrung bow + bowstring → bow (wood + matching cloth). Gold bars are smeltable but have no tool recipes. Server-authoritative START_CRAFT / timer; craft panel supports Craft, Craft X, and Craft all with a progress bar that restarts on each continuing batch step. Play errors (mine gates, full bag, …) show as temporary toasts at the top of the screen. More tree tiers / fishing / other stations later. Code: shared/definitions/gathering.js, shared/definitions/tiles.js (resourceNodeDisplayName, isChopableTreeBlock, isPickablePlantBlock), shared/definitions/rangedItems.js, shared/crafting/tierRecipes.js, shared/world/season.js (treeStumpStateForSeason, growthSeasonIdAt, scaleRegrowDurationMs), server/src/gathering/service.js, server/src/crafting/service.js, shared/crafting/stationRecipes.js, client/src/play/main.js, client/src/play/crafting.js, client/src/render/worldView.js (spawnGatherSwing), tests in server/tests/mining.test.js, server/tests/woodcutting.test.js, server/tests/crafting.test.js, server/tests/ranged.test.js, server/tests/season.test.js

Cloth, dyes, and tailoring

Status: partial (cotton loop + flower dyes + shirt/shorts/skirt/trousers/sweater live; higher cloth sources TBD) Spec: Cloth tiers (same skill gates/ranks as metal/wood): Cotton, Wool, Linen, Cashmere, Silk, Fairy silk, Dragonweave. Shared magenta sprites under items/cloth (wool fibre, yarn, cloth) and items/clothing (shirt, shorts, skirt, trousers, sweater + equip) tinted per tier (or optional dye colour on clothing instances). Spinning wheel (Tailoring): fibre → yarn. Loom: yarn → cloth. Tailor bench UI is template-first: pick clothing template (shirt, shorts, skirt, trousers, sweater) → cloth tier → optional dye from bag → sidebar shows resolved ingredients (shirt/shorts/skirt/trousers = 1 cloth; sweater = 3 yarn). Skirts are not tight-fit (unlike shorts). Display names are tiered (Cotton shirt, …). Historic item id 5 remains the cotton shirt. Crafted clothing can carry instance.dyeColor; otherwise material tint. Flowers (9 colours) brew 1:1 into dye bottles at a cauldron (needs glass bottles / potion-0). Two different dye colours mix paint-style (weighted by fill); bottle count follows inserted dyes; fill packs with overflow into the next bottle (extra glass only if overflow needs more bottles than inputs). Cannot mix flowers with dyes in one brew. Dye uses on tailor consume one fill level per craft. TODO (sources): shear animals / pick plants for wool–silk; fairy silk + dragonweave as mob drops later. Later design (document only for now):

  • Wizard cloth gear — robes and similar give Magic skill bonuses (EquipmentKind.wizardCloth).
  • Cosmetic cloth gear — sum equipped cosmetic item tiers as Style points (quests / exclusive areas).
  • Warm clothing — sweaters and other warm pieces reduce cold-season debuffs (e.g. winter halves stamina regen; each warm-equipped slot except hands mitigates; full warm set nullifies cold; summer reverses). Padding from cloth + matching-tier plate at a crafting bench → padded armour per slot.

Code: shared/definitions/materialTiers.js (ClothTier), shared/definitions/clothItems.js, shared/definitions/dyes.js, shared/crafting/tailor.js, shared/crafting/stationRecipes.js, server/src/alchemy/service.js, server/src/crafting/service.js, server/src/gathering/service.js, client/src/play/crafting.js, client/src/play/alchemy.js

Crafting stations

Status: partial (furnace, anvil, woodworking, crafting, spinning wheel, loom, tailor bench live) Spec: Furnace / anvil / woodworking-bench / crafting-bench / spinning-wheel / loom / tailor-bench blocks + adjacency craft panel. Recipes in stationRecipes.js. Furnace/anvil/woodworking/crafting craft timer = smeltingDurationMs (rank × 2s) when xpMaterial is set; other stations still use CRAFT_DURATION_MS (2s) / UI/dev only (__craftDev). Woodworking shapes components (handles, shafts, unstrung bows); crafting bench joins finished parts (pickaxe/axe head + handle, arrows, strung bows). Spinning wheel / loom / tailor use Tailoring. Anvil, woodworking, spinning wheel, loom, and tailor craft UIs use a single-axis material dropdown so tier variants share one recipe cell. Crafting bench alone shows paired metal/wood labels (e.g. Bronze/Pine) because it mixes metal tools with wood bows on the same tier rank. Hard rule (all stations + cauldron, player and scripts): items in station slots are never committed out of the inventory — slots are a reservation/view over the bag (client-side UI; even if it looks like mats sit in the station, they do not). Server soft-tracks steps/claims only and consumes on successful craft/brew. Closing the UI, cancelling, or dying mid-craft/brew cannot destroy reserved mats. Station progress is per player, not tile-global. See .cursor/rules/station-inventory.mdc. TODO: oven/campfire burn; dedicated station sprites where still placeholder. Code: shared/definitions/craftingStations.js, shared/definitions/tiles.js, server/src/crafting/service.js, client/src/play/crafting.js

Stamina and running

Status: full Spec: Stamina skill sets max stamina (= skill level). Login / new characters floor Stamina at level 5. Each stamina point equals one second of running (drains on successful run tile steps). Running awards 1 Stamina XP per stamina point spent. Walking, idle, or run gait with no active path regenerates 1 stamina per second. At 0 stamina, run gait is forced back to walk; you cannot toggle run until stamina recovers. Client shows vertical HP (always) and stamina bars bottom-right. Code: shared/stamina/rules.js, shared/definitions/skills.js (playerMaxStamina, DEFAULT_PLAYER_SKILL_LEVELS), server/src/simulation/workerWorld.js, server/src/skills/service.js (syncPlayerStamina), client/src/play/stamina.js, tests in server/tests/stamina.test.js

Alchemy / cauldron

Status: partial (starter herb potions + failed-effect list + status ticks live; more recipes TBD) Spec: Herbalism gathers flowers, cotton, and 24 folklore herbs (BlockType.herbPlant). Flowers/cotton need no tool; clipper herbs require plant clippers and Herbalism gates by tier. Alchemy cauldron tabs Alchemy / Dyes. Starter potions: Lesser health tonic (thyme→heat→mint→stir; health regen 1/s for 10s, re-drink extends), Lesser haste draught (2 mint→heat→stir→lavender→cool; stamina regen 1/s for 10s), Strength potion (3 thyme→stir→2 nettle→heat; +5 Strength for 1 min), Clarity potion (rosemary→cool→2 chamomile→stir; +5 Mind for 1 min). Failed brews hash to unstable effects: stamina drain 1/s 15s, weak glow light 10s, shrink to 50% scale 30s, blindness 20s (extra darkness + local vision bubble). Active effects show as HUD icons left of the HP/stamina bars (assets/status-effects/; hover shows description + remaining time). Opening needs empty glass bottles. Dyes unchanged (flowers). Code: shared/definitions/alchemy.js, shared/statusEffects/rules.js, shared/statusEffects/display.js, server/src/statusEffects/service.js, client/src/play/statusEffects.js, shared/definitions/herbs.js, server/src/alchemy/service.js, server/src/items/bags.js, client/src/render/worldView.js, tests in server/tests/alchemy.test.js, server/tests/herbalism.test.js

Folklore herb associations (design only — not in code)

Use later when deciding which ingredients fit which potions. Tiers: 2 / 3 / 3 / 4 / 4 / 4 / 4 for T1–T7.

TierHerbAssociations
1MintRefreshment, stamina, antidotes
1GarlicUndead protection, disease resistance
2ThymeCourage, vitality, resistance
2SageHealing, wisdom, longevity
2RosemaryMemory, protection, clarity
3LavenderSleep, calm, dreams
3ChamomileRestoration, sleep, soothing
3NettleVigour, resilience, protection
4YarrowWound healing, battle medicine
4JuniperPurification, disease resistance
4ElderSpirits, protection, healing
4RueCurse resistance, purification
5ValerianSleep, sedation, tranquillity
5MugwortDreams, visions, divination
5WormwoodPoison resistance, spirits, bitterness
5St. John's wortHoly protection, dispel darkness
6HawthornFey, barriers, enchantment
6FoxgloveFairy magic, heart magic, poison
6MistletoeLife, fertility, druidic magic
6DaturaVisions, insanity, spirit walking
7BelladonnaPoison, hallucination, witchcraft
7HenbaneTrance, madness, sleep, poison
7MandrakePowerful potions, curses, life magic
7AconiteWerewolves, lethal poison, curses

Inventory, items, equipment, ground drops

Status: full Spec: 32-slot inventory, stacking, equipment slots (head, chest, legs, boots, weapon, offhand for shields/arrows) with a separate equipSprite overlay on the body, carried currency, player drops that last groundItemDespawnDurationMs (default 10 minutes). Pickup requires standing on the tile. Inventory is private UI state; nearby clients see ground items and worn overlays. Equip draw order (back → front): boots → chest → weapon → legs → hair (if visible) → head → offhand — so weapons sit above the shirt but under trousers/skirts (legs may cover shirt hem; art should avoid bad waist overlap). New characters receive world Starter Equipment / inventory, then creation clothing dyes on top (see Characters). Right-click bag items for Send / Equip / Drop / Eat (food; apples, eggs, …); paper can be written into unique letter instances (signed on Save; only the signer may edit). Equipping always takes one item from a stack (never the whole stack); unequipping returns one item and merges into an existing compatible inventory stack when stack rules allow. Equip enforces tier min-skill gates. Eating food heals (see Health skill). Code: shared/definitions/items.js (EQUIPMENT_DRAW_ORDER), shared/appearance/hair.js (composeAppearanceLayers), shared/items/inventory.js, server/src/items/bags.js, client/src/play/inventory.js

Proximity chat

Status: full Spec: Enter opens a bottom chat line (max chatMaxCharacters, default 100). Enter trims and sends; Escape cancels. The speaker always sees their own bubble. Other players receive server-side obfuscation: full text within 8 tiles, linear falloff to silent at 16 tiles. At 0% readability the bubble is not sent. Code: shared/speech/proximity.js, server/src/chat/speech.js, client/src/play/chat.js, tests in server/tests/proximity-speech.test.js

Friends

Status: full Spec: Character-to-character friends in state.sqlite. Hover shows first name; click opens inspect (full name, request/accept/remove). Requests must be accepted. Unfriend is symmetric. Incoming/outgoing lists live in the Friends panel. Code: server/src/friends/service.js, server/src/persistence/stateDb.js, client/src/play/social.js, tests in server/tests/friends.test.js

Hair & barber

Status: full Spec: Character creation Appearance tab picks a hair style (per sex body folder) plus hue/saturation/darkness; live preview tints magenta hair sprites (no clothing on that tab). The Clothing tab shows the same body/hair with cotton shirt + legs and per-piece dyes. Hair is stored on the character and drawn as a head overlay unless headgear is worn (item defs may set equipment.keepHair to keep hair under a hat — none yet). Placeable Barber blocks reopen the hair UI to restyle (preview hides headgear). Code: shared/appearance/hair.js, server/src/barber/service.js, client/src/play/hairControls.js, client/src/play/barber.js, client/src/play/createClothingControls.js, client/assets/blocks/barber/

Bounty offices

Status: full Spec: Placeable Bounty Office blocks. Interacting opens a modal with two tabs:

1. Place / raise bounty — Search a character by first + last name. If found, show a small character preview and the current bounty already on that head. The player may spend coins from inventory to add any positive amount to that bounty (server-authoritative; coins consumed only on success). 2. My bounty — Shows how much coin is currently on your head.

Payout on kill: When a player who still has bounty \> 0 is killed by another player (attacker dealt the killing blow / engaged death), a carrier pigeon is dispatched from the nearest bounty office to the killer's bank, delivering a letter stating they received a bounty of N coins, where N is the full sum of all coin placed on the victim. Those N coins are deposited immediately into the killer's bank vault (not inventory). The victim's bounty is then reset to 0.

Inspect UI: Viewing another player's inspect/info modal also shows their bounty amount; if the amount is 0, omit the bounty line entirely.

Code: shared/bounty/pricing.js, shared/definitions/tiles.js (BlockType.bountyOffice), server/src/bounty/service.js, server/src/courier/service.js, server/src/persistence/stateDb.js, client/src/play/bounty.js, client/assets/blocks/bounty-office/, tests in server/tests/bounty.test.js

Banking, cheques, shops, player-driven marketplace

Status: partial (banks/cheques/origins/NPC shops live; Central Exchange order book live) Spec: Bank blocks open bag + vault UI when used (LMB / RMB Bank). Click transfers between bag and vault; RMB offers Transfer all / half / one / X (or Transfer for stacks of 1). Vault slots are unlimited and ignore normal stack caps (except coins still cap at 999B per stack); unique-instance items such as letters never merge, even in the vault. Equipment and weapons max stack to 1 in inventory but may stack in the vault. Stacks track crafter/shop/gather origins; mixed stacks show breakdown labels and splits preserve origin quantities FIFO. Gathered ores stamp Mined by <name>; woodcutting stamps Felled by <name>. Crafted goods stamp a station verb: furnace Forged by, anvil Smithed by, woodworking Carved by, crafting bench Assembled by. NPC catalog purchases stamp Bought from <npc>; player-sold resale stock keeps the original origin (not re-stamped as shop). Get Blank Cheques tops inventory blanks up to 99; Return \<n\> discards free blanks. Blank cheques on the ground can only be picked up until inventory again holds 99; they do not count toward limits on written cheques. Write Cheque works anywhere (pick vault goods to reserve; Reserved tab). Written cheques can be sent by pigeon, sold on the marketplace, and redeemed at a bank (LMB deposit or Redeem Cheque) — redeemed goods go into the vault, not inventory. Blank cheques cannot be sent by pigeon or listed on the marketplace. Coins are a physical stackable inventory item (not a separate counter). Character delete voids that character's outstanding cheque reservations back into the vault before inheritance. NPC shops: Humanoid spawners (sex, equipment, sells list with optional daily quantity, buysItems, hidden discount) spawn shopkeepers. Context menu Shop \<name\> opens a buy panel (grid + sidebar, Buy 1/5/10/x, coin balance, bank-overflow warning). Catalog stock restocks at 00:00 server local time (quantity 0 = infinite) and remains ingredient-only (npcShopAllowed). With Buys items, the NPC buys any transferable bag item except blank cheques (and not coins) at 80% market; filled cheques sell as their reserved goods with a 5% administrative fee (fee = ceil(5% of payout base); UI shows "<n> coins charged as administrative fee" while selected). Limited catalog refills first; extras hold for the day at 120% resale until restock (non-catalog goods still absorb into bought stock). Prices use seedValue (pine log / tin / copper = 5) with market last-sale lerp × discount. Central Exchange (player marketplace): Modal with tabs Your Orders / Sell / Buy. Sell picks a bag item (or written cheque treated as its reserved goods with quantity locked), sets min price, and escrows the goods. Buy searches item names (Enter, max 10 hits), sets qty + max price, and escrows coins (coin-filled cheques count as funds but are spent whole only). Placing either order charges a non-refundable 3% listing fee (ceil(unitPrice × quantity × 3%), min 1) paid immediately from bag funds. BlockType.marketplace wooden counters use neighbor-connect autotile states (0–15 from N/E/S/W bitmask; generic in shared/world/neighborConnect.js). Counters require adjacency. Central Exchange staff spawner (MobId.centralExchange) always spawns every clerk from CENTRAL_EXCHANGE_STAFF (name + sex) with shared authored equipment; no shop UI. Opening a counter paths an idle clerk to the opposite side when free; closing the UI or walking away from that counter releases the clerk so wander resumes, unless another player is still using the same staff station. Hidden order book: match when buyerMax >= sellerMin at deterministic midpoint price; triggering player settles immediately, counterparty gets pigeon→bank cargo plus a staff-signed letter. Open orders auto-cancel after 30 days with escrow returned to bank by pigeon and an expiry letter (listing fee is not returned). Matches update durable item_last_sales for shop/tooltip lerp. Code: shared/definitions/items.js, shared/items/inventory.js, shared/items/origin.js, shared/items/stackRules.js, shared/items/marketplace.js, shared/market/exchange.js, shared/market/funds.js, shared/world/neighborConnect.js, shared/shop/pricing.js, shared/definitions/mobs.js, server/src/shop/service.js, server/src/market/service.js, server/src/simulation/spawners.js, client/src/play/shop.js, client/src/play/market.js, client/src/editor/tileConfigModal.js, server/src/items/bags.js, server/src/courier/service.js, client/src/play/inventory.js, client/assets/blocks/bank/, client/assets/blocks/marketplace/, tests in server/tests/bank.test.js, server/tests/marketplace.test.js, server/tests/central-exchange.test.js, server/tests/shop.test.js, server/tests/origins.test.js

Player scripting (AFK / offline)

Status: not implemented Spec: Full language + UI + online/AFK/offline behaviour is documented in docs/SCRIPTS.md. Scripts are a sandboxed, server-interpreted language that emits normal player intents. Names match exactly (case-insensitive). find / nearest only searches the visible 3×3 chunks (what a player sees). @ variables + set hold targets/coords for waypoints; go fails beyond 2 chunks (Too far away.). Universal can <action> dry-runs any verb. Station/cauldron state is per player; station slots never commit items out of the bag until craft/brew succeeds. AFK auto-start after 30 minutes idle. Death while scripting stops the script and fully logs the instance out. Friends/barber/follow/graphics/editor are out of scope. Architecture hooks remain in design doc §18. Code: — (planned: shared/scripts/, server/src/scripts/, client/src/play/scripts.js, state DB script rows)

Source
1# Feature implementation tracker
2
3Living companion to `tile_mmo_server_technical_design_v0.6.md`.
4Statuses: **not implemented** · **partial** · **full**.
5
6Each entry is a short note on behaviour and where the code lives. Update this file in the same commit as the feature it describes.
7
8---
9
10## World coordinates and spatial hierarchy
11
12**Status:** full
13**Spec:** World tile coordinates are canonical. Chunks are 16×16 tiles; regions are 4×4 chunks. Negative coordinates use true floor division. Positions are scoped by **dimensionId** (default `overworld`); chunk/region keys are `dim|x,y`.
14**Code:** `server/src/world/coordinates.js`, `shared/world/dimensions.js`, tests in `server/tests/coordinates.test.js`
15
16## Interior dimensions
17
18**Status:** partial
19**Spec:** Besides the **overworld**, the world may contain named **dimensions** (caves, houses, …), each with its own chunk grid, default ground, open/closed map, **lighting mode** (`dayNight` / `alwaysLit` / `alwaysDark`), and **season mode** (`auto` / `summer` / `spring` / `autumn` / `winter`; autumn→fall art). Soft-delete marks a non-overworld dim unusable; after **7 days** it is purged (chunks + metadata). Cancel deletion before purge. **Doorway** blocks (`ladder` / `door` / `hole` / `cave`) teleport the player to `{ targetDimensionId, tileX, tileY }` (server-authoritative). Characters persist `dimension_id` + visits for quest conditions. Editor: searchable dim picker with inline create; per-dim settings while selected.
20**Code:** `shared/world/dimensions.js`, `server/src/persistence/worldDb.js` (`world_dimensions`), `server/src/simulation/simulation.js` (`#relocateCharacterThroughDoorway`), `client/src/editor/dimensionCombobox.js`, `BlockType.doorway`
21
22## Ground and block tile layers
23
24**Status:** full
25**Spec:** Every tile has a visual ground type. An optional block supplies collision and behaviour. Unedited chunks are default grass with no blocks. Live ground types include grass, **dirt** (outdoor seasonal, soft-terrain blendable like grass), wood, **water** (passable, animated; wading clips the bottom of entity sprites), and **deep water** (impassable, darker, animated). In **winter**, shallow water uses a static **`water-winter` ice** overlay (no animation, no wade clip, no coast foam); **deep water** keeps coast foam on edges against ice or land. Fishing spots in shallow water are unavailable in winter (fishing TBD). Live block types include stone wall, torch, bank, **church altar** (respawn destination — see **Player death and respawn**), crafting stations, ore boulders, and **pine tree** (32×48 seasonal sprite). Mob spawners are **not** blocks: they are authored chunk markers (`data.spawners[]`), editor-visible only, invisible/non-blocking in play, and may share a tile with a real block. **All** sprite kinds (grounds, blocks, items, mobs, characters) use a per-type folder; base PNGs are visual states and companions (`*-bloom`, `*-equip`, `*-equip-bloom`) live in that same folder and are never placeable editor states. The client bakes immobile ≤16×16 ground/block tiles (plus bloom companions) into per-chunk atlases: one ground layer, per-row block strips for Y-sort, and one bloom layer. Oversized or animated blocks/grounds stay individual sprites so mobiles can Y-sort behind them / water can animate. Liquid water tiles use a coast-foam shader on edges against non-liquid neighbours; entity sprites use a wade clip+foam tint that respects night darkness. Grounds/blocks are marked **`outdoor`** or indoor (building walls and interior props are indoor). Only **outdoor** types may use calendar **seasonal** sprites (`summer` / `fall` / `winter`; grass also keeps legacy `grass`) or optional overlays (e.g. `*-winter` only); play picks those from **server local calendar** (spring+summer share summer: Mar–Aug; fall Sep–Nov; winter Dec–Feb) via `worldTime.season`. Indoor types never need seasonal variants.
26**Code:** `server/src/world/chunkData.js`, `shared/definitions/tiles.js`, `shared/definitions/tileSprites.js`, `shared/world/season.js`, `server/src/assets/spriteCatalog.js`, `client/src/render/worldView.js`, `client/src/render/chunkBake.js`
27
28## Open and closed chunks
29
30**Status:** full
31**Spec:** Never-edited chunks are closed grass. Closed chunks can be replicated but cannot be entered; pathfinding treats them as impassable. Open chunks draw a red border on edges that touch a closed neighbour.
32**Code:** `server/src/world/chunkData.js` (`open` flag), `server/src/world/chunkFlags.js`, `server/src/simulation/simulation.js` (`isEnterable`, `#walkableFor`, `closedEdges`), `client/src/render/worldView.js` (`#rebuildChunkEdges`)
33
34## ECS registry and components
35
36**Status:** full
37**Spec:** Entities are compositions of components with integer tile positions. Live components include `position`, `movement`, `path`, `appearance`, `character`, `networkIdentity`, `chunkLoader`, and `persistent`. Global `EntityId`s are used for storage, networking and transfer; each worker uses compact recycled `EntityHandle`s for hot ECS arrays.
38**Code:** `server/src/ecs/world.js`, `server/src/ecs/serialize.js`, `server/src/ecs/components.js`
39
40## Simulation tick
41
42**Status:** full
43**Spec:** Fixed tick from `WorldSettings.simulationTickHz` (default 20 Hz). Commands drain at tick boundaries, then activation, movement, transfers, and ghost exchange. Multiple isolated simulation workers.
44**Code:** `server/src/simulation/simulation.js` (`step`), `server/src/index.js`
45
46## Authored world and runtime state persistence
47
48**Status:** full
49**Spec:** `world.sqlite` holds revisioned authored chunks, live world settings, and settings/chunk changelogs. `state.sqlite` holds accounts, characters, and runtime entity state. Databases live under `server/data/` and use Node's SQLite binding.
50**Code:** `server/src/persistence/database.js`, `worldDb.js`, `stateDb.js`
51
52## World revisions and pending editor saves
53
54**Status:** partial
55**Spec:** Editor chunk saves write a pending world revision. The running process stays pinned to the map revision loaded at startup until an admin **Apply now** (in-process reload). Live world settings do not use this path. Code updates use the midnight deploy path (see **Midnight restart and Git deploy**).
56**Code:** `server/src/persistence/worldDb.js` (`ensurePendingRevision`, `promotePendingRevision`)
57
58## World settings
59
60**Status:** full
61**Spec:** Global cadence, timers, night darkness, bloom post-chain knobs, and chat max characters live in `world_live_settings` and apply as soon as an admin saves. The editor modal uses category tabs (Simulation, Graphics, Inventory, Economy, **Base prices**, **Equipment Stats**, **Starter Equipment**, …), marks dirty fields, writes only those fields, and shows a settings edit log (who/when/from/to). **Base prices** is a searchable, paginated item list for world `itemSeedValues` overrides (seed = base price); Market shows last-sale lerp when known, Shop shows the undiscounted catalog price from the current seed. **Equipment Stats** edits worn combat bonuses as piece×tier tables (category dropdown: metal armour, leather armour, melee/ranged weapons, magic staves, wizard armour, clothing); multi-stat cells (e.g. leather Agility+Defence) are independent inputs. **Starter Equipment** configures equipped slots and inventory stacks granted only to newly created characters. Editing night darkness snaps the Night preview to night so the effect is visible (day hours otherwise keep ambient darkening at 0). Chunk Apply now is not required. Some timers are stored before the systems that consume them exist.
62**Code:** `shared/definitions/worldSettings.js`, `shared/definitions/equipmentStatCategories.js`, `shared/shop/pricing.js` (`effectiveSeedValue`, `itemPriceSnapshot`), `server/src/persistence/worldDb.js` (`world_live_settings`, `world_settings_edit_log`), `server/src/editor/service.js` (`loadSettings`, `saveSettings`), `client/src/editor/settingsModal.js`
63
64## Baked lighting
65
66**Status:** full
67**Spec:** On chunk save, raycast light from blocks with `lightRangeTiles` through tiles that do not occlude light, including across chunk borders. Occlusion defaults to `!passable`; set `blocksLight: false` on furniture (tables, marketplace counters, crafting stations, ore nodes, cauldron) to let light through while remaining impassable. Set `blocksLight: "partial"` on standing trees so the ray continues but each canopy tile adds +1 to falloff distance; **tree stumps** (`*-stump` state from woodcutting) clear that occlusion at runtime via live chunk snapshots (same dynamic path as torches, without rebaking). Store a 16×16 intensity map (0–255, smoothstep falloff by effective tile distance). Torch range is 8 tiles; furnace is 4.
68**Code:** `server/src/lighting/baker.js`, `shared/lighting/raycast.js`, `shared/definitions/tiles.js` (`LightOcclusion` / `blocksLight`), tests in `server/tests/lighting.test.js`
69
70## World editor (server)
71
72**Status:** full
73**Spec:** Admin API to load/save a chunk, toggle open/closed, paint ground/blocks/spawners, write changelog bullets, edit live world settings, and apply the pending map revision. Central Exchange counters (`BlockType.marketplace`, neighbor-connect autotile), **wooden tables** (`BlockType.table`, magenta autotile `0`–`15` tinted per wood tier; joins only the same material), and **Central Exchange staff** spawners are placeable.
74**Code:** `server/src/editor/service.js`
75
76## World editor (client)
77
78**Status:** full
79**Spec:** Separate `/editor` page. 3×3 chunk view with the selected chunk centred and outlined in red. Chunk-step navigation, paint only inside the selected chunk, hover preview of the selected tool, mouse-wheel zoom (centred on the selected chunk) and Shift+wheel to cycle visual states (for outdoor seasonal tiles: spring/summer/fall/winter, which also updates Season preview), open/closed, right-side **Changelog / Console** tabs (console streams live server output to admins), night preview slider, **season preview** dropdown, world-settings modal, **Dimension settings…** opens a modal (lighting / season / default ground / soft-delete), **Quests** and **Dialogues** buttons under Settings (see docs/QUESTS.md), save chunk and Apply now. **Save chunk** is disabled when clean and **pulses** when the draft is dirty; navigating N/S/E/W with unsaved edits opens a confirm modal (Cancel / Discard / Save). Bottom status bar shows hovered **tile** and **chunk** coordinates. **Select block…** opens a modal with auto-loaded tabs (Ground tiles / Blocks / Spawners — one entry per mob type with mob icon). **Flower** is a single palette entry; each paint rolls a random colour (same as harvest respawn). Hover shows a tooltip of tile/spawner config and highlights a spawner’s spawn range (cyan) and wander range (amber); right-click a spawner opens its config modal. Spawners render as mob icons in the editor only.
80**Code:** `client/editor.html`, `client/src/editor/main.js`, `client/src/editor/paletteModal.js`, `client/src/editor/tileConfigModal.js`, `client/ui/editor.css`
81
82## Per-chunk changelog
83
84**Status:** full
85**Spec:** Each save stores who, when, and structured bullets of ground/block/spawner/open-closed diffs.
86**Code:** `server/src/editor/service.js` (`diffChunks`), `server/src/persistence/worldDb.js` (`world_chunk_edit_log`), tests in `server/tests/editor-diff.test.js`
87
88## WebSocket gateway
89
90**Status:** full
91**Spec:** JSON WebSocket on `/ws`, HTTP static files for the client. Connections belong to the gateway. Clients send intentions that are queued onto the simulation tick. Editor messages are admin-only.
92**Code:** `server/src/gateway/websocket.js`, `server/src/gateway/http.js`, `server/src/index.js`
93
94## Stub authentication
95
96**Status:** full
97**Spec:** Until auth.timfalken.com exists, each connection is `admin-<n>`. `n` starts at connected-count+1 and skips names already in use so two live sessions cannot share a stub id. Stub accounts are admins.
98**Code:** `server/src/auth/stub.js`
99
100## Characters
101
102**Status:** full
103**Spec:** Unlimited characters per account, one in the world. First name is not globally unique; last name is globally unique per account; first+last unique per account, case-insensitive. Male/female body. Spawn requires an open tile. The login screen lists characters first; **Create Character** opens a modal (**Appearance** / **Clothing** tabs) and successful creation enters the world immediately. New characters receive **Starter Equipment** / inventory from live world settings (origin: “Received from the gods”), then **creation clothing** on top: cotton shirt + chosen cotton trousers/shorts/skirt, each with an HSL dye (same controls as hair). Existing characters are unaffected.
104**Code:** `server/src/characters/service.js`, `server/src/persistence/stateDb.js`, `shared/items/starterLoadout.js`, `shared/items/createClothing.js`, `client/index.html`, `client/src/play/createClothingControls.js`
105
106## Character deletion and inheritance
107
108**Status:** full
109**Spec:** 24h delayed delete, cancellable. Notify via stub log (or email when present). Names and surname claims are freed on permanent delete. Inventory, equipment, carried coins, and vault move to the account inheritance tab, claimable at a bank into another character's vault.
110**Code:** `server/src/characters/service.js`, `server/src/persistence/stateDb.js` (`account_inheritance`)
111
112## 3×3 chunk replication
113
114**Status:** full
115**Spec:** Entity and ground-item replication uses the current chunk and eight neighbours. Map tiles (static snapshots) default to a **5×5** ring (`STATIC_CHUNK_RADIUS = 2`); clients may request **Short** viewing distance so the map ring matches the 3×3 entity ring. Closed chunks are still sent. Afterwards the gateway sends `ENTITY_SPAWN`, compact `ENTITY_MOVE` (tile + gait) and `ENTITY_DESPAWN`; appearance and path stay off the move payload. Tile deltas are not used yet because live tile edits wait for Apply now. Visible chunks may be owned by different workers; the gateway never reassigns regions for rendering.
116**Code:** `server/src/simulation/simulation.js` (`snapshotsForView`, `snapshotChunk`, `drainReplication`), `server/src/gateway/websocket.js` (`syncSubscriptions`, `publishEntity`), `shared/graphics/settings.js`
117
118## Click-to-move and A\* pathfinding
119
120**Status:** full
121**Spec:** `MOVE_TO` runs A\* over the visible 3×3 using block passability and open-chunk bounds. Entities do **not** block each other’s movement (players and mobs pass through). Occupied tiles are still preferred-away for mob wander goals and required to be clear for melee attack stance. Client spreads stacked entities evenly on a circle (`ENTITY_STACK_SPREAD_DIAMETER_PX`, centred on the tile) with a short lerp into place; within-tile y-sort still uses each sprite’s visual Y. Server commits integer tiles on the movement cadence. Neighbour expansion prefers steps that most reduce Manhattan distance to the goal; remaining ties break by axis — **players prefer vertical**, **mobs prefer horizontal** — so mutual approaches are less likely to oscillate sideways.
122**Code:** `server/src/navigation/astar.js`, `server/src/simulation/workerWorld.js` (`#moveTo`, `#stepMovement`, `walkableFor`, `isClearStanding`)
123
124## Global walk/run cadence
125
126**Status:** full
127**Spec:** Walk 2 tiles/s, run double. Movement ticks at run rate. `SetGait` chooses every-other vs every movement tick.
128**Code:** `server/src/simulation/workerWorld.js` (`#stepMovement`, `#setGait`)
129
130## Client movement interpolation
131
132**Status:** full
133**Spec:** Client lerps sprites between replicated tiles over the walk or run interval from world settings.
134**Code:** `client/src/render/worldView.js` (`moveEntity`, `update`)
135
136## Play viewport and camera
137
138**Status:** full
139**Spec:** Camera stays centered on the local player. Scroll-wheel zoom is viewport-only (1×–4×) and does not change server visibility. Tiles and chunk atlases more than half a tile outside the screen (zoom-aware) are not drawn and skip per-frame lighting work. Hovering another player shows their first name; clicking them inspects instead of issuing move.
140**Code:** `client/src/render/worldView.js` (`#cullOffscreenDrawables`, `#drawBounds`), `client/src/play/main.js`, `client/index.html`
141
142## Client graphics settings
143
144**Status:** full
145**Spec:** Gear button (top-right) opens a client settings panel persisted in `localStorage`. **Viewing distance** Long (default) keeps the 5×5 map ring; Short limits map subscriptions to the 3×3 around the player (`SET_GRAPHICS_SETTINGS`). **Lighting** Soft (default) uses corner-blended lightmaps; Simple fills each tile flat. **Bloom** On/Off toggles the bloom render layer. **Soft terrain** On/Off (default **On**) edge-blends `blendable` ground tiles (grass, dirt) into differing neighbours along **cardinal** edges only: outer edge pixel 50% neighbour, next pixel 25% (softer 40%/20% when both sides are blendable); baked at chunk atlas time. The settings panel blocks world clicks while open.
146**Code:** `shared/graphics/settings.js`, `client/src/play/graphicsSettings.js`, `client/src/render/worldView.js` (`setGraphicsPrefs`), `client/src/render/chunkBake.js`, `shared/render/softTerrain.js`, `server/src/gateway/websocket.js`
147
148## Night shading
149
150**Status:** full
151**Spec:** World time is server time minus 1200 years. At night, unlit tiles are darkened by `nightDarkness` (a live world setting) and reachable tiles use the baked 0–255 intensity so a torch fades tile-by-tile instead of a hard circle. With **Soft** lighting, baked ground/block atlases sample a per-chunk lightmap with neighbour blending; **Simple** lighting uses a flat per-tile intensity (no corner blend). **Animated liquid water** uses the same lit values via shader uniforms. **Light-occluding tiles** (`blocksLight` / impassable ground) stay flat and contribute **0** into open neighbours (and diagonals need both cardinals clear), so a torch beside a wall does not soft-light the far side. Oversized/animated blocks and mobiles still use a uniform darkness for their standing tile (entities lerp shade while moving). `worldTime` also carries the real **server-local calendar season** (`spring` / `summer` / `fall` / `winter`) for seasonal tile visuals (types without a spring sprite fall back to summer).
152**Code:** `client/src/render/worldView.js` (`nightFactor`, `#updateShade`, `#writeChunkLightmap`, `#placeSpriteShade`, `setWorldSeason`), `server/src/simulation/simulation.js` (`worldTime`), `shared/world/season.js`
153
154## FrameworkV3 client bootstrap
155
156**Status:** full
157**Spec:** FrameworkV3 is a git submodule at `client/frameworkv3`, built first via `npm run build:client`. Game code lives in `client/src`. Server does not import it.
158**Code:** `.gitmodules`, `client/frameworkv3`, `client/scripts/build-framework.mjs`
159
160## Sprite size, pivot and Y-sort
161
162**Status:** full
163**Spec:** World sprites may be any pixel size. Pivot is horizontal centre and 8px from the sprite bottom, placed on the tile centre. Blocks and mobiles are Y-sorted (north behind south). Ground/block definitions set `frames`, `framesPerRow`, and `animationSpeed` for sprite sheets. Immobile ≤16×16 blocks bake into per-row chunk strips; taller sprites stay individually Y-sorted.
164**Code:** `shared/render/pivot.js`, `shared/definitions/tiles.js`, `client/src/render/worldView.js`, `client/src/render/chunkBake.js`, tests in `server/tests/pivot.test.js`
165
166## Visual tile states
167
168**Status:** full
169**Spec:** Each ground and block type has a folder of PNG states. Non-seasonal types use the first alphabetical file as the default; outdoor seasonal types prefer `summer` (or legacy `grass`). States are visual only; the game may set a named state (for example a door or ore). For outdoor types that expose summer/fall/winter (optional `spring`), calendar season overrides authored state in play — spring uses `spring` when present, otherwise summer; the editor Season preview (and Shift+wheel on seasonal tools) chooses which seasonal look to show while editing. Indoor types (floors, walls, furniture) do not need seasonal art. The editor wheel cycles states; hover previews the selected tool on the target tile.
170**Code:** `server/src/assets/spriteCatalog.js`, `shared/definitions/tileSprites.js`, `shared/world/season.js`, `client/src/editor/main.js`, `client/src/render/worldView.js`, tests in `server/tests/tile-states.test.js`, `server/tests/season.test.js`
171
172## Region workers and cross-worker transfer
173
174**Status:** full
175**Spec:** Isolated simulation workers own regions. Default is two in-process workers behind a clone-on-boundary protocol (`SIMULATION_WORKER_MODE=thread` uses `worker_threads`). Neighbour-sticky assignment; an entity that steps into a foreign region is frozen, accepted on the destination, then removed from the source (one authoritative copy). Ghost occupancy is visible for pathfinding. Dynamic load rebalance is later.
176**Code:** `server/src/simulation/simulation.js`, `workerWorld.js`, `inProcessWorker.js`, `threadWorker.js`, tests in `server/tests/worker-*.test.js`
177
178## ChunkLoader activation and unload persistence
179
180**Status:** full
181**Spec:** Players carry `ChunkLoader` (3×3 simulating chunks, 3×3 resident regions). Chunks with no simulation refs stay dormant in memory. Regions with no residency refs unload after `regionUnloadGracePeriodMs`. Persistent entities are written on unload and restored on the next load; non-persistent entities are discarded.
182**Code:** `server/src/simulation/chunkLoader.js`, `server/src/simulation/simulation.js`, `server/src/persistence/stateDb.js` (`persistent_entities`)
183
184## Midnight restart and Git deploy
185
186**Status:** full
187**Spec:** The live process periodically `git fetch`es and compares `HEAD` to `origin/<branch>` (default `master`). When the remote is **ahead**, a graceful restart is scheduled for the next **server-local midnight**. From **3 hours before** midnight, every connected player gets a **permanent toast** with a live countdown. At midnight the server writes `server/data/restart-request.json`, force-logs out sessions, unloads/persists the world, and exits. **systemd** (`Restart=always`) relaunches via `deploy/start-server.sh`, which **always** hard-resets to `origin/<branch>`, pulls, runs `npm install`, then starts Node — including after crashes or power loss (intentional, so a fixed commit can recover a bad build). Install with `sudo ./deploy/install-service.sh`. World editor **Console** tab streams live server stdout to admins.
188**Code:** `shared/deploy/schedule.js`, `server/src/deploy/`, `server/src/index.js`, `server/src/logging/consoleCapture.js`, `deploy/start-server.sh`, `deploy/install-service.sh`, `deploy/tile-mmo.service`, `client/src/play/toasts.js`, `client/src/editor/main.js`, tests in `server/tests/deploy.test.js`
189
190## Spawners
191
192**Status:** full
193**Spec:** Authored chunk spawners (`data.spawners[]`) with mob type, max alive, spawn range, and **max wander range** (≥ spawn range). Legacy `BlockType.spawner` tiles migrate into this array on decode. They fire only in open, simulating chunks. When a chunk first becomes simulating, spawners **pre-heat** and place up to `maxAlive` immediately so the area looks populated. Spawned mobs get `SpawnOrigin` (origin tile + wander range); idle wander goals must stay inside max wander range, while combat chase / approach may leave the area. Persistence follows the mob definition (deer are not persistent). In play, spawners are invisible and non-blocking; players may place real blocks on the same tile. Wildlife options include **deer**, **rats**, and **chickens** (white deer-shaped placeholder sprite); the editor lists every mob definition as a placeable spawner. Hovering a spawner in the world editor highlights spawn range (cyan) and wander range (amber). Pigeons are not ambient wildlife. Living mobs (deer, rats, chickens, etc.) can always fight back when attacked (retaliate on first swing); **rats are aggressive** and auto-engage players within 5 tiles with line of sight. **Humanoid** spawners (incl. town guards / exchange) have an editor **Aggressive** flag for the same in-range aggro; Aggressive forces **Bounty** to 0. Spawner **Level** sets skills/HP and **spell cast chance %** (= level, capped 1–100; shown as a label, not editable).; courier pigeons cannot.
194**Code:** `server/src/simulation/spawners.js`, `server/src/simulation/workerWorld.js`, `server/src/world/chunkData.js`, `shared/definitions/mobs.js`, `shared/definitions/mobCombat.js`, `client/src/editor/tileConfigModal.js`, `client/assets/mobs/deer/`, `client/assets/mobs/rat/`, `client/assets/mobs/chicken/`
195
196## Mob definitions (content schema)
197
198**Status:** partial
199**Spec:** Target mob content shape: `displayName`, `maxHealth`, `attackSkill`, `drops`, `sells`. Drops support `chance`, fixed `quantity`, or inclusive `quantityMin`/`quantityMax`. **Chicken** always drops **1–3 feathers** and has a **20%** chance of an **egg**. **Dialogue trees** are world-scoped assets (Dialogues editor); humanoid spawners assign `config.dialogueId`. See [`docs/QUESTS.md`](QUESTS.md).
200**Code:** `shared/definitions/mobs.js`, `shared/definitions/mobCombat.js`, `server/src/combat/service.js` (`rollDropQuantity`)
201
202## Quests
203
204**Status:** partial
205**Spec:** Full design in [`docs/QUESTS.md`](QUESTS.md). World editor **Quests** / **Dialogues** buttons (under Settings) author world-scoped defs. Spawners link `dialogueId`; unique dialogues require one spawner with `maxAlive: 1`. Shared `ConditionSet` (AND + per-clause NOT). Play **Quests** UI + step-complete toast “Quest objectives achieved”. Progress / journal / `dialogueHeard` in `state.sqlite`.
206**Code:** `shared/quests/`, `server/src/quests/`, `server/src/persistence/worldDb.js`, `server/src/persistence/stateDb.js`, `client/src/editor/questsModal.js`, `client/src/editor/dialoguesModal.js`, `client/src/play/quests.js`, `client/src/play/dialogue.js`
207
208## Character logout resume
209
210**Status:** full
211**Spec:** Despawning a character (logout / disconnect) writes their live tile to `characters`. The next login reloads that row after despawn and resumes there (or the nearest free enterable tile within a short spiral if blocked), instead of jumping to a distant world spawn.
212**Code:** `server/src/simulation/simulation.js` (`spawnCharacter`, `despawnCharacter`), tests in `server/tests/character-resume.test.js`
213
214## Combat resolution (rolls)
215
216**Status:** partial
217**Spec:** Authoritative server rolls; clients only show outcomes. **Melee & ranged (physical):** roll hit skill vs defender **Dexterity (agility)** — miss if attack roll < agility roll, hit on tie or higher; on hit roll damage skill (Strength for melee, Dexterity for ranged) for `baseDamage + roll − 1`; on hit defender rolls Defence — **block** if defence roll > attacker's to-hit roll; otherwise apply damage. **Effective combat levels** add worn equipment tier bonuses to damage/agility/defence rolls (e.g. Strength 10 + bronze weapon +1 → damage roll uses 11). Hit skills (Club/Sword fighting, Archery) use base skill only. XP only on damage hits. **Attack types** (slashing / piercing / blunt) are defined on weapons; mob weak/resist multipliers remain later. **Magic:** roll Magic vs per-spell **difficulty** (contest, tie or higher succeeds); on success roll Mind for damage; multiply by elemental weak ×2 / neutral ×1 / resistant ×0.5; non-damage spells only need a successful cast roll then apply an effect. Spell defs + live cast/impact in `shared/definitions/spells.js` / `server/src/spells/` (starter Light + Spark). More spells and LOS polish remain later.
218**Code:** `shared/combat/rolls.js`, `shared/combat/magic.js`, `shared/definitions/spells.js`, `shared/definitions/attackTypes.js`, `shared/equipment/stats.js`, `server/src/combat/service.js`, `server/src/spells/service.js`, tests in `server/tests/combatRolls.test.js`, `server/tests/magic.test.js`, `server/tests/spells.test.js`, `server/tests/equipment.test.js`
219
220## Combat, skills, groups, pigeons
221
222**Status:** partial (melee + ranged bows + starter spells live; groups later)
223**Spec:** Melee auto-attack with stick (Clubfighting + Strength), LMB/RMB targeting and context menu (including **Follow \<name\>** / **Attack \<name\>**), engage/retaliate, swipe VFX, shove animation, damage flash, HP bars above **mobs and players** when below max HP, and client dynamic-light hooks. Fightable mobs **retaliate on the first resolved swing** (hit or miss), not when Attack is merely clicked. **Players likewise auto-retaliate** when a mob’s first swing resolves against them (clears follow/gather). Melee requires Chebyshev distance 1 (**diagonals allowed**) while the attacker stands alone on their tile; if stacked with others they path to the nearest clear adjacent stance. Approach pathfinding may pass through entities but prefers clear goal tiles. **Aggressive** mobs (e.g. rats: `aggressive` + `aggroRangeTiles`, default 5) auto-engage player characters in Chebyshev range with line of sight through enterable tiles; passive wildlife (deer, chickens) does not. Engaged mobs keep pursuing if the player cancels attack. Physical combat uses skill rolls (see **Combat resolution**). **Ranged:** bow in weapon + arrows in offhand; Archery hit / Dexterity damage; arrow projectiles lerp toward the target’s **live client visual pose** (misses use a fixed fly-by tile). Server resolves the hit immediately; **HP bar / flash / damage numbers wait until the projectile lands** on each client. **Magic:** cast UI + Light/Spark; spell projectiles likewise track moving targets; spell impacts are delayed on the server to match travel time. **Health** skill sets max HP; taking damage awards Health XP equal to damage taken (lethal hits grant none). Reaching **0 HP** is player death (see **Player death and respawn**). Follow reuses the target's vacated trail and remaining path (stop one tile short, wait for vacancy, walkability each step); catch-up A* only when no shared trail yet. Break beyond one chunk width. **Carrier pigeons** dispatch money or one inventory stack to Bank or Player. **Skills:** persistent XP, 50 XP to level 2 then double each level, cap 99; Health starts at 10, others at 1; **login enforces those minima** (raises and persists under-leveled skills). Skills panel. Groups and broader non-combat skill XP remain later.
224**Code:** `shared/combat/rolls.js`, `shared/skills/progression.js`, `shared/skills/state.js`, `shared/definitions/skills.js`, `shared/definitions/mobCombat.js`, `shared/definitions/mobs.js`, `shared/definitions/rangedItems.js`, `server/src/skills/service.js`, `server/src/combat/service.js`, `server/src/spells/service.js`, `client/src/play/skills.js`, `client/src/play/main.js`, `client/src/render/worldView.js`, tests in `server/tests/combatRolls.test.js`, `server/tests/skills.test.js`, `server/tests/mobCombat.test.js`, `server/tests/ranged.test.js` (+ combat/follow/courier/spells tests)
225
226## Player death and respawn
227
228**Status:** full
229**Spec:** When a **player** reaches **0 HP**, they **die** immediately (authoritative on the server):
230
2311. **Corpse drops** on the death tile: a **bones** ground item and a **skull** ground item (new item definitions + sprites). These use normal ground-item rules (pickup, despawn timer). Inventory/equipment are **not** dropped by default (death penalty is the corpse markers + travel to church — revisit if PK/loot rules are added later).
2322. **Combat ends** for the dead player and anyone targeting them (clear engage both ways). The dead player cannot move, attack, follow, pick up, bank, chat-actions that affect the world, or otherwise act until they respawn.
2333. **Death modal (client):** a blocking modal that is the **only** interactable UI while dead (world clicks, hotkeys, bag, etc. are ignored). Copy states that the player is dead; primary action is **Respawn**. Closing the tab/disconnect while dead keeps them dead until they log in and respawn (or auto-prompt the same modal on re-enter).
2344. **Respawn:** server moves the character to the **nearest church altar** block (Chebyshev / path distance TBD — prefer enterable tile adjacent to the altar if the altar tile itself is impassable). New **block type: church altar** (`BlockType` + editor placeable + sprite folder), passable or adjacent-use like bank (exact interaction: respawn destination only for now, not a usable station).
2355. After respawn the player is restored to **full Health** and **full Stamina** (max from skills), cleared of death state, and may fight again.
236
237**TODO:** Revisit player-loot penalties if PK rules are added.
238**Code:** `shared/definitions/items.js`, `shared/definitions/tiles.js`, `shared/protocol/constants.js`, `server/src/combat/service.js`, `server/src/simulation/simulation.js`, `server/src/simulation/workerWorld.js`, `server/src/persistence/stateDb.js`, `server/src/gateway/websocket.js`, `client/src/play/death.js`, tests in `server/tests/death.test.js`
239
240## Equipment tiers and worn stat bonuses
241
242**Status:** partial
243**Spec:** Metal gear exists in seven material tiers (lowest → highest): **Bronze**, **Iron**, **Steel**, **Mithril**, **Adamantium**, **Orichalcum**, **Dragon**. Each has a **rank** (1–7), display **tint**, and equip min skill: 1 / 10 / 20 / 35 / 50 / 70 / 90. Mining a material requires **half** of that equip gate (ceil); smelting requires **75%** (ceil). **Worn combat bonuses** come from live world setting `equipmentStatBonuses` (editor **Equipment Stats** tab); defaults seed from `TIER_STAT_BONUS` (full helms +1 Defence). Leather armour can grant Agility and Defence independently; wizard armour Magic and Defence; clothing Defence. Magic casting uses worn Magic/Mind gear bonuses the same way physical combat uses Strength/Agility/Defence. Tools (pickaxes) gate on Mining and do not use the bonus tables. **Tin** and **copper** ores (no bronze ore) and **coal** use their associated bar tier for mine/smelt timing and gates (tin/copper → bronze, coal → steel). **Silver** and **Gold** are precious-only (ore + bars, no tools; silver mine/smelt like iron rank 2 / skill 10, gold like steel rank 3 / skill 20). **Wood tiers** (same gates/ranks): **Pine**, **Birch**, **Oak**, **Ebony**, **Lignum**, **Heartwood**, **Elder** (match metal ranks for hafts). **Cloth tiers** (same gates/ranks): **Cotton**, **Wool**, **Linen**, **Cashmere**, **Silk**, **Fairy silk**, **Dragonweave**. Logs/handles tint from shared `wood` sprites; **pine trees** are chopable resource nodes (more tree tiers later) — axe sprites (`items/axe`) match pickaxe style for woodcutting. Armour pieces share one set of overlays under `items/armour/` tinted per metal tier (no per-tier icon copies).
244**Shared sprites + magenta tint:** one base sprite per shape under `items/metal` (`ore`, `bar`), `items/pickaxe`, `items/axe` (`axe`, `axe-head`, `axe-equip`), `items/wood` (`log`, `handle`), `items/cloth` (`wool`, `yarn`, `cloth`), `items/clothing` (`shirt`, `shorts`, `skirt`, `trousers`, `sweater`), boulder-ore, and **tables** (`blocks/table/0`–`15`); tintable pixels use magenta rules in `shared/render/tint.js`. **Dual-channel tint** (red = shaft/wood, blue = tip/string; white unchanged): arrows, hafted tools, **bows** / unstrung bows under `items/bow/` (`bow`, `unstrung-bow`, `bowstring` magenta, `bow-equip`). Boulder ore states are catalog aliases of `boulder-ore.png` with per-material tint. Table states are `${woodTier}-${mask}` aliases of mask PNGs with wood-tier tint; tables autotile only with the same wood. Trees use per-season live + **`-stump`** PNGs (mandatory for every tree type).
245**TODO:** full combat gear catalog; more tree tiers / fishing / herbs; silver/gold jewelry / other precious recipes; cloth sources beyond cotton.
246**Code:** `shared/definitions/materialTiers.js`, `shared/definitions/equipmentStatCategories.js`, `shared/render/tint.js`, `shared/definitions/metalItems.js`, `shared/definitions/woodItems.js`, `shared/definitions/rangedItems.js`, `shared/definitions/tierFamilies.js`, `shared/equipment/stats.js`, tests in `server/tests/equipment.test.js`, `server/tests/mining.test.js`, `server/tests/tint.test.js`, `server/tests/ranged.test.js`
247
248## Gathering, crafting, and production skills
249
250**Status:** partial (mining + smelting + pickaxe/axe/bow craft chains + pine woodcutting + cotton/flower/herb herbalism live)
251**Spec:** **Mining:** LMB/RMB on ore boulder (states `tin-ore`, `copper-ore`, `iron-ore`, `silver-ore`, `gold-ore` … `dragon-ore`, `coal`). Uses the **best usable pickaxe in inventory** (or weapon slot) — tools need not be equipped. Tool rank ≥ associated bar rank and Mining ≥ mine gate; otherwise toast *"You need a pickaxe to mine this!"*. Duration `(rank×8s) − (toolRank×3s)` (min 0.5s). Attack shove animation, **no** swipe FX; while swinging, the gather tool's **equip sprite** is shown in the weapon overlay (even if a different weapon is equipped). Awards Mining XP (`rank×5`). On success the node becomes **exhausted** (plain `boulder` sprite, not mineable) for `10s × associated bar rank`, then restores its ore state via runtime `CHUNK_DELTA`. Hovering an active ore/tree/plant node shows a cursor tooltip (`resourceNodeDisplayName`). Outdoor blocks may also use **optional seasonal overlays** (e.g. boulder / ore `*-winter` only — other seasons keep the base sprite). **Woodcutting:** LMB/RMB / **Chop** on outdoor tree blocks (**pine** today). Best usable **axe** in inventory/weapon; Woodcutting + axe tier gates match mining (pine = rank 1). Same duration/exhaust curves. Success grants a **pine log**, stamps **`Felled by <name>`**, awards Woodcutting XP, and sets a **seasonal stump** (`summer-stump` / `fall-stump` / `winter-stump` — required for every tree type). Calendar season still drives stump look while exhausted; after exhaust the live tree returns. Tree / flower / herb **regrow** uses the four-way growth season (spring Mar–May, summer Jun–Aug, fall Sep–Nov, winter Dec–Feb): **summer & fall** keep base exhaust time, **winter** doubles it, **spring** is 25% faster (`×0.75`). **Herbalism (plants):** **Flower** nodes need **no tool** (~1s); each flower block carries a fixed colour tint (chosen on respawn / editor place) and picking yields that colour, stamps **`Picked by <name>`**. **Cotton plant** needs **no tool** (RMB Pick / LMB); yields cotton fibre. Both exhaust ~15s then respawn. **Smelting:** furnace block opens craft UI; duration `rank×2s` by output bar tier. Recipes 1 ore → 1 bar except **bronze** = 1 tin + 1 copper, **steel** = 1 iron ore + 1 coal, **adamantium** = 1 ore + 1 coal, **orichalcum** = 1 ore + 3 coal, **dragon** = 1 ore + 5 coal. Smithing XP on success. **Pickaxe / axe craft:** woodworking bench shapes 1 log → 1 handle; anvil smiths 1 bar → 1 pickaxe head or axe head; **crafting bench** assembles matching-tier handle + head → pickaxe or axe (pine↔bronze … elder↔dragon). **Ranged craft:** woodworking → arrow shafts / unstrung bows; anvil → arrow tips; spinning wheel → bowstring from yarn; crafting bench → feather + shaft + tip → arrow, and unstrung bow + bowstring → bow (wood + matching cloth). Gold bars are smeltable but have no tool recipes. Server-authoritative `START_CRAFT` / timer; craft panel supports **Craft**, **Craft X**, and **Craft all** with a progress bar that restarts on each continuing batch step. Play errors (mine gates, full bag, …) show as temporary **toasts** at the top of the screen. More tree tiers / fishing / other stations later.
252**Code:** `shared/definitions/gathering.js`, `shared/definitions/tiles.js` (`resourceNodeDisplayName`, `isChopableTreeBlock`, `isPickablePlantBlock`), `shared/definitions/rangedItems.js`, `shared/crafting/tierRecipes.js`, `shared/world/season.js` (`treeStumpStateForSeason`, `growthSeasonIdAt`, `scaleRegrowDurationMs`), `server/src/gathering/service.js`, `server/src/crafting/service.js`, `shared/crafting/stationRecipes.js`, `client/src/play/main.js`, `client/src/play/crafting.js`, `client/src/render/worldView.js` (`spawnGatherSwing`), tests in `server/tests/mining.test.js`, `server/tests/woodcutting.test.js`, `server/tests/crafting.test.js`, `server/tests/ranged.test.js`, `server/tests/season.test.js`
253
254## Cloth, dyes, and tailoring
255
256**Status:** partial (cotton loop + flower dyes + shirt/shorts/skirt/trousers/sweater live; higher cloth sources TBD)
257**Spec:** **Cloth tiers** (same skill gates/ranks as metal/wood): Cotton, Wool, Linen, Cashmere, Silk, Fairy silk, Dragonweave. Shared magenta sprites under `items/cloth` (`wool` fibre, `yarn`, `cloth`) and `items/clothing` (`shirt`, `shorts`, `skirt`, `trousers`, `sweater` + equip) tinted per tier (or optional dye colour on clothing instances). **Spinning wheel** (Tailoring): fibre → yarn. **Loom**: yarn → cloth. **Tailor bench** UI is template-first: pick clothing template (**shirt**, **shorts**, **skirt**, **trousers**, **sweater**) → cloth tier → optional dye from bag → sidebar shows resolved ingredients (shirt/shorts/skirt/trousers = **1 cloth**; sweater = 3 yarn). Skirts are not tight-fit (unlike shorts). Display names are tiered (`Cotton shirt`, …). Historic item id 5 remains the cotton shirt. Crafted clothing can carry `instance.dyeColor`; otherwise material tint. **Flowers** (9 colours) brew 1:1 into **dye** bottles at a cauldron (needs **glass bottles** / `potion-0`). Two different dye colours mix paint-style (weighted by fill); bottle count follows inserted dyes; fill packs with overflow into the next bottle (extra glass only if overflow needs more bottles than inputs). Cannot mix flowers with dyes in one brew. Dye uses on tailor consume one fill level per craft.
258**TODO (sources):** shear animals / pick plants for wool–silk; fairy silk + dragonweave as mob drops later.
259**Later design (document only for now):**
260- **Wizard cloth gear** — robes and similar give Magic skill bonuses (`EquipmentKind.wizardCloth`).
261- **Cosmetic cloth gear** — sum equipped cosmetic item tiers as **Style points** (quests / exclusive areas).
262- **Warm clothing** — sweaters and other warm pieces reduce cold-season debuffs (e.g. winter halves stamina regen; each warm-equipped slot except hands mitigates; full warm set nullifies cold; summer reverses). **Padding** from cloth + matching-tier plate at a crafting bench → **padded armour** per slot.
263**Code:** `shared/definitions/materialTiers.js` (`ClothTier`), `shared/definitions/clothItems.js`, `shared/definitions/dyes.js`, `shared/crafting/tailor.js`, `shared/crafting/stationRecipes.js`, `server/src/alchemy/service.js`, `server/src/crafting/service.js`, `server/src/gathering/service.js`, `client/src/play/crafting.js`, `client/src/play/alchemy.js`
264
265## Crafting stations
266
267**Status:** partial (furnace, anvil, woodworking, crafting, spinning wheel, loom, tailor bench live)
268**Spec:** Furnace / anvil / woodworking-bench / crafting-bench / spinning-wheel / loom / tailor-bench blocks + adjacency craft panel. Recipes in `stationRecipes.js`. Furnace/anvil/woodworking/crafting craft timer = `smeltingDurationMs` (`rank × 2s`) when `xpMaterial` is set; other stations still use `CRAFT_DURATION_MS` (2s) / UI/dev only (`__craftDev`). Woodworking shapes components (handles, shafts, unstrung bows); crafting bench joins finished parts (pickaxe/axe head + handle, arrows, strung bows). Spinning wheel / loom / tailor use Tailoring. **Anvil**, **woodworking**, **spinning wheel**, **loom**, and **tailor** craft UIs use a single-axis material dropdown so tier variants share one recipe cell. **Crafting bench** alone shows **paired metal/wood labels** (e.g. `Bronze/Pine`) because it mixes metal tools with wood bows on the same tier rank. **Hard rule (all stations + cauldron, player and scripts):** items in station slots are never committed out of the inventory — slots are a reservation/view over the bag (**client-side UI**; even if it looks like mats sit in the station, they do not). Server soft-tracks steps/claims only and consumes on successful craft/brew. Closing the UI, cancelling, or dying mid-craft/brew cannot destroy reserved mats. Station progress is **per player**, not tile-global. See `.cursor/rules/station-inventory.mdc`.
269**TODO:** oven/campfire burn; dedicated station sprites where still placeholder.
270**Code:** `shared/definitions/craftingStations.js`, `shared/definitions/tiles.js`, `server/src/crafting/service.js`, `client/src/play/crafting.js`
271
272## Stamina and running
273
274**Status:** full
275**Spec:** **Stamina** skill sets max stamina (= skill level). Login / new characters floor Stamina at **level 5**. Each stamina point equals **one second of running** (drains on successful run tile steps). Running awards **1 Stamina XP** per stamina point spent. Walking, idle, or **run gait with no active path** regenerates **1 stamina per second**. At 0 stamina, run gait is forced back to walk; you cannot toggle run until stamina recovers. Client shows vertical **HP** (always) and **stamina** bars bottom-right.
276**Code:** `shared/stamina/rules.js`, `shared/definitions/skills.js` (`playerMaxStamina`, `DEFAULT_PLAYER_SKILL_LEVELS`), `server/src/simulation/workerWorld.js`, `server/src/skills/service.js` (`syncPlayerStamina`), `client/src/play/stamina.js`, tests in `server/tests/stamina.test.js`
277
278## Alchemy / cauldron
279
280**Status:** partial (starter herb potions + failed-effect list + status ticks live; more recipes TBD)
281**Spec:** **Herbalism** gathers flowers, cotton, and **24 folklore herbs** (`BlockType.herbPlant`). Flowers/cotton need **no tool**; clipper herbs require **plant clippers** and Herbalism gates by tier. **Alchemy** cauldron tabs **Alchemy** / **Dyes**. Starter potions: **Lesser health tonic** (thyme→heat→mint→stir; health regen 1/s for 10s, re-drink extends), **Lesser haste draught** (2 mint→heat→stir→lavender→cool; stamina regen 1/s for 10s), **Strength potion** (3 thyme→stir→2 nettle→heat; +5 Strength for 1 min), **Clarity potion** (rosemary→cool→2 chamomile→stir; +5 Mind for 1 min). Failed brews hash to unstable effects: stamina drain 1/s 15s, weak glow light 10s, shrink to 50% scale 30s, blindness 20s (extra darkness + local vision bubble). Active effects show as HUD icons left of the HP/stamina bars (`assets/status-effects/`; hover shows description + remaining time). Opening needs empty glass bottles. **Dyes** unchanged (flowers).
282**Code:** `shared/definitions/alchemy.js`, `shared/statusEffects/rules.js`, `shared/statusEffects/display.js`, `server/src/statusEffects/service.js`, `client/src/play/statusEffects.js`, `shared/definitions/herbs.js`, `server/src/alchemy/service.js`, `server/src/items/bags.js`, `client/src/render/worldView.js`, tests in `server/tests/alchemy.test.js`, `server/tests/herbalism.test.js`
283
284### Folklore herb associations (design only — not in code)
285
286Use later when deciding which ingredients fit which potions. Tiers: **2 / 3 / 3 / 4 / 4 / 4 / 4** for T1–T7.
287
288| Tier | Herb | Associations |
289| --- | --- | --- |
290| 1 | Mint | Refreshment, stamina, antidotes |
291| 1 | Garlic | Undead protection, disease resistance |
292| 2 | Thyme | Courage, vitality, resistance |
293| 2 | Sage | Healing, wisdom, longevity |
294| 2 | Rosemary | Memory, protection, clarity |
295| 3 | Lavender | Sleep, calm, dreams |
296| 3 | Chamomile | Restoration, sleep, soothing |
297| 3 | Nettle | Vigour, resilience, protection |
298| 4 | Yarrow | Wound healing, battle medicine |
299| 4 | Juniper | Purification, disease resistance |
300| 4 | Elder | Spirits, protection, healing |
301| 4 | Rue | Curse resistance, purification |
302| 5 | Valerian | Sleep, sedation, tranquillity |
303| 5 | Mugwort | Dreams, visions, divination |
304| 5 | Wormwood | Poison resistance, spirits, bitterness |
305| 5 | St. John's wort | Holy protection, dispel darkness |
306| 6 | Hawthorn | Fey, barriers, enchantment |
307| 6 | Foxglove | Fairy magic, heart magic, poison |
308| 6 | Mistletoe | Life, fertility, druidic magic |
309| 6 | Datura | Visions, insanity, spirit walking |
310| 7 | Belladonna | Poison, hallucination, witchcraft |
311| 7 | Henbane | Trance, madness, sleep, poison |
312| 7 | Mandrake | Powerful potions, curses, life magic |
313| 7 | Aconite | Werewolves, lethal poison, curses |
314
315## Inventory, items, equipment, ground drops
316
317**Status:** full
318**Spec:** 32-slot inventory, stacking, equipment slots (head, chest, legs, boots, weapon, **offhand** for shields/arrows) with a separate `equipSprite` overlay on the body, carried currency, player drops that last `groundItemDespawnDurationMs` (default 10 minutes). Pickup requires standing on the tile. Inventory is private UI state; nearby clients see ground items and worn overlays. **Equip draw order (back → front):** boots → chest → weapon → legs → hair (if visible) → head → offhand — so weapons sit above the shirt but under trousers/skirts (legs may cover shirt hem; art should avoid bad waist overlap). New characters receive world **Starter Equipment** / inventory, then creation clothing dyes on top (see **Characters**). Right-click bag items for Send / Equip / Drop / Eat (food; apples, eggs, …); paper can be written into unique **letter** instances (signed on Save; only the signer may edit). Equipping always takes **one** item from a stack (never the whole stack); unequipping returns one item and merges into an existing compatible inventory stack when stack rules allow. Equip enforces tier min-skill gates. Eating food heals (see Health skill).
319**Code:** `shared/definitions/items.js` (`EQUIPMENT_DRAW_ORDER`), `shared/appearance/hair.js` (`composeAppearanceLayers`), `shared/items/inventory.js`, `server/src/items/bags.js`, `client/src/play/inventory.js`
320
321## Proximity chat
322
323**Status:** full
324**Spec:** Enter opens a bottom chat line (max `chatMaxCharacters`, default 100). Enter trims and sends; Escape cancels. The speaker always sees their own bubble. Other players receive server-side obfuscation: full text within 8 tiles, linear falloff to silent at 16 tiles. At 0% readability the bubble is not sent.
325**Code:** `shared/speech/proximity.js`, `server/src/chat/speech.js`, `client/src/play/chat.js`, tests in `server/tests/proximity-speech.test.js`
326
327## Friends
328
329**Status:** full
330**Spec:** Character-to-character friends in `state.sqlite`. Hover shows first name; click opens inspect (full name, request/accept/remove). Requests must be accepted. Unfriend is symmetric. Incoming/outgoing lists live in the Friends panel.
331**Code:** `server/src/friends/service.js`, `server/src/persistence/stateDb.js`, `client/src/play/social.js`, tests in `server/tests/friends.test.js`
332
333## Hair & barber
334
335**Status:** full
336**Spec:** Character creation **Appearance** tab picks a hair style (per sex body folder) plus hue/saturation/darkness; live preview tints magenta hair sprites (no clothing on that tab). The **Clothing** tab shows the same body/hair with cotton shirt + legs and per-piece dyes. Hair is stored on the character and drawn as a head overlay unless headgear is worn (item defs may set `equipment.keepHair` to keep hair under a hat — none yet). Placeable **Barber** blocks reopen the hair UI to restyle (preview hides headgear).
337**Code:** `shared/appearance/hair.js`, `server/src/barber/service.js`, `client/src/play/hairControls.js`, `client/src/play/barber.js`, `client/src/play/createClothingControls.js`, `client/assets/blocks/barber/`
338
339## Bounty offices
340
341**Status:** full
342**Spec:** Placeable **Bounty Office** blocks. Interacting opens a modal with two tabs:
343
3441. **Place / raise bounty** — Search a character by first + last name. If found, show a small character preview and the **current bounty** already on that head. The player may spend **coins** from inventory to add any positive amount to that bounty (server-authoritative; coins consumed only on success).
3452. **My bounty** — Shows how much coin is currently on **your** head.
346
347**Payout on kill:** When a player who still has bounty \> 0 is **killed by another player** (attacker dealt the killing blow / engaged death), a **carrier pigeon** is dispatched from the **nearest bounty office** to the **killer's bank**, delivering a letter stating they received a bounty of **N** coins, where **N** is the **full sum** of all coin placed on the victim. Those **N** coins are **deposited immediately into the killer's bank vault** (not inventory). The victim's bounty is then reset to **0**.
348
349**Inspect UI:** Viewing another player's inspect/info modal also shows their bounty amount; if the amount is **0**, omit the bounty line entirely.
350
351**Code:** `shared/bounty/pricing.js`, `shared/definitions/tiles.js` (`BlockType.bountyOffice`), `server/src/bounty/service.js`, `server/src/courier/service.js`, `server/src/persistence/stateDb.js`, `client/src/play/bounty.js`, `client/assets/blocks/bounty-office/`, tests in `server/tests/bounty.test.js`
352
353## Banking, cheques, shops, player-driven marketplace
354
355**Status:** partial (banks/cheques/origins/NPC shops live; Central Exchange order book live)
356**Spec:** Bank blocks open bag + vault UI when used (LMB / RMB **Bank**). Click transfers between bag and vault; RMB offers Transfer all / half / one / X (or **Transfer** for stacks of 1). Vault slots are unlimited and ignore normal stack caps (except coins still cap at 999B per stack); unique-instance items such as letters never merge, even in the vault. Equipment and weapons max stack to 1 in inventory but may stack in the vault. Stacks track crafter/shop/gather origins; mixed stacks show breakdown labels and splits preserve origin quantities FIFO. Gathered ores stamp **`Mined by <name>`**; woodcutting stamps **`Felled by <name>`**. Crafted goods stamp a station verb: furnace **`Forged by`**, anvil **`Smithed by`**, woodworking **`Carved by`**, crafting bench **`Assembled by`**. NPC catalog purchases stamp **`Bought from <npc>`**; player-sold resale stock keeps the original origin (not re-stamped as shop). **Get Blank Cheques** tops inventory blanks up to 99; **Return \<n\>** discards free blanks. Blank cheques on the ground can only be picked up until inventory again holds 99; they do not count toward limits on written cheques. **Write Cheque** works anywhere (pick vault goods to reserve; Reserved tab). **Written cheques** can be sent by pigeon, sold on the marketplace, and redeemed at a bank (LMB deposit or **Redeem Cheque**) — redeemed goods go into the **vault**, not inventory. Blank cheques cannot be sent by pigeon or listed on the marketplace. Coins are a physical stackable inventory item (not a separate counter). Character delete voids that character's outstanding cheque reservations back into the vault before inheritance. **NPC shops:** Humanoid spawners (sex, equipment, sells list with optional daily quantity, buysItems, hidden discount) spawn shopkeepers. Context menu **Shop \<name\>** opens a buy panel (grid + sidebar, Buy 1/5/10/x, coin balance, bank-overflow warning). Catalog stock restocks at **00:00 server local time** (quantity 0 = infinite) and remains **ingredient-only** (`npcShopAllowed`). With **Buys items**, the NPC buys **any transferable bag item except blank cheques** (and not coins) at **80%** market; **filled cheques** sell as their reserved goods with a **5% administrative fee** (fee = ceil(5% of payout base); UI shows "`<n> coins charged as administrative fee`" while selected). Limited catalog refills first; extras hold for the day at **120%** resale until restock (non-catalog goods still absorb into bought stock). Prices use `seedValue` (pine log / tin / copper = 5) with market last-sale lerp × discount. **Central Exchange (player marketplace):** Modal with tabs **Your Orders** / **Sell** / **Buy**. Sell picks a bag item (or written cheque treated as its reserved goods with quantity locked), sets min price, and escrows the goods. Buy searches item names (Enter, max 10 hits), sets qty + max price, and escrows coins (coin-filled cheques count as funds but are spent whole only). Placing either order charges a **non-refundable 3% listing fee** (`ceil(unitPrice × quantity × 3%)`, min 1) paid immediately from bag funds. `BlockType.marketplace` wooden counters use **neighbor-connect** autotile states (`0`–`15` from N/E/S/W bitmask; generic in `shared/world/neighborConnect.js`). Counters require adjacency. **Central Exchange staff** spawner (`MobId.centralExchange`) always spawns every clerk from `CENTRAL_EXCHANGE_STAFF` (name + sex) with shared authored equipment; no shop UI. Opening a counter paths an idle clerk to the opposite side when free; closing the UI or walking away from that counter releases the clerk so wander resumes, unless another player is still using the same staff station. Hidden order book: match when `buyerMax >= sellerMin` at deterministic midpoint price; triggering player settles immediately, counterparty gets pigeon→bank cargo plus a staff-signed letter. Open orders auto-cancel after **30 days** with escrow returned to bank by pigeon and an expiry letter (listing fee is not returned). Matches update durable `item_last_sales` for shop/tooltip lerp.
357**Code:** `shared/definitions/items.js`, `shared/items/inventory.js`, `shared/items/origin.js`, `shared/items/stackRules.js`, `shared/items/marketplace.js`, `shared/market/exchange.js`, `shared/market/funds.js`, `shared/world/neighborConnect.js`, `shared/shop/pricing.js`, `shared/definitions/mobs.js`, `server/src/shop/service.js`, `server/src/market/service.js`, `server/src/simulation/spawners.js`, `client/src/play/shop.js`, `client/src/play/market.js`, `client/src/editor/tileConfigModal.js`, `server/src/items/bags.js`, `server/src/courier/service.js`, `client/src/play/inventory.js`, `client/assets/blocks/bank/`, `client/assets/blocks/marketplace/`, tests in `server/tests/bank.test.js`, `server/tests/marketplace.test.js`, `server/tests/central-exchange.test.js`, `server/tests/shop.test.js`, `server/tests/origins.test.js`
358
359## Player scripting (AFK / offline)
360
361**Status:** not implemented
362**Spec:** Full language + UI + online/AFK/offline behaviour is documented in [`docs/SCRIPTS.md`](SCRIPTS.md). Scripts are a sandboxed, server-interpreted language that emits normal player intents. Names match **exactly** (case-insensitive). `find` / nearest only searches the **visible 3×3** chunks (what a player sees). `@` variables + `set` hold targets/coords for waypoints; `go` fails beyond **2 chunks** (`Too far away.`). Universal `can <action>` dry-runs any verb. Station/cauldron state is **per player**; station slots never commit items out of the bag until craft/brew succeeds. AFK auto-start after **30 minutes** idle. Death while scripting stops the script and fully logs the instance out. Friends/barber/follow/graphics/editor are out of scope. Architecture hooks remain in design doc §18.
363**Code:** — (planned: `shared/scripts/`, `server/src/scripts/`, `client/src/play/scripts.js`, state DB script rows)