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. Code: server/src/world/coordinates.js, tests in server/tests/coordinates.test.js
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, wood, water (passable, animated; wading clips the bottom of entity sprites), and deep water (impassable, darker, animated). Live block types include stone wall, torch, bank, and church altar (respawn destination — see Player death and respawn). 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. Water tiles use a coast-foam shader on edges against non-water; entity sprites use a wade clip+foam tint that respects night darkness. Code: server/src/world/chunkData.js, shared/definitions/tiles.js, shared/definitions/tileSprites.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. Midnight restart/Git deploy is not implemented yet. 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, …), marks dirty fields, writes only those fields, and shows a settings edit log (who/when/from/to). 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, 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 passable tiles, including across chunk borders. Store a 16×16 intensity map (0–255, smoothstep falloff by tile distance). Torch range is 8 tiles. Code: server/src/lighting/baker.js, 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. Marketplace stalls wait on later economy work. 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, open/closed, per-chunk changelog, night preview slider, world-settings modal, save chunk and Apply now. Select block… opens a modal with auto-loaded tabs (Ground tiles / Blocks / Spawners — one entry per mob type with mob icon). 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. Code: server/src/characters/service.js, server/src/persistence/stateDb.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: Players receive the current chunk and eight neighbours as snapshots. 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 (snapshotFor, snapshotChunk, drainReplication), server/src/gateway/websocket.js (syncSubscriptions, publishEntity)
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. Occupied tiles block. Server commits integer tiles on the movement cadence. Code:* server/src/navigation/astar.js, server/src/simulation/workerWorld.js (#moveTo, #stepMovement)
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. Hovering another player shows their first name; clicking them inspects instead of issuing move. Code: client/src/render/worldView.js, client/src/play/main.js, client/index.html
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. Tile shade overlays sit above baked ground/block atlases. Sprites larger than 16×16 (and all mobiles) take the full darkness of their standing tile as a uniform sprite-sized shade overlay, so they are not darkened by neighbouring tile shades. Code: client/src/render/worldView.js (nightFactor, #updateShade, #placeSpriteShade), server/src/simulation/simulation.js (worldTime)
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. The first alphabetical file is the default. States are visual only; the game may set a named state (for example a door). The editor wheel cycles states; hover previews the selected tool on the target tile. Code: server/src/assets/spriteCatalog.js, shared/definitions/tileSprites.js, client/src/editor/main.js, client/src/render/worldView.js, tests in server/tests/tile-states.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: systemd + manifest-driven Git deploy. Pending world/code changes apply at server-local midnight, with an admin immediate-restart path. Crashes must not pull. Code: —
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 and rats; 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, etc.) can always fight back when attacked; 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/assets/mobs/deer/, client/assets/mobs/rat/
Mob definitions (content schema)
Status: partial Spec: Target mob content shape: displayName, maxHealth, attackSkill (one int driving hit chance and damage), drops ({ itemId, chance }[]), sells (item ID list), and dialogue trees. Dialogue nodes use trigger, lines[] ({ isPlayer, text }), and responses[] ({ trigger, text, available? } where available is an optional (ctx) => boolean). Response actions (later): start quest, give item, open trade, or start mob AI behaviour. Rendering fields (sprites, gait, flight) stay alongside gameplay fields until content tooling splits them. Code: shared/definitions/mobs.js, shared/definitions/mobCombat.js
Quests
Status: not implemented Spec: Quests are obtained from friendly mobs (dialogue action). Each quest has ordered progression states that advance when the player completes a requirement: obtain an item, fire a dialogue trigger, kill a quota of mobs, reach a tile, or interact with a block. Completion may award skill XP and items; if inventory is full, overflow items are sent to the character vault by carrier pigeon. Code: —
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 in shared/definitions/spells.js. Full casting UI, LOS, and effect system remain later. Code: shared/combat/rolls.js (physical, live), shared/combat/magic.js (cast + damage rules, shared only), shared/definitions/spells.js, shared/definitions/attackTypes.js, shared/equipment/stats.js, server/src/combat/service.js, tests in server/tests/combatRolls.test.js, server/tests/magic.test.js, server/tests/equipment.test.js
Combat, skills, groups, pigeons
Status: partial 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, mob HP bars, and client dynamic-light hooks. Fightable mobs retaliate when attacked and keep pursuing if the player cancels attack. Physical combat uses skill rolls (see Combat resolution). Health skill sets max HP; taking damage awards Health XP equal to damage taken. 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. Ranged combat, magic, groups, and non-combat skill XP (except Health from damage) remain later. Code:* shared/combat/rolls.js, shared/skills/progression.js, shared/skills/state.js, shared/definitions/skills.js, shared/definitions/mobCombat.js, server/src/skills/service.js, server/src/combat/service.js, client/src/play/skills.js, client/src/render/worldView.js, tests in server/tests/combatRolls.test.js, server/tests/skills.test.js, server/tests/mobCombat.test.js (+ combat/follow/courier 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 still use TIER_STAT_BONUS. Tools (pickaxes) gate on Mining. Coal is a gather material (dark gray tint, iron-tier mine gate) with no bar of its own. Shared sprites + magenta tint: one base sprite per shape (ore, bar, pickaxe, boulder-ore); tintable pixels use magenta rules in shared/render/tint.js. Boulder ore states are catalog aliases of boulder-ore.png with per-material tint. TODO: full combat gear catalog; woodcutting wood tiers; tooltips. Code: shared/definitions/materialTiers.js, shared/render/tint.js, shared/definitions/metalItems.js, shared/equipment/stats.js, tests in server/tests/equipment.test.js, server/tests/mining.test.js, server/tests/tint.test.js
Gathering, crafting, and production skills
Status: partial (mining + smelting live) Spec: Mining: LMB/RMB on ore boulder (states bronze-ore … dragon-ore, coal). Requires equipped pickaxe with tool rank ≥ resource rank and Mining ≥ mine gate. Duration (rank×8s) − (toolRank×3s) (min 0.5s). Attack shove animation, no swipe FX. Awards Mining XP (rank×5). On success the node becomes exhausted (plain boulder sprite, not mineable) for 10s × material rank, then restores its ore state via runtime CHUNK_DELTA. Smelting: furnace block opens craft UI; recipes 1 ore → 1 bar except steel = 1 iron ore + 1 coal. Smithing XP on success. Server-authoritative START_CRAFT / timer. Woodcutting / fishing / other stations later. Code: shared/definitions/gathering.js, server/src/gathering/service.js, server/src/crafting/service.js, shared/crafting/stationRecipes.js, client/src/play/main.js, client/src/render/worldView.js (spawnGatherSwing), tests in server/tests/mining.test.js
Crafting stations
Status: partial (furnace smelting live; UI shell for others) Spec: Furnace block (placeholder sprite) + adjacency craft panel. Recipes in stationRecipes.js. Server craft timer = CRAFT_DURATION_MS (2s). Other stations still UI/dev only (__craftDev). TODO: anvil smithing recipes, oven/campfire burn, spinning wheel once sheep exist. Code: shared/definitions/craftingStations.js, shared/definitions/tiles.js (BlockType.furnace), 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 with walk gait regenerates 1 stamina per second. At 0 stamina, run gait is forced back to walk; you cannot toggle run until stamina recovers. Client shows a vertical stamina bar 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 (scaffolding) Spec: Herbalism gathers herbs from herb nodes with plant clippers (tiers like mining/woodcutting; gather loop TBD). Alchemy uses herbs at a Cauldron block. Nonstandard brew UI (slots, stir/heat/cool, bottle, clear, save recipe). See prior alchemy notes for recipe/unstable potion rules. Code: shared/definitions/alchemy.js, server/src/alchemy/service.js, client/src/play/alchemy.js, tests in server/tests/alchemy.test.js
Inventory, items, equipment, ground drops
Status: full Spec: 32-slot inventory, stacking, equipment slots (head, chest, legs, boots, weapon, offhand for shields) 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. New characters start with paper, apples, a stick, a cloth shirt, and coins. Placeholder item/equipment PNGs until real art exists. Right-click bag items for Send / Equip / Drop / Eat (food); 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, 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
Bounty offices
Status: not implemented Spec: Placeable Bounty Office blocks (sprite/form TBD). Interacting opens a modal with two tabs:
1. Place / raise bounty — Search a character by 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, 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.
TODO: block type + art, modal UI, character search reuse, persistent bounty ledger per character, coin add intent, nearest-office pigeon on PvP kill, vault deposit + letter body, inspect bounty line, tests. Code: —
Banking, cheques, shops, player-driven marketplace
Status: partial 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 origins; mixed stacks show breakdown labels and splits preserve origin quantities FIFO. 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 and the player marketplace UI remain later; marketplace sell rules for cheques are already enforced in shared item definitions. Code: shared/definitions/items.js, shared/items/inventory.js, shared/items/origin.js, shared/items/stackRules.js, shared/items/marketplace.js, server/src/items/bags.js, server/src/courier/service.js, client/src/play/inventory.js, client/assets/blocks/bank/, tests in server/tests/bank.test.js, server/tests/marketplace.test.js, server/tests/origins.test.js
Player scripting hooks
Status: not implemented Spec: Reserved control abstraction; not in the initial release. Code: —
Source
| 1 | # Feature implementation tracker |
| 2 | |
| 3 | Living companion to `tile_mmo_server_technical_design_v0.6.md`. |
| 4 | Statuses: **not implemented** · **partial** · **full**. |
| 5 | |
| 6 | 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. |
| 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. |
| 14 | **Code:** `server/src/world/coordinates.js`, tests in `server/tests/coordinates.test.js` |
| 15 | |
| 16 | ## Ground and block tile layers |
| 17 | |
| 18 | **Status:** full |
| 19 | **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, wood, **water** (passable, animated; wading clips the bottom of entity sprites), and **deep water** (impassable, darker, animated). Live block types include stone wall, torch, bank, and **church altar** (respawn destination — see **Player death and respawn**). 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. Water tiles use a coast-foam shader on edges against non-water; entity sprites use a wade clip+foam tint that respects night darkness. |
| 20 | **Code:** `server/src/world/chunkData.js`, `shared/definitions/tiles.js`, `shared/definitions/tileSprites.js`, `server/src/assets/spriteCatalog.js`, `client/src/render/worldView.js`, `client/src/render/chunkBake.js` |
| 21 | |
| 22 | ## Open and closed chunks |
| 23 | |
| 24 | **Status:** full |
| 25 | **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. |
| 26 | **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`) |
| 27 | |
| 28 | ## ECS registry and components |
| 29 | |
| 30 | **Status:** full |
| 31 | **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. |
| 32 | **Code:** `server/src/ecs/world.js`, `server/src/ecs/serialize.js`, `server/src/ecs/components.js` |
| 33 | |
| 34 | ## Simulation tick |
| 35 | |
| 36 | **Status:** full |
| 37 | **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. |
| 38 | **Code:** `server/src/simulation/simulation.js` (`step`), `server/src/index.js` |
| 39 | |
| 40 | ## Authored world and runtime state persistence |
| 41 | |
| 42 | **Status:** full |
| 43 | **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. |
| 44 | **Code:** `server/src/persistence/database.js`, `worldDb.js`, `stateDb.js` |
| 45 | |
| 46 | ## World revisions and pending editor saves |
| 47 | |
| 48 | **Status:** partial |
| 49 | **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. Midnight restart/Git deploy is not implemented yet. |
| 50 | **Code:** `server/src/persistence/worldDb.js` (`ensurePendingRevision`, `promotePendingRevision`) |
| 51 | |
| 52 | ## World settings |
| 53 | |
| 54 | **Status:** full |
| 55 | **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, …), marks dirty fields, writes only those fields, and shows a settings edit log (who/when/from/to). 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. |
| 56 | **Code:** `shared/definitions/worldSettings.js`, `server/src/persistence/worldDb.js` (`world_live_settings`, `world_settings_edit_log`), `server/src/editor/service.js` (`loadSettings`, `saveSettings`), `client/src/editor/settingsModal.js` |
| 57 | |
| 58 | ## Baked lighting |
| 59 | |
| 60 | **Status:** full |
| 61 | **Spec:** On chunk save, raycast light from blocks with `lightRangeTiles` through passable tiles, including across chunk borders. Store a 16×16 intensity map (0–255, smoothstep falloff by tile distance). Torch range is 8 tiles. |
| 62 | **Code:** `server/src/lighting/baker.js`, tests in `server/tests/lighting.test.js` |
| 63 | |
| 64 | ## World editor (server) |
| 65 | |
| 66 | **Status:** full |
| 67 | **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. Marketplace stalls wait on later economy work. |
| 68 | **Code:** `server/src/editor/service.js` |
| 69 | |
| 70 | ## World editor (client) |
| 71 | |
| 72 | **Status:** full |
| 73 | **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, open/closed, per-chunk changelog, night preview slider, world-settings modal, save chunk and Apply now. **Select block…** opens a modal with auto-loaded tabs (Ground tiles / Blocks / Spawners — one entry per mob type with mob icon). 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. |
| 74 | **Code:** `client/editor.html`, `client/src/editor/main.js`, `client/src/editor/paletteModal.js`, `client/src/editor/tileConfigModal.js`, `client/ui/editor.css` |
| 75 | |
| 76 | ## Per-chunk changelog |
| 77 | |
| 78 | **Status:** full |
| 79 | **Spec:** Each save stores who, when, and structured bullets of ground/block/spawner/open-closed diffs. |
| 80 | **Code:** `server/src/editor/service.js` (`diffChunks`), `server/src/persistence/worldDb.js` (`world_chunk_edit_log`), tests in `server/tests/editor-diff.test.js` |
| 81 | |
| 82 | ## WebSocket gateway |
| 83 | |
| 84 | **Status:** full |
| 85 | **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. |
| 86 | **Code:** `server/src/gateway/websocket.js`, `server/src/gateway/http.js`, `server/src/index.js` |
| 87 | |
| 88 | ## Stub authentication |
| 89 | |
| 90 | **Status:** full |
| 91 | **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. |
| 92 | **Code:** `server/src/auth/stub.js` |
| 93 | |
| 94 | ## Characters |
| 95 | |
| 96 | **Status:** full |
| 97 | **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. |
| 98 | **Code:** `server/src/characters/service.js`, `server/src/persistence/stateDb.js` |
| 99 | |
| 100 | ## Character deletion and inheritance |
| 101 | |
| 102 | **Status:** full |
| 103 | **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. |
| 104 | **Code:** `server/src/characters/service.js`, `server/src/persistence/stateDb.js` (`account_inheritance`) |
| 105 | |
| 106 | ## 3×3 chunk replication |
| 107 | |
| 108 | **Status:** full |
| 109 | **Spec:** Players receive the current chunk and eight neighbours as snapshots. 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. |
| 110 | **Code:** `server/src/simulation/simulation.js` (`snapshotFor`, `snapshotChunk`, `drainReplication`), `server/src/gateway/websocket.js` (`syncSubscriptions`, `publishEntity`) |
| 111 | |
| 112 | ## Click-to-move and A\* pathfinding |
| 113 | |
| 114 | **Status:** full |
| 115 | **Spec:** `MOVE_TO` runs A\* over the visible 3×3 using block passability and open-chunk bounds. Occupied tiles block. Server commits integer tiles on the movement cadence. |
| 116 | **Code:** `server/src/navigation/astar.js`, `server/src/simulation/workerWorld.js` (`#moveTo`, `#stepMovement`) |
| 117 | |
| 118 | ## Global walk/run cadence |
| 119 | |
| 120 | **Status:** full |
| 121 | **Spec:** Walk 2 tiles/s, run double. Movement ticks at run rate. `SetGait` chooses every-other vs every movement tick. |
| 122 | **Code:** `server/src/simulation/workerWorld.js` (`#stepMovement`, `#setGait`) |
| 123 | |
| 124 | ## Client movement interpolation |
| 125 | |
| 126 | **Status:** full |
| 127 | **Spec:** Client lerps sprites between replicated tiles over the walk or run interval from world settings. |
| 128 | **Code:** `client/src/render/worldView.js` (`moveEntity`, `update`) |
| 129 | |
| 130 | ## Play viewport and camera |
| 131 | |
| 132 | **Status:** full |
| 133 | **Spec:** Camera stays centered on the local player. Scroll-wheel zoom is viewport-only (1×–4×) and does not change server visibility. Hovering another player shows their first name; clicking them inspects instead of issuing move. |
| 134 | **Code:** `client/src/render/worldView.js`, `client/src/play/main.js`, `client/index.html` |
| 135 | |
| 136 | ## Night shading |
| 137 | |
| 138 | **Status:** full |
| 139 | **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. Tile shade overlays sit above baked ground/block atlases. Sprites larger than 16×16 (and all mobiles) take the full darkness of their standing tile as a uniform sprite-sized shade overlay, so they are not darkened by neighbouring tile shades. |
| 140 | **Code:** `client/src/render/worldView.js` (`nightFactor`, `#updateShade`, `#placeSpriteShade`), `server/src/simulation/simulation.js` (`worldTime`) |
| 141 | |
| 142 | ## FrameworkV3 client bootstrap |
| 143 | |
| 144 | **Status:** full |
| 145 | **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. |
| 146 | **Code:** `.gitmodules`, `client/frameworkv3`, `client/scripts/build-framework.mjs` |
| 147 | |
| 148 | ## Sprite size, pivot and Y-sort |
| 149 | |
| 150 | **Status:** full |
| 151 | **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. |
| 152 | **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` |
| 153 | |
| 154 | ## Visual tile states |
| 155 | |
| 156 | **Status:** full |
| 157 | **Spec:** Each ground and block type has a folder of PNG states. The first alphabetical file is the default. States are visual only; the game may set a named state (for example a door). The editor wheel cycles states; hover previews the selected tool on the target tile. |
| 158 | **Code:** `server/src/assets/spriteCatalog.js`, `shared/definitions/tileSprites.js`, `client/src/editor/main.js`, `client/src/render/worldView.js`, tests in `server/tests/tile-states.test.js` |
| 159 | |
| 160 | ## Region workers and cross-worker transfer |
| 161 | |
| 162 | **Status:** full |
| 163 | **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. |
| 164 | **Code:** `server/src/simulation/simulation.js`, `workerWorld.js`, `inProcessWorker.js`, `threadWorker.js`, tests in `server/tests/worker-*.test.js` |
| 165 | |
| 166 | ## ChunkLoader activation and unload persistence |
| 167 | |
| 168 | **Status:** full |
| 169 | **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. |
| 170 | **Code:** `server/src/simulation/chunkLoader.js`, `server/src/simulation/simulation.js`, `server/src/persistence/stateDb.js` (`persistent_entities`) |
| 171 | |
| 172 | ## Midnight restart and Git deploy |
| 173 | |
| 174 | **Status:** full |
| 175 | **Spec:** systemd + manifest-driven Git deploy. Pending world/code changes apply at server-local midnight, with an admin immediate-restart path. Crashes must not pull. |
| 176 | **Code:** — |
| 177 | |
| 178 | ## Spawners |
| 179 | |
| 180 | **Status:** full |
| 181 | **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 and rats; 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, etc.) can always fight back when attacked; courier pigeons cannot. |
| 182 | **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/assets/mobs/deer/`, `client/assets/mobs/rat/` |
| 183 | |
| 184 | ## Mob definitions (content schema) |
| 185 | |
| 186 | **Status:** partial |
| 187 | **Spec:** Target mob content shape: `displayName`, `maxHealth`, `attackSkill` (one int driving hit chance and damage), `drops` (`{ itemId, chance }[]`), `sells` (item ID list), and `dialogue` trees. Dialogue nodes use `trigger`, `lines[]` (`{ isPlayer, text }`), and `responses[]` (`{ trigger, text, available? }` where `available` is an optional `(ctx) => boolean`). Response actions (later): start quest, give item, open trade, or start mob AI behaviour. Rendering fields (sprites, gait, flight) stay alongside gameplay fields until content tooling splits them. |
| 188 | **Code:** `shared/definitions/mobs.js`, `shared/definitions/mobCombat.js` |
| 189 | |
| 190 | ## Quests |
| 191 | |
| 192 | **Status:** not implemented |
| 193 | **Spec:** Quests are obtained from friendly mobs (dialogue action). Each quest has ordered progression states that advance when the player completes a requirement: obtain an item, fire a dialogue trigger, kill a quota of mobs, reach a tile, or interact with a block. Completion may award skill XP and items; if inventory is full, overflow items are sent to the character vault by carrier pigeon. |
| 194 | **Code:** — |
| 195 | |
| 196 | ## Character logout resume |
| 197 | |
| 198 | **Status:** full |
| 199 | **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. |
| 200 | **Code:** `server/src/simulation/simulation.js` (`spawnCharacter`, `despawnCharacter`), tests in `server/tests/character-resume.test.js` |
| 201 | |
| 202 | ## Combat resolution (rolls) |
| 203 | |
| 204 | **Status:** partial |
| 205 | **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 in `shared/definitions/spells.js`. Full casting UI, LOS, and effect system remain later. |
| 206 | **Code:** `shared/combat/rolls.js` (physical, live), `shared/combat/magic.js` (cast + damage rules, shared only), `shared/definitions/spells.js`, `shared/definitions/attackTypes.js`, `shared/equipment/stats.js`, `server/src/combat/service.js`, tests in `server/tests/combatRolls.test.js`, `server/tests/magic.test.js`, `server/tests/equipment.test.js` |
| 207 | |
| 208 | ## Combat, skills, groups, pigeons |
| 209 | |
| 210 | **Status:** partial |
| 211 | **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, mob HP bars, and client dynamic-light hooks. Fightable mobs retaliate when attacked and keep pursuing if the player cancels attack. Physical combat uses skill rolls (see **Combat resolution**). **Health** skill sets max HP; taking damage awards Health XP equal to damage taken. 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. Ranged combat, magic, groups, and non-combat skill XP (except Health from damage) remain later. |
| 212 | **Code:** `shared/combat/rolls.js`, `shared/skills/progression.js`, `shared/skills/state.js`, `shared/definitions/skills.js`, `shared/definitions/mobCombat.js`, `server/src/skills/service.js`, `server/src/combat/service.js`, `client/src/play/skills.js`, `client/src/render/worldView.js`, tests in `server/tests/combatRolls.test.js`, `server/tests/skills.test.js`, `server/tests/mobCombat.test.js` (+ combat/follow/courier tests) |
| 213 | |
| 214 | ## Player death and respawn |
| 215 | |
| 216 | **Status:** full |
| 217 | **Spec:** When a **player** reaches **0 HP**, they **die** immediately (authoritative on the server): |
| 218 | |
| 219 | 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). |
| 220 | 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. |
| 221 | 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). |
| 222 | 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). |
| 223 | 5. After respawn the player is restored to **full Health** and **full Stamina** (max from skills), cleared of death state, and may fight again. |
| 224 | |
| 225 | **TODO:** Revisit player-loot penalties if PK rules are added. |
| 226 | **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` |
| 227 | |
| 228 | ## Equipment tiers and worn stat bonuses |
| 229 | |
| 230 | **Status:** partial |
| 231 | **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 still use `TIER_STAT_BONUS`. Tools (pickaxes) gate on Mining. Coal is a gather material (dark gray tint, iron-tier mine gate) with no bar of its own. |
| 232 | **Shared sprites + magenta tint:** one base sprite per shape (ore, bar, pickaxe, boulder-ore); tintable pixels use magenta rules in `shared/render/tint.js`. Boulder ore states are catalog aliases of `boulder-ore.png` with per-material tint. |
| 233 | **TODO:** full combat gear catalog; woodcutting wood tiers; tooltips. |
| 234 | **Code:** `shared/definitions/materialTiers.js`, `shared/render/tint.js`, `shared/definitions/metalItems.js`, `shared/equipment/stats.js`, tests in `server/tests/equipment.test.js`, `server/tests/mining.test.js`, `server/tests/tint.test.js` |
| 235 | |
| 236 | ## Gathering, crafting, and production skills |
| 237 | |
| 238 | **Status:** partial (mining + smelting live) |
| 239 | **Spec:** **Mining:** LMB/RMB on ore boulder (states `bronze-ore` … `dragon-ore`, `coal`). Requires equipped pickaxe with tool rank ≥ resource rank and Mining ≥ mine gate. Duration `(rank×8s) − (toolRank×3s)` (min 0.5s). Attack shove animation, **no** swipe FX. Awards Mining XP (`rank×5`). On success the node becomes **exhausted** (plain `boulder` sprite, not mineable) for `10s × material rank`, then restores its ore state via runtime `CHUNK_DELTA`. **Smelting:** furnace block opens craft UI; recipes 1 ore → 1 bar except **steel** = 1 iron ore + 1 coal. Smithing XP on success. Server-authoritative `START_CRAFT` / timer. Woodcutting / fishing / other stations later. |
| 240 | **Code:** `shared/definitions/gathering.js`, `server/src/gathering/service.js`, `server/src/crafting/service.js`, `shared/crafting/stationRecipes.js`, `client/src/play/main.js`, `client/src/render/worldView.js` (`spawnGatherSwing`), tests in `server/tests/mining.test.js` |
| 241 | |
| 242 | ## Crafting stations |
| 243 | |
| 244 | **Status:** partial (furnace smelting live; UI shell for others) |
| 245 | **Spec:** Furnace block (placeholder sprite) + adjacency craft panel. Recipes in `stationRecipes.js`. Server craft timer = `CRAFT_DURATION_MS` (2s). Other stations still UI/dev only (`__craftDev`). |
| 246 | **TODO:** anvil smithing recipes, oven/campfire burn, spinning wheel once sheep exist. |
| 247 | **Code:** `shared/definitions/craftingStations.js`, `shared/definitions/tiles.js` (`BlockType.furnace`), `server/src/crafting/service.js`, `client/src/play/crafting.js` |
| 248 | |
| 249 | ## Stamina and running |
| 250 | |
| 251 | **Status:** full |
| 252 | **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 with walk gait regenerates **1 stamina per second**. At 0 stamina, run gait is forced back to walk; you cannot toggle run until stamina recovers. Client shows a vertical stamina bar bottom-right. |
| 253 | **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` |
| 254 | |
| 255 | ## Alchemy / cauldron |
| 256 | |
| 257 | **Status:** partial (scaffolding) |
| 258 | **Spec:** **Herbalism** gathers herbs from herb nodes with **plant clippers** (tiers like mining/woodcutting; gather loop TBD). **Alchemy** uses herbs at a **Cauldron** block. Nonstandard brew UI (slots, stir/heat/cool, bottle, clear, save recipe). See prior alchemy notes for recipe/unstable potion rules. |
| 259 | **Code:** `shared/definitions/alchemy.js`, `server/src/alchemy/service.js`, `client/src/play/alchemy.js`, tests in `server/tests/alchemy.test.js` |
| 260 | |
| 261 | ## Inventory, items, equipment, ground drops |
| 262 | |
| 263 | **Status:** full |
| 264 | **Spec:** 32-slot inventory, stacking, equipment slots (head, chest, legs, boots, weapon, **offhand** for shields) 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. New characters start with paper, apples, a stick, a cloth shirt, and coins. Placeholder item/equipment PNGs until real art exists. Right-click bag items for Send / Equip / Drop / Eat (food); 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). |
| 265 | **Code:** `shared/definitions/items.js`, `shared/items/inventory.js`, `server/src/items/bags.js`, `client/src/play/inventory.js` |
| 266 | |
| 267 | ## Proximity chat |
| 268 | |
| 269 | **Status:** full |
| 270 | **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. |
| 271 | **Code:** `shared/speech/proximity.js`, `server/src/chat/speech.js`, `client/src/play/chat.js`, tests in `server/tests/proximity-speech.test.js` |
| 272 | |
| 273 | ## Friends |
| 274 | |
| 275 | **Status:** full |
| 276 | **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. |
| 277 | **Code:** `server/src/friends/service.js`, `server/src/persistence/stateDb.js`, `client/src/play/social.js`, tests in `server/tests/friends.test.js` |
| 278 | |
| 279 | ## Bounty offices |
| 280 | |
| 281 | **Status:** not implemented |
| 282 | **Spec:** Placeable **Bounty Office** blocks (sprite/form TBD). Interacting opens a modal with two tabs: |
| 283 | |
| 284 | 1. **Place / raise bounty** — Search a character by 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). |
| 285 | 2. **My bounty** — Shows how much coin is currently on **your** head. |
| 286 | |
| 287 | **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**, 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**. |
| 288 | |
| 289 | **Inspect UI:** Viewing another player's inspect/info modal also shows their bounty amount; if the amount is **0**, omit the bounty line entirely. |
| 290 | |
| 291 | **TODO:** block type + art, modal UI, character search reuse, persistent bounty ledger per character, coin add intent, nearest-office pigeon on PvP kill, vault deposit + letter body, inspect bounty line, tests. |
| 292 | **Code:** — |
| 293 | |
| 294 | ## Banking, cheques, shops, player-driven marketplace |
| 295 | |
| 296 | **Status:** partial |
| 297 | **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 origins; mixed stacks show breakdown labels and splits preserve origin quantities FIFO. **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 and the player marketplace UI remain later; marketplace sell rules for cheques are already enforced in shared item definitions. |
| 298 | **Code:** `shared/definitions/items.js`, `shared/items/inventory.js`, `shared/items/origin.js`, `shared/items/stackRules.js`, `shared/items/marketplace.js`, `server/src/items/bags.js`, `server/src/courier/service.js`, `client/src/play/inventory.js`, `client/assets/blocks/bank/`, tests in `server/tests/bank.test.js`, `server/tests/marketplace.test.js`, `server/tests/origins.test.js` |
| 299 | |
| 300 | ## Player scripting hooks |
| 301 | |
| 302 | **Status:** not implemented |
| 303 | **Spec:** Reserved control abstraction; not in the initial release. |
| 304 | **Code:** — |