BlueGit

timfa questward

Files

questward / tile_mmo_server_technical_design_v0.6.md

tile_mmo_server_technical_design_v0.6.md

tile_mmo_server_technical_design_v0.6.md 131.4 KiB Download Raw

--- title: Tile MMO Server Technical Design version: 0.12 status: proposed format: living-design-document ---

Tile MMO Server Technical Design

Version: 0.12 Status: Proposed architecture; intended to be iterated as implementation decisions are made. Scope: Authoritative Node.js/ECS backend, FrameworkV3-based game client (16×16 sprites, player-centered viewport), chunk/region streaming, SQLite persistence, admin world editor with per-chunk changelogs, player inventory and items, combat, player communication, banking/cheques, shopkeepers, marketplace/economy systems, skill progression, automatic restart/update orchestration, and future player scripting hooks.

1. Design goals

  • Support a large tile-based MMO world without simulating unused areas.
  • Keep the server fully authoritative: clients send actions and

intentions, never authoritative state changes.

  • Authenticate accounts via auth.timfalken.com (with an admin-<n> stub

until that service is live). An account may have unlimited characters, one in the world at a time, with delayed deletion and an inheritance bank tab.

  • Use ECS composition for entities and systems, while using chunks and

regions for spatial ownership and simulation lifecycle.

  • Allow simulation work to scale across Node.js workers and permit

entities to cross worker-managed region boundaries safely.

  • Keep client replication small: a player receives only the current

16×16 chunk and the eight neighbouring chunks.

  • Keep authored world data separate from ephemeral simulation state.
  • Persist only entities that explicitly need persistence; ordinary

spawned mobs disappear when their chunk is unloaded.

  • Avoid constant chunk writes. Normal chunk persistence occurs on

unload; graceful shutdown is implemented as a forced unload of all resident chunks.

  • Provide an admin-only graphical world editor for painting tiles,

opening or closing chunks, and placing/configuring spawners, with a per-chunk changelog of who changed what and when. Unedited chunks are grass-only and closed.

  • Automatically schedule a graceful midnight restart when live code or

authored world data changes, with an admin-triggered immediate restart path.

  • Reserve a clean control abstraction for a later sandboxed player

scripting language without requiring the scripting system in the initial release.

  • Build the player-facing client on the shared FrameworkV3 library, vendored

as a git submodule and built first so game-specific client code can layer on top of it, while keeping the server-side ECS an implementation detail of the backend. All world sprites are 16×16 pixels. The play viewport stays centered on the local player.

  • Authoritative movement is tile-to-tile at a global walk/run cadence

(default walk 2 tiles/s, run double), not a per-mob speed. Admins edit that cadence and other tick timers in a world-settings modal. World calendar time is server time minus 1200 years. At night the client darkens unlit tiles; static light reach is baked by raycast when a chunk is saved.

  • Give every player a 32-slot inventory in which stackable items occupy a

single slot, and treat dropped items as temporary, non-blocking ground objects rather than tile occupancy.

  • Make ordinary communication spatial rather than global: nearby speech is

progressively degraded by distance, while long-distance exchange is a physical item or currency delivery by carrier pigeon. A letter is simply a paper item with player-written text.

  • Support persistent player groups without turning them into an instant

long-distance chat channel.

  • Provide a shared, unlimited player bank near the marketplace, with later

banks all reading the same vault, plus bearer cheques and free pigeon deposits.

  • Make the central marketplace an order-matching service rather than a public

auction list, with durable escrow and asynchronous pigeon delivery.

  • Keep the economy predominantly player-driven: most ingredients are gathered,

final goods are normally crafted by players, and finished-item drops come from enemies/bosses rather than ordinary NPC shops.

  • Let every combatant — players and other mobs — attack. Melee requires an

adjacent tile including diagonals; ranged attacks and spells use the range of the weapon or spell. A hit roll uses the weapon skill; damage uses Strength, Dexterity or Mind. Attack XP is split equally between those two skills.

  • Let shop NPCs sell items at a seed value that lerps toward the last

player-market sale price over a configurable duration (default one hour), with a hidden per-shop discount. Item inspection shows name, description, origin and the undiscounted current value, refreshed at most once per minute.

  • Use skill-based progression with no player classes. Every gameplay action is

governed by a skill and awards XP to that skill when successfully performed. Combat is the explicit dual-skill exception: hit skill and damage skill share the XP.

2. Core world model

2.1 Spatial hierarchy

World └── Region: 4 × 4 chunks └── Chunk: 16 × 16 tiles └── Tile

One chunk contains 256 tiles. One region is 64×64 tiles and contains 16 chunks (4,096 tiles). World tile coordinates are canonical; chunk and region coordinates are derived from them.

chunkX = floor(tileX / 16) chunkY = floor(tileY / 16) regionX = floor(chunkX / 4) regionY = floor(chunkY / 4)

If negative world coordinates are allowed, use true floor division rather than JavaScript integer truncation.

2.2 Three independent spatial states

The design deliberately separates region residency, chunk simulation, and client visibility.

ConcernUnitMeaning
ResidencyRegionWhether the region and its required chunk data exist in server memory and have a worker owner.
SimulationChunkWhether ECS systems actively simulate entities and gameplay in this chunk.
VisibilityChunkWhether a specific client is subscribed to the chunk and receives its snapshot/deltas.

2.3 Region states

UNLOADED ↓ load RESIDENT ↓ no residency references + grace period UNLOADED

A resident region is assigned to exactly one simulation worker. An unloaded region has no active ECS representation.

2.4 Chunk states

DORMANT ⇄ SIMULATING

A dormant chunk can remain resident in memory while normal gameplay systems ignore it. A simulating chunk participates in movement, combat, AI, spawners and other active systems.

3. Tile layers and occupancy

3.1 Ground layer

Every tile has a ground type. Ground is visual only. It does not by itself block movement, cause collision, or create gameplay behaviour.

TileGround { groundTypeId: GroundTypeId }

3.2 Block layer

A tile may also contain one block. The block is the actual world object standing on the tile and can determine collision and behaviour.

TileBlock { blockTypeId: BlockTypeId \| null config?: BlockConfig }

Examples include walls, doors, trees, torches and other lights, containers, spawners, marketplace counters and banks. Block definitions determine properties such as passability, interaction behaviour, whether a block participates in navigation, and whether it emits light (lightRangeTiles).

3.3 MOBile entities

A moving game entity — player, enemy, animal, NPC or any other mobile actor — is represented by an ECS entity rather than being painted into the static tile map. A mobile entity may inhabit a tile in addition to the tile’s ground and block layers, subject to collision rules.

Tile ├── Ground (visual layer) ├── Block (static/world-object layer; optional) ├── Ground item stacks (ephemeral, non-blocking) └── Mobile ECS entities (dynamic occupancy)

The spatial chunk index maintains which mobile entity IDs currently occupy each tile, allowing collision, nearby queries and replication without scanning the global ECS. Ground item stacks are indexed per tile as well, but they never contribute to movement collision and never prevent a mobile entity from standing on that tile.

4. ECS model

4.1 Entity composition

Entities are numeric identities plus components. Behaviour comes from systems querying component combinations rather than deep class inheritance.

Player Position Movement Health Combat Skills Inventory Currency Equipment Player NetworkIdentity ChunkLoader Persistent

Ordinary enemy Position Movement Health Combat Skills Creature AI

Named NPC Position Movement Health NPC AI Persistent

4.2 Global identity versus local ECS handle

Use a globally meaningful EntityId for storage, networking and cross-worker transfer, and a compact worker-local EntityHandle for hot ECS arrays. A transferred entity keeps its EntityId but may receive a different local handle on the destination worker.

4.3 Recommended initial components

CategoryComponents
SpatialPosition, Movement, Path, Collision
LivingHealth, Combat, Creature, Mob, Skills
PlayerPlayer, NetworkIdentity, Inventory, Currency, Equipment
AIAI, Target, BehaviourState
LifecycleChunkLoader, Persistent, SpawnOrigin
PresentationRenderable / Appearance
Future controlController / ScriptController / OfflineUntil

5. ChunkLoader and simulation activation

5.1 Generic ChunkLoader component

World activation is component-driven rather than player-specific. Any entity may carry a ChunkLoader component that says “keep the surrounding world resident and simulated”.

ChunkLoader { simulationRadiusChunks: 1, regionLoadRadius: 1 }

A normal player can therefore stimulate a 3×3 chunk area while keeping the surrounding 3×3 regions resident. Bosses, travelling NPCs, machines, scripted actors or administrative anchors can use the same mechanism.

5.2 Reference counting

Chunk simulation and region residency should use reference counts. Overlapping loaders increment the same references; leaving decrements them. A chunk sleeps only when its simulation reference count reaches zero. A region becomes eligible for unload only when its residency references reach zero.

5.3 Grace period

After the last residency reference disappears, retain the region briefly before unloading. This prevents repeated SQLite reads and writes when a loader oscillates around a boundary. The delay should be configurable.

6. Chunk lifecycle and persistence

6.1 No periodic chunk saves

Normal gameplay does not periodically rewrite loaded chunks. A chunk is saved as part of the unload path only.

Resident chunk ↓ last residency / forced shutdown unload Prepare unload ↓ Persist required chunk state once ↓ Persist required entities ↓ Remove ECS/runtime representation

A graceful server restart does not introduce a second save mechanism. It force-unloads every resident region/chunk, so the normal unload persistence path remains the single source of truth.

6.2 Persistent versus non-persistent entities

Persistence is an entity property, not a property of the chunk or spawner. An entity with Persistent is serialised when its owning chunk/region unloads. A non-persistent entity is simply discarded.

Non-persistent wolf spawn → simulate → chunk unload → disappear

Persistent named NPC load → simulate → chunk unload → save → recreate when area loads

6.3 Persistent is independent of ChunkLoader

These traits must remain independent. A persistent entity does not automatically keep its area active, and a ChunkLoader does not automatically become persistent.

7. Storage architecture

7.1 Separate authored world and runtime state

Use two SQLite databases with different responsibilities.

DatabaseResponsibility
world.sqliteAdmin-authored ground tiles, block tiles, light maps, world settings, spawner configuration, per-chunk editor changelogs, world revisions and world metadata.
state.sqliteAccounts, characters, inventories, carried currency, character vaults, inheritance tabs, cheque reservations, skills, groups, courier cargo/transit, unexpired ground items, market orders/escrow/trades, per-item last player-market sale, persistent ECS entities, offline-script state, optional persistent runtime chunk overrides, and other durable live-game state.

This prevents editor authoring changes from becoming entangled with live player/entity persistence.

7.2 Chunk writes in runtime state

If initial gameplay does not allow permanent tile/block modification, runtime chunks require no writes at all. If permanent runtime world changes are later added, dirty chunk overrides are held in memory and written to state.sqlite only when that chunk unloads. Shutdown uses forced unload and therefore follows the same rule.

7.3 Central persistence service

Simulation workers should not independently compete for SQLite writes. A persistence service owns the write connection, batches transactions, and receives logical save requests from workers.

Simulation workers │ save/unload messages ▼ Persistence service │ ▼ SQLite (WAL)

Live ECS state remains authoritative while loaded; SQLite is durable state, not a per-tick synchronisation mechanism.

8. World authoring and revision model

8.1 Admin-only world editor

The server includes a separate admin-only world editor UI. It is not part of the normal player client.

  • Display a 3×3 of 16×16 chunks, with the currently selected

chunk in the centre and a red border around that chunk. Painting, open/closed, and changelog apply only to the selected chunk; neighbours are visible for alignment and baked lighting context.

  • Provide Up, Down, Left and Right navigation buttons that move the

editor exactly one chunk in that direction.

  • Show the current chunk coordinates prominently, and whether the chunk

is open or closed.

  • Toggle the current chunk open or closed. Closed chunks remain visible

to nearby players but cannot be entered.

  • Allow painting a ground type on a tile.
  • Allow painting, replacing or erasing the block type on a tile.
  • Render both layers together so the block appears on top of the ground.
  • Do not display ordinary mobile entities as editable map paint.
  • Allow selecting/configuring special block types such as Spawner, Bank,

Marketplace and light-emitting blocks (lightRangeTiles).

  • Open a world settings modal for global tick timers and constants

(movement cadence, shop lerp duration, drop lifetime, and other values listed in section 8.5).

  • Provide a night-to-day slider that only previews lighting; it does

not change live world time. Preview uses the same baked light maps as play, including light that reaches this chunk from neighbouring chunks.

  • Later: allow configuring ground-item spawners analogously to mob

spawners. Exact item tables remain a later content decision.

  • Save changes through an authenticated admin API; the browser never

opens SQLite directly.

  • Show that chunk's changelog: a chronological list of saves, each with

which admin made the edit, when, and a bullet-point diff of the change.

The editor camera is not locked to a player character. It frames the currently selected chunk. This is the only intended exception to the player-centered play viewport in section 21.4.

8.2 World editor save behaviour

Saving a chunk or world settings writes the authored result to world.sqlite. It does not live-patch the currently running simulation. Instead, the change creates or updates a pending world revision and schedules a server restart for the next server-local midnight.

The running game remains pinned to the world revision selected at its own startup. This avoids a dangerous mixed state where some loaded chunks use old authored data and newly loaded chunks use newer editor data.

8.3 Versioned authored chunks

A practical schema is to give every editor change a monotonically increasing world revision. The game process pins one active revision for its entire lifetime. Chunk lookup selects the latest authored version not newer than that pinned revision.

world_revisions revision_id created_at created_by status // pending / active / superseded

world_chunk_versions chunk_x chunk_y revision_id open // player-enterable; default false until set data_blob

world_meta active_revision pending_revision

world_settings revision_id settings_blob // walk speed, tick timers, shop lerp, drop TTL, ...

world_chunk_edit_log log_id chunk_x chunk_y revision_id editor_admin_id edited_at diff_entries // structured bullets for this save

On the next planned restart, startup promotes/selects the latest valid pending revision before world loading begins.

8.4 Per-chunk changelog

Every successful chunk save appends one changelog record for that chunk. The record is durable in world.sqlite and is not gameplay state.

The server diffs the newly saved chunk against the previous authored version of that same chunk (the latest world_chunk_versions row for those coordinates that this save replaces). Unchanged tiles produce no bullets. Each changed tile becomes one of:

- Ground at X, Y changed from Prev to New.
- Block <type> placed at X, Y.
- Block at X, Y changed from Prev to New.
- Chunk opened.
- Chunk closed.

X, Y are world tile coordinates. Prev / New / <type> are the ground or block definition display names. A block paint on an empty block layer is a placement. Replacing one block type (or its config, such as a spawner) with another is a change. Erasing a block is a removal. Ground is never absent; a ground paint is always a change from one type to another.

The editor UI lists records newest-last or newest-first consistently, each headed by admin identity and timestamp, with that save's bullets underneath. The changelog is an audit trail, not an undo stack. Undo/redo remains an open editor-UX decision. Derived light maps are not changelog bullets; they are regenerated on save (section 8.6).

8.5 World settings

Global gameplay constants live in authored world_settings for the world revision. They are not per-mob and not client-authored. Admins edit them from a modal in the world-editor UI. Saving the modal writes into the pending world revision and schedules the same midnight restart as a chunk save. The running process keeps the settings it loaded at startup.

Minimum initial settings and defaults:

WorldSettings
- walkTilesPerSecond          // default 2
- simulationTickHz            // default 20; implementation default, still a setting
- shopPriceLerpDuration       // default 1 hour
- groundItemDespawnDuration   // default 10 minutes
- regionUnloadGracePeriod     // configurable grace after last residency
- defaultGroundTypeId         // grass used for never-edited chunks
- characterDeletionDelay      // default 24 hours

Running is always double walking speed. It is not a separate per-entity field. From walkTilesPerSecond:

runTilesPerSecond   = walkTilesPerSecond * 2     // default 4
movementTickHz      = runTilesPerSecond          // default 4 Hz
walk: commit a tile every 2 movement ticks
run:  commit a tile every 1 movement tick

All ground mobiles — players, enemies, NPCs — use this same cadence. A mob definition does not set move speed. Gait (walk | run) is the only per-entity choice; it selects every-other vs every movement tick.

Other tick-duration constants that already exist in this document (shop lerp, ground-item despawn, residency grace, and later ones of the same kind) are edited here rather than hardcoded. Adding a new global timer means adding a field to WorldSettings and a row in this modal.

8.6 Baked lighting

Light from authored blocks is precomputed when a chunk is saved, not raytraced every simulation tick.

A block definition may set lightRangeTiles > 0. That tile is a static light source. Light travels only through passable tiles (the same passability as walking). Ground type does not block light. Mobiles and ground items do not block light.

For every tile within a source's range, the baker runs a simple grid raycast (for example Bresenham through tile centres). If the ray hits an impassable block before the destination, that source does not light that tile. A tile is lit if any source can reach it. Light does shine across chunk boundaries.

Saving a chunk rebakes:

1. that chunk's 16×16 light map, and 2. every neighbouring chunk that could be affected (chunks within the maximum lightRangeTiles of the saved chunk).

Neighbor rebakes use light sources and walls from the pending revision, including the chunk just saved. Those neighbor light maps are written into the same pending revision so play never mixes old and new lighting.

The light map is stored in the chunk data_blob (a 16×16 reachable-or- not mask, optionally with distance to the nearest reaching source). It is replicated to clients in CHUNK_SNAPSHOT / CHUNK_DELTA.

Runtime door open/close does not rebake static light unless a later iteration adds live lighting. Baked light is authored geometry.

The editor night-to-day slider interpolates preview ambient from full night (dark except baked-lit tiles) to full day (no ambient darkening). It does not persist and does not change server/world clock.

8.7 Default chunks and open / closed

A chunk the editor has never saved does not exist in world_chunk_versions. At runtime it is synthesised as:

  • every tile defaultGroundTypeId (grass),
  • no blocks,
  • closed,
  • no baked lights.

The world is therefore an infinite grass field until admins paint it, and players cannot walk onto it until an admin opens the chunk.

Closed chunks can still appear in a player's 3×3 view. They cannot be entered: MOVE_TO, pathfinding, spawning, and other player-entry actions treat every tile in a closed chunk as impassable. Visibility and lighting previews are unchanged.

Open chunks are the playable map. Opening or closing is an authored chunk flag, saved with the pending revision like paint.

Spawners in a closed chunk do not spawn. Ground movement, including AI, does not step into a closed chunk. If a future bug or admin tool places an entity there, it can still be replicated to observers, but players cannot walk in after it.

9. Spawner blocks

9.1 Spawner data

A Spawner is a block in the authored block layer, with per-instance configuration stored as part of the chunk data.

SpawnerConfig { spawnerId: SpawnerId, mobTypeId: MobTypeId, maxAlive: number, spawnRangeTiles: number }

Additional parameters such as minimum/maximum spawn delay can be added later without changing the core model.

9.2 Spawner editor

Selecting a Spawner tile in the world editor opens a configuration panel containing at minimum: mob type, maximum alive count and spawn range. Validation happens server-side before the pending world revision is written.

9.3 Spawned entity persistence

The spawner never decides whether its mob is persistent. The mob definition/archetype does. When the spawner creates an entity, the entity receives Persistent only if that mob type is defined as persistent.

MobDefinition: deer persistent = false

MobDefinition: named_guard_captain persistent = true

9.4 SpawnOrigin

Spawned mobs receive a SpawnOrigin component referencing the spawner. This lets maxAlive count only entities belonging to that spawner and avoids expensive geometric searches.

SpawnOrigin { spawnerId: SpawnerId }

For non-persistent mobs, disappearance on chunk unload naturally decreases the count. For persistent mobs, SpawnOrigin is persisted so the spawner can recognise an existing persistent instance even after it has moved or been unloaded elsewhere. A lightweight persistence index by spawnerId prevents duplicate persistent spawns.

9.5 Spawner simulation

SpawnerSystem runs only while the spawner’s chunk is simulating and open, and at a much lower frequency than movement. A spawn candidate must satisfy block collision, bounds, an open chunk, and mobile-occupancy rules. Ground type does not affect passability unless a later gameplay system explicitly introduces a separate rule for it.

9.6 Future ground-item spawners

Some items will later spawn naturally on the ground, using a world-editor block analogous to a mob spawner. Those spawned stacks should use the same non-blocking ground-item representation as player drops, but their lifetime, respawn and maxOnGround rules belong to the spawner configuration rather than the 10-minute player-drop timer.

Exact item lists, harvest interactions and spawner parameters are later content decisions and do not block the inventory/bank model.

10. Startup and loading order

Loading order is explicit so authored world state exists before persistent entities are instantiated into it.

> 1. Start process and load configuration, including server time > zone and storage paths. > > 2. Open world.sqlite and validate/migrate its schema. > > 3. Select/promote the world revision to use for this process and > pin it for the lifetime of the process. > > 4. Load static registries: ground definitions, block definitions, > item definitions, material definitions, spell definitions, mob archetypes and component serializers. > > 5. Open state.sqlite and run runtime-state migrations. > > 6. Start the persistence service, durable domain services (such as courier, bank, market and shop-price services when enabled), region coordinator and simulation workers. > > 7. Load the index of persistent entities that themselves require > world activation (for example persistent ChunkLoaders or future > offline scripted players). > > 8. For each required region, load authored chunk data from the > pinned world revision first. > > 9. Apply any durable runtime chunk override state, if the game > supports such modifications. > > 10. Instantiate persistent entities into the already-created > world/chunks. > > 11. Recalculate ChunkLoader references and begin chunk simulation. > > 12. Only after the world reports READY does the gateway accept > normal player logins.

This ordering solves the bootstrap problem for persistent entities that keep their own chunks active: a compact persistence index can locate them without first loading the entire world.

11. Simulation workers and region ownership

11.1 Ownership invariant

Exactly one worker authoritatively owns a region at any instant. Every authoritative entity belongs to the worker that owns the entity’s current region.

11.2 Coordinator

A central region coordinator maintains RegionId → WorkerId and assigns/migrates regions based on actual measured simulation effort, while preferring neighbouring regions on the same worker when load permits.

11.3 Work measurement

  • Average and high-percentile tick execution time.
  • Number of simulating chunks.
  • Number of active entities and AI entities.
  • Pathfinding work and queued searches.
  • Cross-worker boundary message volume.
  • Backlog / tick lateness.

Actual time spent simulating is more important than raw player count or raw region count.

11.4 Node.js implementation

Start with Node.js worker_threads for simulation workers. Keep mutable ECS worlds isolated per worker and use message passing between them. Do not begin with a shared mutable ECS in SharedArrayBuffer.

12. Cross-worker communication

12.1 No remote mutation

A worker may inspect a limited read-only representation of neighbouring entities but never directly mutates authoritative state owned by another worker.

12.2 Border ghosts

Neighbouring workers can exchange compact border/ghost entity data for nearby interaction and AI: EntityId, position, collision footprint, type and minimal combat metadata. Ghosts are not full ECS entities and are never authoritative.

12.3 Remote actions

Worker A goblin targets Player 42 (owned by Worker B) Worker A → REMOTE_ACTION(attack intent) → Worker B Worker B validates range/state and applies authoritative result

12.4 Entity transfer

When an entity crosses from a region owned by Worker A into one owned by Worker B, ownership is handed off at a simulation tick boundary using a sequence-numbered transfer protocol. There is never more than one authoritative copy.

A: prepare transfer B: validate / accept A: freeze at handoff boundary B: instantiate authoritative entity at effective tick Coordinator: update ownership mapping A: remove authoritative copy

13. Server tick and stimulation

13.1 Fixed simulation tick

Use a fixed server simulation tick. The default is 20 Hz (50 ms), stored as WorldSettings.simulationTickHz. This is not a protocol promise.

Movement does not commit a new tile on every simulation tick. See section 13.4.

1\. Drain validated incoming commands 2. Apply completed worker/entity transfers 3. Recalculate activation changes 4. Movement / collision 5. Combat 6. Scheduled AI 7. Scheduled spawners/environment, including ground-item expiry in simulating chunks 8. Produce cross-worker messages 9. Produce client replication deltas 10. Queue unload/persistence work

13.2 Different system frequencies

Not every ECS system should run every tick. Ground movement commits only on the global movement cadence (section 13.4). AI decisions, target searches and spawner checks can run at lower frequencies. Sleeping chunks are not “slow ticked”; they are omitted from normal simulation.

13.3 Timestamp-based inactive progression

Long-lived timers such as growth, cooldowns, ground-item expiry and shop price lerps should store future timestamps where possible. When an area wakes, the system catches up from the timestamp instead of executing missed ticks. An expired ground item is discarded on catch-up without ever reappearing. Shop and tooltip prices are evaluated from last-sale timestamps when observed; they are not ticked. Durations such as shop lerp and ground-item despawn come from WorldSettings, not from hardcoded literals in systems.

13.4 Global movement cadence

All ground-moving entities share one walk speed and one run speed.

  • Default walk: 2 tiles per second (walkTilesPerSecond).
  • Run: always double walk (default 4 tiles per second).
  • Movement ticks fire at runTilesPerSecond (default 4 Hz).
  • Walk: the entity may advance one path tile on every other movement

tick.

  • Run: the entity may advance one path tile on every movement tick.

Mobs do not define their own move speed. Movement.gait is walk or run. Players send SetGait. AI may set gait; it still uses the global cadence. Flying pigeon transit is not this cadence; it keeps its own route clock.

If the path is blocked on a movement tick, the entity stays on its tile and retries on a later legal tick. Occupancy, combat range and pickup always use the last committed tile.

13.5 World calendar time

World time is server time 1:1, in the same configured IANA zone used for midnight restarts, with 1200 years subtracted from the calendar date. A server clock of 24 Aug 2026 21:00 is world 24 Aug 826 21:00. Clock-of-day, including night, therefore matches the host's zone.

The gateway includes current world time (or server unix time plus the year offset) in the status sent to clients so shading does not depend on the player's device clock. Lighting is presentation; combat and movement do not wait on the day/night overlay.

14. Client gateway and authority

14.1 Stable connection ownership

Client WebSocket/TCP connections belong to a gateway rather than simulation workers. When the player crosses into a region owned by another worker, the socket stays connected to the same gateway; only internal routing changes.

14.2 Client commands are intentions

A client sends commands such as MoveTo, Interact, Attack, UseItem, EquipItem, UnequipItem, SelectSpell, SetGait, DropItem, PickupItem, BankDeposit, BankWithdraw, BuyFromShop or SendPigeon. The authenticated account determines the actor; after character select, commands apply to that account's active character. The client never supplies an authoritative resulting position, health value or inventory result.

14.3 Input queue

Socket handlers validate message shape and enqueue commands. Simulation workers consume commands at tick boundaries. WebSocket callbacks do not mutate ECS state directly.

14.4 Authentication

Live login uses auth.timfalken.com. The game server never stores a password. It receives an authenticated account identity (and email) from that service and maps it to a durable accountId in state.sqlite.

Until auth.timfalken.com is available, the gateway uses a stub identity: each new connection is admin-<n>, where n is the number of currently connected clients including this one (the first connection is admin-1). Stub accounts are treated as admins so the world editor can be used during development. Stub accounts have no email; deletion “emails” are logged instead of sent.

When real auth ships, the stub is removed. Admin rights come from that service, not from the admin- name prefix.

An account may have only one active play session at a time (one character in the world).

14.5 Characters

An account has unlimited characters and plays one at a time. First login with no characters must create one before entering the world. Later logins show a character-selection menu: create, choose, mark for deletion, or cancel deletion.

Initial character setup (may change later):

CreateCharacter
- firstName     // not globally unique
- lastName      // unique surname, owned by this account
- sex           // male | female

Rules:

  • Last names are globally unique. The first character to take a surname

claims it for that account. The same player may reuse that last name on their other characters. Another account cannot use it.

  • First names need not be unique globally.
  • For a given account, firstName + lastName must be unique among

characters that still exist (including those pending deletion).

  • Uniqueness is case-insensitive; display uses the casing the player typed.
Account
- accountId
- authSubject               // from auth.timfalken.com, or stub admin-<n>
- email?                    // from auth; absent on stub
- surnameClaims[]

Character
- characterId
- accountId
- firstName
- lastName
- sex
- deletionScheduledAt?      // null if not deleting
- inventory, equipment, currency, vault, skills, ...

The in-world ECS player entity is a character, not the account.

14.6 Character deletion and inheritance

From character select, the player may mark a character for deletion.

  • The character cannot be played while deletion is pending.
  • Permanent delete happens after characterDeletionDelay (default **24

hours**). Until then the player may cancel.

  • The server always notifies the account email when deletion is

marked (and should notify again on cancel and on actual delete). Stub auth logs the message instead.

  • On permanent delete, the name pair is freed. If this account has no

remaining characters with that last name, the surname claim is released.

  • Before the vault is moved, BankService voids outstanding filled

cheques issued by this character (reservations return to the vault).

  • All items in inventory, equipment, carried currency, and the character

vault are moved to that account's inheritance bank tab.

Any living character of the same account may, at a bank, claim inheritance stacks (and currency) into that character's own vault. Claiming is a move from the account tab to the character vault, not a second copy.

15. Client chunk subscription and replication

15.1 3×3 visibility

A player receives the current chunk and the eight surrounding chunks, a maximum viewport of 48×48 tiles. Neighbouring closed chunks are still sent so scenery remains visible; the player simply cannot walk onto them.

┌───┬───┬───┐ │ V │ V │ V │ ├───┼───┼───┤ │ V │ P │ V │ ├───┼───┼───┤ │ V │ V │ V │ └───┴───┴───┘

15.2 Incremental subscription changes

Crossing one chunk east subscribes only the three newly visible eastern chunks and unsubscribes only the three old western chunks. The rest of the 3×3 view remains subscribed.

15.3 Snapshots and deltas

Initial subscription sends a CHUNK_SNAPSHOT containing authored/runtime tile state, currently visible entities and unexpired ground item stacks. Afterwards, revisioned CHUNK_DELTA messages report tile changes, entity spawn/move/change/despawn events and ground-item appear/change/despawn events. Full chunks are not retransmitted every tick.

Entity move events carry the new integer tile and the current gait so the client can lerp over the walk or run interval. They do not carry a fractional in-between position. Smooth walking is a client visual lerp (section 21.5), not part of the replication payload.

Chunk snapshots include the baked light map (section 8.6).

Visible equipment is replicated as a compact appearance payload (body sprite plus worn overlay layers and recolour parameters), not as the entity's full inventory. Nearby clients can draw another player's armour without receiving their bags.

15.4 Visibility can span workers

The gateway can source visible chunks from multiple workers. A player may be authoritative on Worker A while one or more of the eight neighbouring visible chunks are owned by Worker B. Client visibility must never force simulation-region reassignment.

16. Click-to-move and A\* pathfinding

16.1 Command flow

Client: MOVE_TO(tileX, tileY) ↓ Gateway validates/authenticates ↓ Owning worker validates target ↓ A\ calculates authoritative route ↓ Path component attached/updated ↓ MovementSystem advances the entity one tile at a time* on the global walk/run cadence (section 13.4)

Authoritative Position is always an integer tileX, tileY. The server does not store a sub-tile location for walking mobiles. When a movement tick allows this gait to step, MovementSystem commits the next path tile in a single jump. Combat, occupancy, pickup and interaction all use that committed tile.

Flying pigeons still ignore the ground navigation grid, but their replicated ECS position is likewise a tile. The transit clock determines which tile they occupy at a given time; the client may lerp the sprite between those tiles like any other mobile.

16.2 Initial A\* implementation

For normal player clicks within the visible 3×3 chunks, the search space is at most 48×48 = 2,304 tiles, so conventional A\* is a strong starting point.

  • Binary heap priority queue for the open set.
  • Manhattan heuristic for four-direction movement; octile heuristic if

diagonal movement is later allowed.

  • Reusable typed-array or pooled search buffers for hot paths to reduce

allocation and garbage collection.

  • Rate-limit path requests per player and avoid recalculation every

tick.

  • Use block passability, open-chunk bounds, and dynamic occupancy;

ground is visual only. Tiles in closed or never-edited chunks are not legal path targets for players.

16.3 Navigation revisions

Each chunk maintains a navigation revision that increments when a movement-affecting block changes. A path records the relevant revisions. Static geometry changes can invalidate paths; temporary mobile occupancy normally causes a short wait or small local re-path rather than rebuilding every path.

16.4 Long-distance extension

If long-distance autonomous travel is added later, introduce hierarchical pathfinding: region graph → chunk portals/edges → local tile A\*. The client movement command interface does not need to change. Server movement remains discrete tile steps; only the path length changes.

17. Automatic update and restart scheduler

17.1 Restart triggers

A graceful restart is scheduled for the next midnight in configured server-local time when either of these conditions occurs:

  • A new commit is detected on origin/master. The master branch is the

live branch.

  • An administrator saves a world-editor change, creating/updating a

pending authored world revision.

Multiple triggers coalesce into one scheduled restart. The scheduler stores all reasons so players and admins can see why a restart is pending.

17.2 Detecting live-code changes

The running server periodically performs a non-destructive remote check, for example git fetch origin master followed by comparison of the running commit with origin/master. It does not update the checked-out code while the game is live.

17.3 Server-local midnight

Midnight is calculated in a configured IANA time zone rather than by adding 24 hours to the current time. This keeps behaviour correct across daylight-saving transitions.

17.4 Player-visible restart state

Restart status is part of the server status sent to clients. Connected players see that a restart is scheduled and the scheduled local time. The server can also issue configurable countdown notices as the restart approaches and includes the state immediately when a player logs in.

RestartStatus { scheduled: true, scheduledAt: timestamp, reasons: \["code-update", "world-update"\] }

17.5 Manual admin restart

An authorised admin action can invoke the same graceful restart pipeline immediately. This is not a separate “hard restart” path; it differs only in scheduled time.

17.6 Graceful restart sequence

> 1. Enter DRAINING / RESTARTING state and reject new logins. > > 2. Broadcast the final restart notice. > > 3. Disconnect player sessions cleanly and persist session state. > Shutdown handling overrides normal offline-script retention so chunk > unload cannot be blocked by a retiring process. > > 4. Stop accepting new gameplay commands and finish the current > safe tick boundary. > > 5. Force-unload every resident region/chunk, ignoring normal > ChunkLoader references. This invokes the ordinary chunk/entity unload > persistence path exactly once. > > 6. Flush the persistence service and close SQLite connections > cleanly. > > 7. Atomically write a restart request manifest. It records the > restart reasons, whether a code deployment is requested, the target Git > commit if known, and the pending world revision if one exists. > > 8. Exit the Node.js game process cleanly. At this point the game > process has no responsibility for updating or relaunching itself.

17.7 systemd process supervisor

The production Node.js process is owned by a systemd service. systemd therefore already knows when the process has fully exited; no separate polling process is needed. Only after the previous ExecStart process is gone does systemd begin the next service start.

The preferred lifecycle is:

Running Node.js server
        |
        | graceful planned restart or crash
        v
Node.js process fully exits
        |
        v
systemd starts the service again
        |
        +--> conditional update hook
        |       |
        |       +--> planned code deployment: git fetch/pull --ff-only
        |       +--> world-only restart: no Git mutation
        |       +--> crash/no restart manifest: no Git mutation
        |
        +--> optional dependency/build step if deployment changed code
        |
        v
Start Node.js server
        |
        v
Startup selects the new active world revision
        |
        v
Gateway opens when the world reports READY

17.7.1 Why Git pull must be conditional

A naive ExecStartPre=git pull on every restart is unsafe. Suppose a new commit is detected at 14:00 and correctly scheduled for midnight, but the game process crashes at 16:00. An unconditional pull would deploy the new commit immediately during crash recovery, bypassing the scheduled maintenance window.

Therefore the restart manifest distinguishes an intentional deployment restart from an ordinary process failure:

{
  "reason": ["code-update", "world-update"],
  "deployCode": true,
  "targetCommit": "<optional commit hash>",
  "pendingWorldRevision": 184
}

The manifest should be written using a temporary file plus atomic rename so the supervisor never consumes a half-written request. The supervisor consumes/removes the request only after it has successfully interpreted it.

If the Node.js process dies without a valid deployment request, systemd restarts the currently checked-out version. This gives fast crash recovery without prematurely deploying pending code.

17.7.2 Suggested systemd shape

A production unit can conceptually look like this:

[Unit]
Description=Tile MMO Server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=tilemmo
Group=tilemmo
WorkingDirectory=/srv/tile-mmo/current

# This hook checks the restart manifest. It pulls/builds only when an
# intentional deployment was requested. Prefixing with '+' optionally
# allows the hook to run with privileges different from the game user.
ExecStartPre=+/usr/local/sbin/tile-mmo-update-if-requested
ExecStart=/usr/bin/node /srv/tile-mmo/current/dist/server.js

Restart=always
RestartSec=5s
TimeoutStopSec=120s
KillSignal=SIGTERM

[Install]
WantedBy=multi-user.target

Restart=always is appropriate here because an explicit systemctl stop tile-mmo does not cause systemd to restart the unit, while a clean in-game restart exit and an unexpected crash both do.

The exact paths, build command and privilege split are deployment details, but the important invariant is that the Node.js process does not pull Git itself.

17.7.3 Code-update, world-update and crash behaviour

SituationRestart manifestGit pull before restartWorld revision
Scheduled code updatedeployCode=trueYes, fast-forward onlyActivate pending revision if present
World-editor-only updatedeployCode=falseNoActivate pending revision
Manual deployment restartExplicit admin intentAs requestedActivate pending revision if present
Unexpected Node.js crashMissing/invalidNoContinue current active revision
systemctl stopIrrelevantNo automatic restartN/A

This preserves the midnight deployment promise even when the game crashes before the scheduled maintenance window.

17.8 Failure behaviour

Deployment should fail closed. If Git cannot fast-forward, a build or migration fails, or startup validation fails, the game must not open to players on a partially updated state. The update hook should log the failure clearly and return non-zero; systemd may retry according to its restart/start-limit policy. Databases remain intact, and backups or snapshots before schema migrations are recommended.

A failed crash recovery that did not request deployment must not silently switch to a newer Git commit as a recovery strategy.

18. Future player scripting architecture

18.1 Scope

The custom scripting language is explicitly a later feature. Version 1 only needs architectural hooks so adding scripts does not require replacing the player-control or simulation model.

18.2 Controller abstraction

All player actions should already pass through an internal command interface. Manual client input is therefore one possible controller. A future script is another controller that emits the same validated action intentions.

ClientController ─┐
                  ├─> ActionCommand queue ─> authoritative game systems
ScriptController ─┘

Scripts never mutate ECS components directly. They request actions such as MoveTo, Interact or Attack and receive the same validation as a human client.

18.3 Online scripted mode

A logged-in player may enable the script while remaining connected and observing the game. Control mode explicitly determines whether manual input or the script is currently producing gameplay commands. The server remains authoritative either way.

18.4 Logout with active script

If a player has configured offline script execution, logout removes the network/controller connection but keeps the player entity alive. The entity changes to an offline script-controlled state and continues acting until it dies or its configured offline duration expires.

Player online Player + NetworkIdentity + ChunkLoader + Controller ↓ logout with offline scripting Player + ScriptController + ChunkLoader + OfflineUntil ↓ death OR expiry persist player state → remove runtime entity

18.5 Offline scripted players and loading

An offline scripted player must continue to stimulate the world it traverses, so it retains a ChunkLoader. This is powerful but potentially expensive: thousands of offline scripts could keep large parts of the world active. Offline duration, script CPU budget and concurrent offline-script limits therefore become explicit resource policy, not implementation accidents.

18.6 Restart continuity

A planned restart persists the offline-script state and expiry time, force-unloads the old process, and rehydrates still-valid offline scripted players during startup. This is why the startup index for persistent ChunkLoaders is part of the base architecture.

18.7 Scripting language safety requirements

When the language is implemented, it should be interpreted/compiled into a purpose-built sandbox rather than evaluated as JavaScript. At minimum it should enforce:

  • No file-system, operating-system, database or arbitrary network

access.

  • No eval or escape into Node.js objects.
  • Per-tick/per-event instruction budgets and bounded memory.
  • Rate-limited expensive operations such as path requests and world

queries.

  • Capability-based read APIs for nearby visible/known world state.
  • Action output only through the normal server command pipeline.
  • Persistable script variables/state if offline execution must survive

restarts.

  • Deterministic or tightly controlled timing semantics where practical.

An event-driven language is preferable to running every player script continuously at full simulation frequency. Events such as arrival, attack, nearby entity changes or timer expiration can wake scripts only when useful.

19. Security and administration

  • World-editor endpoints require an explicit admin role and separate

server-side authorisation checks.

  • Client-supplied entity/player IDs are never trusted as authority;

authenticated connection/session context identifies the actor.

  • World-editor data is validated against known ground, block, item and mob

definitions before database write.

  • Admin restart and deployment controls use the same authenticated

administration layer.

  • The Node.js game process should run as a dedicated unprivileged user.

Where practical, source-update permission belongs only to the systemd update hook (for example a privileged ExecStartPre helper), leaving the running Node.js process unable to modify its own checkout.

  • SQLite writes are parameterised and centralised through

persistence/editor services.

  • Inventory, vault, cheque and courier mutations are server-authoritative.

Clients cannot invent cheque IDs, forge cargo, or credit a vault.

  • Attack hit/miss and damage are server-authoritative. Clients cannot supply

a roll or a damage result. Shop purchase prices are computed at buy time on the server.

20. Recommended process topology

Clients
  |
  v
WebSocket/API Gateway
  |
  +-- Region Coordinator ----> Simulation Worker A
  |                              <--> Simulation Worker B
  |
  +-- Communication Service --> proximity speech
  |
  +-- CourierService ---------> pigeon cargo / transit
  |
  +-- BankService ------------> shared vaults / cheques / reservations
  |
  +-- MarketService ----------> order book / escrow / trades / last-sale index
  |
  +-- Persistence Service ----> state.sqlite
  |
  +-- Admin / World Editor ---> world.sqlite

External process supervision:
systemd ---> conditional deployment hook ---> Node.js relaunch

21. Player client architecture

21.1 FrameworkV3 as a git submodule

The player-facing client is built on the shared FrameworkV3 library:

<https://gitlab.com/Timfa/frameworkv3>

FrameworkV3 contains generic reusable client-side code. Game-specific rendering, UI, input, assets and protocol handling live in this repository, on top of that library. They are not patched into FrameworkV3 unless they are genuinely reusable across games.

This repository vendors FrameworkV3 as a git submodule rather than copying its source or depending on an unpublished global install.

mmo/
  client/
    frameworkv3/     # git submodule → gitlab.com/Timfa/frameworkv3
    src/             # this game's client: protocol, UI, world view, assets
  server/            # Node.js ECS backend; does not import FrameworkV3

The submodule path is client/frameworkv3. A clone of this repo is not client-buildable until submodules are present:

git clone --recurse-submodules <this-repo>
# or, in an existing checkout:
git submodule update --init --recursive

The submodule records a pinned commit. Bumping FrameworkV3 is an explicit commit in this repository (new submodule SHA). Game code must not rely on an uncommitted dirty checkout of the submodule.

Build order:

1. Build FrameworkV3 from client/frameworkv3
2. Build this game's client against that output
3. The Node.js server is a separate build and does not link FrameworkV3

The exact FrameworkV3 build command follows that project's own instructions. This game's client build must consume the framework's public/build artefacts, not fork its internals.

CI and developer machines check out submodules before the client job. A missing or uninitialized submodule is a failed client build, not a fallback to a system copy of FrameworkV3.

If this repo's master also ships the built web/desktop client from the same process that deploys the game server, a submodule bump is just another commit and follows the normal midnight restart/deploy path. The running Node.js game process still does not compile or import FrameworkV3.

The backend remains the authoritative Node.js ECS simulation described in this document. The client does not need to use ECS. It receives only a small 3×3-chunk view plus player/UI state, so a conventional object/view-model model is simpler and entirely appropriate.

21.2 Server/client model separation

Backend ECS components are not treated as a shared client object model. Network messages form the contract between the two sides.

Authoritative Node.js ECS
        |
        | snapshots / deltas / UI state
        v
Network protocol DTOs
        |
        v
Built FrameworkV3 (from client/frameworkv3 submodule)
        |
        v
This game's client code (client/src)

The two projects may share protocol schemas, enums or generated message types, but the client must not depend on the internal layout of ECS component storage. That allows server internals to be optimised without forcing corresponding client rewrites.

21.3 Sprites are 16×16

Every world sprite — ground tiles, blocks, mobs, item icons and other in-world art — is exactly 16×16 pixels. Sprites are not individually stretched to a different size. One sprite corresponds to one tile on the world pixel grid.

At load time, any image whose width or height is not 16 is rejected. The asset must not enter the runtime atlas or definition registry. The failure should name the file and its actual dimensions.

A unit test walks the sprite asset tree (grounds, blocks, mobs, items, equipment overlays, recolour masks, and any other world-sprite folders) and performs the same check. It reports every offender and fails if any are found. This test belongs in CI so a non-16×16 sprite cannot ship even if a local load path is skipped. Recolour masks are 16×16 world sprites too; a mismatched mask is a failed test.

Camera zoom (section 21.4) scales the whole viewport uniformly. It is not a per-sprite size override. Rendering should use nearest-neighbour sampling so 16×16 pixels stay sharp.

21.4 Viewport, camera and zoom

In normal play the viewport is always centered on the local player's character. The camera does not free-pan. Scrolling the world happens only because the player moved.

The player may zoom in and out within configured minimum and maximum bounds (for example 1× to 4×; the exact numbers are a game setting). Zoom does not move the camera off the player and does not change server visibility: the client still receives only the 3×3 chunk window.

The admin world editor is the exception: it frames the selected 16×16 chunk and navigates by chunk, as in section 8.1.

21.5 Client movement interpolation

The server jumps mobiles from tile to tile. The client draws a visual lerp between the previous replicated tile and the new one over the interval implied by gait and WorldSettings (walk: 1 / walkTilesPerSecond, run: half of that). If a delta arrives late, clamp the remaining lerp. That lerp is presentation only:

  • Hit tests, range, pickup and occupancy use the authoritative tile.
  • A corrected server position snaps the interpolation target; the client

does not accumulate drift.

  • Interpolation does not entitle the client to send fractional positions.

21.6 Equipment layers and recolouring

A mob (including a player character) is drawn as a stack of 16×16 sprites on the same tile: the body sprite (male or female from character sex, or the mob archetype body), then each piece of visible equipment. Overlays are not baked into the body art.

draw order (back → front, default)
  1. body / mob base
  2. boots
  3. legs
  4. chest
  5. head
  6. off-hand
  7. weapon

Slot draw order is data so a cloak or a two-handed sprite can be inserted without a renderer rewrite. Every overlay sprite, like every other world sprite, is exactly 16×16 and is rejected on load / CI if it is not.

Equipment items stay in dedicated equipment slots, not in the 32 inventory slots, while worn. EquipItem(slotIndex) moves a legal item from inventory into the matching equipment slot, returning any previously worn item to inventory if there is space. UnequipItem(equipSlot) does the reverse. The weapon equipment slot is what combat uses; it replaces the older “wielded flag on an inventory slot” idea.

Non-player mobs may carry an Equipment component or a simpler appearance list on the mob definition so a guard can show armour without a player inventory.

Equipment
- slots: { head?, chest?, legs?, boots?, weapon?, offhand?, ... }

ItemDefinition.equipment?
- slot
- overlaySpriteId
- recolourableChannels?: ["metal"]   // omitted if the art is not recoloured
- materialId?                        // e.g. iron, steel; used with "metal"

Inventory icons and worn overlays may be different 16×16 files. Both are world sprites and both go through the size check.

Recolourable equipment

Some gear shares one overlay and is tinted per material. Metal armour is the initial case: iron, steel and later metals are not separate full-size art sets.

MaterialDefinition
- materialId            // iron, steel, ...
- displayName
- channel               // metal for armour; later channels may include cloth
- colour                // destination RGB for that channel

A recolourable overlay is authored as:

  • the 16×16 overlay sprite, with shading in the channel regions, and
  • an optional 16×16 channel mask of the same dimensions, whose pixels

name which recolour channel they belong to (for example a reserved mask colour meaning metal). Unmasked pixels are drawn unchanged.

At draw time, masked pixels keep the overlay’s relative brightness (highlights and shadows) and replace the hue/saturation with the item’s MaterialDefinition.colour. The client must not invent a colour; the server sends the material id (or the already-resolved colour) on the appearance layer.

Iron plate and steel plate therefore share overlaySpriteId = platebody and differ only by materialId. Non-metal unique art omits recolourableChannels and is blitted as authored.

Recolour happens on the client as a presentation step. It does not change item identity, combat stats or inventory. Nearby observers receive enough appearance data to apply the same layers and tints.

21.7 World time and night shading

The client treats world time as server time minus 1200 years (section 13.5). It uses that clock-of-day to shade the 3×3 view.

At night, tiles that the baked light map says are unreachable from any static light are drawn darker. Tiles a light can reach stay brighter. Light does not bleed through walls: the mask was raycast through passable tiles at editor save, including across chunk borders, so a torch on the edge of one chunk can light tiles in the next.

By day, ambient light is full and the baked mask does not darken the ground. The day/night curve (how dark “night” is, dusk length) can stay a world setting or a later tuning value; the invariant is that night uses baked reachability, not a per-frame raycast.

The world-editor night-to-day slider is the same shading function, driven by the slider instead of the clock, so an admin can preview a chunk at any light level without changing live world time.

22. Items, inventory and ground drops

22.1 Item definitions

Every obtainable object is an ItemDefinition. Stacking, uniqueness and later economy rules are data on that definition, not special cases in UI code.

ItemDefinition
- itemId
- displayName
- description
- seedValue               // base price before player-market adaptation
- stackable
- maxStackSize            // default 99 for stackable items
- uniqueInstance          // true for letters, filled cheques, and similar
- category: ingredient | intermediate | finished | document | other
- npcShopAllowed
- gatherSources
- craftingRecipe(s)
- dropTableSources
- attack?: AttackProfile  // weapons; omitted for non-weapons
- equipment?:             // worn/wielded visuals; see 21.6
    slot
    overlaySpriteId
    recolourableChannels?
    materialId?

A stackable item with no instance data merges with an identical itemId in the same container up to maxStackSize. Unique-instance items never merge; each occupies its own slot at quantity 1.

Currency is not an inventory item. Carried money is a numeric Currency balance on the player. Banked money is a numeric balance on that player's vault. Coins do not occupy inventory slots and cannot be dropped on the ground in this model.

How most items are obtained is specified later. Two source families already fit this model without changing it:

  • Ground-item spawners in the world editor, analogous to mob spawners.
  • Later harvesting from the environment by players.

Paper, blank cheques and letters are specified now because communication, banking and pigeons depend on them.

22.2 Player inventory

A player inventory has exactly 32 slots.

Inventory
- slots[32]: empty | ItemStack

ItemStack
- itemId
- quantity                 // 1 for unique-instance items
- instance?: ItemInstance  // present only when uniqueInstance is true
- origin?: ItemOrigin      // crafter or shop NPC; see 22.6

Rules:

  • A stack occupies exactly one slot, regardless of quantity.
  • Inserting a stackable item first tries to merge into an existing compatible

stack whose combined quantity would not exceed maxStackSize. Stacks are compatible only when itemId matches and origin matches (including both being empty). Any remainder needs an empty slot, or the whole action fails.

  • Moving, swapping and splitting stacks are ordinary server-validated

commands. The client never asserts the resulting inventory.

  • Inventory, wallet and vault contents are player-private UI state. They

are not part of 3×3 chunk replication. Other clients see ground items and pigeon entities, not another player's bags or a pigeon's cargo.

  • Logout and restart persist the full inventory and carried currency in

state.sqlite.

22.3 Paper and letters

Blank paper is a stackable item.

Writing consumes one paper and produces a letter: a unique-instance item whose instance data is text written by a player. A letter is not a mail record and has no inherent recipient. It is just paper with writing on it.

LetterInstance
- letterId
- authorPlayerId
- body
- writtenAt

If the paper stack's quantity is 1, the slot may be converted in place into the letter. If quantity is greater than 1, writing requires a free inventory slot for the new letter and decrements the paper stack.

Reading a letter inspects its instance data. Sending a letter is the same pigeon-cargo action used for any other item stack.

Maximum letter length is a defined game rule and can be chosen during implementation.

22.4 Dropping items

A player may drop an item stack, or part of a stack, onto their current tile.

GroundItem
- groundItemId
- tileX / tileY
- ItemStack
- droppedAt
- expiresAt               // droppedAt + WorldSettings.groundItemDespawnDuration
- source                  // player-drop | later: item-spawner
- droppedByPlayerId?

Rules:

  • Player-dropped items remain for WorldSettings.groundItemDespawnDuration

(default 10 minutes), then vanish forever.

  • Anyone may pick up a ground item. There is no owner lock and no loot-rights

delay.

  • Ground items do not block movement and do not prevent a player from

standing on that tile.

  • Pickup requires the player to stand on that tile. The command names the

groundItemId when several stacks share the tile.

  • Pickup fails if the player's inventory cannot accept the stack (no legal

merge and no empty slot). The ground item is unchanged.

  • Several distinct stacks may occupy one tile at once.
  • Later naturally spawned ground items use the same non-blocking

representation, but their lifetime and respawn belong to the item spawner rather than this 10-minute player-drop timer.

Dropped items are not ChunkLoaders and do not keep a chunk simulated.

They do survive chunk unload until expiresAt, using timestamp expiry rather than a per-tick countdown. On unload, unexpired ground items are written to state.sqlite. On load or wake, items whose expiresAt is in the past are discarded and never replicated. Simulating chunks also remove them when the timestamp elapses.

If a unique-instance item that encodes a bank reservation (a filled cheque) expires on the ground or is otherwise destroyed without being redeemed, that reservation is released and the reserved goods become available in the issuer's vault again.

22.5 Pickup and drop commands

DROP_ITEM(slotIndex, quantity?)
PICKUP_ITEM(groundItemId)

Both are intentions. The owning worker validates the actor's tile, inventory space and stack rules, then applies the result. Standing on a tile that has ground items does not pick them up automatically.

22.6 Item inspection, origin and displayed value

Hovering an item — in inventory, a shop stock list, or on the ground — shows at least:

ItemTooltip
- displayName
- description
- originLabel              // who crafted it, or the shop NPC if bought there
- currentValue             // undiscounted adapted value; see section 27

Origin is stored on the stack:

ItemOrigin
- kind: crafted | shop | unknown
- playerId?                // when crafted by a player
- npcId?                   // when bought from a shop NPC

The origin label is the crafting player's name, or the shop NPC's name when the stack was bought from that NPC. Harvested, looted or otherwise unstamped stacks use unknown and omit the origin line until later content says otherwise. Buying from a shop stamps that NPC as origin. Crafting stamps the crafter. Shop-bought goods are not treated as crafted by the NPC; the NPC name simply occupies that inspection field.

currentValue uses the same last-sale lerp as shopkeepers (section 27.6) but without the per-shop discount. It is informational. The client must not recompute it every simulation tick. The player UI may refresh displayed values at most once per minute, from the last-sale record plus seedValue. The actual shop purchase price is always computed server-side at the moment of purchase.

23. Player communication and carrier pigeons

23.1 Proximity chat is the default

Ordinary chat is spatial. A player speaks from a world position and only nearby players receive a useful version of the message. Legibility decreases as the recipient gets farther from the speaker.

For example:

Near:       I'm really far away
Farther:    I'm re...y far aw.y
Very far:   I'...re..ly..ar.aw.y
Beyond range: no message

The exact distance bands/function are configurable game rules.

Crucially, degradation is performed server-side. The server must not send the full plaintext to a distant client and merely ask that client to obscure it, because a modified client could then recover speech it was not supposed to understand.

A chat message therefore conceptually contains:

ChatSpeech
- messageId
- speakerEntityId
- originX / originY
- createdAt
- text

The communication service performs a spatial recipient query and derives the recipient-specific legible representation before routing it through the gateway. Chat routing is separate from normal 3×3 chunk replication, so the eventual hearing/text range does not have to equal the visual chunk-subscription radius.

23.2 Persistent player groups

Players can create permanent groups and invite other players into them. Groups are durable social entities stored in state.sqlite, with membership surviving logout and server restart.

A minimal model contains:

PlayerGroup
- groupId
- name
- owner / roles
- createdAt

PlayerGroupMember
- groupId
- playerId
- role
- joinedAt

Invite, accept, leave, kick and role-management operations are authoritative server actions.

Group membership does not create magical long-distance communication. If members are close enough, they can communicate through the normal proximity rules. Communication to distant group members means sending items — including letters — by carrier pigeon, the same mechanism available to any player.

If group-wide letter sending is later supported, it is an addressing convenience that still consumes one paper/letter item and one pigeon dispatch per recipient. The group is not a global instant chat channel.

23.3 Pigeons carry cargo, not messages

A carrier pigeon is a free physical courier. It does not send a chat packet. It carries either:

  • an amount of the sender's carried currency, or
  • exactly one item stack (a letter, a filled cheque, blank paper, or any

other stack)

One pigeon cannot carry both money and an item, and cannot carry two item stacks. Dispatching a pigeon is free, so a player who wants to move several stacks sends several pigeons one after another.

Cargo is removed from the sender immediately and placed into durable transit. A crash or restart cannot duplicate that cargo or silently erase it.

Pigeons are not inventory items. Any player may dispatch one from anywhere, provided they have valid cargo.

SendPigeon
- destination: Player(playerId) | Bank
- cargo: Money(amount) | Item(slotIndex, quantity?)

23.4 Destinations

Player destination. The pigeon flies toward the named player. On arrival:

  • Money is added to the recipient's carried Currency if they are online;

otherwise it is deposited into the recipient's bank.

  • An item stack is placed in the recipient's inventory if they are online and

have space (a legal merge or an empty slot). If they are offline or cannot accept the stack, the pigeon continues to the nearest bank and deposits the stack into the recipient's vault.

This keeps offline and full-inventory delivery durable without a separate mailbox object.

Bank destination. The pigeon flies to the nearest bank to the dispatch tile. Travel time is that aerial journey, even though every bank shares the same vault. On arrival the cargo is deposited into the sender's vault, except for the filled-cheque special case in section 24.7.

"Nearest bank" is computed from authored Bank block positions in the pinned world revision. If additional banks are added later, a pigeon sent to Bank still lands at whichever bank is closest to where it was dispatched; the goods then appear in the shared vault.

23.5 Carrier pigeon transit

A carrier pigeon must take time to cross the world; long-distance item and currency delivery is intentionally not instantaneous.

At MMO scale, however, every delivery should not keep an entire trail of regions fully stimulated merely so a pigeon can advance. The recommended model is a persistent courier transit record with world position/route/progress that can advance through dormant space using coarse path segments and timestamps.

CourierTransit
- courierId
- cargo                   // Money(amount) | ItemStack
- senderPlayerId
- destination             // Player(playerId) | Bank
- currentPosition
- route
- speed / timing state
- status

A carrier pigeon is part of the shared physical world, not a private visual belonging only to its sender or recipient. Whenever its calculated route passes through a simulating chunk, the courier should materialise there as a normal ECS Mob entity, regardless of whether the sender or recipient is nearby. Any client whose normal 3x3 chunk subscription includes that pigeon receives it like any other visible mobile entity and can therefore see unrelated pigeons flying past in the distance.

The visible pigeon does not receive ChunkLoader. It exists because the chunk is already simulating for some other reason. If it leaves the last relevant simulating chunk, its exact position/progress is folded back into the durable CourierTransit record and the ECS instance can disappear while the journey continues abstractly. If a dormant/unloaded part of its route later becomes simulated while the pigeon should currently be inside it, the owning worker materialises the pigeon at the position implied by the transit clock and route.

Dormant route                 Simulating chunk                 Dormant route

abstract transit  -------->  ECS pigeon visible to clients  -------->  abstract transit
                                  |       |       |
                               Player A Player B unrelated observer

This means a player standing halfway between sender and recipient can see the pigeon fly through their area even though the cargo has nothing to do with them. Unrelated clients receive the pigeon entity, not the cargo contents. It preserves the sense that deliveries physically cross the world without requiring thousands of deliveries to become thousands of permanent ChunkLoaders.

Because pigeons fly rather than use the ground navigation grid, their coarse route can initially be represented by direct or waypoint-based aerial segments. This makes deterministic materialisation from route + elapsed time considerably simpler than it would be for a ground-based courier.

If future gameplay allows pigeons to be intercepted, killed or rerouted anywhere along their journey, the transit model can be made progressively more detailed; that interaction is not required by the initial courier design.

23.6 Courier service

A dedicated CourierService should own durable cargo and delivery state. Simulation workers may own visible pigeon entities while the service owns the durable fact that a delivery exists.

Player action -> CourierService -> durable cargo/transit
                                  |
                                  +-> visible pigeon when needed
                                  |
                                  +-> inventory, wallet or BankService deposit

This separation is also useful for marketplace settlement, which uses the same carrier-pigeon delivery infrastructure for remote counterparties.

24. Bank, cheques and shared vaults

24.1 Bank location and access

A bank exists at or near the central marketplace as an authored Bank block. Deposit, withdraw, cheque issue and in-person cheque redemption require server-validated access to a bank interaction; the bank is not a global menu usable from anywhere.

Pigeon dispatch to Bank is the exception: that command may be issued from anywhere, and the goods become available only after the pigeon arrives.

24.2 One shared vault

Each character has a single vault in state.sqlite:

CharacterVault
- characterId
- bankedCurrency
- stacks[]
- reservations[]

Capacity is unlimited: there is no slot cap. Per-stack stacking rules still apply (maxStackSize; unique instances never merge), so 200 blank paper is stored as 99 + 99 + 2 rather than one unbounded pile.

If more banks are authored later, all banks are linked. Withdrawing at bank B can retrieve goods deposited at bank A. The vault is not per-branch.

Pigeon deposits affect when goods become available, not which vault they enter. After the pigeon arrives at the nearest bank, the goods appear in the same shared vault accessible from every bank.

24.3 Deposit and withdraw

While interacting with a bank, a player may:

  • Deposit any carried currency and any inventory stacks, in whole or in part.
  • Withdraw currency into the carried wallet.
  • Withdraw an item stack, or part of a stack, into inventory, subject to the

32-slot and merge rules.

  • Claim items or currency from the account inheritance tab into this

character's vault (section 24.9).

Goods reserved by an outstanding filled cheque cannot be withdrawn by the issuer until that cheque is redeemed or voided.

24.4 Blank cheques

A player at a bank may request blank cheques.

  • Blank cheques are a stackable item with maxStackSize 99.
  • The bank counts blank cheques already in the player's inventory (not

the vault) and issues only enough to bring that total to 99.

  • If the player already holds 99, the bank issues none.
  • Issued cheques go into inventory, merging into an existing blank-cheque

stack when possible. If the player holds none and has no empty slot, the request fails.

The bank will not issue more than 99 blank cheques into inventory, even on repeated requests.

24.5 Filling a cheque

Using a blank cheque at a bank lets the issuer pick vault goods and a quantity. For stackable items they choose an itemId and quantity; the quantity may be larger than one maxStackSize, and the reservation covers that many available (unreserved) items of that type in the vault. For unique-instance items they choose that exact instance and the quantity is 1.

FilledChequeInstance
- chequeId
- issuerPlayerId
- itemId
- quantity
- instance?: ItemInstance   // set when the reserved goods are unique
- createdAt

Filling:

1. Validates that the vault has at least quantity of that item available (not already reserved). Unique instances must still be present and unreserved. 2. Reserves those goods in the issuer's vault. Reserved goods cannot be withdrawn, sold or reserved again. 3. Consumes one blank cheque. If that was the last cheque in the slot, the slot becomes the filled cheque in place; otherwise a free slot is required for the filled cheque.

A filled cheque is a unique-instance bearer item. It does not stack. Whoever holds it may redeem it. Cheques specify vault items and a quantity, not carried currency. Money is moved with a pigeon, or by depositing and withdrawing at a bank.

24.6 Redeeming a cheque in person

The bearer interacts with any bank and redeems the filled cheque.

  • The server moves the reserved goods from the issuer's vault into the

bearer's inventory, subject to inventory space. A quantity larger than maxStackSize becomes as many stacks as needed.

  • The cheque item is consumed.
  • If inventory cannot accept the resulting stacks, redemption fails and both

cheque and reservation remain unchanged.

The bearer may then deposit those goods into their own vault if they wish.

24.7 Redeeming a cheque by pigeon

If the bearer dispatches a pigeon whose cargo is a filled cheque and whose destination is Bank:

  • The pigeon flies to the nearest bank from the dispatch tile.
  • On arrival, BankService transfers the reserved goods from the issuer's

vault into the pigeon's sender's vault.

  • The cheque is consumed in transit; it is not deposited as an item.

The receiver of the transfer is whoever sent that pigeon, not the original cheque issuer. This is how a cheque moves goods from one vault to another without the receiver standing at a bank.

Sending a filled cheque to a player delivers the cheque item itself (or into that player's bank if they cannot hold it). It does not redeem it.

24.8 Bank service

Vault mutation, cheque issue, reservation, in-person redemption and pigeon-arrival deposits are owned by a single authoritative BankService (or an equivalently serialised service) so two concurrent withdrawals, cheque fills or pigeon arrivals cannot double-spend the same goods.

Bank interaction or pigeon arrival
        |
        v
BankService
  - shared vault
  - reservations
  - cheque issue / redeem
        |
        +-> inventory / currency on the acting player when in person
        |
        +-> vault credit on pigeon arrival

Cheque identifiers are server-issued. A client cannot forge a claim against another player's vault.

24.9 Inheritance bank tab

Each account has one inheritance tab, separate from every character vault:

AccountInheritance
- accountId
- currency
- stacks[]

It is written only when a character of that account is permanently deleted (section 14.6). Any of that player's living characters can move stacks and currency from this tab into their own vault at a bank. They cannot deposit into inheritance except through character deletion.

25. Central marketplace and order matching

25.1 Marketplace location

A central marketplace exists at or near the centre of the game world. Creating, modifying or cancelling market orders requires server-validated access to the marketplace interaction; the marketplace is not intended to be a global menu that can be used from anywhere.

Orders themselves remain durable after the player leaves the marketplace or logs out.

25.2 No public list of sell orders

The market is an order book, but players do not browse a list of individual items currently offered for sale.

A seller submits:

SellOrder
- item / item definition
- quantity
- minimum unit/total price

A buyer submits:

BuyOrder
- requested item / matching criteria
- quantity
- maximum unit/total price

The UI may know which item types exist and may eventually show historical data, but it does not expose the live asks in a way that lets a buyer simply pick a listed seller.

25.3 Escrow

Market orders escrow the asset required to honour them. Escrow is taken from carried inventory and carried currency. The marketplace sits next to the bank, so a player can withdraw from the vault immediately before placing an order.

  • Creating a sell order removes/reserves the offered item stack from the

seller's inventory.

  • Creating a buy order removes/reserves the buyer's maximum offered currency.
  • Cancelling an unmatched order returns the escrowed asset through the defined

settlement/delivery rules.

This prevents double spending, selling the same item twice, or a buyer spending currency after placing a bid.

25.4 Matching rules

A buy and sell order match when:

buyerMaximum >= sellerMinimum

Sell orders are considered cheapest first. Within the same minimum price, a stable creation sequence/FIFO rule should be used unless later game rules choose otherwise.

For a symmetric order book, buy orders are naturally prioritised by highest maximum bid and then oldest sequence. This means a newly submitted sell order matches the best compatible existing bid, while a newly submitted buy order matches the cheapest compatible existing ask.

The trade price is exactly the midpoint between the two limits:

tradePrice = midpoint(buyerMaximum, sellerMinimum)

Example:

Seller minimum:  80
Buyer maximum:  100
Trade price:      90

The exact rounding rule when integer currency produces a half-unit midpoint is a defined-but-still-open game rule and must be deterministic.

25.5 Immediate side versus pigeon side

The order that is submitted last is the order that triggers the match.

The player who submitted that matching order receives the acquired asset immediately because they are currently present at the marketplace interaction (item stack into inventory, or currency into the carried wallet). The pre-existing counterparty receives their acquired item or currency through a carrier pigeon whose destination is Bank, landing at the nearest bank to the marketplace. On arrival the settlement is deposited into that counterparty's shared vault. This remains valid if they are offline.

Existing sell + new matching buy
-> new buyer receives item immediately
-> existing seller receives payment by pigeon to bank

Existing buy + new matching sell
-> new seller receives payment immediately
-> existing buyer receives item by pigeon to bank

If a trade requires more than one item stack (for example a quantity that does not fit in a single maxStackSize), the older counterparty receives as many free sequential pigeons as needed. Each pigeon still carries only one stack or only currency.

Any unused part of buy-order currency escrow caused by the midpoint price is returned immediately to the triggering player when they are the buyer, and returned by the settlement pigeon into the older counterparty's vault when they were the buyer.

25.6 Market service and atomicity

Marketplace matching should not live inside an arbitrary region worker. Use a single authoritative MarketService (or an equivalently serialised partitioned service later) so two simultaneous orders cannot both consume the same escrow.

Order insertion, matching, escrow movement and creation of the resulting settlement deliveries are committed atomically in state.sqlite.

Conceptually:

Marketplace interaction
        |
        v
MarketService
  - durable order book
  - escrow
  - deterministic matching
  - trade record
        |
        +-> immediate settlement to triggering player's inventory or wallet
        |
        +-> CourierService pigeon to Bank for the older counterparty
        |
        +-> last-sale index update for that itemId

The system should also retain an immutable trade record for auditing and recovery.

25.7 Last player-market sale per item

Each successful player-market match updates a single durable record for that itemId. There is no price history series — only the latest sale:

ItemLastMarketSale
- itemId
- lastTradePrice           // unit price of that match (the midpoint)
- lastTradeAt
- priceFrom                // evaluated undiscounted value at lastTradeAt

priceFrom is not a history log. It is the lerp origin captured at the moment of this sale so the displayed price does not jump back to seed when a new trade occurs:

1. Evaluate the current undiscounted value at now using the previous last-sale record (or seedValue if none exists). 2. Store that value as priceFrom, store the new trade's unit price as lastTradePrice, and store now as lastTradeAt.

Shopkeepers and item tooltips both read this record. They do not tick it; they evaluate it from timestamps when a shop is opened, a purchase is attempted, or a tooltip refresh is requested.

26. Combat

26.1 Every combatant can attack

Players, enemies, animals and any other mobile with a Combat component can attack. Shopkeepers and other non-fighting NPCs simply omit Combat, or never issue attack commands.

Attacking is an intention. The client (or AI, or a future script) sends ATTACK(targetEntityId). The owning worker validates range, line-of-use, the current attack profile and cooldown, then resolves hit and damage authoritatively. The client never supplies a hit result or a damage number.

Cross-worker attacks already use REMOTE_ACTION(attack intent): the worker that owns the target applies the authoritative result.

26.2 Attack profiles

The current attack comes from the wielder's selected profile: a wielded weapon's AttackProfile, a selected spell, or a default unarmed melee profile when nothing is wielded.

AttackProfile
- attackId
- mode: melee | ranged | magic
- rangeTiles               // melee is always 1; ranged/magic from the item or spell
- hitSkillId
- damageSkillId
SpellDefinition
- spellId
- displayName
- AttackProfile            // mode = magic, hitSkillId = Magic, damageSkillId = Mind
- other costs/effects      // later content

Typical weapon mappings:

Sword     -> melee,  range 1,           hit Swordfighting, damage Strength
Axe       -> melee,  range 1,           hit Axefighting,   damage Strength
Bow       -> ranged, range from item,   hit Archery,       damage Dexterity
Spell     -> magic,  range from spell,  hit Magic,         damage Mind
Unarmed   -> melee,  range 1,           hit Unarmed,       damage Strength

The exact weapon and spell catalogue is content. The pairing rule is not: melee weapons use a weapon skill plus Strength, ranged weapons use a weapon skill plus Dexterity, and spells use Magic plus Mind.

EquipItem(slotIndex) moves a legal item from inventory into the matching equipment slot (section 21.6). The weapon slot supplies the current AttackProfile. SelectSpell(spellId) selects a spell the actor is allowed to use. The selected profile determines range and both skills.

26.3 Melee range

A melee attack is legal only when the attacker stands on one of the eight tiles surrounding the target's tile: orthogonal or diagonal, Chebyshev distance exactly 1. The attacker cannot melee from the target's own tile.

. . .
. T .     attacker must occupy one of the eight `.` tiles
. . .

This adjacency rule is independent of whether ordinary walking is four- or eight-directional.

26.4 Ranged attacks and spells

Ranged weapons and spells may fire from further away. Maximum Chebyshev distance is rangeTiles on that item or spell. Distance 0 (same tile) is not a legal ranged/spell attack unless a later exception is defined.

The attacker must still occupy a simulating chunk and satisfy any later line-of-sight rule. Exact obstruction rules are an open content decision; range itself is not.

26.5 Hit roll

Whether the attack lands is a server-side roll driven by the hit skill of the current profile (Swordfighting, Axefighting, Archery, Magic, Unarmed, and so on). The client does not roll.

The exact hit curve, any defender contribution from Defence, and the RNG are later tuning. The invariant is that the hit chance is a function of the attacker's hit-skill level, not of Strength, Dexterity or Mind.

A miss deals no damage.

26.6 Damage

On a hit, damage is determined by the damage skill:

  • Melee → Strength
  • Ranged → Dexterity
  • Magic → Mind

Weapon or spell base damage and the defender's mitigation (including whether Defence reduces damage) are later tuning. The governing damage skill is not.

26.7 Experience split

When a player successfully hits, the attack's XP award is split equally between the hit skill and the damage skill:

totalXp = attack xp formula for this successful hit
hitSkill     += totalXp / 2
damageSkill  += totalXp / 2

Example: a sword hit awards half its XP to Swordfighting and half to Strength. A bow hit splits Archery and Dexterity. A spell hit splits Magic and Mind.

If an unusual profile ever named the same skill twice, XP is awarded once, not doubled. Misses award no combat XP. Ordinary mobs do not earn XP; their Skills component is filled from the mob archetype and stays at those levels.

Non-combat actions remain single-skill as in section 27.4.

26.8 Mob combat stats

MobDefinition
- ...
- skillLevels: { skillId → level }
- defaultAttack: attackId | unarmed

A wolf might have Unarmed and Strength. An archer guard might have Archery and Dexterity. Those levels feed the same hit and damage resolution as players.

27. Player-driven economy and skill progression

27.1 Item-source philosophy

The economy is intentionally player-driven.

Normal NPC shops should sell only basic ingredients. The vast majority of materials are gathered directly from the world by players. Finished goods are normally produced by player crafting/professions.

The only normal non-player source of finished items is enemy or boss loot.

This gives four broad source paths, with ground-item spawners as an additional early world source once content defines them:

World gathering / harvesting -> ingredients
Ground-item spawners --------> some world items, later specified
Basic NPC shops -------------> limited basic ingredients
Player production -----------> intermediate/final products
Enemies and bosses ----------> loot, including possible finished items

Stacking, unique instances, letters and cheques are defined in section 22. Economy-facing fields remain on the same ItemDefinition:

ItemDefinition
- itemId
- displayName / description / seedValue
- stackable / maxStackSize / uniqueInstance
- category: ingredient | intermediate | finished | document | other
- npcShopAllowed
- gatherSources
- craftingRecipe(s)
- dropTableSources
- attack?: AttackProfile
- equipment?: slot / overlaySpriteId / recolourableChannels / materialId

Content validation can then reject an ordinary shop inventory that accidentally contains a finished product unless explicitly permitted by a future exception.

27.2 No player classes

Players do not choose a class. Capabilities and progression come from independent skills.

Examples include:

  • Swordfighting, Axefighting, Archery, Magic, Unarmed
  • Strength, Dexterity, Mind
  • Defence
  • Lumbering
  • Fishing
  • Smithing

The final skill list is game content and is not limited to skills found in any particular inspiration game.

27.3 Skill state

Skill progression is persistent player state.

SkillProgress
- skillId
- xp

Level should preferably be derived from XP and the skill's level curve rather than stored as an independent source of truth, although it may be cached.

SkillDefinition
- skillId
- displayName
- levelCurve
- maxLevel (if any)

27.4 Actions are governed by skills

Every gameplay action that participates in progression is associated with a governing skill. Combat attacks are the explicit exception: they have a hit skill and a damage skill, and split XP equally between them (section 26.7).

ActionDefinition
- actionId
- governingSkillId
- requiredLevel
- xpAward / xpFormula
- other requirements

Examples:

Cut tree        -> Lumbering
Catch fish      -> Fishing
Forge sword     -> Smithing
Sword hit       -> Swordfighting + Strength (equal split)
Bow hit         -> Archery + Dexterity (equal split)
Spell hit       -> Magic + Mind (equal split)
Defensive act   -> Defence

The server validates the action, performs the authoritative outcome, and then awards XP according to the action result. A client cannot claim XP independently.

27.5 Skills replace class restrictions

Equipment, recipes, actions, gathering nodes and other content may require skill levels, but there is no permanent class gate. A player can train any combination of skills over time.

This also fits the future scripting model: scripts issue normal actions, and successful scripted actions use exactly the same skill checks and XP rules as manual player actions.

27.6 NPC shops and market-adapted prices

Named shop NPCs can sell items to players. They are not the player marketplace and they do not expose live sell orders. A shop interaction requires being at that NPC.

Stock remains constrained by npcShopAllowed and the ingredient-only rule in 27.1. Each shop NPC has a hidden discount that players never see:

ShopNpc
- npcId
- hiddenDiscount           // multiplier, e.g. 0.9; not shown to clients
- stock[]                  // itemIds this NPC sells

Until an itemId has a player-market last-sale record, the undiscounted value is seedValue from the item definition.

When a last-sale record exists, both tooltips and shops evaluate a timestamp lerp that does not require a per-tick update:

t = min(1, (now - lastTradeAt) / WorldSettings.shopPriceLerpDuration)
undiscounted = lerp(priceFrom, lastTradePrice, t)
shopPrice    = undiscounted * thatNpc.hiddenDiscount

lerp(a, b, t) = a + (b - a) * t. After the configured lerp duration (default one hour), t is capped at 100% and the value rests on the last player-market unit price (times discount, for shops) until another player-market sale occurs.

A new player-market sale captures the then-current undiscounted value as priceFrom (section 25.7), so the lerp restarts toward the new last price without jumping back to seed.

Integer currency must be rounded deterministically at evaluation time. Shop purchase price is computed on the server at the instant of BuyFromShop. Displayed tooltip value is the undiscounted figure and may be refreshed at most once per minute (section 22.6).

Buying from a shop removes the listed price from the player's carried currency, puts the stack in inventory subject to the 32-slot rules, and stamps ItemOrigin.kind = shop with that NPC. Shops in this model sell to players; they do not buy player goods unless a later iteration adds that.

28. Suggested implementation phases

Phase 1 — Single-worker playable core

  • World coordinate helpers, 16×16 chunks and 4×4-chunk regions.
  • Ground/block tile model and chunk spatial occupancy.
  • Basic ECS and fixed simulation tick.
  • ChunkLoader reference counting and sleeping/unloading.
  • Single simulation worker behind the same worker interface planned for

later scaling.

  • world.sqlite read path and state.sqlite persistence service.
  • Admin world editor: chunk navigation, open/closed flag, default grass for

unsaved chunks, ground/block paint, light-emitting blocks, baked cross-chunk light maps, night-to-day preview slider, world settings modal, per-chunk changelog, save to pending revision.

  • SpawnerSystem for at least one non-persistent mob archetype.
  • WebSocket gateway, stub admin-<n> auth until auth.timfalken.com,

character create/select/delete, authoritative command queue and 3×3 chunk replication.

  • Click-to-move with server-side A\*, global walk/run cadence (default 2

tiles/s walk, run every movement tick, walk every other), and SetGait.

  • FrameworkV3 git submodule at client/frameworkv3, built first, then a

game-specific client on top of it with 16×16 sprites, load-time and CI rejection of wrong-sized art (including equipment overlays and recolour masks), layered worn equipment with material recolouring, a player-centered viewport with bounded zoom, client-only lerp of tile-to-tile movement, and night shading from baked light maps.

  • 32-slot player inventory, stack merging, drop/pickup, and 10-minute

non-blocking ground items.

  • Paper items that can be written into unique letter items.
  • Basic proximity chat with server-side distance degradation.
  • Persistent player skill state, including Strength, Dexterity and Mind, and

at least a small initial set of skill-governed actions.

  • Melee and ranged/spell attack validation (8-tile melee adjacency, item/spell

range), server-side hit rolls, damage from the matching damage skill, and equal XP split on a successful player hit.

  • Graceful forced-unload shutdown.

Phase 2 — Operations and live deployment

  • RestartScheduler and player-visible scheduled restart state.
  • origin/master change detection.
  • systemd service supervision and conditional deployment hook.
  • World-revision activation on restart.
  • Admin immediate restart.
  • Migration, backup and startup readiness checks.

Phase 3 — Multi-worker world

  • Multiple worker_threads simulation workers.
  • Region coordinator and dynamic region ownership.
  • Cross-worker entity transfers.
  • Border ghosts and remote actions.
  • Gateway subscriptions spanning multiple workers.
  • Load metrics and neighbour-aware region balancing.

Phase 4 — World depth, social systems and economy

  • Persistent named NPCs and other persistent mob archetypes.
  • Spawner persistent-instance index and duplicate prevention.
  • Optional durable gameplay chunk overrides, written only on unload.
  • Hierarchical pathfinding if long-distance autonomous travel needs it.
  • Persistent player groups and invitations.
  • Carrier-pigeon cargo transit: free dispatch, money or one item stack,

player or nearest-bank destinations, including offline/full-inventory fallback to the recipient vault.

  • Shared unlimited character bank near the marketplace, account

inheritance tab on character delete, blank cheques filled to 99, reserved filled cheques, in-person redemption and pigeon-to-bank cheque transfers.

  • Central marketplace, escrow, deterministic order matching, pigeon-to-bank

settlement for the older counterparty, and a per-item last-sale record for shop/tooltip adaptation.

  • NPC shops that sell npcShopAllowed stock at seed value lerped toward the

last player-market price over shopPriceLerpDuration, with a hidden per-shop discount.

  • Item inspection: name, description, origin (crafter or shop NPC) and

undiscounted current value, refreshed at most once per minute.

  • Player crafting/gathering economy rules and shop-content validation.
  • Broader skill catalogue, progression curves and skill-gated content.

Phase 5 — Player scripting

  • Custom language grammar/compiler/interpreter.
  • ScriptController and event API.
  • CPU/memory/query quotas and sandboxing.
  • Online scripted control mode.
  • Offline retained player entities with expiry and ChunkLoader

behaviour.

  • Persisted/restart-safe script state.

29. Core invariants

InvariantRule
Server authorityClients send intent; the server computes and owns outcomes.
Region ownershipExactly one simulation worker authoritatively owns a region.
Entity ownershipExactly one worker authoritatively owns an entity.
Remote mutationWorkers never directly mutate remote authoritative state.
Spatial separationRegion residency, chunk simulation and client visibility remain distinct.
Persistence separationPersistent and ChunkLoader are independent entity traits.
Chunk persistenceNormal dirty chunk state is written on unload, not periodically.
World authoringEditor changes create pending authored state; the running server stays pinned to its startup revision. Each chunk save appends an admin-attributed diff changelog.
Restart pathPlanned restart force-unloads the world and reuses the ordinary unload save path.
ControlHuman and future scripted control both emit validated action commands.
DeploymentThe game exits gracefully; systemd relaunches it and only pulls/builds when an intentional deployment manifest requests it.
Client architectureFrameworkV3 is a git submodule under client/frameworkv3, built before game client code; backend ECS internals do not become the client object model.
SpritesAll world sprites are exactly 16×16 pixels; any other size is rejected on load and fails CI. Equipment overlays and recolour masks are included.
AppearanceVisible gear is layered 16×16 overlays on the mob; recolourable channels (such as metal) use material colour without duplicate art sets. Nearby clients receive appearance layers, not another player's inventory.
Play cameraThe play viewport is centered on the local player. Only the admin world editor uses a free chunk camera.
MovementAll ground mobiles share a global walk/run cadence from world settings; the server commits integer tiles; clients lerp for presentation only.
World timeWorld calendar time is server time minus 1200 years. Night darkens tiles the baked light map cannot reach.
World settingsTick timers and global constants are authored in the editor modal, pinned to the world revision, and not hot-patched into a live process.
Baked lightStatic light reach is raycast through passable tiles on chunk save, may cross chunks, and is not recomputed every tick.
Ground itemsPlayer drops last groundItemDespawnDuration (default 10 minutes), block nobody, and are picked up only by a player standing on that tile.
Shop pricesNPC shop prices lerp from the captured pre-sale value toward the last player-market unit price over shopPriceLerpDuration (default one hour), times a hidden per-shop discount.
Proximity speechDistant clients never receive unobscured plaintext that game rules say they cannot understand.
Courier cargoPigeons carry money or one item stack, never a chat packet; cargo is durable in transit and remains delayed.
InventoryA player has 32 slots; a stack occupies one slot; the client never asserts inventory, wallet or vault results.
Shared bankEvery bank reads the same character vault; pigeon deposits become available only after arrival at the nearest bank.
Closed chunksClosed or never-edited chunks are visible but not enterable; never-edited terrain is default grass with no blocks.
AccountsLogin is auth.timfalken.com (or admin-<n> stub). Characters belong to an account; one may be in the world at a time.
NamesSurnames are globally unique per account; first+last is unique per account; names free only after permanent delete.
InheritanceDeleted characters dump inventory, equipment, wallet and vault into an account inheritance tab other characters can claim.
ChequesFilling a cheque reserves vault goods; the bearer item is the claim; destruction without redemption releases the reservation.
Marketplace escrowEvery open order is fully backed by escrow and matching/settlement is atomic and deterministic.
CombatMelee requires an 8-neighbour tile; ranged/spell range comes from the item or spell; hit uses the weapon skill; damage uses Strength, Dexterity or Mind.
ProgressionPlayers have no classes; non-combat actions award XP to one governing skill; a successful attack splits XP equally between hit and damage skills.

30. Important edge cases to preserve during implementation

  • A ChunkLoader crossing a region boundary can change

residency/simulation references and worker ownership in the same tick; ordering must avoid temporary double ownership.

  • A player at a worker boundary may receive visible chunks from multiple

workers without moving ownership solely for rendering.

  • A planned restart must ignore normal ChunkLoader retention when

forcing the world to unload.

  • A world-editor save must never cause newly loaded chunks in the

current process to use the pending revision. It must append a changelog record naming the admin, timestamp and tile diffs.

  • Pathfinding and player movement must reject tiles in closed or

never-edited chunks even when those chunks are in the 3×3 view.

  • Two accounts must not claim the same surname. One account may reuse its

surname; first+last must stay unique on that account until permanent delete.

  • Marking a character for deletion must not free the name or move items

until the delay elapses. Cancelling must restore playability.

  • Character deletion must notify the account email (or log, on stub auth).

Permanent delete must void that character's issued cheques, then move inventory, equipment, wallet and vault into the account inheritance tab.

  • Saving a chunk must rebake that chunk's light map and any neighbour

chunks within max light range, using passable-tile raycasts. Light from a source in chunk A may appear in chunk B.

  • A mob definition must not carry its own walk/run speed; gait only

selects every-other vs every movement tick on the global cadence.

  • World-settings saves must not apply to the live process; they wait for

the same pending-revision restart as chunk edits.

  • Night shading must not light a tile the baked mask marks unreachable,

even if a torch is nearby through a wall.

  • A sprite whose pixel size is not 16×16 must be rejected at load and must

fail the sprite-dimension unit test. Equipment overlays and recolour masks are included.

  • Equipping must not leave two items in the same equipment slot. Unequip

into a full inventory must fail and leave the item worn.

  • Nearby clients must not receive another player's inventory in order to

draw their armour; appearance layers and material ids are sufficient.

  • A client build without client/frameworkv3 initialized must fail rather

than silently using some other FrameworkV3 install.

  • Client interpolation of movement must not be treated as authority. Combat

range and pickup use the server tile, not the lerped draw position.

  • The play camera must remain centered on the local player. Zoom must not

expand the subscribed chunk set.

  • A persistent mob spawned by a spawner must not be duplicated merely

because it moved out of the spawner’s loaded area.

  • A non-persistent mob disappears when its chunk is actually unloaded,

not merely when it becomes dormant.

  • If a persistent ChunkLoader or offline scripted player exists after

restart, startup must discover it from an index without loading the entire world.

  • A pending code update followed by an unrelated Node.js crash must

restart the currently deployed commit rather than deploying early.

  • Negative coordinates, daylight-saving midnight calculation, duplicate

transfer messages and failed deployment migrations should all have explicit tests.

  • Proximity chat degradation must happen before plaintext reaches an unauthorised

distant client; rendering-only obfuscation is not sufficient.

  • Carrier-pigeon deliveries must survive restarts and recipient logout without

requiring every traversed chunk to remain stimulated.

  • A pigeon carrying an item to a player whose inventory cannot accept it must

not destroy the cargo; it deposits into that player's vault via the nearest bank.

  • Two concurrent bank withdrawals, cheque fills or pigeon-arrival deposits must

not spend the same vault goods twice.

  • Filling two cheques against the same vault stack must reserve disjoint

quantities or reject the second fill.

  • A filled cheque that expires on the ground must release its reservation and

must not remain redeemable.

  • A player-dropped ground item must not block movement, must not keep its chunk

loaded, and must still be present after a chunk unload/reload if expiresAt has not passed.

  • Pickup of a ground item from a tile the player is not standing on must fail.
  • Requesting blank cheques must never raise the player's carried blank-cheque

count above 99.

  • A marketplace match must atomically consume both escrows exactly once, even if

two compatible orders arrive concurrently.

  • A matching market order from an online player may settle immediately for that

player while the older/offline counterparty's delivery remains durable.

  • Skill XP is awarded only after authoritative action resolution, never directly

from a client-reported result. A successful player attack splits that XP; a miss awards none.

  • A melee attack from the target's own tile, or from Chebyshev distance greater

than 1, must fail. A ranged or spell attack beyond that item or spell's rangeTiles must fail.

  • A new player-market sale must capture the then-current undiscounted lerp

value as priceFrom so shop and tooltip prices do not jump back to seed.

  • Two shop NPCs may charge different prices for the same item at the same

instant because each applies its own hidden discount to the same lerp.

  • Item tooltip value must not be recomputed every tick; a one-minute refresh

is sufficient. Purchase price is still evaluated at the moment of buy.

31. Decisions through version 0.12

  • Chunk persistence is unload-driven rather than periodic.
  • The authored tile model has separate visual ground and functional

block layers.

  • Mobile actors remain ECS entities and are not authored as painted tile

contents.

  • Spawner blocks are editor-placeable and configurable per instance;

persistence belongs to the spawned mob type.

  • world.sqlite is an authored, revisioned world source; state.sqlite

holds runtime durable state.

  • Editor changes are staged for activation on restart instead of

hot-patching the running world.

  • Code/world changes schedule a player-visible midnight restart; admins

can trigger the same graceful pipeline immediately.

  • Git pull/build/relaunch belongs to systemd supervision after the

game process has safely exited.

  • Deployment is manifest-driven: crash recovery restarts the currently

checked-out commit, while only an intentional deployment restart may fast-forward master.

  • Future player scripting is modelled as an alternative controller

producing normal server action commands.

  • Offline scripted players may remain in-world as ChunkLoaders until

death or expiry and must survive planned restarts through persistence.

  • The player client is built on FrameworkV3, included as the git submodule

client/frameworkv3 and built first so this game's client code can layer on top. The client does not need an ECS and consumes protocol state independently of backend ECS storage. The Node.js server does not import FrameworkV3.

  • All world sprites (tiles, blocks, mobs, items) are exactly 16×16 pixels.

Other sizes are rejected at load. A unit test lists offenders and fails if any exist. Sprites are not individually resized; the player may zoom the whole viewport within configured bounds.

  • Visible equipment is drawn as extra 16×16 layers on the mob, including

players. Worn items occupy equipment slots, not the 32 inventory slots. Nearby clients replicate appearance layers only, never another player's inventory.

  • Recolourable gear (metal armour) shares one overlay sprite and a 16×16

channel mask. Material definitions supply the metal colour; luminance of the overlay is preserved. Iron and steel plate are different items with the same art and different materialId.

  • The play camera is always centered on the local player. The admin world

editor is the only exception, and it frames one chunk at a time.

  • Authoritative movement is a tile-to-tile jump on a global cadence:

default walk 2 tiles/s, run double. Walk steps every other movement tick; run steps every movement tick. Mobs do not set their own speed. Clients lerp for visuals only and never send interpolated positions.

  • Admins edit global tick timers and constants in a world-settings modal.

Those values live in the pending world revision and apply on the next process start, like other editor saves.

  • World calendar time is server time minus 1200 years, same IANA zone as

midnight restarts. At night the client darkens tiles the baked light map cannot reach.

  • Static light is baked on chunk save by raycast through passable tiles,

including across chunk borders. The editor has a night-to-day slider for preview only.

  • Each world-editor chunk save stores who edited it, when, and a bullet

diff of ground changes, block placements, block replacements and block removals at world tile coordinates.

  • Default speech is proximity-based and becomes less legible with distance.

Long-distance exchange is physical: a pigeon carries money or one item stack. A letter is paper with player-written text, not a separate mail record.

  • Permanent player groups are social/addressing structures and do not create an

instant global chat channel.

  • Carrier-pigeon transit is persistent but does not automatically keep every

traversed chunk simulated. Whenever a pigeon passes through a chunk that is already simulating, it materialises as an ECS Mob and is visible to any nearby client whose normal chunk subscription includes it, even if that client is unrelated to the delivery. Unrelated clients do not receive cargo contents.

  • A player has a 32-slot inventory. Stackable items occupy one slot. Currency is

a numeric wallet/vault balance, not an inventory item.

  • Player-dropped items lie on the tile for groundItemDespawnDuration

(default 10 minutes), block nobody, and may be picked up by anyone standing on that tile. They survive unload until expiry via timestamps.

  • The bank near the marketplace holds an unlimited character vault.

Later banks are linked to the same vault. Pigeons may deposit money or one stack into the sender's vault after arriving at the nearest bank. An account-level inheritance tab receives a deleted character's goods.

  • Blank cheques are issued at a bank up to a carried total of 99. Filling a

cheque reserves a vault item quantity. The filled cheque is a bearer item. In-person redemption withdraws into the bearer's inventory. Sending the cheque to the bank by pigeon transfers the reserved goods into the pigeon's sender's vault.

  • The central marketplace hides individual live sell listings and matches durable

escrowed buy/sell orders at the midpoint of compatible bid/ask limits. Quantities are item stacks.

  • The newest matching market participant receives the trade result locally; the

older counterparty receives theirs by pigeon into their bank.

  • NPC shops remain restricted to npcShopAllowed basic ingredients. They sell

to players at lerp(priceFrom, lastTradePrice, min(1, (now - lastTradeAt) / shopPriceLerpDuration)) times a hidden per-shop discount. With no player-market sale yet, the undiscounted value is seedValue. Tooltips use the same lerp without the discount and refresh at most once per minute.

  • Hovering an item shows name, description, origin (crafter, or shop NPC name

if bought there) and current undiscounted value.

  • All combatants can attack. Melee requires standing on one of the eight

neighbouring tiles. Ranged attacks and spells use the item's or spell's range. The hit roll uses the weapon skill; damage uses Strength (melee), Dexterity (ranged) or Mind (magic). Successful player-attack XP is split equally between those two skills.

  • Player progression is skill-based rather than class-based. Non-combat

actions award XP to one governing skill; combat hits split XP as above.

  • Never-edited chunks are default grass, no blocks, and closed. The

editor opens or closes each chunk. Closed chunks are visible but not enterable.

  • Accounts authenticate at auth.timfalken.com. Until that service is up,

each connection is stub admin-<n> (n = connected client count including this one) and is treated as admin.

  • An account has unlimited characters and plays one at a time. Creation

takes first name (not globally unique), last name (globally unique to the account, reusable on that account's other characters), and male/female. first+last must be unique for that account. This setup may change later.

  • Character deletion is a 24-hour (configurable) delay with email notify

and cancel. Permanent delete frees names and moves inventory, equipment, wallet and vault to the account inheritance tab, which any of that player's characters can claim into their own vault.

32. Open design decisions for later iterations

These do not block the initial implementation, but should eventually be specified explicitly:

  • Whether multiple mobile entities may occupy one tile and, if so, which

categories can overlap.

  • Whether player movement is four-direction only or also supports

diagonals. Combat melee adjacency already includes diagonals.

  • Exact hit-chance and damage curves, attack intervals/cooldowns, whether

Defence modifies incoming hit chance or damage, and ranged/spell line-of-sight or obstruction rules.

  • Deterministic rounding when shop discount or lerp produces a fractional

currency amount.

  • Exact equipment slot list, per-slot draw order exceptions (cloaks,

two-handed weapons), and whether worn overlays have facing frames to match the mob.

  • Additional recolour channels beyond metal (for example cloth dyes) and

the exact luminance-preserving remap function.

  • Exact camera zoom minimum, maximum and whether zoom is restricted to

integer steps.

  • Exact night ambient curve (how dark, dusk length) and whether baked light

stores a boolean reach mask or a distance/falloff value per tile.

  • Whether opening a door at runtime should rebake or ignore static light.
  • Exact simulation tick rate stays a world setting; lower-frequency AI and

spawner cadences can still be tuned independently.

  • Exact world/chunk binary serialisation format and schema/version

migration strategy.

  • Whether gameplay can permanently modify ground/block tiles in the

initial release.

  • Spawner timing rules, spawn-point restrictions and behaviour when

persistent spawned mobs travel very far away.

  • World-editor undo/redo and rollback UI. The per-chunk changelog is an audit

log, not by itself an undo stack.

  • Exact restart warning intervals and whether admins can

cancel/reschedule a planned restart.

  • Worker rebalance thresholds and whether regions may migrate while

players are actively crossing their boundaries.

  • Future scripting language syntax, event model and resource quotas.
  • Exact proximity-chat distance curve, maximum range and character degradation

algorithm.

  • Group naming/roles, membership limits and whether group-wide letter sending

is offered as an addressing convenience that still dispatches one pigeon and consumes one paper/letter per recipient.

  • Whether pigeons can eventually be intercepted, killed or redirected in transit.
  • Marketplace partial fills, cancellation rules, fees/taxes (if any),

tie-breaking details and midpoint rounding for indivisible currency.

  • Whether market price history or aggregate statistics are visible despite live

order listings remaining hidden.

  • Initial skill catalogue, XP curves, level caps, action XP formulas and the

remaining interpretation of skills such as Defence.

  • Maximum letter body length and whether writing paper requires a desk or can be

done from inventory anywhere.

  • Exact item catalogue, which items stack, per-item maxStackSize exceptions,

harvest interactions and ground-item spawner parameters.

  • Whether death drops inventory, and whether dropped unique items other than

cheques have destruction side-effects.

  • Whether the issuer can void a filled cheque without the bearer item being

destroyed, and whether cheques can ever represent currency rather than items.

  • Whether a short dispatch interval is needed so many pigeons cannot leave in a

single tick, even though sending remains free.

  • New-character spawn location (must be an open chunk) and name length /

allowed-character rules.

  • Later changes to character creation beyond first name, last name and sex.

33. Architectural summary

ECS → what an entity is and what systems can act on it Chunk → tile data, spatial lookup, simulation and client subscription Region → residency and simulation-worker ownership Coordinator→ where regions execute Gateway → stable client connections, auth, character select, and command/update routing world.sqlite→ authored versioned ground/block/spawner/light/settings world; unedited chunks are closed grass state.sqlite→ accounts, characters, vaults, inheritance, and other durable live-game state systemd → process supervision and relaunch Deployment hook → conditional Git update/build only for intentional deployment restarts Controller → manual client input today; sandboxed player scripts later FrameworkV3 → git submodule at client/frameworkv3; built first; game client code layers on top Sprites → all world art is 16×16; reject and CI-fail any other size Equipment → layered 16×16 overlays on mobs; metal armour shares art and recolours by material Camera → play view centered on the local player; bounded zoom; editor is chunk-framed Movement → global walk/run cadence (default 2 tiles/s walk, run double); server tile steps; client visual lerp World time → server clock minus 1200 years; night darkens unlit tiles Light → baked passable-tile raycast on editor save; shines across chunks World settings → admin modal for tick timers and global constants; pending revision Inventory → 32 slots; stacks occupy one slot; letters are written paper items Bank → per-character vault; account inheritance tab on character delete Auth → auth.timfalken.com, stub admin-<n> until live; unlimited characters, one in world Chunks → editor open/closed; default grass and closed until painted Ground items → non-blocking, 10-minute player drops, pickup only while standing on the tile Communication service → proximity speech CourierService → pigeons carrying money or one item stack through durable transit BankService → shared unlimited vaults, cheque reservations and redemption MarketService → durable escrowed order book, matching, last-sale index and pigeon-to-bank settlement Shop NPCs → sell allowed stock; price lerps toward last player-market sale over shopPriceLerpDuration, times a hidden discount Combat → 8-tile melee, item/spell ranged range; hit skill roll; Strength / Dexterity / Mind damage; equal XP split Skills → classless progression; non-combat XP to one skill; attack XP split hit/damage

34. Version history

0.12

  • Chunks are open or closed in the world editor. Closed chunks stay visible

but cannot be entered. Never-edited chunks are default grass with no blocks and are closed.

  • Login uses auth.timfalken.com; until that is live, connections are stub

admin-<n> (connected-client count including this one) and are admins.

  • Accounts have unlimited characters, one in the world at a time. Creation

is first name, unique account-owned last name, and male/female.

  • Character deletion waits 24 hours with email and cancel. Permanent delete

frees names and moves goods to an account inheritance bank tab.

0.11

  • Made walk/run a global cadence from world settings (default 2 tiles/s

walk, run double): walk steps every other movement tick, run every tick. Mob definitions do not set move speed.

  • Added an admin world-settings modal for tick timers and global constants

(shop lerp duration, drop lifetime, simulation tick, and the same class of values). Settings ride the pending world revision.

  • World calendar time is server time minus 1200 years.
  • Baked static lighting by passable-tile raycast on chunk save, including

across chunk borders. Clients darken unreachable tiles at night. The editor has a night-to-day preview slider.

0.10

  • Drew visible equipment as 16×16 overlay layers on mobs (including players),

with worn items in equipment slots rather than the 32-slot inventory.

  • Replicated compact appearance layers to nearby clients instead of another

player's inventory.

  • Recolourable metal armour shares one overlay plus a 16×16 channel mask;

material definitions supply the metal colour while preserving shading.

0.9

  • Vendored FrameworkV3 as the git submodule client/frameworkv3. The game

client builds that library first and implements game-specific code on top of it. The Node.js server does not import the submodule.

0.8

  • Required all world sprites (tiles, blocks, mobs, items) to be 16×16 pixels,

rejected at load, with a CI unit test that reports and fails on any other size. Sprites are not individually scaled; the player may zoom the viewport within configured bounds.

  • Locked the play camera to the local player. The admin world editor remains

the only non-player-centered view.

  • Made authoritative movement integer tile-to-tile steps. Clients lerp

mobiles for presentation only.

  • Added a per-chunk world-editor changelog: admin, timestamp, and bullet

diffs for ground changes, block place/change/remove.

0.7

  • Added combat for all mobs including players: melee from any of the eight

neighbouring tiles, ranged and spells from the item or spell range.

  • Hit rolls use the weapon skill (Swordfighting, Axefighting, Archery, Magic,

and so on). Damage uses Strength, Dexterity or Mind according to melee, ranged or magic.

  • Successful player-attack XP is split equally between the hit skill and the

damage skill. Ordinary mobs use archetype skill levels and do not earn XP.

  • Shop NPCs sell items at seed value adapted to the last player-market unit

price, lerping over one hour, multiplied by a hidden per-shop discount.

  • Only the latest player-market sale per item is stored (price, timestamp, and

lerp origin). No historical series.

  • Item hover shows name, description, origin (crafter or shop NPC) and the

undiscounted current value, refreshed at most once per minute.

0.6

  • Added a 32-slot player inventory, stackable items, carried currency as a

numeric wallet, and unique-instance items for letters and filled cheques.

  • Redefined letters as paper items with player-written text rather than a

separate mail record.

  • Redefined carrier pigeons as free couriers that carry money or one item

stack to a player or to the nearest bank.

  • Added a shared unlimited bank near the marketplace, blank cheques filled to

99, vault reservations on fill, in-person redemption and pigeon-to-bank cheque transfers between vaults.

  • Added player-dropped ground items: 10-minute lifetime, non-blocking, pickup

only while standing on the tile, timestamp persistence across unload.

  • Specified later ground-item spawners and harvesting as content that reuses

this item model.

  • Routed offline/full-inventory pigeon delivery and older-side market

settlement into the recipient's shared bank vault.

0.5

  • Made carrier pigeons shared world-visible entities whenever their route crosses an already-simulating chunk.
  • Unrelated nearby players can see pigeons in their normal 3x3 chunk view; pigeons do not keep chunks loaded themselves.
  • Added deterministic materialisation/dematerialisation between durable abstract transit and worker-owned ECS pigeon entities.

0.4

  • Added FrameworkV3 as the shared player-client foundation while keeping backend ECS internal to the server.
  • Added server-side proximity chat degradation, persistent player groups and durable carrier-pigeon letters.
  • Added scalable courier transit that can cross dormant world space without forcing normal chunk simulation.
  • Added the central marketplace, escrowed hidden order book, midpoint pricing and pigeon-based remote settlement.
  • Added the player-driven item-source philosophy and restrictions on NPC shop inventories.
  • Added classless, skill-based player progression and authoritative skill XP.

0.3

  • Converted the living design document to Markdown as the canonical format.
  • Defined systemd as the production process supervisor.
  • Added a conditional, manifest-driven deployment path so crashes do not deploy pending code early.
  • Added a concrete example systemd service shape and clarified privilege separation.

0.2

  • Added unload-driven chunk persistence, authored world revisions, the admin world editor, spawner blocks, graceful scheduled restarts and future player scripting hooks.
Source
1---
2title: Tile MMO Server Technical Design
3version: 0.12
4status: proposed
5format: living-design-document
6---
7
8# Tile MMO Server Technical Design
9
10**Version:** 0.12
11**Status:** Proposed architecture; intended to be iterated as implementation decisions are made.
12**Scope:** Authoritative Node.js/ECS backend, FrameworkV3-based game client (16×16 sprites, player-centered viewport), chunk/region streaming, SQLite persistence, admin world editor with per-chunk changelogs, player inventory and items, combat, player communication, banking/cheques, shopkeepers, marketplace/economy systems, skill progression, automatic restart/update orchestration, and future player scripting hooks.
13
14# 1. Design goals
15
16- Support a large tile-based MMO world without simulating unused areas.
17
18- Keep the server fully authoritative: clients send actions and
19 intentions, never authoritative state changes.
20
21- Authenticate accounts via auth.timfalken.com (with an `admin-<n>` stub
22 until that service is live). An account may have unlimited characters,
23 one in the world at a time, with delayed deletion and an inheritance
24 bank tab.
25
26- Use ECS composition for entities and systems, while using chunks and
27 regions for spatial ownership and simulation lifecycle.
28
29- Allow simulation work to scale across Node.js workers and permit
30 entities to cross worker-managed region boundaries safely.
31
32- Keep client replication small: a player receives only the current
33 16×16 chunk and the eight neighbouring chunks.
34
35- Keep authored world data separate from ephemeral simulation state.
36
37- Persist only entities that explicitly need persistence; ordinary
38 spawned mobs disappear when their chunk is unloaded.
39
40- Avoid constant chunk writes. Normal chunk persistence occurs on
41 unload; graceful shutdown is implemented as a forced unload of all
42 resident chunks.
43
44- Provide an admin-only graphical world editor for painting tiles,
45 opening or closing chunks, and placing/configuring spawners, with a
46 per-chunk changelog of who changed what and when. Unedited chunks are
47 grass-only and closed.
48
49- Automatically schedule a graceful midnight restart when live code or
50 authored world data changes, with an admin-triggered immediate restart
51 path.
52
53- Reserve a clean control abstraction for a later sandboxed player
54 scripting language without requiring the scripting system in the
55 initial release.
56
57- Build the player-facing client on the shared FrameworkV3 library, vendored
58 as a git submodule and built first so game-specific client code can layer
59 on top of it, while keeping the server-side ECS an implementation detail of
60 the backend. All world sprites are 16×16 pixels. The play viewport stays
61 centered on the local player.
62
63- Authoritative movement is tile-to-tile at a **global** walk/run cadence
64 (default walk 2 tiles/s, run double), not a per-mob speed. Admins edit
65 that cadence and other tick timers in a world-settings modal. World
66 calendar time is server time minus 1200 years. At night the client
67 darkens unlit tiles; static light reach is baked by raycast when a
68 chunk is saved.
69
70- Give every player a 32-slot inventory in which stackable items occupy a
71 single slot, and treat dropped items as temporary, non-blocking ground
72 objects rather than tile occupancy.
73
74- Make ordinary communication spatial rather than global: nearby speech is
75 progressively degraded by distance, while long-distance exchange is a
76 physical item or currency delivery by carrier pigeon. A letter is simply a
77 paper item with player-written text.
78
79- Support persistent player groups without turning them into an instant
80 long-distance chat channel.
81
82- Provide a shared, unlimited player bank near the marketplace, with later
83 banks all reading the same vault, plus bearer cheques and free pigeon
84 deposits.
85
86- Make the central marketplace an order-matching service rather than a public
87 auction list, with durable escrow and asynchronous pigeon delivery.
88
89- Keep the economy predominantly player-driven: most ingredients are gathered,
90 final goods are normally crafted by players, and finished-item drops come from
91 enemies/bosses rather than ordinary NPC shops.
92
93- Let every combatant — players and other mobs — attack. Melee requires an
94 adjacent tile including diagonals; ranged attacks and spells use the range
95 of the weapon or spell. A hit roll uses the weapon skill; damage uses
96 Strength, Dexterity or Mind. Attack XP is split equally between those two
97 skills.
98
99- Let shop NPCs sell items at a seed value that lerps toward the last
100 player-market sale price over a configurable duration (default one hour),
101 with a hidden per-shop discount.
102 Item inspection shows name, description, origin and the undiscounted
103 current value, refreshed at most once per minute.
104
105- Use skill-based progression with no player classes. Every gameplay action is
106 governed by a skill and awards XP to that skill when successfully performed.
107 Combat is the explicit dual-skill exception: hit skill and damage skill
108 share the XP.
109
110# 2. Core world model
111
112## 2.1 Spatial hierarchy
113
114World
115└── Region: 4 × 4 chunks
116└── Chunk: 16 × 16 tiles
117└── Tile
118
119One chunk contains 256 tiles. One region is 64×64 tiles and contains 16
120chunks (4,096 tiles). World tile coordinates are canonical; chunk and
121region coordinates are derived from them.
122
123chunkX = floor(tileX / 16)
124chunkY = floor(tileY / 16)
125regionX = floor(chunkX / 4)
126regionY = floor(chunkY / 4)
127
128If negative world coordinates are allowed, use true floor division
129rather than JavaScript integer truncation.
130
131## 2.2 Three independent spatial states
132
133The design deliberately separates region residency, chunk simulation,
134and client visibility.
135
136| **Concern** | **Unit** | **Meaning** |
137|-------------|----------|------------------------------------------------------------------------------------------------|
138| Residency | Region | Whether the region and its required chunk data exist in server memory and have a worker owner. |
139| Simulation | Chunk | Whether ECS systems actively simulate entities and gameplay in this chunk. |
140| Visibility | Chunk | Whether a specific client is subscribed to the chunk and receives its snapshot/deltas. |
141
142## 2.3 Region states
143
144UNLOADED
145↓ load
146RESIDENT
147↓ no residency references + grace period
148UNLOADED
149
150A resident region is assigned to exactly one simulation worker. An
151unloaded region has no active ECS representation.
152
153## 2.4 Chunk states
154
155DORMANT ⇄ SIMULATING
156
157A dormant chunk can remain resident in memory while normal gameplay
158systems ignore it. A simulating chunk participates in movement, combat,
159AI, spawners and other active systems.
160
161# 3. Tile layers and occupancy
162
163## 3.1 Ground layer
164
165Every tile has a ground type. Ground is visual only. It does not by
166itself block movement, cause collision, or create gameplay behaviour.
167
168TileGround {
169groundTypeId: GroundTypeId
170}
171
172## 3.2 Block layer
173
174A tile may also contain one block. The block is the actual world object
175standing on the tile and can determine collision and behaviour.
176
177TileBlock {
178blockTypeId: BlockTypeId \| null
179config?: BlockConfig
180}
181
182Examples include walls, doors, trees, torches and other lights, containers,
183spawners, marketplace counters and banks. Block definitions determine
184properties such as passability, interaction behaviour, whether a block
185participates in navigation, and whether it emits light (`lightRangeTiles`).
186
187## 3.3 MOBile entities
188
189A moving game entity — player, enemy, animal, NPC or any other mobile
190actor — is represented by an ECS entity rather than being painted into
191the static tile map. A mobile entity may inhabit a tile in addition to
192the tile’s ground and block layers, subject to collision rules.
193
194Tile
195├── Ground (visual layer)
196├── Block (static/world-object layer; optional)
197├── Ground item stacks (ephemeral, non-blocking)
198└── Mobile ECS entities (dynamic occupancy)
199
200The spatial chunk index maintains which mobile entity IDs currently
201occupy each tile, allowing collision, nearby queries and replication
202without scanning the global ECS. Ground item stacks are indexed per
203tile as well, but they never contribute to movement collision and never
204prevent a mobile entity from standing on that tile.
205
206# 4. ECS model
207
208## 4.1 Entity composition
209
210Entities are numeric identities plus components. Behaviour comes from
211systems querying component combinations rather than deep class
212inheritance.
213
214Player
215Position
216Movement
217Health
218Combat
219Skills
220Inventory
221Currency
222Equipment
223Player
224NetworkIdentity
225ChunkLoader
226Persistent
227
228Ordinary enemy
229Position
230Movement
231Health
232Combat
233Skills
234Creature
235AI
236
237Named NPC
238Position
239Movement
240Health
241NPC
242AI
243Persistent
244
245## 4.2 Global identity versus local ECS handle
246
247Use a globally meaningful EntityId for storage, networking and
248cross-worker transfer, and a compact worker-local EntityHandle for hot
249ECS arrays. A transferred entity keeps its EntityId but may receive a
250different local handle on the destination worker.
251
252## 4.3 Recommended initial components
253
254| **Category** | **Components** |
255|----------------|----------------------------------------------|
256| Spatial | Position, Movement, Path, Collision |
257| Living | Health, Combat, Creature, Mob, Skills |
258| Player | Player, NetworkIdentity, Inventory, Currency, Equipment |
259| AI | AI, Target, BehaviourState |
260| Lifecycle | ChunkLoader, Persistent, SpawnOrigin |
261| Presentation | Renderable / Appearance |
262| Future control | Controller / ScriptController / OfflineUntil |
263
264# 5. ChunkLoader and simulation activation
265
266## 5.1 Generic ChunkLoader component
267
268World activation is component-driven rather than player-specific. Any
269entity may carry a ChunkLoader component that says “keep the surrounding
270world resident and simulated”.
271
272ChunkLoader {
273simulationRadiusChunks: 1,
274regionLoadRadius: 1
275}
276
277A normal player can therefore stimulate a 3×3 chunk area while keeping
278the surrounding 3×3 regions resident. Bosses, travelling NPCs, machines,
279scripted actors or administrative anchors can use the same mechanism.
280
281## 5.2 Reference counting
282
283Chunk simulation and region residency should use reference counts.
284Overlapping loaders increment the same references; leaving decrements
285them. A chunk sleeps only when its simulation reference count reaches
286zero. A region becomes eligible for unload only when its residency
287references reach zero.
288
289## 5.3 Grace period
290
291After the last residency reference disappears, retain the region briefly
292before unloading. This prevents repeated SQLite reads and writes when a
293loader oscillates around a boundary. The delay should be configurable.
294
295# 6. Chunk lifecycle and persistence
296
297## 6.1 No periodic chunk saves
298
299Normal gameplay does not periodically rewrite loaded chunks. A chunk is
300saved as part of the unload path only.
301
302Resident chunk
303↓ last residency / forced shutdown unload
304Prepare unload
305↓
306Persist required chunk state once
307↓
308Persist required entities
309↓
310Remove ECS/runtime representation
311
312A graceful server restart does not introduce a second save mechanism. It
313force-unloads every resident region/chunk, so the normal unload
314persistence path remains the single source of truth.
315
316## 6.2 Persistent versus non-persistent entities
317
318Persistence is an entity property, not a property of the chunk or
319spawner. An entity with Persistent is serialised when its owning
320chunk/region unloads. A non-persistent entity is simply discarded.
321
322Non-persistent wolf
323spawn → simulate → chunk unload → disappear
324
325Persistent named NPC
326load → simulate → chunk unload → save → recreate when area loads
327
328## 6.3 Persistent is independent of ChunkLoader
329
330These traits must remain independent. A persistent entity does not
331automatically keep its area active, and a ChunkLoader does not
332automatically become persistent.
333
334# 7. Storage architecture
335
336## 7.1 Separate authored world and runtime state
337
338Use two SQLite databases with different responsibilities.
339
340| **Database** | **Responsibility** |
341|--------------|-----------------------------------------------------------------------------------------------------------------------------------------|
342| world.sqlite | Admin-authored ground tiles, block tiles, light maps, world settings, spawner configuration, per-chunk editor changelogs, world revisions and world metadata. |
343| state.sqlite | Accounts, characters, inventories, carried currency, character vaults, inheritance tabs, cheque reservations, skills, groups, courier cargo/transit, unexpired ground items, market orders/escrow/trades, per-item last player-market sale, persistent ECS entities, offline-script state, optional persistent runtime chunk overrides, and other durable live-game state. |
344
345This prevents editor authoring changes from becoming entangled with live
346player/entity persistence.
347
348## 7.2 Chunk writes in runtime state
349
350If initial gameplay does not allow permanent tile/block modification,
351runtime chunks require no writes at all. If permanent runtime world
352changes are later added, dirty chunk overrides are held in memory and
353written to state.sqlite only when that chunk unloads. Shutdown uses
354forced unload and therefore follows the same rule.
355
356## 7.3 Central persistence service
357
358Simulation workers should not independently compete for SQLite writes. A
359persistence service owns the write connection, batches transactions, and
360receives logical save requests from workers.
361
362Simulation workers
363│ save/unload messages
364▼
365Persistence service
366│
367▼
368SQLite (WAL)
369
370Live ECS state remains authoritative while loaded; SQLite is durable
371state, not a per-tick synchronisation mechanism.
372
373# 8. World authoring and revision model
374
375## 8.1 Admin-only world editor
376
377The server includes a separate admin-only world editor UI. It is not
378part of the normal player client.
379
380- Display a 3×3 of 16×16 chunks, with the currently selected
381 chunk in the centre and a red border around that chunk.
382 Painting, open/closed, and changelog apply only to the
383 selected chunk; neighbours are visible for alignment and
384 baked lighting context.
385
386- Provide Up, Down, Left and Right navigation buttons that move the
387 editor exactly one chunk in that direction.
388
389- Show the current chunk coordinates prominently, and whether the chunk
390 is **open** or **closed**.
391
392- Toggle the current chunk open or closed. Closed chunks remain visible
393 to nearby players but cannot be entered.
394
395- Allow painting a ground type on a tile.
396
397- Allow painting, replacing or erasing the block type on a tile.
398
399- Render both layers together so the block appears on top of the ground.
400
401- Do not display ordinary mobile entities as editable map paint.
402
403- Allow selecting/configuring special block types such as Spawner, Bank,
404 Marketplace and light-emitting blocks (`lightRangeTiles`).
405
406- Open a **world settings** modal for global tick timers and constants
407 (movement cadence, shop lerp duration, drop lifetime, and other values
408 listed in section 8.5).
409
410- Provide a **night-to-day slider** that only previews lighting; it does
411 not change live world time. Preview uses the same baked light maps as
412 play, including light that reaches this chunk from neighbouring chunks.
413
414- Later: allow configuring ground-item spawners analogously to mob
415 spawners. Exact item tables remain a later content decision.
416
417- Save changes through an authenticated admin API; the browser never
418 opens SQLite directly.
419
420- Show that chunk's changelog: a chronological list of saves, each with
421 which admin made the edit, when, and a bullet-point diff of the change.
422
423The editor camera is **not** locked to a player character. It frames the
424currently selected chunk. This is the only intended exception to the
425player-centered play viewport in section 21.4.
426
427## 8.2 World editor save behaviour
428
429Saving a chunk **or world settings** writes the authored result to
430world.sqlite. It does not live-patch the currently running simulation.
431Instead, the change creates or updates a pending world revision and
432schedules a server restart for the next server-local midnight.
433
434The running game remains pinned to the world revision selected at its
435own startup. This avoids a dangerous mixed state where some loaded
436chunks use old authored data and newly loaded chunks use newer editor
437data.
438
439## 8.3 Versioned authored chunks
440
441A practical schema is to give every editor change a monotonically
442increasing world revision. The game process pins one active revision for
443its entire lifetime. Chunk lookup selects the latest authored version
444not newer than that pinned revision.
445
446world_revisions
447revision_id
448created_at
449created_by
450status // pending / active / superseded
451
452world_chunk_versions
453chunk_x
454chunk_y
455revision_id
456open // player-enterable; default false until set
457data_blob
458
459world_meta
460active_revision
461pending_revision
462
463world_settings
464revision_id
465settings_blob // walk speed, tick timers, shop lerp, drop TTL, ...
466
467world_chunk_edit_log
468log_id
469chunk_x
470chunk_y
471revision_id
472editor_admin_id
473edited_at
474diff_entries // structured bullets for this save
475
476On the next planned restart, startup promotes/selects the latest valid
477pending revision before world loading begins.
478
479## 8.4 Per-chunk changelog
480
481Every successful chunk save appends one changelog record for that chunk.
482The record is durable in `world.sqlite` and is not gameplay state.
483
484The server diffs the newly saved chunk against the previous authored
485version of that same chunk (the latest `world_chunk_versions` row for
486those coordinates that this save replaces). Unchanged tiles produce no
487bullets. Each changed tile becomes one of:
488
489```text
490- Ground at X, Y changed from Prev to New.
491- Block <type> placed at X, Y.
492- Block at X, Y changed from Prev to New.
493- Chunk opened.
494- Chunk closed.
495```
496
497`X, Y` are world tile coordinates. `Prev` / `New` / `<type>` are the
498ground or block definition display names. A block paint on an empty block
499layer is a placement. Replacing one block type (or its config, such as a
500spawner) with another is a change. Erasing a block is a removal. Ground is
501never absent; a ground paint is always a change from one type to another.
502
503The editor UI lists records newest-last or newest-first consistently, each
504headed by admin identity and timestamp, with that save's bullets underneath.
505The changelog is an audit trail, not an undo stack. Undo/redo remains an
506open editor-UX decision. Derived light maps are not changelog bullets;
507they are regenerated on save (section 8.6).
508
509## 8.5 World settings
510
511Global gameplay constants live in authored `world_settings` for the world
512revision. They are **not** per-mob and **not** client-authored. Admins
513edit them from a modal in the world-editor UI. Saving the modal writes
514into the pending world revision and schedules the same midnight restart
515as a chunk save. The running process keeps the settings it loaded at
516startup.
517
518Minimum initial settings and defaults:
519
520```text
521WorldSettings
522- walkTilesPerSecond // default 2
523- simulationTickHz // default 20; implementation default, still a setting
524- shopPriceLerpDuration // default 1 hour
525- groundItemDespawnDuration // default 10 minutes
526- regionUnloadGracePeriod // configurable grace after last residency
527- defaultGroundTypeId // grass used for never-edited chunks
528- characterDeletionDelay // default 24 hours
529```
530
531Running is always **double** walking speed. It is not a separate per-entity
532field. From `walkTilesPerSecond`:
533
534```text
535runTilesPerSecond = walkTilesPerSecond * 2 // default 4
536movementTickHz = runTilesPerSecond // default 4 Hz
537walk: commit a tile every 2 movement ticks
538run: commit a tile every 1 movement tick
539```
540
541All ground mobiles — players, enemies, NPCs — use this same cadence. A
542mob definition does not set move speed. Gait (`walk` | `run`) is the only
543per-entity choice; it selects every-other vs every movement tick.
544
545Other tick-duration constants that already exist in this document (shop
546lerp, ground-item despawn, residency grace, and later ones of the same
547kind) are edited here rather than hardcoded. Adding a new global timer
548means adding a field to `WorldSettings` and a row in this modal.
549
550## 8.6 Baked lighting
551
552Light from authored blocks is precomputed when a chunk is saved, not
553raytraced every simulation tick.
554
555A block definition may set `lightRangeTiles > 0`. That tile is a static
556light source. Light travels only through **passable** tiles (the same
557passability as walking). Ground type does not block light. Mobiles and
558ground items do not block light.
559
560For every tile within a source's range, the baker runs a simple grid
561raycast (for example Bresenham through tile centres). If the ray hits an
562impassable block before the destination, that source does not light that
563tile. A tile is lit if **any** source can reach it. Light **does** shine
564across chunk boundaries.
565
566Saving a chunk rebakes:
567
5681. that chunk's 16×16 light map, and
5692. every neighbouring chunk that could be affected (chunks within the
570 maximum `lightRangeTiles` of the saved chunk).
571
572Neighbor rebakes use light sources and walls from the pending revision,
573including the chunk just saved. Those neighbor light maps are written
574into the same pending revision so play never mixes old and new lighting.
575
576The light map is stored in the chunk `data_blob` (a 16×16 reachable-or-
577not mask, optionally with distance to the nearest reaching source). It is
578replicated to clients in `CHUNK_SNAPSHOT` / `CHUNK_DELTA`.
579
580Runtime door open/close does not rebake static light unless a later
581iteration adds live lighting. Baked light is authored geometry.
582
583The editor night-to-day slider interpolates preview ambient from full
584night (dark except baked-lit tiles) to full day (no ambient darkening).
585It does not persist and does not change server/world clock.
586
587## 8.7 Default chunks and open / closed
588
589A chunk the editor has never saved does not exist in `world_chunk_versions`.
590At runtime it is synthesised as:
591
592- every tile `defaultGroundTypeId` (grass),
593- no blocks,
594- **closed**,
595- no baked lights.
596
597The world is therefore an infinite grass field until admins paint it, and
598players cannot walk onto it until an admin **opens** the chunk.
599
600**Closed** chunks can still appear in a player's 3×3 view. They cannot be
601entered: `MOVE_TO`, pathfinding, spawning, and other player-entry actions
602treat every tile in a closed chunk as impassable. Visibility and lighting
603previews are unchanged.
604
605**Open** chunks are the playable map. Opening or closing is an authored
606chunk flag, saved with the pending revision like paint.
607
608Spawners in a closed chunk do not spawn. Ground movement, including AI,
609does not step into a closed chunk. If a future bug or admin tool places an
610entity there, it can still be replicated to observers, but players cannot
611walk in after it.
612
613# 9. Spawner blocks
614
615## 9.1 Spawner data
616
617A Spawner is a block in the authored block layer, with per-instance
618configuration stored as part of the chunk data.
619
620SpawnerConfig {
621spawnerId: SpawnerId,
622mobTypeId: MobTypeId,
623maxAlive: number,
624spawnRangeTiles: number
625}
626
627Additional parameters such as minimum/maximum spawn delay can be added
628later without changing the core model.
629
630## 9.2 Spawner editor
631
632Selecting a Spawner tile in the world editor opens a configuration panel
633containing at minimum: mob type, maximum alive count and spawn range.
634Validation happens server-side before the pending world revision is
635written.
636
637## 9.3 Spawned entity persistence
638
639The spawner never decides whether its mob is persistent. The mob
640definition/archetype does. When the spawner creates an entity, the
641entity receives Persistent only if that mob type is defined as
642persistent.
643
644MobDefinition: deer
645persistent = false
646
647MobDefinition: named_guard_captain
648persistent = true
649
650## 9.4 SpawnOrigin
651
652Spawned mobs receive a SpawnOrigin component referencing the spawner.
653This lets maxAlive count only entities belonging to that spawner and
654avoids expensive geometric searches.
655
656SpawnOrigin {
657spawnerId: SpawnerId
658}
659
660For non-persistent mobs, disappearance on chunk unload naturally
661decreases the count. For persistent mobs, SpawnOrigin is persisted so
662the spawner can recognise an existing persistent instance even after it
663has moved or been unloaded elsewhere. A lightweight persistence index by
664spawnerId prevents duplicate persistent spawns.
665
666## 9.5 Spawner simulation
667
668SpawnerSystem runs only while the spawner’s chunk is simulating **and
669open**, and at a much lower frequency than movement. A spawn candidate
670must satisfy block collision, bounds, an open chunk, and mobile-occupancy
671rules. Ground type does not affect passability unless a later gameplay
672system explicitly introduces a separate rule for it.
673
674## 9.6 Future ground-item spawners
675
676Some items will later spawn naturally on the ground, using a world-editor
677block analogous to a mob spawner. Those spawned stacks should use the same
678non-blocking ground-item representation as player drops, but their lifetime,
679respawn and `maxOnGround` rules belong to the spawner configuration rather
680than the 10-minute player-drop timer.
681
682Exact item lists, harvest interactions and spawner parameters are later
683content decisions and do not block the inventory/bank model.
684
685# 10. Startup and loading order
686
687Loading order is explicit so authored world state exists before
688persistent entities are instantiated into it.
689
690> **1.** Start process and load configuration, including server time
691> zone and storage paths.
692>
693> **2.** Open world.sqlite and validate/migrate its schema.
694>
695> **3.** Select/promote the world revision to use for this process and
696> pin it for the lifetime of the process.
697>
698> **4.** Load static registries: ground definitions, block definitions,
699> item definitions, material definitions, spell definitions, mob archetypes and component serializers.
700>
701> **5.** Open state.sqlite and run runtime-state migrations.
702>
703> **6.** Start the persistence service, durable domain services (such as courier, bank, market and shop-price services when enabled), region coordinator and simulation workers.
704>
705> **7.** Load the index of persistent entities that themselves require
706> world activation (for example persistent ChunkLoaders or future
707> offline scripted players).
708>
709> **8.** For each required region, load authored chunk data from the
710> pinned world revision first.
711>
712> **9.** Apply any durable runtime chunk override state, if the game
713> supports such modifications.
714>
715> **10.** Instantiate persistent entities into the already-created
716> world/chunks.
717>
718> **11.** Recalculate ChunkLoader references and begin chunk simulation.
719>
720> **12.** Only after the world reports READY does the gateway accept
721> normal player logins.
722
723This ordering solves the bootstrap problem for persistent entities that
724keep their own chunks active: a compact persistence index can locate
725them without first loading the entire world.
726
727# 11. Simulation workers and region ownership
728
729## 11.1 Ownership invariant
730
731Exactly one worker authoritatively owns a region at any instant. Every
732authoritative entity belongs to the worker that owns the entity’s
733current region.
734
735## 11.2 Coordinator
736
737A central region coordinator maintains RegionId → WorkerId and
738assigns/migrates regions based on actual measured simulation effort,
739while preferring neighbouring regions on the same worker when load
740permits.
741
742## 11.3 Work measurement
743
744- Average and high-percentile tick execution time.
745
746- Number of simulating chunks.
747
748- Number of active entities and AI entities.
749
750- Pathfinding work and queued searches.
751
752- Cross-worker boundary message volume.
753
754- Backlog / tick lateness.
755
756Actual time spent simulating is more important than raw player count or
757raw region count.
758
759## 11.4 Node.js implementation
760
761Start with Node.js worker_threads for simulation workers. Keep mutable
762ECS worlds isolated per worker and use message passing between them. Do
763not begin with a shared mutable ECS in SharedArrayBuffer.
764
765# 12. Cross-worker communication
766
767## 12.1 No remote mutation
768
769A worker may inspect a limited read-only representation of neighbouring
770entities but never directly mutates authoritative state owned by another
771worker.
772
773## 12.2 Border ghosts
774
775Neighbouring workers can exchange compact border/ghost entity data for
776nearby interaction and AI: EntityId, position, collision footprint, type
777and minimal combat metadata. Ghosts are not full ECS entities and are
778never authoritative.
779
780## 12.3 Remote actions
781
782Worker A goblin targets Player 42 (owned by Worker B)
783Worker A → REMOTE_ACTION(attack intent) → Worker B
784Worker B validates range/state and applies authoritative result
785
786## 12.4 Entity transfer
787
788When an entity crosses from a region owned by Worker A into one owned by
789Worker B, ownership is handed off at a simulation tick boundary using a
790sequence-numbered transfer protocol. There is never more than one
791authoritative copy.
792
793A: prepare transfer
794B: validate / accept
795A: freeze at handoff boundary
796B: instantiate authoritative entity at effective tick
797Coordinator: update ownership mapping
798A: remove authoritative copy
799
800# 13. Server tick and stimulation
801
802## 13.1 Fixed simulation tick
803
804Use a fixed server simulation tick. The default is 20 Hz (50 ms), stored
805as `WorldSettings.simulationTickHz`. This is not a protocol promise.
806
807Movement does **not** commit a new tile on every simulation tick. See
808section 13.4.
809
8101\. Drain validated incoming commands
8112. Apply completed worker/entity transfers
8123. Recalculate activation changes
8134. Movement / collision
8145. Combat
8156. Scheduled AI
8167. Scheduled spawners/environment, including ground-item expiry in simulating chunks
8178. Produce cross-worker messages
8189. Produce client replication deltas
81910. Queue unload/persistence work
820
821## 13.2 Different system frequencies
822
823Not every ECS system should run every tick. Ground movement commits only
824on the global movement cadence (section 13.4). AI decisions, target
825searches and spawner checks can run at lower frequencies. Sleeping chunks
826are not “slow ticked”; they are omitted from normal simulation.
827
828## 13.3 Timestamp-based inactive progression
829
830Long-lived timers such as growth, cooldowns, ground-item expiry and shop
831price lerps should store future timestamps where possible. When an area
832wakes, the system catches up from the timestamp instead of executing missed
833ticks. An expired ground item is discarded on catch-up without ever
834reappearing. Shop and tooltip prices are evaluated from last-sale timestamps
835when observed; they are not ticked. Durations such as shop lerp and
836ground-item despawn come from `WorldSettings`, not from hardcoded
837literals in systems.
838
839## 13.4 Global movement cadence
840
841All ground-moving entities share one walk speed and one run speed.
842
843- Default walk: **2 tiles per second** (`walkTilesPerSecond`).
844- Run: always **double** walk (default 4 tiles per second).
845- Movement ticks fire at `runTilesPerSecond` (default 4 Hz).
846- **Walk:** the entity may advance one path tile on every other movement
847 tick.
848- **Run:** the entity may advance one path tile on every movement tick.
849
850Mobs do not define their own move speed. `Movement.gait` is `walk` or
851`run`. Players send `SetGait`. AI may set gait; it still uses the global
852cadence. Flying pigeon transit is not this cadence; it keeps its own
853route clock.
854
855If the path is blocked on a movement tick, the entity stays on its tile
856and retries on a later legal tick. Occupancy, combat range and pickup
857always use the last committed tile.
858
859## 13.5 World calendar time
860
861World time is server time **1:1**, in the same configured IANA zone used
862for midnight restarts, with **1200 years subtracted** from the calendar
863date. A server clock of 24 Aug 2026 21:00 is world 24 Aug 826 21:00.
864Clock-of-day, including night, therefore matches the host's zone.
865
866The gateway includes current world time (or server unix time plus the
867year offset) in the status sent to clients so shading does not depend on
868the player's device clock. Lighting is presentation; combat and movement
869do not wait on the day/night overlay.
870
871# 14. Client gateway and authority
872
873## 14.1 Stable connection ownership
874
875Client WebSocket/TCP connections belong to a gateway rather than
876simulation workers. When the player crosses into a region owned by
877another worker, the socket stays connected to the same gateway; only
878internal routing changes.
879
880## 14.2 Client commands are intentions
881
882A client sends commands such as MoveTo, Interact, Attack, UseItem,
883EquipItem, UnequipItem, SelectSpell, SetGait, DropItem, PickupItem, BankDeposit,
884BankWithdraw, BuyFromShop or SendPigeon. The authenticated **account**
885determines the actor; after character select, commands apply to that
886account's **active character**. The
887client never supplies an authoritative resulting position, health
888value or inventory result.
889
890## 14.3 Input queue
891
892Socket handlers validate message shape and enqueue commands. Simulation
893workers consume commands at tick boundaries. WebSocket callbacks do not
894mutate ECS state directly.
895
896## 14.4 Authentication
897
898Live login uses **auth.timfalken.com**. The game server never stores a
899password. It receives an authenticated account identity (and email) from
900that service and maps it to a durable `accountId` in `state.sqlite`.
901
902Until auth.timfalken.com is available, the gateway uses a **stub identity**:
903each new connection is `admin-<n>`, where `n` is the number of currently
904connected clients **including this one** (the first connection is
905`admin-1`). Stub accounts are treated as admins so the world editor can be
906used during development. Stub accounts have no email; deletion “emails”
907are logged instead of sent.
908
909When real auth ships, the stub is removed. Admin rights come from that
910service, not from the `admin-` name prefix.
911
912An account may have only **one active play session** at a time (one
913character in the world).
914
915## 14.5 Characters
916
917An account has unlimited characters and plays **one** at a time. First
918login with no characters must create one before entering the world. Later
919logins show a character-selection menu: create, choose, mark for deletion,
920or cancel deletion.
921
922Initial character setup (may change later):
923
924```text
925CreateCharacter
926- firstName // not globally unique
927- lastName // unique surname, owned by this account
928- sex // male | female
929```
930
931Rules:
932
933- **Last names** are globally unique. The first character to take a surname
934 claims it for that **account**. The same player may reuse that last name
935 on their other characters. Another account cannot use it.
936- **First names** need not be unique globally.
937- For a given account, `firstName` + `lastName` must be unique among
938 characters that still exist (including those pending deletion).
939- Uniqueness is case-insensitive; display uses the casing the player typed.
940
941```text
942Account
943- accountId
944- authSubject // from auth.timfalken.com, or stub admin-<n>
945- email? // from auth; absent on stub
946- surnameClaims[]
947
948Character
949- characterId
950- accountId
951- firstName
952- lastName
953- sex
954- deletionScheduledAt? // null if not deleting
955- inventory, equipment, currency, vault, skills, ...
956```
957
958The in-world ECS player entity is a **character**, not the account.
959
960## 14.6 Character deletion and inheritance
961
962From character select, the player may mark a character for deletion.
963
964- The character cannot be played while deletion is pending.
965- Permanent delete happens after `characterDeletionDelay` (default **24
966 hours**). Until then the player may cancel.
967- The server **always** notifies the account email when deletion is
968 marked (and should notify again on cancel and on actual delete). Stub
969 auth logs the message instead.
970- On permanent delete, the name pair is freed. If this account has no
971 remaining characters with that last name, the surname claim is released.
972- Before the vault is moved, `BankService` voids outstanding filled
973 cheques **issued by** this character (reservations return to the vault).
974- All items in inventory, equipment, carried currency, and the character
975 vault are moved to that **account's inheritance bank tab**.
976
977Any living character of the same account may, at a bank, **claim**
978inheritance stacks (and currency) into that character's own vault. Claiming
979is a move from the account tab to the character vault, not a second copy.
980
981# 15. Client chunk subscription and replication
982
983## 15.1 3×3 visibility
984
985A player receives the current chunk and the eight surrounding chunks, a
986maximum viewport of 48×48 tiles. Neighbouring **closed** chunks are still
987sent so scenery remains visible; the player simply cannot walk onto them.
988
989┌───┬───┬───┐
990│ V │ V │ V │
991├───┼───┼───┤
992│ V │ P │ V │
993├───┼───┼───┤
994│ V │ V │ V │
995└───┴───┴───┘
996
997## 15.2 Incremental subscription changes
998
999Crossing one chunk east subscribes only the three newly visible eastern
1000chunks and unsubscribes only the three old western chunks. The rest of
1001the 3×3 view remains subscribed.
1002
1003## 15.3 Snapshots and deltas
1004
1005Initial subscription sends a CHUNK_SNAPSHOT containing authored/runtime
1006tile state, currently visible entities and unexpired ground item stacks.
1007Afterwards, revisioned CHUNK_DELTA messages report tile changes, entity
1008spawn/move/change/despawn events and ground-item appear/change/despawn
1009events. Full chunks are not retransmitted every tick.
1010
1011Entity `move` events carry the new integer tile and the current gait so
1012the client can lerp over the walk or run interval. They do not carry a
1013fractional in-between position. Smooth walking is a client visual lerp
1014(section 21.5), not part of the replication payload.
1015
1016Chunk snapshots include the baked light map (section 8.6).
1017
1018Visible equipment is replicated as a compact appearance payload (body
1019sprite plus worn overlay layers and recolour parameters), not as the
1020entity's full inventory. Nearby clients can draw another player's armour
1021without receiving their bags.
1022
1023## 15.4 Visibility can span workers
1024
1025The gateway can source visible chunks from multiple workers. A player
1026may be authoritative on Worker A while one or more of the eight
1027neighbouring visible chunks are owned by Worker B. Client visibility
1028must never force simulation-region reassignment.
1029
1030# 16. Click-to-move and A\* pathfinding
1031
1032## 16.1 Command flow
1033
1034Client: MOVE_TO(tileX, tileY)
1035↓
1036Gateway validates/authenticates
1037↓
1038Owning worker validates target
1039↓
1040A\* calculates authoritative route
1041↓
1042Path component attached/updated
1043↓
1044MovementSystem advances the entity **one tile at a time** on the global
1045walk/run cadence (section 13.4)
1046
1047Authoritative `Position` is always an integer `tileX`, `tileY`. The server
1048does not store a sub-tile location for walking mobiles. When a movement
1049tick allows this gait to step, `MovementSystem` commits the next path
1050tile in a single jump. Combat, occupancy, pickup and interaction all use
1051that committed tile.
1052
1053Flying pigeons still ignore the ground navigation grid, but their
1054replicated ECS position is likewise a tile. The transit clock determines
1055which tile they occupy at a given time; the client may lerp the sprite
1056between those tiles like any other mobile.
1057
1058## 16.2 Initial A\* implementation
1059
1060For normal player clicks within the visible 3×3 chunks, the search space
1061is at most 48×48 = 2,304 tiles, so conventional A\* is a strong starting
1062point.
1063
1064- Binary heap priority queue for the open set.
1065
1066- Manhattan heuristic for four-direction movement; octile heuristic if
1067 diagonal movement is later allowed.
1068
1069- Reusable typed-array or pooled search buffers for hot paths to reduce
1070 allocation and garbage collection.
1071
1072- Rate-limit path requests per player and avoid recalculation every
1073 tick.
1074
1075- Use block passability, **open-chunk** bounds, and dynamic occupancy;
1076 ground is visual only. Tiles in closed or never-edited chunks are not
1077 legal path targets for players.
1078
1079## 16.3 Navigation revisions
1080
1081Each chunk maintains a navigation revision that increments when a
1082movement-affecting block changes. A path records the relevant revisions.
1083Static geometry changes can invalidate paths; temporary mobile occupancy
1084normally causes a short wait or small local re-path rather than
1085rebuilding every path.
1086
1087## 16.4 Long-distance extension
1088
1089If long-distance autonomous travel is added later, introduce
1090hierarchical pathfinding: region graph → chunk portals/edges → local
1091tile A\*. The client movement command interface does not need to change.
1092Server movement remains discrete tile steps; only the path length changes.
1093
1094# 17. Automatic update and restart scheduler
1095
1096## 17.1 Restart triggers
1097
1098A graceful restart is scheduled for the next midnight in configured
1099server-local time when either of these conditions occurs:
1100
1101- A new commit is detected on origin/master. The master branch is the
1102 live branch.
1103
1104- An administrator saves a world-editor change, creating/updating a
1105 pending authored world revision.
1106
1107Multiple triggers coalesce into one scheduled restart. The scheduler
1108stores all reasons so players and admins can see why a restart is
1109pending.
1110
1111## 17.2 Detecting live-code changes
1112
1113The running server periodically performs a non-destructive remote check,
1114for example git fetch origin master followed by comparison of the
1115running commit with origin/master. It does not update the checked-out
1116code while the game is live.
1117
1118## 17.3 Server-local midnight
1119
1120Midnight is calculated in a configured IANA time zone rather than by
1121adding 24 hours to the current time. This keeps behaviour correct across
1122daylight-saving transitions.
1123
1124## 17.4 Player-visible restart state
1125
1126Restart status is part of the server status sent to clients. Connected
1127players see that a restart is scheduled and the scheduled local time.
1128The server can also issue configurable countdown notices as the restart
1129approaches and includes the state immediately when a player logs in.
1130
1131RestartStatus {
1132scheduled: true,
1133scheduledAt: timestamp,
1134reasons: \["code-update", "world-update"\]
1135}
1136
1137## 17.5 Manual admin restart
1138
1139An authorised admin action can invoke the same graceful restart pipeline
1140immediately. This is not a separate “hard restart” path; it differs only
1141in scheduled time.
1142
1143## 17.6 Graceful restart sequence
1144
1145> **1.** Enter `DRAINING` / `RESTARTING` state and reject new logins.
1146>
1147> **2.** Broadcast the final restart notice.
1148>
1149> **3.** Disconnect player sessions cleanly and persist session state.
1150> Shutdown handling overrides normal offline-script retention so chunk
1151> unload cannot be blocked by a retiring process.
1152>
1153> **4.** Stop accepting new gameplay commands and finish the current
1154> safe tick boundary.
1155>
1156> **5.** Force-unload every resident region/chunk, ignoring normal
1157> `ChunkLoader` references. This invokes the ordinary chunk/entity unload
1158> persistence path exactly once.
1159>
1160> **6.** Flush the persistence service and close SQLite connections
1161> cleanly.
1162>
1163> **7.** Atomically write a restart request manifest. It records the
1164> restart reasons, whether a code deployment is requested, the target Git
1165> commit if known, and the pending world revision if one exists.
1166>
1167> **8.** Exit the Node.js game process cleanly. At this point the game
1168> process has no responsibility for updating or relaunching itself.
1169
1170## 17.7 systemd process supervisor
1171
1172The production Node.js process is owned by a `systemd` service. `systemd`
1173therefore already knows when the process has **fully exited**; no separate
1174polling process is needed. Only after the previous `ExecStart` process is
1175gone does `systemd` begin the next service start.
1176
1177The preferred lifecycle is:
1178
1179```text
1180Running Node.js server
1181 |
1182 | graceful planned restart or crash
1183 v
1184Node.js process fully exits
1185 |
1186 v
1187systemd starts the service again
1188 |
1189 +--> conditional update hook
1190 | |
1191 | +--> planned code deployment: git fetch/pull --ff-only
1192 | +--> world-only restart: no Git mutation
1193 | +--> crash/no restart manifest: no Git mutation
1194 |
1195 +--> optional dependency/build step if deployment changed code
1196 |
1197 v
1198Start Node.js server
1199 |
1200 v
1201Startup selects the new active world revision
1202 |
1203 v
1204Gateway opens when the world reports READY
1205```
1206
1207### 17.7.1 Why Git pull must be conditional
1208
1209A naive `ExecStartPre=git pull` on **every** restart is unsafe. Suppose a
1210new commit is detected at 14:00 and correctly scheduled for midnight, but
1211the game process crashes at 16:00. An unconditional pull would deploy the
1212new commit immediately during crash recovery, bypassing the scheduled
1213maintenance window.
1214
1215Therefore the restart manifest distinguishes an intentional deployment
1216restart from an ordinary process failure:
1217
1218```json
1219{
1220 "reason": ["code-update", "world-update"],
1221 "deployCode": true,
1222 "targetCommit": "<optional commit hash>",
1223 "pendingWorldRevision": 184
1224}
1225```
1226
1227The manifest should be written using a temporary file plus atomic rename
1228so the supervisor never consumes a half-written request. The supervisor
1229consumes/removes the request only after it has successfully interpreted
1230it.
1231
1232If the Node.js process dies without a valid deployment request, `systemd`
1233restarts the **currently checked-out version**. This gives fast crash
1234recovery without prematurely deploying pending code.
1235
1236### 17.7.2 Suggested systemd shape
1237
1238A production unit can conceptually look like this:
1239
1240```ini
1241[Unit]
1242Description=Tile MMO Server
1243After=network-online.target
1244Wants=network-online.target
1245
1246[Service]
1247Type=simple
1248User=tilemmo
1249Group=tilemmo
1250WorkingDirectory=/srv/tile-mmo/current
1251
1252# This hook checks the restart manifest. It pulls/builds only when an
1253# intentional deployment was requested. Prefixing with '+' optionally
1254# allows the hook to run with privileges different from the game user.
1255ExecStartPre=+/usr/local/sbin/tile-mmo-update-if-requested
1256ExecStart=/usr/bin/node /srv/tile-mmo/current/dist/server.js
1257
1258Restart=always
1259RestartSec=5s
1260TimeoutStopSec=120s
1261KillSignal=SIGTERM
1262
1263[Install]
1264WantedBy=multi-user.target
1265```
1266
1267`Restart=always` is appropriate here because an explicit
1268`systemctl stop tile-mmo` does not cause systemd to restart the unit,
1269while a clean in-game restart exit and an unexpected crash both do.
1270
1271The exact paths, build command and privilege split are deployment
1272details, but the important invariant is that the **Node.js process does
1273not pull Git itself**.
1274
1275### 17.7.3 Code-update, world-update and crash behaviour
1276
1277| Situation | Restart manifest | Git pull before restart | World revision |
1278|---|---|---|---|
1279| Scheduled code update | `deployCode=true` | Yes, fast-forward only | Activate pending revision if present |
1280| World-editor-only update | `deployCode=false` | No | Activate pending revision |
1281| Manual deployment restart | Explicit admin intent | As requested | Activate pending revision if present |
1282| Unexpected Node.js crash | Missing/invalid | **No** | Continue current active revision |
1283| `systemctl stop` | Irrelevant | No automatic restart | N/A |
1284
1285This preserves the midnight deployment promise even when the game crashes
1286before the scheduled maintenance window.
1287
1288## 17.8 Failure behaviour
1289
1290Deployment should fail closed. If Git cannot fast-forward, a build or
1291migration fails, or startup validation fails, the game must not open to
1292players on a partially updated state. The update hook should log the
1293failure clearly and return non-zero; systemd may retry according to its
1294restart/start-limit policy. Databases remain intact, and backups or
1295snapshots before schema migrations are recommended.
1296
1297A failed **crash recovery** that did not request deployment must not
1298silently switch to a newer Git commit as a recovery strategy.
1299
1300# 18. Future player scripting architecture
1301
1302## 18.1 Scope
1303
1304The custom scripting language is explicitly a later feature. Version 1
1305only needs architectural hooks so adding scripts does not require
1306replacing the player-control or simulation model.
1307
1308## 18.2 Controller abstraction
1309
1310All player actions should already pass through an internal command
1311interface. Manual client input is therefore one possible controller. A
1312future script is another controller that emits the same validated action
1313intentions.
1314
1315```text
1316ClientController ─┐
1317 ├─> ActionCommand queue ─> authoritative game systems
1318ScriptController ─┘
1319```
1320
1321Scripts never mutate ECS components directly. They request actions such
1322as MoveTo, Interact or Attack and receive the same validation as a human
1323client.
1324
1325## 18.3 Online scripted mode
1326
1327A logged-in player may enable the script while remaining connected and
1328observing the game. Control mode explicitly determines whether manual
1329input or the script is currently producing gameplay commands. The server
1330remains authoritative either way.
1331
1332## 18.4 Logout with active script
1333
1334If a player has configured offline script execution, logout removes the
1335network/controller connection but keeps the player entity alive. The
1336entity changes to an offline script-controlled state and continues
1337acting until it dies or its configured offline duration expires.
1338
1339Player online
1340Player + NetworkIdentity + ChunkLoader + Controller
1341↓ logout with offline scripting
1342Player + ScriptController + ChunkLoader + OfflineUntil
1343↓ death OR expiry
1344persist player state → remove runtime entity
1345
1346## 18.5 Offline scripted players and loading
1347
1348An offline scripted player must continue to stimulate the world it
1349traverses, so it retains a ChunkLoader. This is powerful but potentially
1350expensive: thousands of offline scripts could keep large parts of the
1351world active. Offline duration, script CPU budget and concurrent
1352offline-script limits therefore become explicit resource policy, not
1353implementation accidents.
1354
1355## 18.6 Restart continuity
1356
1357A planned restart persists the offline-script state and expiry time,
1358force-unloads the old process, and rehydrates still-valid offline
1359scripted players during startup. This is why the startup index for
1360persistent ChunkLoaders is part of the base architecture.
1361
1362## 18.7 Scripting language safety requirements
1363
1364When the language is implemented, it should be interpreted/compiled into
1365a purpose-built sandbox rather than evaluated as JavaScript. At minimum
1366it should enforce:
1367
1368- No file-system, operating-system, database or arbitrary network
1369 access.
1370
1371- No eval or escape into Node.js objects.
1372
1373- Per-tick/per-event instruction budgets and bounded memory.
1374
1375- Rate-limited expensive operations such as path requests and world
1376 queries.
1377
1378- Capability-based read APIs for nearby visible/known world state.
1379
1380- Action output only through the normal server command pipeline.
1381
1382- Persistable script variables/state if offline execution must survive
1383 restarts.
1384
1385- Deterministic or tightly controlled timing semantics where practical.
1386
1387An event-driven language is preferable to running every player script
1388continuously at full simulation frequency. Events such as arrival,
1389attack, nearby entity changes or timer expiration can wake scripts only
1390when useful.
1391
1392# 19. Security and administration
1393
1394- World-editor endpoints require an explicit admin role and separate
1395 server-side authorisation checks.
1396
1397- Client-supplied entity/player IDs are never trusted as authority;
1398 authenticated connection/session context identifies the actor.
1399
1400- World-editor data is validated against known ground, block, item and mob
1401 definitions before database write.
1402
1403- Admin restart and deployment controls use the same authenticated
1404 administration layer.
1405
1406- The Node.js game process should run as a dedicated unprivileged user.
1407 Where practical, source-update permission belongs only to the systemd
1408 update hook (for example a privileged `ExecStartPre` helper), leaving
1409 the running Node.js process unable to modify its own checkout.
1410
1411- SQLite writes are parameterised and centralised through
1412 persistence/editor services.
1413
1414- Inventory, vault, cheque and courier mutations are server-authoritative.
1415 Clients cannot invent cheque IDs, forge cargo, or credit a vault.
1416
1417- Attack hit/miss and damage are server-authoritative. Clients cannot supply
1418 a roll or a damage result. Shop purchase prices are computed at buy time
1419 on the server.
1420
1421# 20. Recommended process topology
1422
1423```text
1424Clients
1425 |
1426 v
1427WebSocket/API Gateway
1428 |
1429 +-- Region Coordinator ----> Simulation Worker A
1430 | <--> Simulation Worker B
1431 |
1432 +-- Communication Service --> proximity speech
1433 |
1434 +-- CourierService ---------> pigeon cargo / transit
1435 |
1436 +-- BankService ------------> shared vaults / cheques / reservations
1437 |
1438 +-- MarketService ----------> order book / escrow / trades / last-sale index
1439 |
1440 +-- Persistence Service ----> state.sqlite
1441 |
1442 +-- Admin / World Editor ---> world.sqlite
1443
1444External process supervision:
1445systemd ---> conditional deployment hook ---> Node.js relaunch
1446```
1447
1448# 21. Player client architecture
1449
1450## 21.1 FrameworkV3 as a git submodule
1451
1452The player-facing client is built on the shared FrameworkV3 library:
1453
1454<https://gitlab.com/Timfa/frameworkv3>
1455
1456FrameworkV3 contains generic reusable client-side code. Game-specific rendering,
1457UI, input, assets and protocol handling live in this repository, on top of
1458that library. They are not patched into FrameworkV3 unless they are genuinely
1459reusable across games.
1460
1461This repository vendors FrameworkV3 as a **git submodule** rather than
1462copying its source or depending on an unpublished global install.
1463
1464```text
1465mmo/
1466 client/
1467 frameworkv3/ # git submodule → gitlab.com/Timfa/frameworkv3
1468 src/ # this game's client: protocol, UI, world view, assets
1469 server/ # Node.js ECS backend; does not import FrameworkV3
1470```
1471
1472The submodule path is `client/frameworkv3`. A clone of this repo is not
1473client-buildable until submodules are present:
1474
1475```text
1476git clone --recurse-submodules <this-repo>
1477# or, in an existing checkout:
1478git submodule update --init --recursive
1479```
1480
1481The submodule records a **pinned commit**. Bumping FrameworkV3 is an explicit
1482commit in this repository (new submodule SHA). Game code must not rely on an
1483uncommitted dirty checkout of the submodule.
1484
1485Build order:
1486
1487```text
14881. Build FrameworkV3 from client/frameworkv3
14892. Build this game's client against that output
14903. The Node.js server is a separate build and does not link FrameworkV3
1491```
1492
1493The exact FrameworkV3 build command follows that project's own instructions.
1494This game's client build must consume the framework's public/build artefacts,
1495not fork its internals.
1496
1497CI and developer machines check out submodules before the client job. A
1498missing or uninitialized submodule is a failed client build, not a fallback
1499to a system copy of FrameworkV3.
1500
1501If this repo's `master` also ships the built web/desktop client from the
1502same process that deploys the game server, a submodule bump is just another
1503commit and follows the normal midnight restart/deploy path. The running
1504Node.js game process still does not compile or import FrameworkV3.
1505
1506The backend remains the authoritative Node.js ECS simulation described in this
1507document. The client does **not** need to use ECS. It receives only a small
15083×3-chunk view plus player/UI state, so a conventional object/view-model model is
1509simpler and entirely appropriate.
1510
1511## 21.2 Server/client model separation
1512
1513Backend ECS components are not treated as a shared client object model. Network
1514messages form the contract between the two sides.
1515
1516```text
1517Authoritative Node.js ECS
1518 |
1519 | snapshots / deltas / UI state
1520 v
1521Network protocol DTOs
1522 |
1523 v
1524Built FrameworkV3 (from client/frameworkv3 submodule)
1525 |
1526 v
1527This game's client code (client/src)
1528```
1529
1530The two projects may share protocol schemas, enums or generated message types,
1531but the client must not depend on the internal layout of ECS component storage.
1532That allows server internals to be optimised without forcing corresponding
1533client rewrites.
1534
1535## 21.3 Sprites are 16×16
1536
1537Every world sprite — ground tiles, blocks, mobs, item icons and other
1538in-world art — is exactly **16×16 pixels**. Sprites are not individually
1539stretched to a different size. One sprite corresponds to one tile on the
1540world pixel grid.
1541
1542At load time, any image whose width or height is not 16 is **rejected**.
1543The asset must not enter the runtime atlas or definition registry. The
1544failure should name the file and its actual dimensions.
1545
1546A unit test walks the sprite asset tree (grounds, blocks, mobs, items,
1547equipment overlays, recolour masks, and any other world-sprite folders)
1548and performs the same check. It reports every offender and **fails if any
1549are found**. This test belongs in CI so a non-16×16 sprite cannot ship even
1550if a local load path is skipped. Recolour masks are 16×16 world sprites
1551too; a mismatched mask is a failed test.
1552
1553Camera zoom (section 21.4) scales the whole viewport uniformly. It is not
1554a per-sprite size override. Rendering should use nearest-neighbour
1555sampling so 16×16 pixels stay sharp.
1556
1557## 21.4 Viewport, camera and zoom
1558
1559In normal play the viewport is **always centered on the local player's
1560character**. The camera does not free-pan. Scrolling the world happens
1561only because the player moved.
1562
1563The player may zoom in and out within configured minimum and maximum
1564bounds (for example 1× to 4×; the exact numbers are a game setting). Zoom
1565does not move the camera off the player and does not change server
1566visibility: the client still receives only the 3×3 chunk window.
1567
1568The admin world editor is the exception: it frames the selected 16×16
1569chunk and navigates by chunk, as in section 8.1.
1570
1571## 21.5 Client movement interpolation
1572
1573The server jumps mobiles from tile to tile. The client draws a visual
1574lerp between the previous replicated tile and the new one over the
1575interval implied by gait and `WorldSettings` (walk: `1 / walkTilesPerSecond`,
1576run: half of that). If a delta arrives late, clamp the remaining lerp.
1577That lerp is presentation only:
1578
1579- Hit tests, range, pickup and occupancy use the authoritative tile.
1580- A corrected server position snaps the interpolation target; the client
1581 does not accumulate drift.
1582- Interpolation does not entitle the client to send fractional positions.
1583
1584## 21.6 Equipment layers and recolouring
1585
1586A mob (including a player character) is drawn as a **stack of 16×16
1587sprites** on the same tile: the body sprite (male or female from character
1588sex, or the mob archetype body), then each piece of visible equipment.
1589Overlays are not baked into the body art.
1590
1591```text
1592draw order (back → front, default)
1593 1. body / mob base
1594 2. boots
1595 3. legs
1596 4. chest
1597 5. head
1598 6. off-hand
1599 7. weapon
1600```
1601
1602Slot draw order is data so a cloak or a two-handed sprite can be inserted
1603without a renderer rewrite. Every overlay sprite, like every other world
1604sprite, is exactly 16×16 and is rejected on load / CI if it is not.
1605
1606Equipment items stay in dedicated **equipment slots**, not in the 32
1607inventory slots, while worn. `EquipItem(slotIndex)` moves a legal item
1608from inventory into the matching equipment slot, returning any previously
1609worn item to inventory if there is space. `UnequipItem(equipSlot)` does
1610the reverse. The weapon equipment slot is what combat uses; it replaces
1611the older “wielded flag on an inventory slot” idea.
1612
1613Non-player mobs may carry an `Equipment` component or a simpler appearance
1614list on the mob definition so a guard can show armour without a player
1615inventory.
1616
1617```text
1618Equipment
1619- slots: { head?, chest?, legs?, boots?, weapon?, offhand?, ... }
1620
1621ItemDefinition.equipment?
1622- slot
1623- overlaySpriteId
1624- recolourableChannels?: ["metal"] // omitted if the art is not recoloured
1625- materialId? // e.g. iron, steel; used with "metal"
1626```
1627
1628Inventory icons and worn overlays may be different 16×16 files. Both are
1629world sprites and both go through the size check.
1630
1631### Recolourable equipment
1632
1633Some gear shares one overlay and is tinted per material. Metal armour is
1634the initial case: iron, steel and later metals are not separate full-size
1635art sets.
1636
1637```text
1638MaterialDefinition
1639- materialId // iron, steel, ...
1640- displayName
1641- channel // metal for armour; later channels may include cloth
1642- colour // destination RGB for that channel
1643```
1644
1645A recolourable overlay is authored as:
1646
1647- the 16×16 overlay sprite, with shading in the channel regions, and
1648- an optional 16×16 **channel mask** of the same dimensions, whose pixels
1649 name which recolour channel they belong to (for example a reserved mask
1650 colour meaning `metal`). Unmasked pixels are drawn unchanged.
1651
1652At draw time, masked pixels keep the overlay’s relative brightness
1653(highlights and shadows) and replace the hue/saturation with the
1654item’s `MaterialDefinition.colour`. The client must not invent a colour;
1655the server sends the material id (or the already-resolved colour) on the
1656appearance layer.
1657
1658Iron plate and steel plate therefore share `overlaySpriteId = platebody`
1659and differ only by `materialId`. Non-metal unique art omits
1660`recolourableChannels` and is blitted as authored.
1661
1662Recolour happens on the client as a presentation step. It does not change
1663item identity, combat stats or inventory. Nearby observers receive enough
1664appearance data to apply the same layers and tints.
1665
1666## 21.7 World time and night shading
1667
1668The client treats **world time** as server time minus 1200 years (section
166913.5). It uses that clock-of-day to shade the 3×3 view.
1670
1671At night, tiles that the baked light map says are unreachable from any
1672static light are drawn darker. Tiles a light can reach stay brighter.
1673Light does not bleed through walls: the mask was raycast through passable
1674tiles at editor save, including across chunk borders, so a torch on the
1675edge of one chunk can light tiles in the next.
1676
1677By day, ambient light is full and the baked mask does not darken the
1678ground. The day/night curve (how dark “night” is, dusk length) can stay a
1679world setting or a later tuning value; the invariant is that night uses
1680baked reachability, not a per-frame raycast.
1681
1682The world-editor night-to-day slider is the same shading function, driven
1683by the slider instead of the clock, so an admin can preview a chunk at
1684any light level without changing live world time.
1685
1686# 22. Items, inventory and ground drops
1687
1688## 22.1 Item definitions
1689
1690Every obtainable object is an `ItemDefinition`. Stacking, uniqueness and
1691later economy rules are data on that definition, not special cases in UI
1692code.
1693
1694```text
1695ItemDefinition
1696- itemId
1697- displayName
1698- description
1699- seedValue // base price before player-market adaptation
1700- stackable
1701- maxStackSize // default 99 for stackable items
1702- uniqueInstance // true for letters, filled cheques, and similar
1703- category: ingredient | intermediate | finished | document | other
1704- npcShopAllowed
1705- gatherSources
1706- craftingRecipe(s)
1707- dropTableSources
1708- attack?: AttackProfile // weapons; omitted for non-weapons
1709- equipment?: // worn/wielded visuals; see 21.6
1710 slot
1711 overlaySpriteId
1712 recolourableChannels?
1713 materialId?
1714```
1715
1716A stackable item with no instance data merges with an identical `itemId` in
1717the same container up to `maxStackSize`. Unique-instance items never merge;
1718each occupies its own slot at quantity 1.
1719
1720**Currency is not an inventory item.** Carried money is a numeric `Currency`
1721balance on the player. Banked money is a numeric balance on that player's
1722vault. Coins do not occupy inventory slots and cannot be dropped on the
1723ground in this model.
1724
1725How most items are obtained is specified later. Two source families already
1726fit this model without changing it:
1727
1728- Ground-item spawners in the world editor, analogous to mob spawners.
1729- Later harvesting from the environment by players.
1730
1731Paper, blank cheques and letters are specified now because communication,
1732banking and pigeons depend on them.
1733
1734## 22.2 Player inventory
1735
1736A player inventory has exactly **32 slots**.
1737
1738```text
1739Inventory
1740- slots[32]: empty | ItemStack
1741
1742ItemStack
1743- itemId
1744- quantity // 1 for unique-instance items
1745- instance?: ItemInstance // present only when uniqueInstance is true
1746- origin?: ItemOrigin // crafter or shop NPC; see 22.6
1747```
1748
1749Rules:
1750
1751- A stack occupies exactly one slot, regardless of quantity.
1752- Inserting a stackable item first tries to merge into an existing compatible
1753 stack whose combined quantity would not exceed `maxStackSize`. Stacks are
1754 compatible only when `itemId` matches and `origin` matches (including both
1755 being empty). Any remainder needs an empty slot, or the whole action fails.
1756- Moving, swapping and splitting stacks are ordinary server-validated
1757 commands. The client never asserts the resulting inventory.
1758- Inventory, wallet and vault contents are **player-private UI state**. They
1759 are not part of 3×3 chunk replication. Other clients see ground items and
1760 pigeon entities, not another player's bags or a pigeon's cargo.
1761- Logout and restart persist the full inventory and carried currency in
1762 `state.sqlite`.
1763
1764## 22.3 Paper and letters
1765
1766Blank paper is a stackable item.
1767
1768Writing consumes one paper and produces a **letter**: a unique-instance item
1769whose instance data is text written by a player. A letter is not a mail
1770record and has no inherent recipient. It is just paper with writing on it.
1771
1772```text
1773LetterInstance
1774- letterId
1775- authorPlayerId
1776- body
1777- writtenAt
1778```
1779
1780If the paper stack's quantity is 1, the slot may be converted in place into
1781the letter. If quantity is greater than 1, writing requires a free inventory
1782slot for the new letter and decrements the paper stack.
1783
1784Reading a letter inspects its instance data. Sending a letter is the same
1785pigeon-cargo action used for any other item stack.
1786
1787Maximum letter length is a defined game rule and can be chosen during
1788implementation.
1789
1790## 22.4 Dropping items
1791
1792A player may drop an item stack, or part of a stack, onto their current tile.
1793
1794```text
1795GroundItem
1796- groundItemId
1797- tileX / tileY
1798- ItemStack
1799- droppedAt
1800- expiresAt // droppedAt + WorldSettings.groundItemDespawnDuration
1801- source // player-drop | later: item-spawner
1802- droppedByPlayerId?
1803```
1804
1805Rules:
1806
1807- Player-dropped items remain for `WorldSettings.groundItemDespawnDuration`
1808 (default **10 minutes**), then vanish forever.
1809- Anyone may pick up a ground item. There is no owner lock and no loot-rights
1810 delay.
1811- Ground items **do not block movement** and do not prevent a player from
1812 standing on that tile.
1813- Pickup requires the player to **stand on that tile**. The command names the
1814 `groundItemId` when several stacks share the tile.
1815- Pickup fails if the player's inventory cannot accept the stack (no legal
1816 merge and no empty slot). The ground item is unchanged.
1817- Several distinct stacks may occupy one tile at once.
1818- Later naturally spawned ground items use the same non-blocking
1819 representation, but their lifetime and respawn belong to the item spawner
1820 rather than this 10-minute player-drop timer.
1821
1822Dropped items are not `ChunkLoader`s and do not keep a chunk simulated.
1823
1824They **do** survive chunk unload until `expiresAt`, using timestamp expiry
1825rather than a per-tick countdown. On unload, unexpired ground items are
1826written to `state.sqlite`. On load or wake, items whose `expiresAt` is in
1827the past are discarded and never replicated. Simulating chunks also remove
1828them when the timestamp elapses.
1829
1830If a unique-instance item that encodes a bank reservation (a filled cheque)
1831expires on the ground or is otherwise destroyed without being redeemed, that
1832reservation is released and the reserved goods become available in the
1833issuer's vault again.
1834
1835## 22.5 Pickup and drop commands
1836
1837```text
1838DROP_ITEM(slotIndex, quantity?)
1839PICKUP_ITEM(groundItemId)
1840```
1841
1842Both are intentions. The owning worker validates the actor's tile, inventory
1843space and stack rules, then applies the result. Standing on a tile that has
1844ground items does not pick them up automatically.
1845
1846## 22.6 Item inspection, origin and displayed value
1847
1848Hovering an item — in inventory, a shop stock list, or on the ground — shows
1849at least:
1850
1851```text
1852ItemTooltip
1853- displayName
1854- description
1855- originLabel // who crafted it, or the shop NPC if bought there
1856- currentValue // undiscounted adapted value; see section 27
1857```
1858
1859Origin is stored on the stack:
1860
1861```text
1862ItemOrigin
1863- kind: crafted | shop | unknown
1864- playerId? // when crafted by a player
1865- npcId? // when bought from a shop NPC
1866```
1867
1868The origin label is the crafting player's name, or the shop NPC's name when
1869the stack was bought from that NPC. Harvested, looted or otherwise unstamped
1870stacks use `unknown` and omit the origin line until later content says
1871otherwise. Buying from a shop stamps that NPC as origin. Crafting stamps the
1872crafter. Shop-bought goods are not treated as crafted by the NPC; the NPC
1873name simply occupies that inspection field.
1874
1875`currentValue` uses the same last-sale lerp as shopkeepers (section 27.6) but
1876**without** the per-shop discount. It is informational. The client must not
1877recompute it every simulation tick. The player UI may refresh displayed
1878values at most once per minute, from the last-sale record plus `seedValue`.
1879The actual shop purchase price is always computed server-side at the moment
1880of purchase.
1881
1882# 23. Player communication and carrier pigeons
1883
1884## 23.1 Proximity chat is the default
1885
1886Ordinary chat is spatial. A player speaks from a world position and only nearby
1887players receive a useful version of the message. Legibility decreases as the
1888recipient gets farther from the speaker.
1889
1890For example:
1891
1892```text
1893Near: I'm really far away
1894Farther: I'm re...y far aw.y
1895Very far: I'...re..ly..ar.aw.y
1896Beyond range: no message
1897```
1898
1899The exact distance bands/function are configurable game rules.
1900
1901Crucially, degradation is performed **server-side**. The server must not send the
1902full plaintext to a distant client and merely ask that client to obscure it,
1903because a modified client could then recover speech it was not supposed to
1904understand.
1905
1906A chat message therefore conceptually contains:
1907
1908```text
1909ChatSpeech
1910- messageId
1911- speakerEntityId
1912- originX / originY
1913- createdAt
1914- text
1915```
1916
1917The communication service performs a spatial recipient query and derives the
1918recipient-specific legible representation before routing it through the gateway.
1919Chat routing is separate from normal 3×3 chunk replication, so the eventual
1920hearing/text range does not have to equal the visual chunk-subscription radius.
1921
1922## 23.2 Persistent player groups
1923
1924Players can create permanent groups and invite other players into them. Groups
1925are durable social entities stored in `state.sqlite`, with membership surviving
1926logout and server restart.
1927
1928A minimal model contains:
1929
1930```text
1931PlayerGroup
1932- groupId
1933- name
1934- owner / roles
1935- createdAt
1936
1937PlayerGroupMember
1938- groupId
1939- playerId
1940- role
1941- joinedAt
1942```
1943
1944Invite, accept, leave, kick and role-management operations are authoritative
1945server actions.
1946
1947Group membership does **not** create magical long-distance communication. If
1948members are close enough, they can communicate through the normal proximity
1949rules. Communication to distant group members means sending items — including
1950letters — by carrier pigeon, the same mechanism available to any player.
1951
1952If group-wide letter sending is later supported, it is an addressing
1953convenience that still consumes one paper/letter item and one pigeon dispatch
1954per recipient. The group is not a global instant chat channel.
1955
1956## 23.3 Pigeons carry cargo, not messages
1957
1958A carrier pigeon is a free physical courier. It does not send a chat packet.
1959It carries **either**:
1960
1961- an amount of the sender's carried currency, or
1962- exactly one item stack (a letter, a filled cheque, blank paper, or any
1963 other stack)
1964
1965One pigeon cannot carry both money and an item, and cannot carry two item
1966stacks. Dispatching a pigeon is **free**, so a player who wants to move
1967several stacks sends several pigeons one after another.
1968
1969Cargo is removed from the sender immediately and placed into durable transit.
1970A crash or restart cannot duplicate that cargo or silently erase it.
1971
1972Pigeons are not inventory items. Any player may dispatch one from anywhere,
1973provided they have valid cargo.
1974
1975```text
1976SendPigeon
1977- destination: Player(playerId) | Bank
1978- cargo: Money(amount) | Item(slotIndex, quantity?)
1979```
1980
1981## 23.4 Destinations
1982
1983**Player destination.** The pigeon flies toward the named player. On arrival:
1984
1985- Money is added to the recipient's carried `Currency` if they are online;
1986 otherwise it is deposited into the recipient's bank.
1987- An item stack is placed in the recipient's inventory if they are online and
1988 have space (a legal merge or an empty slot). If they are offline or cannot
1989 accept the stack, the pigeon continues to the **nearest bank** and deposits
1990 the stack into the recipient's vault.
1991
1992This keeps offline and full-inventory delivery durable without a separate
1993mailbox object.
1994
1995**Bank destination.** The pigeon flies to the **nearest bank** to the dispatch
1996tile. Travel time is that aerial journey, even though every bank shares the
1997same vault. On arrival the cargo is deposited into the **sender's** vault,
1998except for the filled-cheque special case in section 24.7.
1999
2000"Nearest bank" is computed from authored Bank block positions in the pinned
2001world revision. If additional banks are added later, a pigeon sent to `Bank`
2002still lands at whichever bank is closest to where it was dispatched; the
2003goods then appear in the shared vault.
2004
2005## 23.5 Carrier pigeon transit
2006
2007A carrier pigeon must take time to cross the world; long-distance item and
2008currency delivery is intentionally not instantaneous.
2009
2010At MMO scale, however, every delivery should not keep an entire trail of regions
2011fully stimulated merely so a pigeon can advance. The recommended model is a
2012persistent courier transit record with world position/route/progress that can
2013advance through dormant space using coarse path segments and timestamps.
2014
2015```text
2016CourierTransit
2017- courierId
2018- cargo // Money(amount) | ItemStack
2019- senderPlayerId
2020- destination // Player(playerId) | Bank
2021- currentPosition
2022- route
2023- speed / timing state
2024- status
2025```
2026
2027A carrier pigeon is part of the shared physical world, not a private visual
2028belonging only to its sender or recipient. Whenever its calculated route passes
2029through a **simulating chunk**, the courier should materialise there as a normal
2030ECS `Mob` entity, regardless of whether the sender or recipient is nearby. Any
2031client whose normal 3x3 chunk subscription includes that pigeon receives it like
2032any other visible mobile entity and can therefore see unrelated pigeons flying
2033past in the distance.
2034
2035The visible pigeon does **not** receive `ChunkLoader`. It exists because the chunk
2036is already simulating for some other reason. If it leaves the last relevant
2037simulating chunk, its exact position/progress is folded back into the durable
2038`CourierTransit` record and the ECS instance can disappear while the journey
2039continues abstractly. If a dormant/unloaded part of its route later becomes
2040simulated while the pigeon should currently be inside it, the owning worker
2041materialises the pigeon at the position implied by the transit clock and route.
2042
2043```text
2044Dormant route Simulating chunk Dormant route
2045
2046abstract transit --------> ECS pigeon visible to clients --------> abstract transit
2047 | | |
2048 Player A Player B unrelated observer
2049```
2050
2051This means a player standing halfway between sender and recipient can see the
2052pigeon fly through their area even though the cargo has nothing to do with
2053them. Unrelated clients receive the pigeon entity, not the cargo contents. It
2054preserves the sense that deliveries physically cross the world without
2055requiring thousands of deliveries to become thousands of permanent
2056`ChunkLoader`s.
2057
2058Because pigeons fly rather than use the ground navigation grid, their coarse
2059route can initially be represented by direct or waypoint-based aerial segments.
2060This makes deterministic materialisation from route + elapsed time considerably
2061simpler than it would be for a ground-based courier.
2062
2063If future gameplay allows pigeons to be intercepted, killed or rerouted anywhere
2064along their journey, the transit model can be made progressively more detailed;
2065that interaction is not required by the initial courier design.
2066
2067## 23.6 Courier service
2068
2069A dedicated `CourierService` should own durable cargo and delivery state.
2070Simulation workers may own visible pigeon entities while the service owns the
2071durable fact that a delivery exists.
2072
2073```text
2074Player action -> CourierService -> durable cargo/transit
2075 |
2076 +-> visible pigeon when needed
2077 |
2078 +-> inventory, wallet or BankService deposit
2079```
2080
2081This separation is also useful for marketplace settlement, which uses the same
2082carrier-pigeon delivery infrastructure for remote counterparties.
2083
2084# 24. Bank, cheques and shared vaults
2085
2086## 24.1 Bank location and access
2087
2088A bank exists at or near the central marketplace as an authored Bank block.
2089Deposit, withdraw, cheque issue and in-person cheque redemption require
2090server-validated access to a bank interaction; the bank is not a global menu
2091usable from anywhere.
2092
2093Pigeon dispatch to `Bank` is the exception: that command may be issued from
2094anywhere, and the goods become available only after the pigeon arrives.
2095
2096## 24.2 One shared vault
2097
2098Each **character** has a single vault in `state.sqlite`:
2099
2100```text
2101CharacterVault
2102- characterId
2103- bankedCurrency
2104- stacks[]
2105- reservations[]
2106```
2107
2108Capacity is unlimited: there is no slot cap. Per-stack stacking rules still
2109apply (`maxStackSize`; unique instances never merge), so 200 blank paper is
2110stored as 99 + 99 + 2 rather than one unbounded pile.
2111
2112If more banks are authored later, **all banks are linked**. Withdrawing at
2113bank B can retrieve goods deposited at bank A. The vault is not per-branch.
2114
2115Pigeon deposits affect *when* goods become available, not *which* vault they
2116enter. After the pigeon arrives at the nearest bank, the goods appear in the
2117same shared vault accessible from every bank.
2118
2119## 24.3 Deposit and withdraw
2120
2121While interacting with a bank, a player may:
2122
2123- Deposit any carried currency and any inventory stacks, in whole or in part.
2124- Withdraw currency into the carried wallet.
2125- Withdraw an item stack, or part of a stack, into inventory, subject to the
2126 32-slot and merge rules.
2127- Claim items or currency from the account **inheritance tab** into this
2128 character's vault (section 24.9).
2129
2130Goods reserved by an outstanding filled cheque cannot be withdrawn by the
2131issuer until that cheque is redeemed or voided.
2132
2133## 24.4 Blank cheques
2134
2135A player at a bank may request blank cheques.
2136
2137- Blank cheques are a stackable item with `maxStackSize` 99.
2138- The bank counts blank cheques already in the player's **inventory** (not
2139 the vault) and issues only enough to bring that total to 99.
2140- If the player already holds 99, the bank issues none.
2141- Issued cheques go into inventory, merging into an existing blank-cheque
2142 stack when possible. If the player holds none and has no empty slot, the
2143 request fails.
2144
2145The bank will not issue more than 99 blank cheques into inventory, even on
2146repeated requests.
2147
2148## 24.5 Filling a cheque
2149
2150Using a blank cheque at a bank lets the issuer pick vault goods and a
2151**quantity**. For stackable items they choose an `itemId` and quantity; the
2152quantity may be larger than one `maxStackSize`, and the reservation covers
2153that many available (unreserved) items of that type in the vault. For
2154unique-instance items they choose that exact instance and the quantity is 1.
2155
2156```text
2157FilledChequeInstance
2158- chequeId
2159- issuerPlayerId
2160- itemId
2161- quantity
2162- instance?: ItemInstance // set when the reserved goods are unique
2163- createdAt
2164```
2165
2166Filling:
2167
21681. Validates that the vault has at least `quantity` of that item available
2169 (not already reserved). Unique instances must still be present and unreserved.
21702. Reserves those goods in the issuer's vault. Reserved goods cannot be
2171 withdrawn, sold or reserved again.
21723. Consumes one blank cheque. If that was the last cheque in the slot, the
2173 slot becomes the filled cheque in place; otherwise a free slot is required
2174 for the filled cheque.
2175
2176A filled cheque is a unique-instance **bearer** item. It does not stack.
2177Whoever holds it may redeem it. Cheques specify vault items and a quantity,
2178not carried currency. Money is moved with a pigeon, or by depositing and
2179withdrawing at a bank.
2180
2181## 24.6 Redeeming a cheque in person
2182
2183The bearer interacts with any bank and redeems the filled cheque.
2184
2185- The server moves the reserved goods from the **issuer's** vault into the
2186 **bearer's inventory**, subject to inventory space. A quantity larger than
2187 `maxStackSize` becomes as many stacks as needed.
2188- The cheque item is consumed.
2189- If inventory cannot accept the resulting stacks, redemption fails and both
2190 cheque and reservation remain unchanged.
2191
2192The bearer may then deposit those goods into their own vault if they wish.
2193
2194## 24.7 Redeeming a cheque by pigeon
2195
2196If the bearer dispatches a pigeon whose cargo is a filled cheque and whose
2197destination is `Bank`:
2198
2199- The pigeon flies to the nearest bank from the dispatch tile.
2200- On arrival, `BankService` transfers the reserved goods from the **issuer's**
2201 vault into the **pigeon's sender's** vault.
2202- The cheque is consumed in transit; it is not deposited as an item.
2203
2204The receiver of the transfer is whoever sent that pigeon, not the original
2205cheque issuer. This is how a cheque moves goods from one vault to another
2206without the receiver standing at a bank.
2207
2208Sending a filled cheque to a **player** delivers the cheque item itself (or
2209into that player's bank if they cannot hold it). It does not redeem it.
2210
2211## 24.8 Bank service
2212
2213Vault mutation, cheque issue, reservation, in-person redemption and
2214pigeon-arrival deposits are owned by a single authoritative `BankService`
2215(or an equivalently serialised service) so two concurrent withdrawals,
2216cheque fills or pigeon arrivals cannot double-spend the same goods.
2217
2218```text
2219Bank interaction or pigeon arrival
2220 |
2221 v
2222BankService
2223 - shared vault
2224 - reservations
2225 - cheque issue / redeem
2226 |
2227 +-> inventory / currency on the acting player when in person
2228 |
2229 +-> vault credit on pigeon arrival
2230```
2231
2232Cheque identifiers are server-issued. A client cannot forge a claim against
2233another player's vault.
2234
2235## 24.9 Inheritance bank tab
2236
2237Each **account** has one inheritance tab, separate from every character
2238vault:
2239
2240```text
2241AccountInheritance
2242- accountId
2243- currency
2244- stacks[]
2245```
2246
2247It is written only when a character of that account is permanently deleted
2248(section 14.6). Any of that player's living characters can move stacks and
2249currency from this tab into their own vault at a bank. They cannot deposit
2250into inheritance except through character deletion.
2251
2252# 25. Central marketplace and order matching
2253
2254## 25.1 Marketplace location
2255
2256A central marketplace exists at or near the centre of the game world. Creating,
2257modifying or cancelling market orders requires server-validated access to the
2258marketplace interaction; the marketplace is not intended to be a global menu
2259that can be used from anywhere.
2260
2261Orders themselves remain durable after the player leaves the marketplace or
2262logs out.
2263
2264## 25.2 No public list of sell orders
2265
2266The market is an order book, but players do not browse a list of individual
2267items currently offered for sale.
2268
2269A seller submits:
2270
2271```text
2272SellOrder
2273- item / item definition
2274- quantity
2275- minimum unit/total price
2276```
2277
2278A buyer submits:
2279
2280```text
2281BuyOrder
2282- requested item / matching criteria
2283- quantity
2284- maximum unit/total price
2285```
2286
2287The UI may know which item types exist and may eventually show historical data,
2288but it does not expose the live asks in a way that lets a buyer simply pick a
2289listed seller.
2290
2291## 25.3 Escrow
2292
2293Market orders escrow the asset required to honour them. Escrow is taken from
2294carried inventory and carried currency. The marketplace sits next to the bank,
2295so a player can withdraw from the vault immediately before placing an order.
2296
2297- Creating a sell order removes/reserves the offered item stack from the
2298 seller's inventory.
2299- Creating a buy order removes/reserves the buyer's maximum offered currency.
2300- Cancelling an unmatched order returns the escrowed asset through the defined
2301 settlement/delivery rules.
2302
2303This prevents double spending, selling the same item twice, or a buyer spending
2304currency after placing a bid.
2305
2306## 25.4 Matching rules
2307
2308A buy and sell order match when:
2309
2310```text
2311buyerMaximum >= sellerMinimum
2312```
2313
2314Sell orders are considered cheapest first. Within the same minimum price, a
2315stable creation sequence/FIFO rule should be used unless later game rules choose
2316otherwise.
2317
2318For a symmetric order book, buy orders are naturally prioritised by highest
2319maximum bid and then oldest sequence. This means a newly submitted sell order
2320matches the best compatible existing bid, while a newly submitted buy order
2321matches the cheapest compatible existing ask.
2322
2323The trade price is exactly the midpoint between the two limits:
2324
2325```text
2326tradePrice = midpoint(buyerMaximum, sellerMinimum)
2327```
2328
2329Example:
2330
2331```text
2332Seller minimum: 80
2333Buyer maximum: 100
2334Trade price: 90
2335```
2336
2337The exact rounding rule when integer currency produces a half-unit midpoint is a
2338defined-but-still-open game rule and must be deterministic.
2339
2340## 25.5 Immediate side versus pigeon side
2341
2342The order that is submitted last is the order that triggers the match.
2343
2344The player who submitted that matching order receives the acquired asset
2345immediately because they are currently present at the marketplace interaction
2346(item stack into inventory, or currency into the carried wallet). The
2347pre-existing counterparty receives their acquired item or currency through a
2348carrier pigeon whose destination is `Bank`, landing at the nearest bank to the
2349marketplace. On arrival the settlement is deposited into that counterparty's
2350shared vault. This remains valid if they are offline.
2351
2352```text
2353Existing sell + new matching buy
2354-> new buyer receives item immediately
2355-> existing seller receives payment by pigeon to bank
2356
2357Existing buy + new matching sell
2358-> new seller receives payment immediately
2359-> existing buyer receives item by pigeon to bank
2360```
2361
2362If a trade requires more than one item stack (for example a quantity that does
2363not fit in a single `maxStackSize`), the older counterparty receives as many
2364free sequential pigeons as needed. Each pigeon still carries only one stack or
2365only currency.
2366
2367Any unused part of buy-order currency escrow caused by the midpoint price is
2368returned immediately to the triggering player when they are the buyer, and
2369returned by the settlement pigeon into the older counterparty's vault when
2370they were the buyer.
2371
2372## 25.6 Market service and atomicity
2373
2374Marketplace matching should not live inside an arbitrary region worker. Use a
2375single authoritative `MarketService` (or an equivalently serialised partitioned
2376service later) so two simultaneous orders cannot both consume the same escrow.
2377
2378Order insertion, matching, escrow movement and creation of the resulting
2379settlement deliveries are committed atomically in `state.sqlite`.
2380
2381Conceptually:
2382
2383```text
2384Marketplace interaction
2385 |
2386 v
2387MarketService
2388 - durable order book
2389 - escrow
2390 - deterministic matching
2391 - trade record
2392 |
2393 +-> immediate settlement to triggering player's inventory or wallet
2394 |
2395 +-> CourierService pigeon to Bank for the older counterparty
2396 |
2397 +-> last-sale index update for that itemId
2398```
2399
2400The system should also retain an immutable trade record for auditing and recovery.
2401
2402## 25.7 Last player-market sale per item
2403
2404Each successful player-market match updates a single durable record for that
2405`itemId`. There is no price history series — only the latest sale:
2406
2407```text
2408ItemLastMarketSale
2409- itemId
2410- lastTradePrice // unit price of that match (the midpoint)
2411- lastTradeAt
2412- priceFrom // evaluated undiscounted value at lastTradeAt
2413```
2414
2415`priceFrom` is not a history log. It is the lerp origin captured at the
2416moment of this sale so the displayed price does not jump back to seed when
2417a new trade occurs:
2418
24191. Evaluate the current undiscounted value at `now` using the previous
2420 last-sale record (or `seedValue` if none exists).
24212. Store that value as `priceFrom`, store the new trade's unit price as
2422 `lastTradePrice`, and store `now` as `lastTradeAt`.
2423
2424Shopkeepers and item tooltips both read this record. They do not tick it;
2425they evaluate it from timestamps when a shop is opened, a purchase is
2426attempted, or a tooltip refresh is requested.
2427
2428# 26. Combat
2429
2430## 26.1 Every combatant can attack
2431
2432Players, enemies, animals and any other mobile with a `Combat` component can
2433attack. Shopkeepers and other non-fighting NPCs simply omit `Combat`, or
2434never issue attack commands.
2435
2436Attacking is an intention. The client (or AI, or a future script) sends
2437`ATTACK(targetEntityId)`. The owning worker validates range, line-of-use,
2438the current attack profile and cooldown, then resolves hit and damage
2439authoritatively. The client never supplies a hit result or a damage number.
2440
2441Cross-worker attacks already use `REMOTE_ACTION(attack intent)`: the worker
2442that owns the target applies the authoritative result.
2443
2444## 26.2 Attack profiles
2445
2446The current attack comes from the wielder's selected profile: a wielded
2447weapon's `AttackProfile`, a selected spell, or a default unarmed melee
2448profile when nothing is wielded.
2449
2450```text
2451AttackProfile
2452- attackId
2453- mode: melee | ranged | magic
2454- rangeTiles // melee is always 1; ranged/magic from the item or spell
2455- hitSkillId
2456- damageSkillId
2457```
2458
2459```text
2460SpellDefinition
2461- spellId
2462- displayName
2463- AttackProfile // mode = magic, hitSkillId = Magic, damageSkillId = Mind
2464- other costs/effects // later content
2465```
2466
2467Typical weapon mappings:
2468
2469```text
2470Sword -> melee, range 1, hit Swordfighting, damage Strength
2471Axe -> melee, range 1, hit Axefighting, damage Strength
2472Bow -> ranged, range from item, hit Archery, damage Dexterity
2473Spell -> magic, range from spell, hit Magic, damage Mind
2474Unarmed -> melee, range 1, hit Unarmed, damage Strength
2475```
2476
2477The exact weapon and spell catalogue is content. The pairing rule is not:
2478melee weapons use a weapon skill plus **Strength**, ranged weapons use a
2479weapon skill plus **Dexterity**, and spells use **Magic** plus **Mind**.
2480
2481`EquipItem(slotIndex)` moves a legal item from inventory into the matching
2482equipment slot (section 21.6). The **weapon** slot supplies the current
2483`AttackProfile`. `SelectSpell(spellId)` selects a spell the actor is
2484allowed to use. The selected profile determines range and both skills.
2485
2486## 26.3 Melee range
2487
2488A melee attack is legal only when the attacker stands on **one of the eight
2489tiles surrounding** the target's tile: orthogonal or diagonal, Chebyshev
2490distance exactly 1. The attacker cannot melee from the target's own tile.
2491
2492```text
2493. . .
2494. T . attacker must occupy one of the eight `.` tiles
2495. . .
2496```
2497
2498This adjacency rule is independent of whether ordinary walking is four- or
2499eight-directional.
2500
2501## 26.4 Ranged attacks and spells
2502
2503Ranged weapons and spells may fire from further away. Maximum Chebyshev
2504distance is `rangeTiles` on that item or spell. Distance 0 (same tile) is
2505not a legal ranged/spell attack unless a later exception is defined.
2506
2507The attacker must still occupy a simulating chunk and satisfy any later
2508line-of-sight rule. Exact obstruction rules are an open content decision;
2509range itself is not.
2510
2511## 26.5 Hit roll
2512
2513Whether the attack lands is a server-side roll driven by the **hit skill**
2514of the current profile (Swordfighting, Axefighting, Archery, Magic, Unarmed,
2515and so on). The client does not roll.
2516
2517The exact hit curve, any defender contribution from Defence, and the RNG
2518are later tuning. The invariant is that the hit chance is a function of the
2519attacker's hit-skill level, not of Strength, Dexterity or Mind.
2520
2521A miss deals no damage.
2522
2523## 26.6 Damage
2524
2525On a hit, damage is determined by the **damage skill**:
2526
2527- Melee → Strength
2528- Ranged → Dexterity
2529- Magic → Mind
2530
2531Weapon or spell base damage and the defender's mitigation (including whether
2532Defence reduces damage) are later tuning. The governing damage skill is not.
2533
2534## 26.7 Experience split
2535
2536When a **player** successfully hits, the attack's XP award is split equally
2537between the hit skill and the damage skill:
2538
2539```text
2540totalXp = attack xp formula for this successful hit
2541hitSkill += totalXp / 2
2542damageSkill += totalXp / 2
2543```
2544
2545Example: a sword hit awards half its XP to Swordfighting and half to
2546Strength. A bow hit splits Archery and Dexterity. A spell hit splits Magic
2547and Mind.
2548
2549If an unusual profile ever named the same skill twice, XP is awarded once,
2550not doubled. Misses award no combat XP. Ordinary mobs do not earn XP; their
2551`Skills` component is filled from the mob archetype and stays at those
2552levels.
2553
2554Non-combat actions remain single-skill as in section 27.4.
2555
2556## 26.8 Mob combat stats
2557
2558```text
2559MobDefinition
2560- ...
2561- skillLevels: { skillId → level }
2562- defaultAttack: attackId | unarmed
2563```
2564
2565A wolf might have Unarmed and Strength. An archer guard might have Archery
2566and Dexterity. Those levels feed the same hit and damage resolution as
2567players.
2568
2569# 27. Player-driven economy and skill progression
2570
2571## 27.1 Item-source philosophy
2572
2573The economy is intentionally player-driven.
2574
2575Normal NPC shops should sell only basic ingredients. The vast majority of
2576materials are gathered directly from the world by players. Finished goods are
2577normally produced by player crafting/professions.
2578
2579The only normal non-player source of finished items is enemy or boss loot.
2580
2581This gives four broad source paths, with ground-item spawners as an additional
2582early world source once content defines them:
2583
2584```text
2585World gathering / harvesting -> ingredients
2586Ground-item spawners --------> some world items, later specified
2587Basic NPC shops -------------> limited basic ingredients
2588Player production -----------> intermediate/final products
2589Enemies and bosses ----------> loot, including possible finished items
2590```
2591
2592Stacking, unique instances, letters and cheques are defined in section 22.
2593Economy-facing fields remain on the same `ItemDefinition`:
2594
2595```text
2596ItemDefinition
2597- itemId
2598- displayName / description / seedValue
2599- stackable / maxStackSize / uniqueInstance
2600- category: ingredient | intermediate | finished | document | other
2601- npcShopAllowed
2602- gatherSources
2603- craftingRecipe(s)
2604- dropTableSources
2605- attack?: AttackProfile
2606- equipment?: slot / overlaySpriteId / recolourableChannels / materialId
2607```
2608
2609Content validation can then reject an ordinary shop inventory that accidentally
2610contains a finished product unless explicitly permitted by a future exception.
2611
2612## 27.2 No player classes
2613
2614Players do not choose a class. Capabilities and progression come from independent
2615skills.
2616
2617Examples include:
2618
2619- Swordfighting, Axefighting, Archery, Magic, Unarmed
2620- Strength, Dexterity, Mind
2621- Defence
2622- Lumbering
2623- Fishing
2624- Smithing
2625
2626The final skill list is game content and is not limited to skills found in any
2627particular inspiration game.
2628
2629## 27.3 Skill state
2630
2631Skill progression is persistent player state.
2632
2633```text
2634SkillProgress
2635- skillId
2636- xp
2637```
2638
2639Level should preferably be derived from XP and the skill's level curve rather
2640than stored as an independent source of truth, although it may be cached.
2641
2642```text
2643SkillDefinition
2644- skillId
2645- displayName
2646- levelCurve
2647- maxLevel (if any)
2648```
2649
2650## 27.4 Actions are governed by skills
2651
2652Every gameplay action that participates in progression is associated with a
2653governing skill. Combat attacks are the explicit exception: they have a hit
2654skill and a damage skill, and split XP equally between them (section 26.7).
2655
2656```text
2657ActionDefinition
2658- actionId
2659- governingSkillId
2660- requiredLevel
2661- xpAward / xpFormula
2662- other requirements
2663```
2664
2665Examples:
2666
2667```text
2668Cut tree -> Lumbering
2669Catch fish -> Fishing
2670Forge sword -> Smithing
2671Sword hit -> Swordfighting + Strength (equal split)
2672Bow hit -> Archery + Dexterity (equal split)
2673Spell hit -> Magic + Mind (equal split)
2674Defensive act -> Defence
2675```
2676
2677The server validates the action, performs the authoritative outcome, and then
2678awards XP according to the action result. A client cannot claim XP independently.
2679
2680## 27.5 Skills replace class restrictions
2681
2682Equipment, recipes, actions, gathering nodes and other content may require skill
2683levels, but there is no permanent class gate. A player can train any combination
2684of skills over time.
2685
2686This also fits the future scripting model: scripts issue normal actions, and
2687successful scripted actions use exactly the same skill checks and XP rules as
2688manual player actions.
2689
2690## 27.6 NPC shops and market-adapted prices
2691
2692Named shop NPCs can sell items to players. They are not the player marketplace
2693and they do not expose live sell orders. A shop interaction requires being at
2694that NPC.
2695
2696Stock remains constrained by `npcShopAllowed` and the ingredient-only rule in
269727.1. Each shop NPC has a hidden discount that players never see:
2698
2699```text
2700ShopNpc
2701- npcId
2702- hiddenDiscount // multiplier, e.g. 0.9; not shown to clients
2703- stock[] // itemIds this NPC sells
2704```
2705
2706Until an `itemId` has a player-market last-sale record, the undiscounted
2707value is `seedValue` from the item definition.
2708
2709When a last-sale record exists, both tooltips and shops evaluate a timestamp
2710lerp that does not require a per-tick update:
2711
2712```text
2713t = min(1, (now - lastTradeAt) / WorldSettings.shopPriceLerpDuration)
2714undiscounted = lerp(priceFrom, lastTradePrice, t)
2715shopPrice = undiscounted * thatNpc.hiddenDiscount
2716```
2717
2718`lerp(a, b, t) = a + (b - a) * t`. After the configured lerp duration
2719(default one hour), `t` is capped at 100% and the value rests on the last
2720player-market unit price (times discount, for shops) until another
2721player-market sale occurs.
2722
2723A new player-market sale captures the then-current `undiscounted` value as
2724`priceFrom` (section 25.7), so the lerp restarts toward the new last price
2725without jumping back to seed.
2726
2727Integer currency must be rounded deterministically at evaluation time. Shop
2728purchase price is computed on the server at the instant of `BuyFromShop`.
2729Displayed tooltip value is the undiscounted figure and may be refreshed at
2730most once per minute (section 22.6).
2731
2732Buying from a shop removes the listed price from the player's carried
2733currency, puts the stack in inventory subject to the 32-slot rules, and
2734stamps `ItemOrigin.kind = shop` with that NPC. Shops in this model sell to
2735players; they do not buy player goods unless a later iteration adds that.
2736
2737# 28. Suggested implementation phases
2738
2739## Phase 1 — Single-worker playable core
2740
2741- World coordinate helpers, 16×16 chunks and 4×4-chunk regions.
2742
2743- Ground/block tile model and chunk spatial occupancy.
2744
2745- Basic ECS and fixed simulation tick.
2746
2747- ChunkLoader reference counting and sleeping/unloading.
2748
2749- Single simulation worker behind the same worker interface planned for
2750 later scaling.
2751
2752- world.sqlite read path and state.sqlite persistence service.
2753
2754- Admin world editor: chunk navigation, open/closed flag, default grass for
2755 unsaved chunks, ground/block paint, light-emitting blocks, baked
2756 cross-chunk light maps, night-to-day preview slider, world settings modal,
2757 per-chunk changelog, save to pending revision.
2758
2759- SpawnerSystem for at least one non-persistent mob archetype.
2760
2761- WebSocket gateway, stub `admin-<n>` auth until auth.timfalken.com,
2762 character create/select/delete, authoritative command queue and 3×3 chunk
2763 replication.
2764
2765- Click-to-move with server-side A\*, global walk/run cadence (default 2
2766 tiles/s walk, run every movement tick, walk every other), and `SetGait`.
2767
2768- FrameworkV3 git submodule at `client/frameworkv3`, built first, then a
2769 game-specific client on top of it with 16×16 sprites, load-time and CI
2770 rejection of wrong-sized art (including equipment overlays and recolour
2771 masks), layered worn equipment with material recolouring, a
2772 player-centered viewport with bounded zoom, client-only lerp of
2773 tile-to-tile movement, and night shading from baked light maps.
2774
2775- 32-slot player inventory, stack merging, drop/pickup, and 10-minute
2776 non-blocking ground items.
2777
2778- Paper items that can be written into unique letter items.
2779
2780- Basic proximity chat with server-side distance degradation.
2781
2782- Persistent player skill state, including Strength, Dexterity and Mind, and
2783 at least a small initial set of skill-governed actions.
2784
2785- Melee and ranged/spell attack validation (8-tile melee adjacency, item/spell
2786 range), server-side hit rolls, damage from the matching damage skill, and
2787 equal XP split on a successful player hit.
2788
2789- Graceful forced-unload shutdown.
2790
2791## Phase 2 — Operations and live deployment
2792
2793- RestartScheduler and player-visible scheduled restart state.
2794
2795- origin/master change detection.
2796
2797- `systemd` service supervision and conditional deployment hook.
2798
2799- World-revision activation on restart.
2800
2801- Admin immediate restart.
2802
2803- Migration, backup and startup readiness checks.
2804
2805## Phase 3 — Multi-worker world
2806
2807- Multiple worker_threads simulation workers.
2808
2809- Region coordinator and dynamic region ownership.
2810
2811- Cross-worker entity transfers.
2812
2813- Border ghosts and remote actions.
2814
2815- Gateway subscriptions spanning multiple workers.
2816
2817- Load metrics and neighbour-aware region balancing.
2818
2819## Phase 4 — World depth, social systems and economy
2820
2821- Persistent named NPCs and other persistent mob archetypes.
2822
2823- Spawner persistent-instance index and duplicate prevention.
2824
2825- Optional durable gameplay chunk overrides, written only on unload.
2826
2827- Hierarchical pathfinding if long-distance autonomous travel needs it.
2828
2829- Persistent player groups and invitations.
2830
2831- Carrier-pigeon cargo transit: free dispatch, money or one item stack,
2832 player or nearest-bank destinations, including offline/full-inventory
2833 fallback to the recipient vault.
2834
2835- Shared unlimited **character** bank near the marketplace, account
2836 inheritance tab on character delete, blank cheques filled to 99, reserved
2837 filled cheques, in-person redemption and pigeon-to-bank cheque transfers.
2838
2839- Central marketplace, escrow, deterministic order matching, pigeon-to-bank
2840 settlement for the older counterparty, and a per-item last-sale record for
2841 shop/tooltip adaptation.
2842
2843- NPC shops that sell `npcShopAllowed` stock at seed value lerped toward the
2844 last player-market price over `shopPriceLerpDuration`, with a hidden per-shop discount.
2845
2846- Item inspection: name, description, origin (crafter or shop NPC) and
2847 undiscounted current value, refreshed at most once per minute.
2848
2849- Player crafting/gathering economy rules and shop-content validation.
2850
2851- Broader skill catalogue, progression curves and skill-gated content.
2852
2853## Phase 5 — Player scripting
2854
2855- Custom language grammar/compiler/interpreter.
2856
2857- ScriptController and event API.
2858
2859- CPU/memory/query quotas and sandboxing.
2860
2861- Online scripted control mode.
2862
2863- Offline retained player entities with expiry and ChunkLoader
2864 behaviour.
2865
2866- Persisted/restart-safe script state.
2867
2868# 29. Core invariants
2869
2870| **Invariant** | **Rule** |
2871|------------------------|--------------------------------------------------------------------------------------------------------|
2872| Server authority | Clients send intent; the server computes and owns outcomes. |
2873| Region ownership | Exactly one simulation worker authoritatively owns a region. |
2874| Entity ownership | Exactly one worker authoritatively owns an entity. |
2875| Remote mutation | Workers never directly mutate remote authoritative state. |
2876| Spatial separation | Region residency, chunk simulation and client visibility remain distinct. |
2877| Persistence separation | Persistent and ChunkLoader are independent entity traits. |
2878| Chunk persistence | Normal dirty chunk state is written on unload, not periodically. |
2879| World authoring | Editor changes create pending authored state; the running server stays pinned to its startup revision. Each chunk save appends an admin-attributed diff changelog. |
2880| Restart path | Planned restart force-unloads the world and reuses the ordinary unload save path. |
2881| Control | Human and future scripted control both emit validated action commands. |
2882| Deployment | The game exits gracefully; systemd relaunches it and only pulls/builds when an intentional deployment manifest requests it. |
2883| Client architecture | FrameworkV3 is a git submodule under `client/frameworkv3`, built before game client code; backend ECS internals do not become the client object model. |
2884| Sprites | All world sprites are exactly 16×16 pixels; any other size is rejected on load and fails CI. Equipment overlays and recolour masks are included. |
2885| Appearance | Visible gear is layered 16×16 overlays on the mob; recolourable channels (such as metal) use material colour without duplicate art sets. Nearby clients receive appearance layers, not another player's inventory. |
2886| Play camera | The play viewport is centered on the local player. Only the admin world editor uses a free chunk camera. |
2887| Movement | All ground mobiles share a global walk/run cadence from world settings; the server commits integer tiles; clients lerp for presentation only. |
2888| World time | World calendar time is server time minus 1200 years. Night darkens tiles the baked light map cannot reach. |
2889| World settings | Tick timers and global constants are authored in the editor modal, pinned to the world revision, and not hot-patched into a live process. |
2890| Baked light | Static light reach is raycast through passable tiles on chunk save, may cross chunks, and is not recomputed every tick. |
2891| Ground items | Player drops last `groundItemDespawnDuration` (default 10 minutes), block nobody, and are picked up only by a player standing on that tile. |
2892| Shop prices | NPC shop prices lerp from the captured pre-sale value toward the last player-market unit price over `shopPriceLerpDuration` (default one hour), times a hidden per-shop discount. |
2893| Proximity speech | Distant clients never receive unobscured plaintext that game rules say they cannot understand. |
2894| Courier cargo | Pigeons carry money or one item stack, never a chat packet; cargo is durable in transit and remains delayed. |
2895| Inventory | A player has 32 slots; a stack occupies one slot; the client never asserts inventory, wallet or vault results. |
2896| Shared bank | Every bank reads the same **character** vault; pigeon deposits become available only after arrival at the nearest bank. |
2897| Closed chunks | Closed or never-edited chunks are visible but not enterable; never-edited terrain is default grass with no blocks. |
2898| Accounts | Login is auth.timfalken.com (or `admin-<n>` stub). Characters belong to an account; one may be in the world at a time. |
2899| Names | Surnames are globally unique per account; first+last is unique per account; names free only after permanent delete. |
2900| Inheritance | Deleted characters dump inventory, equipment, wallet and vault into an account inheritance tab other characters can claim. |
2901| Cheques | Filling a cheque reserves vault goods; the bearer item is the claim; destruction without redemption releases the reservation. |
2902| Marketplace escrow | Every open order is fully backed by escrow and matching/settlement is atomic and deterministic. |
2903| Combat | Melee requires an 8-neighbour tile; ranged/spell range comes from the item or spell; hit uses the weapon skill; damage uses Strength, Dexterity or Mind. |
2904| Progression | Players have no classes; non-combat actions award XP to one governing skill; a successful attack splits XP equally between hit and damage skills. |
2905
2906# 30. Important edge cases to preserve during implementation
2907
2908- A ChunkLoader crossing a region boundary can change
2909 residency/simulation references and worker ownership in the same tick;
2910 ordering must avoid temporary double ownership.
2911
2912- A player at a worker boundary may receive visible chunks from multiple
2913 workers without moving ownership solely for rendering.
2914
2915- A planned restart must ignore normal ChunkLoader retention when
2916 forcing the world to unload.
2917
2918- A world-editor save must never cause newly loaded chunks in the
2919 current process to use the pending revision. It must append a changelog
2920 record naming the admin, timestamp and tile diffs.
2921
2922- Pathfinding and player movement must reject tiles in closed or
2923 never-edited chunks even when those chunks are in the 3×3 view.
2924
2925- Two accounts must not claim the same surname. One account may reuse its
2926 surname; first+last must stay unique on that account until permanent
2927 delete.
2928
2929- Marking a character for deletion must not free the name or move items
2930 until the delay elapses. Cancelling must restore playability.
2931
2932- Character deletion must notify the account email (or log, on stub auth).
2933 Permanent delete must void that character's issued cheques, then move
2934 inventory, equipment, wallet and vault into the account inheritance tab.
2935
2936- Saving a chunk must rebake that chunk's light map and any neighbour
2937 chunks within max light range, using passable-tile raycasts. Light from
2938 a source in chunk A may appear in chunk B.
2939
2940- A mob definition must not carry its own walk/run speed; gait only
2941 selects every-other vs every movement tick on the global cadence.
2942
2943- World-settings saves must not apply to the live process; they wait for
2944 the same pending-revision restart as chunk edits.
2945
2946- Night shading must not light a tile the baked mask marks unreachable,
2947 even if a torch is nearby through a wall.
2948
2949- A sprite whose pixel size is not 16×16 must be rejected at load and must
2950 fail the sprite-dimension unit test. Equipment overlays and recolour
2951 masks are included.
2952
2953- Equipping must not leave two items in the same equipment slot. Unequip
2954 into a full inventory must fail and leave the item worn.
2955
2956- Nearby clients must not receive another player's inventory in order to
2957 draw their armour; appearance layers and material ids are sufficient.
2958
2959- A client build without `client/frameworkv3` initialized must fail rather
2960 than silently using some other FrameworkV3 install.
2961
2962- Client interpolation of movement must not be treated as authority. Combat
2963 range and pickup use the server tile, not the lerped draw position.
2964
2965- The play camera must remain centered on the local player. Zoom must not
2966 expand the subscribed chunk set.
2967
2968- A persistent mob spawned by a spawner must not be duplicated merely
2969 because it moved out of the spawner’s loaded area.
2970
2971- A non-persistent mob disappears when its chunk is actually unloaded,
2972 not merely when it becomes dormant.
2973
2974- If a persistent ChunkLoader or offline scripted player exists after
2975 restart, startup must discover it from an index without loading the
2976 entire world.
2977
2978- A pending code update followed by an unrelated Node.js crash must
2979 restart the currently deployed commit rather than deploying early.
2980
2981- Negative coordinates, daylight-saving midnight calculation, duplicate
2982 transfer messages and failed deployment migrations should all have
2983 explicit tests.
2984
2985- Proximity chat degradation must happen before plaintext reaches an unauthorised
2986 distant client; rendering-only obfuscation is not sufficient.
2987
2988- Carrier-pigeon deliveries must survive restarts and recipient logout without
2989 requiring every traversed chunk to remain stimulated.
2990
2991- A pigeon carrying an item to a player whose inventory cannot accept it must
2992 not destroy the cargo; it deposits into that player's vault via the nearest
2993 bank.
2994
2995- Two concurrent bank withdrawals, cheque fills or pigeon-arrival deposits must
2996 not spend the same vault goods twice.
2997
2998- Filling two cheques against the same vault stack must reserve disjoint
2999 quantities or reject the second fill.
3000
3001- A filled cheque that expires on the ground must release its reservation and
3002 must not remain redeemable.
3003
3004- A player-dropped ground item must not block movement, must not keep its chunk
3005 loaded, and must still be present after a chunk unload/reload if `expiresAt`
3006 has not passed.
3007
3008- Pickup of a ground item from a tile the player is not standing on must fail.
3009
3010- Requesting blank cheques must never raise the player's carried blank-cheque
3011 count above 99.
3012
3013- A marketplace match must atomically consume both escrows exactly once, even if
3014 two compatible orders arrive concurrently.
3015
3016- A matching market order from an online player may settle immediately for that
3017 player while the older/offline counterparty's delivery remains durable.
3018
3019- Skill XP is awarded only after authoritative action resolution, never directly
3020 from a client-reported result. A successful player attack splits that XP;
3021 a miss awards none.
3022
3023- A melee attack from the target's own tile, or from Chebyshev distance greater
3024 than 1, must fail. A ranged or spell attack beyond that item or spell's
3025 `rangeTiles` must fail.
3026
3027- A new player-market sale must capture the then-current undiscounted lerp
3028 value as `priceFrom` so shop and tooltip prices do not jump back to seed.
3029
3030- Two shop NPCs may charge different prices for the same item at the same
3031 instant because each applies its own hidden discount to the same lerp.
3032
3033- Item tooltip value must not be recomputed every tick; a one-minute refresh
3034 is sufficient. Purchase price is still evaluated at the moment of buy.
3035
3036# 31. Decisions through version 0.12
3037
3038- Chunk persistence is unload-driven rather than periodic.
3039
3040- The authored tile model has separate visual ground and functional
3041 block layers.
3042
3043- Mobile actors remain ECS entities and are not authored as painted tile
3044 contents.
3045
3046- Spawner blocks are editor-placeable and configurable per instance;
3047 persistence belongs to the spawned mob type.
3048
3049- world.sqlite is an authored, revisioned world source; state.sqlite
3050 holds runtime durable state.
3051
3052- Editor changes are staged for activation on restart instead of
3053 hot-patching the running world.
3054
3055- Code/world changes schedule a player-visible midnight restart; admins
3056 can trigger the same graceful pipeline immediately.
3057
3058- Git pull/build/relaunch belongs to `systemd` supervision after the
3059 game process has safely exited.
3060
3061- Deployment is manifest-driven: crash recovery restarts the currently
3062 checked-out commit, while only an intentional deployment restart may
3063 fast-forward `master`.
3064
3065- Future player scripting is modelled as an alternative controller
3066 producing normal server action commands.
3067
3068- Offline scripted players may remain in-world as ChunkLoaders until
3069 death or expiry and must survive planned restarts through persistence.
3070
3071- The player client is built on FrameworkV3, included as the git submodule
3072 `client/frameworkv3` and built first so this game's client code can layer on
3073 top. The client does not need an ECS and consumes protocol state
3074 independently of backend ECS storage. The Node.js server does not import
3075 FrameworkV3.
3076
3077- All world sprites (tiles, blocks, mobs, items) are exactly 16×16 pixels.
3078 Other sizes are rejected at load. A unit test lists offenders and fails if
3079 any exist. Sprites are not individually resized; the player may zoom the
3080 whole viewport within configured bounds.
3081
3082- Visible equipment is drawn as extra 16×16 layers on the mob, including
3083 players. Worn items occupy equipment slots, not the 32 inventory slots.
3084 Nearby clients replicate appearance layers only, never another player's
3085 inventory.
3086
3087- Recolourable gear (metal armour) shares one overlay sprite and a 16×16
3088 channel mask. Material definitions supply the metal colour; luminance of
3089 the overlay is preserved. Iron and steel plate are different items with
3090 the same art and different `materialId`.
3091
3092- The play camera is always centered on the local player. The admin world
3093 editor is the only exception, and it frames one chunk at a time.
3094
3095- Authoritative movement is a tile-to-tile jump on a **global** cadence:
3096 default walk 2 tiles/s, run double. Walk steps every other movement tick;
3097 run steps every movement tick. Mobs do not set their own speed. Clients
3098 lerp for visuals only and never send interpolated positions.
3099
3100- Admins edit global tick timers and constants in a world-settings modal.
3101 Those values live in the pending world revision and apply on the next
3102 process start, like other editor saves.
3103
3104- World calendar time is server time minus 1200 years, same IANA zone as
3105 midnight restarts. At night the client darkens tiles the baked light map
3106 cannot reach.
3107
3108- Static light is baked on chunk save by raycast through passable tiles,
3109 including across chunk borders. The editor has a night-to-day slider for
3110 preview only.
3111
3112- Each world-editor chunk save stores who edited it, when, and a bullet
3113 diff of ground changes, block placements, block replacements and block
3114 removals at world tile coordinates.
3115
3116- Default speech is proximity-based and becomes less legible with distance.
3117 Long-distance exchange is physical: a pigeon carries money or one item stack.
3118 A letter is paper with player-written text, not a separate mail record.
3119
3120- Permanent player groups are social/addressing structures and do not create an
3121 instant global chat channel.
3122
3123- Carrier-pigeon transit is persistent but does not automatically keep every
3124 traversed chunk simulated. Whenever a pigeon passes through a chunk that is
3125 already simulating, it materialises as an ECS `Mob` and is visible to any
3126 nearby client whose normal chunk subscription includes it, even if that client
3127 is unrelated to the delivery. Unrelated clients do not receive cargo contents.
3128
3129- A player has a 32-slot inventory. Stackable items occupy one slot. Currency is
3130 a numeric wallet/vault balance, not an inventory item.
3131
3132- Player-dropped items lie on the tile for `groundItemDespawnDuration`
3133 (default 10 minutes), block nobody, and may be picked up by anyone standing
3134 on that tile. They survive unload until expiry via timestamps.
3135
3136- The bank near the marketplace holds an unlimited **character** vault.
3137 Later banks are linked to the same vault. Pigeons may deposit money or one
3138 stack into the sender's vault after arriving at the nearest bank. An
3139 account-level inheritance tab receives a deleted character's goods.
3140
3141- Blank cheques are issued at a bank up to a carried total of 99. Filling a
3142 cheque reserves a vault item quantity. The filled cheque is a bearer item.
3143 In-person redemption withdraws into the bearer's inventory. Sending the cheque
3144 to the bank by pigeon transfers the reserved goods into the pigeon's sender's
3145 vault.
3146
3147- The central marketplace hides individual live sell listings and matches durable
3148 escrowed buy/sell orders at the midpoint of compatible bid/ask limits.
3149 Quantities are item stacks.
3150
3151- The newest matching market participant receives the trade result locally; the
3152 older counterparty receives theirs by pigeon into their bank.
3153
3154- NPC shops remain restricted to `npcShopAllowed` basic ingredients. They sell
3155 to players at
3156 `lerp(priceFrom, lastTradePrice, min(1, (now - lastTradeAt) / shopPriceLerpDuration))`
3157 times a hidden per-shop discount. With no player-market sale yet, the
3158 undiscounted value is `seedValue`. Tooltips use the same lerp without the
3159 discount and refresh at most once per minute.
3160
3161- Hovering an item shows name, description, origin (crafter, or shop NPC name
3162 if bought there) and current undiscounted value.
3163
3164- All combatants can attack. Melee requires standing on one of the eight
3165 neighbouring tiles. Ranged attacks and spells use the item's or spell's
3166 range. The hit roll uses the weapon skill; damage uses Strength (melee),
3167 Dexterity (ranged) or Mind (magic). Successful player-attack XP is split
3168 equally between those two skills.
3169
3170- Player progression is skill-based rather than class-based. Non-combat
3171 actions award XP to one governing skill; combat hits split XP as above.
3172
3173- Never-edited chunks are default grass, no blocks, and **closed**. The
3174 editor opens or closes each chunk. Closed chunks are visible but not
3175 enterable.
3176
3177- Accounts authenticate at auth.timfalken.com. Until that service is up,
3178 each connection is stub `admin-<n>` (n = connected client count including
3179 this one) and is treated as admin.
3180
3181- An account has unlimited characters and plays one at a time. Creation
3182 takes first name (not globally unique), last name (globally unique to the
3183 account, reusable on that account's other characters), and male/female.
3184 first+last must be unique for that account. This setup may change later.
3185
3186- Character deletion is a 24-hour (configurable) delay with email notify
3187 and cancel. Permanent delete frees names and moves inventory, equipment,
3188 wallet and vault to the account inheritance tab, which any of that
3189 player's characters can claim into their own vault.
3190
3191# 32. Open design decisions for later iterations
3192
3193These do not block the initial implementation, but should eventually be
3194specified explicitly:
3195
3196- Whether multiple mobile entities may occupy one tile and, if so, which
3197 categories can overlap.
3198
3199- Whether player movement is four-direction only or also supports
3200 diagonals. Combat melee adjacency already includes diagonals.
3201
3202- Exact hit-chance and damage curves, attack intervals/cooldowns, whether
3203 Defence modifies incoming hit chance or damage, and ranged/spell
3204 line-of-sight or obstruction rules.
3205
3206- Deterministic rounding when shop discount or lerp produces a fractional
3207 currency amount.
3208
3209- Exact equipment slot list, per-slot draw order exceptions (cloaks,
3210 two-handed weapons), and whether worn overlays have facing frames to
3211 match the mob.
3212
3213- Additional recolour channels beyond metal (for example cloth dyes) and
3214 the exact luminance-preserving remap function.
3215
3216- Exact camera zoom minimum, maximum and whether zoom is restricted to
3217 integer steps.
3218
3219- Exact night ambient curve (how dark, dusk length) and whether baked light
3220 stores a boolean reach mask or a distance/falloff value per tile.
3221
3222- Whether opening a door at runtime should rebake or ignore static light.
3223
3224- Exact simulation tick rate stays a world setting; lower-frequency AI and
3225 spawner cadences can still be tuned independently.
3226
3227- Exact world/chunk binary serialisation format and schema/version
3228 migration strategy.
3229
3230- Whether gameplay can permanently modify ground/block tiles in the
3231 initial release.
3232
3233- Spawner timing rules, spawn-point restrictions and behaviour when
3234 persistent spawned mobs travel very far away.
3235
3236- World-editor undo/redo and rollback UI. The per-chunk changelog is an audit
3237 log, not by itself an undo stack.
3238
3239- Exact restart warning intervals and whether admins can
3240 cancel/reschedule a planned restart.
3241
3242- Worker rebalance thresholds and whether regions may migrate while
3243 players are actively crossing their boundaries.
3244
3245- Future scripting language syntax, event model and resource quotas.
3246
3247- Exact proximity-chat distance curve, maximum range and character degradation
3248 algorithm.
3249
3250- Group naming/roles, membership limits and whether group-wide letter sending
3251 is offered as an addressing convenience that still dispatches one pigeon and
3252 consumes one paper/letter per recipient.
3253
3254- Whether pigeons can eventually be intercepted, killed or redirected in transit.
3255
3256- Marketplace partial fills, cancellation rules, fees/taxes (if any),
3257 tie-breaking details and midpoint rounding for indivisible currency.
3258
3259- Whether market price history or aggregate statistics are visible despite live
3260 order listings remaining hidden.
3261
3262- Initial skill catalogue, XP curves, level caps, action XP formulas and the
3263 remaining interpretation of skills such as Defence.
3264
3265- Maximum letter body length and whether writing paper requires a desk or can be
3266 done from inventory anywhere.
3267
3268- Exact item catalogue, which items stack, per-item `maxStackSize` exceptions,
3269 harvest interactions and ground-item spawner parameters.
3270
3271- Whether death drops inventory, and whether dropped unique items other than
3272 cheques have destruction side-effects.
3273
3274- Whether the issuer can void a filled cheque without the bearer item being
3275 destroyed, and whether cheques can ever represent currency rather than items.
3276
3277- Whether a short dispatch interval is needed so many pigeons cannot leave in a
3278 single tick, even though sending remains free.
3279
3280- New-character spawn location (must be an open chunk) and name length /
3281 allowed-character rules.
3282
3283- Later changes to character creation beyond first name, last name and sex.
3284
3285# 33. Architectural summary
3286
3287ECS → what an entity is and what systems can act on it
3288Chunk → tile data, spatial lookup, simulation and client subscription
3289Region → residency and simulation-worker ownership
3290Coordinator→ where regions execute
3291Gateway → stable client connections, auth, character select, and command/update routing
3292world.sqlite→ authored versioned ground/block/spawner/light/settings world; unedited chunks are closed grass
3293state.sqlite→ accounts, characters, vaults, inheritance, and other durable live-game state
3294systemd → process supervision and relaunch
3295Deployment hook → conditional Git update/build only for intentional deployment restarts
3296Controller → manual client input today; sandboxed player scripts later
3297FrameworkV3 → git submodule at `client/frameworkv3`; built first; game client code layers on top
3298Sprites → all world art is 16×16; reject and CI-fail any other size
3299Equipment → layered 16×16 overlays on mobs; metal armour shares art and recolours by material
3300Camera → play view centered on the local player; bounded zoom; editor is chunk-framed
3301Movement → global walk/run cadence (default 2 tiles/s walk, run double); server tile steps; client visual lerp
3302World time → server clock minus 1200 years; night darkens unlit tiles
3303Light → baked passable-tile raycast on editor save; shines across chunks
3304World settings → admin modal for tick timers and global constants; pending revision
3305Inventory → 32 slots; stacks occupy one slot; letters are written paper items
3306Bank → per-character vault; account inheritance tab on character delete
3307Auth → auth.timfalken.com, stub admin-<n> until live; unlimited characters, one in world
3308Chunks → editor open/closed; default grass and closed until painted
3309Ground items → non-blocking, 10-minute player drops, pickup only while standing on the tile
3310Communication service → proximity speech
3311CourierService → pigeons carrying money or one item stack through durable transit
3312BankService → shared unlimited vaults, cheque reservations and redemption
3313MarketService → durable escrowed order book, matching, last-sale index and pigeon-to-bank settlement
3314Shop NPCs → sell allowed stock; price lerps toward last player-market sale over shopPriceLerpDuration, times a hidden discount
3315Combat → 8-tile melee, item/spell ranged range; hit skill roll; Strength / Dexterity / Mind damage; equal XP split
3316Skills → classless progression; non-combat XP to one skill; attack XP split hit/damage
3317
3318
3319# 34. Version history
3320
3321## 0.12
3322
3323- Chunks are open or closed in the world editor. Closed chunks stay visible
3324 but cannot be entered. Never-edited chunks are default grass with no
3325 blocks and are closed.
3326- Login uses auth.timfalken.com; until that is live, connections are stub
3327 `admin-<n>` (connected-client count including this one) and are admins.
3328- Accounts have unlimited characters, one in the world at a time. Creation
3329 is first name, unique account-owned last name, and male/female.
3330- Character deletion waits 24 hours with email and cancel. Permanent delete
3331 frees names and moves goods to an account inheritance bank tab.
3332
3333## 0.11
3334
3335- Made walk/run a global cadence from world settings (default 2 tiles/s
3336 walk, run double): walk steps every other movement tick, run every tick.
3337 Mob definitions do not set move speed.
3338- Added an admin world-settings modal for tick timers and global constants
3339 (shop lerp duration, drop lifetime, simulation tick, and the same class
3340 of values). Settings ride the pending world revision.
3341- World calendar time is server time minus 1200 years.
3342- Baked static lighting by passable-tile raycast on chunk save, including
3343 across chunk borders. Clients darken unreachable tiles at night. The
3344 editor has a night-to-day preview slider.
3345
3346## 0.10
3347
3348- Drew visible equipment as 16×16 overlay layers on mobs (including players),
3349 with worn items in equipment slots rather than the 32-slot inventory.
3350- Replicated compact appearance layers to nearby clients instead of another
3351 player's inventory.
3352- Recolourable metal armour shares one overlay plus a 16×16 channel mask;
3353 material definitions supply the metal colour while preserving shading.
3354
3355## 0.9
3356
3357- Vendored FrameworkV3 as the git submodule `client/frameworkv3`. The game
3358 client builds that library first and implements game-specific code on top
3359 of it. The Node.js server does not import the submodule.
3360
3361## 0.8
3362
3363- Required all world sprites (tiles, blocks, mobs, items) to be 16×16 pixels,
3364 rejected at load, with a CI unit test that reports and fails on any other
3365 size. Sprites are not individually scaled; the player may zoom the viewport
3366 within configured bounds.
3367- Locked the play camera to the local player. The admin world editor remains
3368 the only non-player-centered view.
3369- Made authoritative movement integer tile-to-tile steps. Clients lerp
3370 mobiles for presentation only.
3371- Added a per-chunk world-editor changelog: admin, timestamp, and bullet
3372 diffs for ground changes, block place/change/remove.
3373
3374## 0.7
3375
3376- Added combat for all mobs including players: melee from any of the eight
3377 neighbouring tiles, ranged and spells from the item or spell range.
3378- Hit rolls use the weapon skill (Swordfighting, Axefighting, Archery, Magic,
3379 and so on). Damage uses Strength, Dexterity or Mind according to melee,
3380 ranged or magic.
3381- Successful player-attack XP is split equally between the hit skill and the
3382 damage skill. Ordinary mobs use archetype skill levels and do not earn XP.
3383- Shop NPCs sell items at seed value adapted to the last player-market unit
3384 price, lerping over one hour, multiplied by a hidden per-shop discount.
3385- Only the latest player-market sale per item is stored (price, timestamp, and
3386 lerp origin). No historical series.
3387- Item hover shows name, description, origin (crafter or shop NPC) and the
3388 undiscounted current value, refreshed at most once per minute.
3389
3390## 0.6
3391
3392- Added a 32-slot player inventory, stackable items, carried currency as a
3393 numeric wallet, and unique-instance items for letters and filled cheques.
3394- Redefined letters as paper items with player-written text rather than a
3395 separate mail record.
3396- Redefined carrier pigeons as free couriers that carry money or one item
3397 stack to a player or to the nearest bank.
3398- Added a shared unlimited bank near the marketplace, blank cheques filled to
3399 99, vault reservations on fill, in-person redemption and pigeon-to-bank
3400 cheque transfers between vaults.
3401- Added player-dropped ground items: 10-minute lifetime, non-blocking, pickup
3402 only while standing on the tile, timestamp persistence across unload.
3403- Specified later ground-item spawners and harvesting as content that reuses
3404 this item model.
3405- Routed offline/full-inventory pigeon delivery and older-side market
3406 settlement into the recipient's shared bank vault.
3407
3408## 0.5
3409
3410- Made carrier pigeons shared world-visible entities whenever their route crosses an already-simulating chunk.
3411- Unrelated nearby players can see pigeons in their normal 3x3 chunk view; pigeons do not keep chunks loaded themselves.
3412- Added deterministic materialisation/dematerialisation between durable abstract transit and worker-owned ECS pigeon entities.
3413
3414## 0.4
3415
3416- Added FrameworkV3 as the shared player-client foundation while keeping backend ECS internal to the server.
3417- Added server-side proximity chat degradation, persistent player groups and durable carrier-pigeon letters.
3418- Added scalable courier transit that can cross dormant world space without forcing normal chunk simulation.
3419- Added the central marketplace, escrowed hidden order book, midpoint pricing and pigeon-based remote settlement.
3420- Added the player-driven item-source philosophy and restrictions on NPC shop inventories.
3421- Added classless, skill-based player progression and authoritative skill XP.
3422
3423## 0.3
3424
3425- Converted the living design document to Markdown as the canonical format.
3426- Defined `systemd` as the production process supervisor.
3427- Added a conditional, manifest-driven deployment path so crashes do not deploy pending code early.
3428- Added a concrete example systemd service shape and clarified privilege separation.
3429
3430## 0.2
3431
3432- Added unload-driven chunk persistence, authored world revisions, the admin world editor, spawner blocks, graceful scheduled restarts and future player scripting hooks.