BlueGit

timfa questward

Files

questward / docs / FEATURES.md

FEATURES.md

FEATURES.md 28.4 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. 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. First-version types are grass, wood, stone wall, and torch. 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 stay individual sprites so mobiles can Y-sort behind them. 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 (including spawners and banks), 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. Spawner paint uses mob type, max alive and range; bank is a placeable block. Placeholder sprites stand in until real art exists. Code: client/editor.html, client/src/editor/main.js, client/ui/editor.css

Per-chunk changelog

Status: full Spec: Each save stores who, when, and structured bullets of ground/block/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: not implemented 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: Spawner blocks with mob type, max alive, and range. They fire only in open, simulating chunks. Spawned mobs get SpawnOrigin; persistence follows the mob definition (deer are not persistent). Wildlife options are deer and rats. 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, shared/definitions/mobs.js, shared/definitions/mobCombat.js, client/assets/blocks/spawner/, 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. 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; 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)

Equipment tiers and worn stat bonuses

Status: partial Spec: Metal gear exists in six material tiers (lowest → highest): Bronze, Iron, Steel, Mithril, Adamantium, Orichalcum. Bronze has no extra gate (min relevant skill 1). Every higher tier requires a minimum level of the item's relevant skill (weapons → their hit skill e.g. Sword fighting; metal armour & shields → Defence; bows → Archery; wizard cloth & staves → Magic; gathering tools → Woodcutting / Mining / Fishing). Tier min levels and per-tier stat bonuses live in shared/definitions/materialTiers.js. Worn items add flat bonuses to effective combat stats (not base skill XP): metal weapons & clubs → Strength; metal armour & shields → Defence; bows → Dexterity; wizard cloth → Magic; staves → Mind; leather armour → Dexterity (Agility); cloth armour → Defence. Item defs carry equipment.tier, equipment.kind, optional equipment.bonus override, and attack.attackType. Equip checks enforce min skill; combat rolls use shared/equipment/stats.js. TODO: full tiered item catalog (all metals, bows, shields, wizard sets, leather, tools); placeholder art per tier; client tooltip showing reqs/bonuses. Code: shared/definitions/materialTiers.js, shared/definitions/equipmentKinds.js, shared/definitions/attackTypes.js, shared/equipment/stats.js, shared/definitions/items.js (stick, cloth shirt), server/src/items/bags.js, server/src/combat/service.js, tests in server/tests/equipment.test.js

Gathering, crafting, and production skills

Status: not implemented Spec: Skill IDs exist for Woodcutting, Mining, Fishing, Smithing, Crafting, Leatherworking, Tailoring, and Cooking. Axes (Woodcutting) and pickaxes (Mining) are tools, not melee weapons — tier sets min Woodcutting/Mining to equip; better tools gather faster. Fishing rods and nets use Fishing. Smithing crafts metal items (min Smithing per recipe). Crafting makes misc items (e.g. arrows from smithed tips). Leatherworking makes leather armour (Dexterity bonus, not Defence). Tailoring makes cloth armour; separate wizard cloth tiers grant Magic bonus. Cooking prepares raw food at ovens and campfires (see Crafting stations). Gathering attempts always succeed when in range; non-cooking crafts always succeed when skill ≥ recipe min. Resources have a minimum tier (tool tier must meet or exceed). Leather needs no tool — drops from certain mobs. TODO: resource nodes (trees, ores, fish spots), gather commands, recipe data files, tool/item sprites, gather speed formula, mob leather drops, sheep shearing. Craft UI is specified under Crafting stations. Code: shared/definitions/skills.js (skill IDs + panel entries only)

Crafting stations

Status: UI shell + item/recipe scaffolding; server crafting not implemented Spec: Recipes run at a station adjacent to or under the player (exact interaction radius TBD). Station IDs and linked skills live in shared/definitions/craftingStations.js.

StationRoleSkill
FurnaceSmelt gathered ore → barsSmithing
Spinning wheelWool → thread (wool from shorn sheep — sheep/WIP)Tailoring
LoomWeave cloth clothingTailoring
AnvilSmith metal items from barsSmithing
Leatherworking stationCraft leather goodsLeatherworking
Crafting benchGeneral Crafting (e.g. arrows + tips)Crafting
OvenCook raw meatCooking
Fireplace (campfire)Same cooking as ovenCooking

Cooking: Requires Cooking ≥ recipe minimum or the attempt can burn the food (lost). Oven uses a lower burn chance than fireplace for the same recipe/skill gap.

Fireplace (portable): Drop a log on the ground; right-click the log → Start Fire while carrying a tinderbox in inventory (consumes tinderbox use TBD). Creates a shared campfire on that tile for 10 minutes (FIREPLACE_DURATION_MS). Any player may cook at it. At most one fireplace per tile. Fixed oven blocks are separate placeables (editor/content later).

Station UI (shared across all stations): Opening a station shows a recipe grid on the left — each cell is the output item icon with display name underneath. Clicking a recipe selects it; the detail pane on the right repeats the icon and name, lists required materials (icon + quantity per input), and a Craft button. Crafting is blocked unless the server confirms room for the product: canCraftFitInventory() simulates consuming inputs first, then inserting the output, so freed slots from spent materials count toward space (shared/crafting/recipes.js). While crafting, a 2 s progress bar runs (CRAFT_DURATION_MS) for every recipe regardless of item. Only one craft at a time per player; closing the panel cancels in-progress craft (sends CANCEL_CRAFT). Cooking stations use the same shell; burn failure is an outcome after the timer, not a separate UI.

Item scaffolding: Reserved IDs and stub definitions for gathering/crafting content live in shared/definitions/craftingItems.js (CraftingItemId, CRAFTING_ITEM_STUBS merged into ITEM_DEFINITIONS). Replace stubs with full defs (sprites, equipment, tiers) as rules land. Recipe rows go in shared/crafting/stationRecipes.js (CRAFT_RECIPES); filter with recipesForStation().

Dev: In the browser console, __craftDev() opens the crafting bench UI; pass any CraftingStationId string for other stations.

TODO: station block/entity types and sprites, real recipe tables per station, open/close from world interaction, server craft command + timer + adjacency checks, Cooking burn formula, log/tinderbox behaviour, campfire ground entity lifecycle & replication, spinning wheel wool input once sheep exist. Code: shared/definitions/craftingStations.js, shared/definitions/craftingItems.js, shared/definitions/itemCategories.js, shared/crafting/recipes.js, shared/crafting/stationRecipes.js, client/src/play/crafting.js, client/ui/play.css (#craft-panel)

Stamina and running

Status: not implemented Spec: Stamina skill sets max stamina (= skill level). Each stamina point equals one second of running. Running consumes stamina; running awards Stamina XP. Walking does not consume stamina. TODO: stamina component sync, run gate when empty, regen rules, Stamina XP on run ticks, client stamina bar. Code: shared/definitions/skills.js (playerMaxStamina helper only)

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

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
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.
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. First-version types are grass, wood, stone wall, and torch. **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 stay individual sprites so mobiles can Y-sort behind them.
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 (including spawners and banks), 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. Spawner paint uses mob type, max alive and range; bank is a placeable block. Placeholder sprites stand in until real art exists.
74**Code:** `client/editor.html`, `client/src/editor/main.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/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:** not implemented
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:** Spawner blocks with mob type, max alive, and range. They fire only in open, simulating chunks. Spawned mobs get `SpawnOrigin`; persistence follows the mob definition (deer are not persistent). Wildlife options are deer and rats. 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`, `shared/definitions/mobs.js`, `shared/definitions/mobCombat.js`, `client/assets/blocks/spawner/`, `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. 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; 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## Equipment tiers and worn stat bonuses
215
216**Status:** partial
217**Spec:** Metal gear exists in six material tiers (lowest → highest): **Bronze**, **Iron**, **Steel**, **Mithril**, **Adamantium**, **Orichalcum**. Bronze has no extra gate (min relevant skill 1). Every higher tier requires a minimum level of the item's **relevant skill** (weapons → their hit skill e.g. Sword fighting; metal armour & shields → Defence; bows → Archery; wizard cloth & staves → Magic; gathering tools → Woodcutting / Mining / Fishing). Tier min levels and per-tier stat bonuses live in `shared/definitions/materialTiers.js`. Worn items add flat bonuses to **effective** combat stats (not base skill XP): metal weapons & clubs → Strength; metal armour & shields → Defence; bows → Dexterity; wizard cloth → Magic; staves → Mind; leather armour → Dexterity (Agility); cloth armour → Defence. Item defs carry `equipment.tier`, `equipment.kind`, optional `equipment.bonus` override, and `attack.attackType`. Equip checks enforce min skill; combat rolls use `shared/equipment/stats.js`. **TODO:** full tiered item catalog (all metals, bows, shields, wizard sets, leather, tools); placeholder art per tier; client tooltip showing reqs/bonuses.
218**Code:** `shared/definitions/materialTiers.js`, `shared/definitions/equipmentKinds.js`, `shared/definitions/attackTypes.js`, `shared/equipment/stats.js`, `shared/definitions/items.js` (stick, cloth shirt), `server/src/items/bags.js`, `server/src/combat/service.js`, tests in `server/tests/equipment.test.js`
219
220## Gathering, crafting, and production skills
221
222**Status:** not implemented
223**Spec:** Skill IDs exist for **Woodcutting**, **Mining**, **Fishing**, **Smithing**, **Crafting**, **Leatherworking**, **Tailoring**, and **Cooking**. **Axes** (Woodcutting) and **pickaxes** (Mining) are tools, not melee weapons — tier sets min Woodcutting/Mining to equip; better tools gather faster. **Fishing rods** and **nets** use Fishing. **Smithing** crafts metal items (min Smithing per recipe). **Crafting** makes misc items (e.g. arrows from smithed tips). **Leatherworking** makes leather armour (Dexterity bonus, not Defence). **Tailoring** makes cloth armour; separate **wizard cloth** tiers grant Magic bonus. **Cooking** prepares raw food at ovens and campfires (see **Crafting stations**). Gathering attempts always succeed when in range; non-cooking crafts always succeed when skill ≥ recipe min. Resources have a **minimum tier** (tool tier must meet or exceed). **Leather** needs no tool — drops from certain mobs. **TODO:** resource nodes (trees, ores, fish spots), gather commands, recipe data files, tool/item sprites, gather speed formula, mob leather drops, sheep shearing. Craft UI is specified under **Crafting stations**.
224**Code:** `shared/definitions/skills.js` (skill IDs + panel entries only)
225
226## Crafting stations
227
228**Status:** UI shell + item/recipe scaffolding; server crafting not implemented
229**Spec:** Recipes run at a **station** adjacent to or under the player (exact interaction radius TBD). Station IDs and linked skills live in `shared/definitions/craftingStations.js`.
230
231| Station | Role | Skill |
232| --- | --- | --- |
233| **Furnace** | Smelt gathered **ore → bars** | Smithing |
234| **Spinning wheel** | **Wool → thread** (wool from shorn sheep — sheep/WIP) | Tailoring |
235| **Loom** | Weave **cloth clothing** | Tailoring |
236| **Anvil** | Smith **metal items** from bars | Smithing |
237| **Leatherworking station** | Craft **leather** goods | Leatherworking |
238| **Crafting bench** | General **Crafting** (e.g. arrows + tips) | Crafting |
239| **Oven** | Cook **raw meat** | Cooking |
240| **Fireplace (campfire)** | Same cooking as oven | Cooking |
241
242**Cooking:** Requires Cooking ≥ recipe minimum or the attempt can **burn** the food (lost). **Oven** uses a lower burn chance than **fireplace** for the same recipe/skill gap.
243
244**Fireplace (portable):** Drop a **log** on the ground; **right-click the log → Start Fire** while carrying a **tinderbox** in inventory (consumes tinderbox use TBD). Creates a shared **campfire** on that tile for **10 minutes** (`FIREPLACE_DURATION_MS`). Any player may cook at it. **At most one fireplace per tile.** Fixed **oven** blocks are separate placeables (editor/content later).
245
246**Station UI (shared across all stations):** Opening a station shows a **recipe grid** on the left — each cell is the output **item icon** with **display name** underneath. Clicking a recipe selects it; the **detail pane on the right** repeats the icon and name, lists **required materials** (icon + quantity per input), and a **Craft** button. Crafting is blocked unless the server confirms room for the product: `canCraftFitInventory()` simulates **consuming inputs first**, then inserting the output, so freed slots from spent materials count toward space (`shared/crafting/recipes.js`). While crafting, a **2 s** progress bar runs (`CRAFT_DURATION_MS`) for every recipe regardless of item. Only one craft at a time per player; closing the panel cancels in-progress craft (sends `CANCEL_CRAFT`). Cooking stations use the same shell; burn failure is an outcome after the timer, not a separate UI.
247
248**Item scaffolding:** Reserved IDs and stub definitions for gathering/crafting content live in `shared/definitions/craftingItems.js` (`CraftingItemId`, `CRAFTING_ITEM_STUBS` merged into `ITEM_DEFINITIONS`). Replace stubs with full defs (sprites, equipment, tiers) as rules land. Recipe rows go in `shared/crafting/stationRecipes.js` (`CRAFT_RECIPES`); filter with `recipesForStation()`.
249
250**Dev:** In the browser console, `__craftDev()` opens the crafting bench UI; pass any `CraftingStationId` string for other stations.
251
252**TODO:** station block/entity types and sprites, real recipe tables per station, open/close from world interaction, server craft command + timer + adjacency checks, Cooking burn formula, log/tinderbox behaviour, campfire ground entity lifecycle & replication, spinning wheel wool input once sheep exist.
253**Code:** `shared/definitions/craftingStations.js`, `shared/definitions/craftingItems.js`, `shared/definitions/itemCategories.js`, `shared/crafting/recipes.js`, `shared/crafting/stationRecipes.js`, `client/src/play/crafting.js`, `client/ui/play.css` (#craft-panel)
254
255## Stamina and running
256
257**Status:** not implemented
258**Spec:** **Stamina** skill sets max stamina (= skill level). Each stamina point equals **one second of running**. Running consumes stamina; running awards Stamina XP. Walking does not consume stamina. **TODO:** stamina component sync, run gate when empty, regen rules, Stamina XP on run ticks, client stamina bar.
259**Code:** `shared/definitions/skills.js` (`playerMaxStamina` helper only)
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## Banking, cheques, shops, player-driven marketplace
280
281**Status:** partial
282**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.
283**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`
284
285## Player scripting hooks
286
287**Status:** not implemented
288**Spec:** Reserved control abstraction; not in the initial release.
289**Code:** —