BlueGit

timfa questward

Document ranged combat, chickens, and equip draw order.

Bring FEATURES and the design draw-order list in line with bows, batch craft UI, chicken/egg drops, and deferred projectile hit FX.

timfa Tim Falken · pushed by timfa

Authored 2026-08-27 · 2 months ago

Hash
af10d2b5b2cb99d8a0498c7ad73a3e4b77dfd110
Parent
e6eae69d
3 files changed +29 −26
docs/FEATURES.md +18 −18
@@ -190,14 +190,14 @@ Each entry is a short note on behaviour and where the code lives. Update this fi
190 190 ## Spawners
191 191
192 192 **Status:** full
193 **Spec:** Authored chunk spawners (`data.spawners[]`) with mob type, max alive, spawn range, and **max wander range** (≥ spawn range). Legacy `BlockType.spawner` tiles migrate into this array on decode. They fire only in open, simulating chunks. When a chunk first becomes simulating, spawners **pre-heat** and place up to `maxAlive` immediately so the area looks populated. Spawned mobs get `SpawnOrigin` (origin tile + wander range); idle wander goals must stay inside max wander range, while combat chase / approach may leave the area. Persistence follows the mob definition (deer are not persistent). In play, spawners are invisible and non-blocking; players may place real blocks on the same tile. Wildlife options include deer and rats; the editor lists every mob definition as a placeable spawner. Hovering a spawner in the world editor highlights spawn range (cyan) and wander range (amber). Pigeons are not ambient wildlife. Living mobs (deer, rats, etc.) can always fight back when attacked (retaliate on first swing); **rats are aggressive** and auto-engage players within 5 tiles with line of sight. **Humanoid** spawners (incl. town guards / exchange) have an editor **Aggressive** flag for the same in-range aggro; Aggressive forces **Bounty** to 0. Spawner **Level** sets skills/HP and **spell cast chance %** (= level, capped 1–100; shown as a label, not editable).; courier pigeons cannot.
194 **Code:** `server/src/simulation/spawners.js`, `server/src/simulation/workerWorld.js`, `server/src/world/chunkData.js`, `shared/definitions/mobs.js`, `shared/definitions/mobCombat.js`, `client/src/editor/tileConfigModal.js`, `client/assets/mobs/deer/`, `client/assets/mobs/rat/`
193 **Spec:** Authored chunk spawners (`data.spawners[]`) with mob type, max alive, spawn range, and **max wander range** (≥ spawn range). Legacy `BlockType.spawner` tiles migrate into this array on decode. They fire only in open, simulating chunks. When a chunk first becomes simulating, spawners **pre-heat** and place up to `maxAlive` immediately so the area looks populated. Spawned mobs get `SpawnOrigin` (origin tile + wander range); idle wander goals must stay inside max wander range, while combat chase / approach may leave the area. Persistence follows the mob definition (deer are not persistent). In play, spawners are invisible and non-blocking; players may place real blocks on the same tile. Wildlife options include **deer**, **rats**, and **chickens** (white deer-shaped placeholder sprite); the editor lists every mob definition as a placeable spawner. Hovering a spawner in the world editor highlights spawn range (cyan) and wander range (amber). Pigeons are not ambient wildlife. Living mobs (deer, rats, chickens, etc.) can always fight back when attacked (retaliate on first swing); **rats are aggressive** and auto-engage players within 5 tiles with line of sight. **Humanoid** spawners (incl. town guards / exchange) have an editor **Aggressive** flag for the same in-range aggro; Aggressive forces **Bounty** to 0. Spawner **Level** sets skills/HP and **spell cast chance %** (= level, capped 1–100; shown as a label, not editable).; courier pigeons cannot.
194 **Code:** `server/src/simulation/spawners.js`, `server/src/simulation/workerWorld.js`, `server/src/world/chunkData.js`, `shared/definitions/mobs.js`, `shared/definitions/mobCombat.js`, `client/src/editor/tileConfigModal.js`, `client/assets/mobs/deer/`, `client/assets/mobs/rat/`, `client/assets/mobs/chicken/`
195 195
196 196 ## Mob definitions (content schema)
197 197
198 198 **Status:** partial
199 **Spec:** Target mob content shape: `displayName`, `maxHealth`, `attackSkill`, `drops`, `sells`. **Dialogue trees** are world-scoped assets (Dialogues editor); humanoid spawners assign `config.dialogueId`. See [`docs/QUESTS.md`](QUESTS.md).
200 **Code:** `shared/definitions/mobs.js`, `shared/definitions/mobCombat.js`
199 **Spec:** Target mob content shape: `displayName`, `maxHealth`, `attackSkill`, `drops`, `sells`. Drops support `chance`, fixed `quantity`, or inclusive `quantityMin`/`quantityMax`. **Chicken** always drops **1–3 feathers** and has a **20%** chance of an **egg**. **Dialogue trees** are world-scoped assets (Dialogues editor); humanoid spawners assign `config.dialogueId`. See [`docs/QUESTS.md`](QUESTS.md).
200 **Code:** `shared/definitions/mobs.js`, `shared/definitions/mobCombat.js`, `server/src/combat/service.js` (`rollDropQuantity`)
201 201
202 202 ## Quests
203 203
@@ -214,14 +214,14 @@ Each entry is a short note on behaviour and where the code lives. Update this fi
214 214 ## Combat resolution (rolls)
215 215
216 216 **Status:** partial
217 **Spec:** Authoritative server rolls; clients only show outcomes. **Melee & ranged (physical):** roll hit skill vs defender **Dexterity (agility)** — miss if attack roll < agility roll, hit on tie or higher; on hit roll damage skill (Strength for melee, Dexterity for ranged) for `baseDamage + roll − 1`; on hit defender rolls Defence — **block** if defence roll > attacker's to-hit roll; otherwise apply damage. **Effective combat levels** add worn equipment tier bonuses to damage/agility/defence rolls (e.g. Strength 10 + bronze weapon +1 → damage roll uses 11). Hit skills (Club/Sword fighting, Archery) use base skill only. XP only on damage hits. **Attack types** (slashing / piercing / blunt) are defined on weapons; mob weak/resist multipliers remain later. **Magic:** roll Magic vs per-spell **difficulty** (contest, tie or higher succeeds); on success roll Mind for damage; multiply by elemental weak ×2 / neutral ×1 / resistant ×0.5; non-damage spells only need a successful cast roll then apply an effect. Spell defs in `shared/definitions/spells.js`. Full casting UI, LOS, and effect system remain later.
218 **Code:** `shared/combat/rolls.js` (physical, live), `shared/combat/magic.js` (cast + damage rules, shared only), `shared/definitions/spells.js`, `shared/definitions/attackTypes.js`, `shared/equipment/stats.js`, `server/src/combat/service.js`, tests in `server/tests/combatRolls.test.js`, `server/tests/magic.test.js`, `server/tests/equipment.test.js`
217 **Spec:** Authoritative server rolls; clients only show outcomes. **Melee & ranged (physical):** roll hit skill vs defender **Dexterity (agility)** — miss if attack roll < agility roll, hit on tie or higher; on hit roll damage skill (Strength for melee, Dexterity for ranged) for `baseDamage + roll − 1`; on hit defender rolls Defence — **block** if defence roll > attacker's to-hit roll; otherwise apply damage. **Effective combat levels** add worn equipment tier bonuses to damage/agility/defence rolls (e.g. Strength 10 + bronze weapon +1 → damage roll uses 11). Hit skills (Club/Sword fighting, Archery) use base skill only. XP only on damage hits. **Attack types** (slashing / piercing / blunt) are defined on weapons; mob weak/resist multipliers remain later. **Magic:** roll Magic vs per-spell **difficulty** (contest, tie or higher succeeds); on success roll Mind for damage; multiply by elemental weak ×2 / neutral ×1 / resistant ×0.5; non-damage spells only need a successful cast roll then apply an effect. Spell defs + live cast/impact in `shared/definitions/spells.js` / `server/src/spells/` (starter Light + Spark). More spells and LOS polish remain later.
218 **Code:** `shared/combat/rolls.js`, `shared/combat/magic.js`, `shared/definitions/spells.js`, `shared/definitions/attackTypes.js`, `shared/equipment/stats.js`, `server/src/combat/service.js`, `server/src/spells/service.js`, tests in `server/tests/combatRolls.test.js`, `server/tests/magic.test.js`, `server/tests/spells.test.js`, `server/tests/equipment.test.js`
219 219
220 220 ## Combat, skills, groups, pigeons
221 221
222 **Status:** partial
223 **Spec:** Melee auto-attack with stick (Clubfighting + Strength), LMB/RMB targeting and context menu (including **Follow \<name\>** / **Attack \<name\>**), engage/retaliate, swipe VFX, shove animation, damage flash, HP bars above **mobs and players** when below max HP, and client dynamic-light hooks. Fightable mobs **retaliate on the first resolved swing** (hit or miss), not when Attack is merely clicked. **Players likewise auto-retaliate** when a mob’s first swing resolves against them (clears follow/gather). Melee requires Chebyshev distance 1 (**diagonals allowed**) while the attacker stands alone on their tile; if stacked with others they path to the nearest clear adjacent stance. Approach pathfinding may pass through entities but prefers clear goal tiles. **Aggressive** mobs (e.g. rats: `aggressive` + `aggroRangeTiles`, default 5) auto-engage player characters in Chebyshev range with line of sight through enterable tiles; passive wildlife (deer) does not. Engaged mobs keep pursuing if the player cancels attack. Physical combat uses skill rolls (see **Combat resolution**). **Health** skill sets max HP; taking damage awards Health XP equal to damage taken (lethal hits grant none). Reaching **0 HP** is player death (see **Player death and respawn**). Follow reuses the target's vacated trail and remaining path (stop one tile short, wait for vacancy, walkability each step); catch-up A* only when no shared trail yet. Break beyond one chunk width. **Carrier pigeons** dispatch money or one inventory stack to Bank or Player. **Skills:** persistent XP, 50 XP to level 2 then double each level, cap 99; Health starts at 10, others at 1; **login enforces those minima** (raises and persists under-leveled skills). Skills panel. Ranged combat, magic, groups, and non-combat skill XP (except Health from damage) remain later.
224 **Code:** `shared/combat/rolls.js`, `shared/skills/progression.js`, `shared/skills/state.js`, `shared/definitions/skills.js`, `shared/definitions/mobCombat.js`, `shared/definitions/mobs.js`, `server/src/skills/service.js`, `server/src/combat/service.js`, `client/src/play/skills.js`, `client/src/render/worldView.js`, tests in `server/tests/combatRolls.test.js`, `server/tests/skills.test.js`, `server/tests/mobCombat.test.js` (+ combat/follow/courier tests)
222 **Status:** partial (melee + ranged bows + starter spells live; groups later)
223 **Spec:** Melee auto-attack with stick (Clubfighting + Strength), LMB/RMB targeting and context menu (including **Follow \<name\>** / **Attack \<name\>**), engage/retaliate, swipe VFX, shove animation, damage flash, HP bars above **mobs and players** when below max HP, and client dynamic-light hooks. Fightable mobs **retaliate on the first resolved swing** (hit or miss), not when Attack is merely clicked. **Players likewise auto-retaliate** when a mob’s first swing resolves against them (clears follow/gather). Melee requires Chebyshev distance 1 (**diagonals allowed**) while the attacker stands alone on their tile; if stacked with others they path to the nearest clear adjacent stance. Approach pathfinding may pass through entities but prefers clear goal tiles. **Aggressive** mobs (e.g. rats: `aggressive` + `aggroRangeTiles`, default 5) auto-engage player characters in Chebyshev range with line of sight through enterable tiles; passive wildlife (deer, chickens) does not. Engaged mobs keep pursuing if the player cancels attack. Physical combat uses skill rolls (see **Combat resolution**). **Ranged:** bow in weapon + arrows in offhand; Archery hit / Dexterity damage; arrow projectiles lerp toward the target’s **live client visual pose** (misses use a fixed fly-by tile). Server resolves the hit immediately; **HP bar / flash / damage numbers wait until the projectile lands** on each client. **Magic:** cast UI + Light/Spark; spell projectiles likewise track moving targets; spell impacts are delayed on the server to match travel time. **Health** skill sets max HP; taking damage awards Health XP equal to damage taken (lethal hits grant none). Reaching **0 HP** is player death (see **Player death and respawn**). Follow reuses the target's vacated trail and remaining path (stop one tile short, wait for vacancy, walkability each step); catch-up A* only when no shared trail yet. Break beyond one chunk width. **Carrier pigeons** dispatch money or one inventory stack to Bank or Player. **Skills:** persistent XP, 50 XP to level 2 then double each level, cap 99; Health starts at 10, others at 1; **login enforces those minima** (raises and persists under-leveled skills). Skills panel. Groups and broader non-combat skill XP remain later.
224 **Code:** `shared/combat/rolls.js`, `shared/skills/progression.js`, `shared/skills/state.js`, `shared/definitions/skills.js`, `shared/definitions/mobCombat.js`, `shared/definitions/mobs.js`, `shared/definitions/rangedItems.js`, `server/src/skills/service.js`, `server/src/combat/service.js`, `server/src/spells/service.js`, `client/src/play/skills.js`, `client/src/play/main.js`, `client/src/render/worldView.js`, tests in `server/tests/combatRolls.test.js`, `server/tests/skills.test.js`, `server/tests/mobCombat.test.js`, `server/tests/ranged.test.js` (+ combat/follow/courier/spells tests)
225 225
226 226 ## Player death and respawn
227 227
@@ -241,15 +241,15 @@ Each entry is a short note on behaviour and where the code lives. Update this fi
241 241
242 242 **Status:** partial
243 243 **Spec:** Metal gear exists in seven material tiers (lowest → highest): **Bronze**, **Iron**, **Steel**, **Mithril**, **Adamantium**, **Orichalcum**, **Dragon**. Each has a **rank** (1–7), display **tint**, and equip min skill: 1 / 10 / 20 / 35 / 50 / 70 / 90. Mining a material requires **half** of that equip gate (ceil); smelting requires **75%** (ceil). **Worn combat bonuses** come from live world setting `equipmentStatBonuses` (editor **Equipment Stats** tab); defaults seed from `TIER_STAT_BONUS` (full helms +1 Defence). Leather armour can grant Agility and Defence independently; wizard armour Magic and Defence; clothing Defence. Magic casting uses worn Magic/Mind gear bonuses the same way physical combat uses Strength/Agility/Defence. Tools (pickaxes) gate on Mining and do not use the bonus tables. **Tin** and **copper** ores (no bronze ore) and **coal** use their associated bar tier for mine/smelt timing and gates (tin/copper → bronze, coal → steel). **Silver** and **Gold** are precious-only (ore + bars, no tools; silver mine/smelt like iron rank 2 / skill 10, gold like steel rank 3 / skill 20). **Wood tiers** (same gates/ranks): **Pine**, **Birch**, **Oak**, **Ebony**, **Lignum**, **Heartwood**, **Elder** (match metal ranks for hafts). **Cloth tiers** (same gates/ranks): **Cotton**, **Wool**, **Linen**, **Cashmere**, **Silk**, **Fairy silk**, **Dragonweave**. Logs/handles tint from shared `wood` sprites; **pine trees** are chopable resource nodes (more tree tiers later) — axe sprites (`items/axe`) match pickaxe style for woodcutting. Armour pieces share one set of overlays under `items/armour/` tinted per metal tier (no per-tier icon copies).
244 **Shared sprites + magenta tint:** one base sprite per shape under `items/metal` (`ore`, `bar`), `items/pickaxe`, `items/axe` (`axe`, `axe-head`, `axe-equip`), `items/wood` (`log`, `handle`), `items/cloth` (`wool`, `yarn`, `cloth`), `items/clothing` (`shirt`, `shorts`, `skirt`, `trousers`, `sweater`), boulder-ore, and **tables** (`blocks/table/0`–`15`); tintable pixels use magenta rules in `shared/render/tint.js`. Boulder ore states are catalog aliases of `boulder-ore.png` with per-material tint. Table states are `${woodTier}-${mask}` aliases of mask PNGs with wood-tier tint; tables autotile only with the same wood. Trees use per-season live + **`-stump`** PNGs (mandatory for every tree type).
245 **TODO:** full combat gear catalog; more tree tiers / fishing / herbs; silver/gold jewelry / other precious recipes; cloth sources beyond cotton.
246 **Code:** `shared/definitions/materialTiers.js`, `shared/definitions/equipmentStatCategories.js`, `shared/render/tint.js`, `shared/definitions/metalItems.js`, `shared/definitions/woodItems.js`, `shared/equipment/stats.js`, tests in `server/tests/equipment.test.js`, `server/tests/mining.test.js`, `server/tests/tint.test.js`
244 **Shared sprites + magenta tint:** one base sprite per shape under `items/metal` (`ore`, `bar`), `items/pickaxe`, `items/axe` (`axe`, `axe-head`, `axe-equip`), `items/wood` (`log`, `handle`), `items/cloth` (`wool`, `yarn`, `cloth`), `items/clothing` (`shirt`, `shorts`, `skirt`, `trousers`, `sweater`), boulder-ore, and **tables** (`blocks/table/0`–`15`); tintable pixels use magenta rules in `shared/render/tint.js`. **Dual-channel tint** (red = shaft/wood, blue = tip/string; white unchanged): arrows, hafted tools, **bows** / unstrung bows under `items/bow/` (`bow`, `unstrung-bow`, `bowstring` magenta, `bow-equip`). Boulder ore states are catalog aliases of `boulder-ore.png` with per-material tint. Table states are `${woodTier}-${mask}` aliases of mask PNGs with wood-tier tint; tables autotile only with the same wood. Trees use per-season live + **`-stump`** PNGs (mandatory for every tree type).
245 **TODO:** full combat gear catalog; more tree tiers / fishing / herbs; silver/gold jewelry / other precious recipes; cloth sources beyond cotton.
246 **Code:** `shared/definitions/materialTiers.js`, `shared/definitions/equipmentStatCategories.js`, `shared/render/tint.js`, `shared/definitions/metalItems.js`, `shared/definitions/woodItems.js`, `shared/definitions/rangedItems.js`, `shared/definitions/tierFamilies.js`, `shared/equipment/stats.js`, tests in `server/tests/equipment.test.js`, `server/tests/mining.test.js`, `server/tests/tint.test.js`, `server/tests/ranged.test.js`
247 247
248 248 ## Gathering, crafting, and production skills
249 249
250 **Status:** partial (mining + smelting + pickaxe/axe craft chains + pine woodcutting + cotton/flower/herb herbalism live)
251 **Spec:** **Mining:** LMB/RMB on ore boulder (states `tin-ore`, `copper-ore`, `iron-ore`, `silver-ore`, `gold-ore` … `dragon-ore`, `coal`). Uses the **best usable pickaxe in inventory** (or weapon slot) — tools need not be equipped. Tool rank ≥ associated bar rank and Mining ≥ mine gate; otherwise toast *"You need a pickaxe to mine this!"*. Duration `(rank×8s) − (toolRank×3s)` (min 0.5s). Attack shove animation, **no** swipe FX; while swinging, the gather tool's **equip sprite** is shown in the weapon overlay (even if a different weapon is equipped). Awards Mining XP (`rank×5`). On success the node becomes **exhausted** (plain `boulder` sprite, not mineable) for `10s × associated bar rank`, then restores its ore state via runtime `CHUNK_DELTA`. Hovering an active ore/tree/plant node shows a cursor tooltip (`resourceNodeDisplayName`). Outdoor blocks may also use **optional seasonal overlays** (e.g. boulder / ore `*-winter` only — other seasons keep the base sprite). **Woodcutting:** LMB/RMB / **Chop** on outdoor tree blocks (**pine** today). Best usable **axe** in inventory/weapon; Woodcutting + axe tier gates match mining (pine = rank 1). Same duration/exhaust curves. Success grants a **pine log**, stamps **`Felled by <name>`**, awards Woodcutting XP, and sets a **seasonal stump** (`summer-stump` / `fall-stump` / `winter-stump` — required for every tree type). Calendar season still drives stump look while exhausted; after exhaust the live tree returns. Tree / flower / herb **regrow** uses the four-way growth season (spring Mar–May, summer Jun–Aug, fall Sep–Nov, winter Dec–Feb): **summer & fall** keep base exhaust time, **winter** doubles it, **spring** is 25% faster (`×0.75`). **Herbalism (plants):** **Flower** nodes need **no tool** (~1s); each flower block carries a fixed colour tint (chosen on respawn / editor place) and picking yields that colour, stamps **`Picked by <name>`**. **Cotton plant** needs **no tool** (RMB Pick / LMB); yields cotton fibre. Both exhaust ~15s then respawn. **Smelting:** furnace block opens craft UI; duration `rank×2s` by output bar tier. Recipes 1 ore → 1 bar except **bronze** = 1 tin + 1 copper, **steel** = 1 iron ore + 1 coal, **adamantium** = 1 ore + 1 coal, **orichalcum** = 1 ore + 3 coal, **dragon** = 1 ore + 5 coal. Smithing XP on success. **Pickaxe / axe craft:** woodworking bench shapes 1 log → 1 handle; anvil smiths 1 bar → 1 pickaxe head or axe head; **crafting bench** assembles matching-tier handle + head → pickaxe or axe (pine↔bronze … elder↔dragon). Gold bars are smeltable but have no tool recipes. Server-authoritative `START_CRAFT` / timer. Play errors (mine gates, full bag, …) show as temporary **toasts** at the top of the screen. More tree tiers / fishing / other stations later.
252 **Code:** `shared/definitions/gathering.js`, `shared/definitions/tiles.js` (`resourceNodeDisplayName`, `isChopableTreeBlock`, `isPickablePlantBlock`), `shared/world/season.js` (`treeStumpStateForSeason`, `growthSeasonIdAt`, `scaleRegrowDurationMs`), `server/src/gathering/service.js`, `server/src/crafting/service.js`, `shared/crafting/stationRecipes.js`, `client/src/play/main.js`, `client/src/render/worldView.js` (`spawnGatherSwing`), tests in `server/tests/mining.test.js`, `server/tests/woodcutting.test.js`, `server/tests/crafting.test.js`, `server/tests/season.test.js`
250 **Status:** partial (mining + smelting + pickaxe/axe/bow craft chains + pine woodcutting + cotton/flower/herb herbalism live)
251 **Spec:** **Mining:** LMB/RMB on ore boulder (states `tin-ore`, `copper-ore`, `iron-ore`, `silver-ore`, `gold-ore` … `dragon-ore`, `coal`). Uses the **best usable pickaxe in inventory** (or weapon slot) — tools need not be equipped. Tool rank ≥ associated bar rank and Mining ≥ mine gate; otherwise toast *"You need a pickaxe to mine this!"*. Duration `(rank×8s) − (toolRank×3s)` (min 0.5s). Attack shove animation, **no** swipe FX; while swinging, the gather tool's **equip sprite** is shown in the weapon overlay (even if a different weapon is equipped). Awards Mining XP (`rank×5`). On success the node becomes **exhausted** (plain `boulder` sprite, not mineable) for `10s × associated bar rank`, then restores its ore state via runtime `CHUNK_DELTA`. Hovering an active ore/tree/plant node shows a cursor tooltip (`resourceNodeDisplayName`). Outdoor blocks may also use **optional seasonal overlays** (e.g. boulder / ore `*-winter` only — other seasons keep the base sprite). **Woodcutting:** LMB/RMB / **Chop** on outdoor tree blocks (**pine** today). Best usable **axe** in inventory/weapon; Woodcutting + axe tier gates match mining (pine = rank 1). Same duration/exhaust curves. Success grants a **pine log**, stamps **`Felled by <name>`**, awards Woodcutting XP, and sets a **seasonal stump** (`summer-stump` / `fall-stump` / `winter-stump` — required for every tree type). Calendar season still drives stump look while exhausted; after exhaust the live tree returns. Tree / flower / herb **regrow** uses the four-way growth season (spring Mar–May, summer Jun–Aug, fall Sep–Nov, winter Dec–Feb): **summer & fall** keep base exhaust time, **winter** doubles it, **spring** is 25% faster (`×0.75`). **Herbalism (plants):** **Flower** nodes need **no tool** (~1s); each flower block carries a fixed colour tint (chosen on respawn / editor place) and picking yields that colour, stamps **`Picked by <name>`**. **Cotton plant** needs **no tool** (RMB Pick / LMB); yields cotton fibre. Both exhaust ~15s then respawn. **Smelting:** furnace block opens craft UI; duration `rank×2s` by output bar tier. Recipes 1 ore → 1 bar except **bronze** = 1 tin + 1 copper, **steel** = 1 iron ore + 1 coal, **adamantium** = 1 ore + 1 coal, **orichalcum** = 1 ore + 3 coal, **dragon** = 1 ore + 5 coal. Smithing XP on success. **Pickaxe / axe craft:** woodworking bench shapes 1 log → 1 handle; anvil smiths 1 bar → 1 pickaxe head or axe head; **crafting bench** assembles matching-tier handle + head → pickaxe or axe (pine↔bronze … elder↔dragon). **Ranged craft:** woodworking → arrow shafts / unstrung bows; anvil → arrow tips; spinning wheel → bowstring from yarn; crafting bench → feather + shaft + tip → arrow, and unstrung bow + bowstring → bow (wood + matching cloth). Gold bars are smeltable but have no tool recipes. Server-authoritative `START_CRAFT` / timer; craft panel supports **Craft**, **Craft X**, and **Craft all** with a progress bar that restarts on each continuing batch step. Play errors (mine gates, full bag, …) show as temporary **toasts** at the top of the screen. More tree tiers / fishing / other stations later.
252 **Code:** `shared/definitions/gathering.js`, `shared/definitions/tiles.js` (`resourceNodeDisplayName`, `isChopableTreeBlock`, `isPickablePlantBlock`), `shared/definitions/rangedItems.js`, `shared/crafting/tierRecipes.js`, `shared/world/season.js` (`treeStumpStateForSeason`, `growthSeasonIdAt`, `scaleRegrowDurationMs`), `server/src/gathering/service.js`, `server/src/crafting/service.js`, `shared/crafting/stationRecipes.js`, `client/src/play/main.js`, `client/src/play/crafting.js`, `client/src/render/worldView.js` (`spawnGatherSwing`), tests in `server/tests/mining.test.js`, `server/tests/woodcutting.test.js`, `server/tests/crafting.test.js`, `server/tests/ranged.test.js`, `server/tests/season.test.js`
253 253
254 254 ## Cloth, dyes, and tailoring
255 255
@@ -265,7 +265,7 @@ Each entry is a short note on behaviour and where the code lives. Update this fi
265 265 ## Crafting stations
266 266
267 267 **Status:** partial (furnace, anvil, woodworking, crafting, spinning wheel, loom, tailor bench live)
268 **Spec:** Furnace / anvil / woodworking-bench / crafting-bench / spinning-wheel / loom / tailor-bench blocks + adjacency craft panel. Recipes in `stationRecipes.js`. Furnace/anvil/woodworking/crafting craft timer = `smeltingDurationMs` (`rank × 2s`) when `xpMaterial` is set; other stations still use `CRAFT_DURATION_MS` (2s) / UI/dev only (`__craftDev`). Woodworking shapes components (handles); crafting bench joins finished parts (pickaxe/axe head + handle). Spinning wheel / loom / tailor use Tailoring. **Anvil**, **woodworking**, and **tailor** craft UIs use a material dropdown so tier variants share one recipe cell (plant clippers = 1 bar per metal tier). **Hard rule (all stations + cauldron, player and scripts):** items in station slots are never committed out of the inventory — slots are a reservation/view over the bag (**client-side UI**; even if it looks like mats sit in the station, they do not). Server soft-tracks steps/claims only and consumes on successful craft/brew. Closing the UI, cancelling, or dying mid-craft/brew cannot destroy reserved mats. Station progress is **per player**, not tile-global. See `.cursor/rules/station-inventory.mdc`.
268 **Spec:** Furnace / anvil / woodworking-bench / crafting-bench / spinning-wheel / loom / tailor-bench blocks + adjacency craft panel. Recipes in `stationRecipes.js`. Furnace/anvil/woodworking/crafting craft timer = `smeltingDurationMs` (`rank × 2s`) when `xpMaterial` is set; other stations still use `CRAFT_DURATION_MS` (2s) / UI/dev only (`__craftDev`). Woodworking shapes components (handles, shafts, unstrung bows); crafting bench joins finished parts (pickaxe/axe head + handle, arrows, strung bows). Spinning wheel / loom / tailor use Tailoring. **Anvil**, **woodworking**, **spinning wheel**, **loom**, and **tailor** craft UIs use a single-axis material dropdown so tier variants share one recipe cell. **Crafting bench** alone shows **paired metal/wood labels** (e.g. `Bronze/Pine`) because it mixes metal tools with wood bows on the same tier rank. **Hard rule (all stations + cauldron, player and scripts):** items in station slots are never committed out of the inventory — slots are a reservation/view over the bag (**client-side UI**; even if it looks like mats sit in the station, they do not). Server soft-tracks steps/claims only and consumes on successful craft/brew. Closing the UI, cancelling, or dying mid-craft/brew cannot destroy reserved mats. Station progress is **per player**, not tile-global. See `.cursor/rules/station-inventory.mdc`.
269 269 **TODO:** oven/campfire burn; dedicated station sprites where still placeholder.
270 270 **Code:** `shared/definitions/craftingStations.js`, `shared/definitions/tiles.js`, `server/src/crafting/service.js`, `client/src/play/crafting.js`
271 271
@@ -315,8 +315,8 @@ Use later when deciding which ingredients fit which potions. Tiers: **2 / 3 / 3
315 315 ## Inventory, items, equipment, ground drops
316 316
317 317 **Status:** full
318 **Spec:** 32-slot inventory, stacking, equipment slots (head, chest, legs, boots, weapon, **offhand** for shields) with a separate `equipSprite` overlay on the body, carried currency, player drops that last `groundItemDespawnDurationMs` (default 10 minutes). Pickup requires standing on the tile. Inventory is private UI state; nearby clients see ground items and worn overlays. New characters start with paper, apples, a stick, a cloth shirt, and coins. Placeholder item/equipment PNGs until real art exists. Right-click bag items for Send / Equip / Drop / Eat (food); paper can be written into unique **letter** instances (signed on Save; only the signer may edit). Equipping always takes **one** item from a stack (never the whole stack); unequipping returns one item and merges into an existing compatible inventory stack when stack rules allow. Equip enforces tier min-skill gates. Eating food heals (see Health skill).
319 **Code:** `shared/definitions/items.js`, `shared/items/inventory.js`, `server/src/items/bags.js`, `client/src/play/inventory.js`
318 **Spec:** 32-slot inventory, stacking, equipment slots (head, chest, legs, boots, weapon, **offhand** for shields/arrows) with a separate `equipSprite` overlay on the body, carried currency, player drops that last `groundItemDespawnDurationMs` (default 10 minutes). Pickup requires standing on the tile. Inventory is private UI state; nearby clients see ground items and worn overlays. **Equip draw order (back → front):** boots → chest → weapon → legs → hair (if visible) → head → offhand — so weapons sit above the shirt but under trousers/skirts (legs may cover shirt hem; art should avoid bad waist overlap). New characters receive world **Starter Equipment** / inventory, then creation clothing dyes on top (see **Characters**). Right-click bag items for Send / Equip / Drop / Eat (food; apples, eggs, …); paper can be written into unique **letter** instances (signed on Save; only the signer may edit). Equipping always takes **one** item from a stack (never the whole stack); unequipping returns one item and merges into an existing compatible inventory stack when stack rules allow. Equip enforces tier min-skill gates. Eating food heals (see Health skill).
319 **Code:** `shared/definitions/items.js` (`EQUIPMENT_DRAW_ORDER`), `shared/appearance/hair.js` (`composeAppearanceLayers`), `shared/items/inventory.js`, `server/src/items/bags.js`, `client/src/play/inventory.js`
320 320
321 321 ## Proximity chat
322 322
@@ -190,14 +190,14 @@ Each entry is a short note on behaviour and where the code lives. Update this fi
190## Spawners
190## Spawners
191
191
192**Status:** full
192**Status:** full
193**Spec:** Authored chunk spawners (`data.spawners[]`) with mob type, max alive, spawn range, and **max wander range** (≥ spawn range). Legacy `BlockType.spawner` tiles migrate into this array on decode. They fire only in open, simulating chunks. When a chunk first becomes simulating, spawners **pre-heat** and place up to `maxAlive` immediately so the area looks populated. Spawned mobs get `SpawnOrigin` (origin tile + wander range); idle wander goals must stay inside max wander range, while combat chase / approach may leave the area. Persistence follows the mob definition (deer are not persistent). In play, spawners are invisible and non-blocking; players may place real blocks on the same tile. Wildlife options include deer and rats; the editor lists every mob definition as a placeable spawner. Hovering a spawner in the world editor highlights spawn range (cyan) and wander range (amber). Pigeons are not ambient wildlife. Living mobs (deer, rats, etc.) can always fight back when attacked (retaliate on first swing); **rats are aggressive** and auto-engage players within 5 tiles with line of sight. **Humanoid** spawners (incl. town guards / exchange) have an editor **Aggressive** flag for the same in-range aggro; Aggressive forces **Bounty** to 0. Spawner **Level** sets skills/HP and **spell cast chance %** (= level, capped 1–100; shown as a label, not editable).; courier pigeons cannot.
193**Spec:** Authored chunk spawners (`data.spawners[]`) with mob type, max alive, spawn range, and **max wander range** (≥ spawn range). Legacy `BlockType.spawner` tiles migrate into this array on decode. They fire only in open, simulating chunks. When a chunk first becomes simulating, spawners **pre-heat** and place up to `maxAlive` immediately so the area looks populated. Spawned mobs get `SpawnOrigin` (origin tile + wander range); idle wander goals must stay inside max wander range, while combat chase / approach may leave the area. Persistence follows the mob definition (deer are not persistent). In play, spawners are invisible and non-blocking; players may place real blocks on the same tile. Wildlife options include **deer**, **rats**, and **chickens** (white deer-shaped placeholder sprite); the editor lists every mob definition as a placeable spawner. Hovering a spawner in the world editor highlights spawn range (cyan) and wander range (amber). Pigeons are not ambient wildlife. Living mobs (deer, rats, chickens, etc.) can always fight back when attacked (retaliate on first swing); **rats are aggressive** and auto-engage players within 5 tiles with line of sight. **Humanoid** spawners (incl. town guards / exchange) have an editor **Aggressive** flag for the same in-range aggro; Aggressive forces **Bounty** to 0. Spawner **Level** sets skills/HP and **spell cast chance %** (= level, capped 1–100; shown as a label, not editable).; courier pigeons cannot.
194**Code:** `server/src/simulation/spawners.js`, `server/src/simulation/workerWorld.js`, `server/src/world/chunkData.js`, `shared/definitions/mobs.js`, `shared/definitions/mobCombat.js`, `client/src/editor/tileConfigModal.js`, `client/assets/mobs/deer/`, `client/assets/mobs/rat/`
194**Code:** `server/src/simulation/spawners.js`, `server/src/simulation/workerWorld.js`, `server/src/world/chunkData.js`, `shared/definitions/mobs.js`, `shared/definitions/mobCombat.js`, `client/src/editor/tileConfigModal.js`, `client/assets/mobs/deer/`, `client/assets/mobs/rat/`, `client/assets/mobs/chicken/`
195
195
196## Mob definitions (content schema)
196## Mob definitions (content schema)
197
197
198**Status:** partial
198**Status:** partial
199**Spec:** Target mob content shape: `displayName`, `maxHealth`, `attackSkill`, `drops`, `sells`. **Dialogue trees** are world-scoped assets (Dialogues editor); humanoid spawners assign `config.dialogueId`. See [`docs/QUESTS.md`](QUESTS.md).
199**Spec:** Target mob content shape: `displayName`, `maxHealth`, `attackSkill`, `drops`, `sells`. Drops support `chance`, fixed `quantity`, or inclusive `quantityMin`/`quantityMax`. **Chicken** always drops **1–3 feathers** and has a **20%** chance of an **egg**. **Dialogue trees** are world-scoped assets (Dialogues editor); humanoid spawners assign `config.dialogueId`. See [`docs/QUESTS.md`](QUESTS.md).
200**Code:** `shared/definitions/mobs.js`, `shared/definitions/mobCombat.js`
200**Code:** `shared/definitions/mobs.js`, `shared/definitions/mobCombat.js`, `server/src/combat/service.js` (`rollDropQuantity`)
201
201
202## Quests
202## Quests
203
203
@@ -214,14 +214,14 @@ Each entry is a short note on behaviour and where the code lives. Update this fi
214## Combat resolution (rolls)
214## Combat resolution (rolls)
215
215
216**Status:** partial
216**Status:** partial
217**Spec:** Authoritative server rolls; clients only show outcomes. **Melee & ranged (physical):** roll hit skill vs defender **Dexterity (agility)** — miss if attack roll < agility roll, hit on tie or higher; on hit roll damage skill (Strength for melee, Dexterity for ranged) for `baseDamage + roll − 1`; on hit defender rolls Defence — **block** if defence roll > attacker's to-hit roll; otherwise apply damage. **Effective combat levels** add worn equipment tier bonuses to damage/agility/defence rolls (e.g. Strength 10 + bronze weapon +1 → damage roll uses 11). Hit skills (Club/Sword fighting, Archery) use base skill only. XP only on damage hits. **Attack types** (slashing / piercing / blunt) are defined on weapons; mob weak/resist multipliers remain later. **Magic:** roll Magic vs per-spell **difficulty** (contest, tie or higher succeeds); on success roll Mind for damage; multiply by elemental weak ×2 / neutral ×1 / resistant ×0.5; non-damage spells only need a successful cast roll then apply an effect. Spell defs in `shared/definitions/spells.js`. Full casting UI, LOS, and effect system remain later.
217**Spec:** Authoritative server rolls; clients only show outcomes. **Melee & ranged (physical):** roll hit skill vs defender **Dexterity (agility)** — miss if attack roll < agility roll, hit on tie or higher; on hit roll damage skill (Strength for melee, Dexterity for ranged) for `baseDamage + roll − 1`; on hit defender rolls Defence — **block** if defence roll > attacker's to-hit roll; otherwise apply damage. **Effective combat levels** add worn equipment tier bonuses to damage/agility/defence rolls (e.g. Strength 10 + bronze weapon +1 → damage roll uses 11). Hit skills (Club/Sword fighting, Archery) use base skill only. XP only on damage hits. **Attack types** (slashing / piercing / blunt) are defined on weapons; mob weak/resist multipliers remain later. **Magic:** roll Magic vs per-spell **difficulty** (contest, tie or higher succeeds); on success roll Mind for damage; multiply by elemental weak ×2 / neutral ×1 / resistant ×0.5; non-damage spells only need a successful cast roll then apply an effect. Spell defs + live cast/impact in `shared/definitions/spells.js` / `server/src/spells/` (starter Light + Spark). More spells and LOS polish remain later.
218**Code:** `shared/combat/rolls.js` (physical, live), `shared/combat/magic.js` (cast + damage rules, shared only), `shared/definitions/spells.js`, `shared/definitions/attackTypes.js`, `shared/equipment/stats.js`, `server/src/combat/service.js`, tests in `server/tests/combatRolls.test.js`, `server/tests/magic.test.js`, `server/tests/equipment.test.js`
218**Code:** `shared/combat/rolls.js`, `shared/combat/magic.js`, `shared/definitions/spells.js`, `shared/definitions/attackTypes.js`, `shared/equipment/stats.js`, `server/src/combat/service.js`, `server/src/spells/service.js`, tests in `server/tests/combatRolls.test.js`, `server/tests/magic.test.js`, `server/tests/spells.test.js`, `server/tests/equipment.test.js`
219
219
220## Combat, skills, groups, pigeons
220## Combat, skills, groups, pigeons
221
221
222**Status:** partial
222**Status:** partial (melee + ranged bows + starter spells live; groups later)
223**Spec:** Melee auto-attack with stick (Clubfighting + Strength), LMB/RMB targeting and context menu (including **Follow \<name\>** / **Attack \<name\>**), engage/retaliate, swipe VFX, shove animation, damage flash, HP bars above **mobs and players** when below max HP, and client dynamic-light hooks. Fightable mobs **retaliate on the first resolved swing** (hit or miss), not when Attack is merely clicked. **Players likewise auto-retaliate** when a mob’s first swing resolves against them (clears follow/gather). Melee requires Chebyshev distance 1 (**diagonals allowed**) while the attacker stands alone on their tile; if stacked with others they path to the nearest clear adjacent stance. Approach pathfinding may pass through entities but prefers clear goal tiles. **Aggressive** mobs (e.g. rats: `aggressive` + `aggroRangeTiles`, default 5) auto-engage player characters in Chebyshev range with line of sight through enterable tiles; passive wildlife (deer) does not. Engaged mobs keep pursuing if the player cancels attack. Physical combat uses skill rolls (see **Combat resolution**). **Health** skill sets max HP; taking damage awards Health XP equal to damage taken (lethal hits grant none). Reaching **0 HP** is player death (see **Player death and respawn**). Follow reuses the target's vacated trail and remaining path (stop one tile short, wait for vacancy, walkability each step); catch-up A* only when no shared trail yet. Break beyond one chunk width. **Carrier pigeons** dispatch money or one inventory stack to Bank or Player. **Skills:** persistent XP, 50 XP to level 2 then double each level, cap 99; Health starts at 10, others at 1; **login enforces those minima** (raises and persists under-leveled skills). Skills panel. Ranged combat, magic, groups, and non-combat skill XP (except Health from damage) remain later.
223**Spec:** Melee auto-attack with stick (Clubfighting + Strength), LMB/RMB targeting and context menu (including **Follow \<name\>** / **Attack \<name\>**), engage/retaliate, swipe VFX, shove animation, damage flash, HP bars above **mobs and players** when below max HP, and client dynamic-light hooks. Fightable mobs **retaliate on the first resolved swing** (hit or miss), not when Attack is merely clicked. **Players likewise auto-retaliate** when a mob’s first swing resolves against them (clears follow/gather). Melee requires Chebyshev distance 1 (**diagonals allowed**) while the attacker stands alone on their tile; if stacked with others they path to the nearest clear adjacent stance. Approach pathfinding may pass through entities but prefers clear goal tiles. **Aggressive** mobs (e.g. rats: `aggressive` + `aggroRangeTiles`, default 5) auto-engage player characters in Chebyshev range with line of sight through enterable tiles; passive wildlife (deer, chickens) does not. Engaged mobs keep pursuing if the player cancels attack. Physical combat uses skill rolls (see **Combat resolution**). **Ranged:** bow in weapon + arrows in offhand; Archery hit / Dexterity damage; arrow projectiles lerp toward the target’s **live client visual pose** (misses use a fixed fly-by tile). Server resolves the hit immediately; **HP bar / flash / damage numbers wait until the projectile lands** on each client. **Magic:** cast UI + Light/Spark; spell projectiles likewise track moving targets; spell impacts are delayed on the server to match travel time. **Health** skill sets max HP; taking damage awards Health XP equal to damage taken (lethal hits grant none). Reaching **0 HP** is player death (see **Player death and respawn**). Follow reuses the target's vacated trail and remaining path (stop one tile short, wait for vacancy, walkability each step); catch-up A* only when no shared trail yet. Break beyond one chunk width. **Carrier pigeons** dispatch money or one inventory stack to Bank or Player. **Skills:** persistent XP, 50 XP to level 2 then double each level, cap 99; Health starts at 10, others at 1; **login enforces those minima** (raises and persists under-leveled skills). Skills panel. Groups and broader non-combat skill XP remain later.
224**Code:** `shared/combat/rolls.js`, `shared/skills/progression.js`, `shared/skills/state.js`, `shared/definitions/skills.js`, `shared/definitions/mobCombat.js`, `shared/definitions/mobs.js`, `server/src/skills/service.js`, `server/src/combat/service.js`, `client/src/play/skills.js`, `client/src/render/worldView.js`, tests in `server/tests/combatRolls.test.js`, `server/tests/skills.test.js`, `server/tests/mobCombat.test.js` (+ combat/follow/courier tests)
224**Code:** `shared/combat/rolls.js`, `shared/skills/progression.js`, `shared/skills/state.js`, `shared/definitions/skills.js`, `shared/definitions/mobCombat.js`, `shared/definitions/mobs.js`, `shared/definitions/rangedItems.js`, `server/src/skills/service.js`, `server/src/combat/service.js`, `server/src/spells/service.js`, `client/src/play/skills.js`, `client/src/play/main.js`, `client/src/render/worldView.js`, tests in `server/tests/combatRolls.test.js`, `server/tests/skills.test.js`, `server/tests/mobCombat.test.js`, `server/tests/ranged.test.js` (+ combat/follow/courier/spells tests)
225
225
226## Player death and respawn
226## Player death and respawn
227
227
@@ -241,15 +241,15 @@ Each entry is a short note on behaviour and where the code lives. Update this fi
241
241
242**Status:** partial
242**Status:** partial
243**Spec:** Metal gear exists in seven material tiers (lowest → highest): **Bronze**, **Iron**, **Steel**, **Mithril**, **Adamantium**, **Orichalcum**, **Dragon**. Each has a **rank** (1–7), display **tint**, and equip min skill: 1 / 10 / 20 / 35 / 50 / 70 / 90. Mining a material requires **half** of that equip gate (ceil); smelting requires **75%** (ceil). **Worn combat bonuses** come from live world setting `equipmentStatBonuses` (editor **Equipment Stats** tab); defaults seed from `TIER_STAT_BONUS` (full helms +1 Defence). Leather armour can grant Agility and Defence independently; wizard armour Magic and Defence; clothing Defence. Magic casting uses worn Magic/Mind gear bonuses the same way physical combat uses Strength/Agility/Defence. Tools (pickaxes) gate on Mining and do not use the bonus tables. **Tin** and **copper** ores (no bronze ore) and **coal** use their associated bar tier for mine/smelt timing and gates (tin/copper → bronze, coal → steel). **Silver** and **Gold** are precious-only (ore + bars, no tools; silver mine/smelt like iron rank 2 / skill 10, gold like steel rank 3 / skill 20). **Wood tiers** (same gates/ranks): **Pine**, **Birch**, **Oak**, **Ebony**, **Lignum**, **Heartwood**, **Elder** (match metal ranks for hafts). **Cloth tiers** (same gates/ranks): **Cotton**, **Wool**, **Linen**, **Cashmere**, **Silk**, **Fairy silk**, **Dragonweave**. Logs/handles tint from shared `wood` sprites; **pine trees** are chopable resource nodes (more tree tiers later) — axe sprites (`items/axe`) match pickaxe style for woodcutting. Armour pieces share one set of overlays under `items/armour/` tinted per metal tier (no per-tier icon copies).
243**Spec:** Metal gear exists in seven material tiers (lowest → highest): **Bronze**, **Iron**, **Steel**, **Mithril**, **Adamantium**, **Orichalcum**, **Dragon**. Each has a **rank** (1–7), display **tint**, and equip min skill: 1 / 10 / 20 / 35 / 50 / 70 / 90. Mining a material requires **half** of that equip gate (ceil); smelting requires **75%** (ceil). **Worn combat bonuses** come from live world setting `equipmentStatBonuses` (editor **Equipment Stats** tab); defaults seed from `TIER_STAT_BONUS` (full helms +1 Defence). Leather armour can grant Agility and Defence independently; wizard armour Magic and Defence; clothing Defence. Magic casting uses worn Magic/Mind gear bonuses the same way physical combat uses Strength/Agility/Defence. Tools (pickaxes) gate on Mining and do not use the bonus tables. **Tin** and **copper** ores (no bronze ore) and **coal** use their associated bar tier for mine/smelt timing and gates (tin/copper → bronze, coal → steel). **Silver** and **Gold** are precious-only (ore + bars, no tools; silver mine/smelt like iron rank 2 / skill 10, gold like steel rank 3 / skill 20). **Wood tiers** (same gates/ranks): **Pine**, **Birch**, **Oak**, **Ebony**, **Lignum**, **Heartwood**, **Elder** (match metal ranks for hafts). **Cloth tiers** (same gates/ranks): **Cotton**, **Wool**, **Linen**, **Cashmere**, **Silk**, **Fairy silk**, **Dragonweave**. Logs/handles tint from shared `wood` sprites; **pine trees** are chopable resource nodes (more tree tiers later) — axe sprites (`items/axe`) match pickaxe style for woodcutting. Armour pieces share one set of overlays under `items/armour/` tinted per metal tier (no per-tier icon copies).
244**Shared sprites + magenta tint:** one base sprite per shape under `items/metal` (`ore`, `bar`), `items/pickaxe`, `items/axe` (`axe`, `axe-head`, `axe-equip`), `items/wood` (`log`, `handle`), `items/cloth` (`wool`, `yarn`, `cloth`), `items/clothing` (`shirt`, `shorts`, `skirt`, `trousers`, `sweater`), boulder-ore, and **tables** (`blocks/table/0`–`15`); tintable pixels use magenta rules in `shared/render/tint.js`. Boulder ore states are catalog aliases of `boulder-ore.png` with per-material tint. Table states are `${woodTier}-${mask}` aliases of mask PNGs with wood-tier tint; tables autotile only with the same wood. Trees use per-season live + **`-stump`** PNGs (mandatory for every tree type).
244**Shared sprites + magenta tint:** one base sprite per shape under `items/metal` (`ore`, `bar`), `items/pickaxe`, `items/axe` (`axe`, `axe-head`, `axe-equip`), `items/wood` (`log`, `handle`), `items/cloth` (`wool`, `yarn`, `cloth`), `items/clothing` (`shirt`, `shorts`, `skirt`, `trousers`, `sweater`), boulder-ore, and **tables** (`blocks/table/0`–`15`); tintable pixels use magenta rules in `shared/render/tint.js`. **Dual-channel tint** (red = shaft/wood, blue = tip/string; white unchanged): arrows, hafted tools, **bows** / unstrung bows under `items/bow/` (`bow`, `unstrung-bow`, `bowstring` magenta, `bow-equip`). Boulder ore states are catalog aliases of `boulder-ore.png` with per-material tint. Table states are `${woodTier}-${mask}` aliases of mask PNGs with wood-tier tint; tables autotile only with the same wood. Trees use per-season live + **`-stump`** PNGs (mandatory for every tree type).
245**TODO:** full combat gear catalog; more tree tiers / fishing / herbs; silver/gold jewelry / other precious recipes; cloth sources beyond cotton.
245**TODO:** full combat gear catalog; more tree tiers / fishing / herbs; silver/gold jewelry / other precious recipes; cloth sources beyond cotton.
246**Code:** `shared/definitions/materialTiers.js`, `shared/definitions/equipmentStatCategories.js`, `shared/render/tint.js`, `shared/definitions/metalItems.js`, `shared/definitions/woodItems.js`, `shared/equipment/stats.js`, tests in `server/tests/equipment.test.js`, `server/tests/mining.test.js`, `server/tests/tint.test.js`
246**Code:** `shared/definitions/materialTiers.js`, `shared/definitions/equipmentStatCategories.js`, `shared/render/tint.js`, `shared/definitions/metalItems.js`, `shared/definitions/woodItems.js`, `shared/definitions/rangedItems.js`, `shared/definitions/tierFamilies.js`, `shared/equipment/stats.js`, tests in `server/tests/equipment.test.js`, `server/tests/mining.test.js`, `server/tests/tint.test.js`, `server/tests/ranged.test.js`
247
247
248## Gathering, crafting, and production skills
248## Gathering, crafting, and production skills
249
249
250**Status:** partial (mining + smelting + pickaxe/axe craft chains + pine woodcutting + cotton/flower/herb herbalism live)
250**Status:** partial (mining + smelting + pickaxe/axe/bow craft chains + pine woodcutting + cotton/flower/herb herbalism live)
251**Spec:** **Mining:** LMB/RMB on ore boulder (states `tin-ore`, `copper-ore`, `iron-ore`, `silver-ore`, `gold-ore` … `dragon-ore`, `coal`). Uses the **best usable pickaxe in inventory** (or weapon slot) — tools need not be equipped. Tool rank ≥ associated bar rank and Mining ≥ mine gate; otherwise toast *"You need a pickaxe to mine this!"*. Duration `(rank×8s) − (toolRank×3s)` (min 0.5s). Attack shove animation, **no** swipe FX; while swinging, the gather tool's **equip sprite** is shown in the weapon overlay (even if a different weapon is equipped). Awards Mining XP (`rank×5`). On success the node becomes **exhausted** (plain `boulder` sprite, not mineable) for `10s × associated bar rank`, then restores its ore state via runtime `CHUNK_DELTA`. Hovering an active ore/tree/plant node shows a cursor tooltip (`resourceNodeDisplayName`). Outdoor blocks may also use **optional seasonal overlays** (e.g. boulder / ore `*-winter` only — other seasons keep the base sprite). **Woodcutting:** LMB/RMB / **Chop** on outdoor tree blocks (**pine** today). Best usable **axe** in inventory/weapon; Woodcutting + axe tier gates match mining (pine = rank 1). Same duration/exhaust curves. Success grants a **pine log**, stamps **`Felled by <name>`**, awards Woodcutting XP, and sets a **seasonal stump** (`summer-stump` / `fall-stump` / `winter-stump` — required for every tree type). Calendar season still drives stump look while exhausted; after exhaust the live tree returns. Tree / flower / herb **regrow** uses the four-way growth season (spring Mar–May, summer Jun–Aug, fall Sep–Nov, winter Dec–Feb): **summer & fall** keep base exhaust time, **winter** doubles it, **spring** is 25% faster (`×0.75`). **Herbalism (plants):** **Flower** nodes need **no tool** (~1s); each flower block carries a fixed colour tint (chosen on respawn / editor place) and picking yields that colour, stamps **`Picked by <name>`**. **Cotton plant** needs **no tool** (RMB Pick / LMB); yields cotton fibre. Both exhaust ~15s then respawn. **Smelting:** furnace block opens craft UI; duration `rank×2s` by output bar tier. Recipes 1 ore → 1 bar except **bronze** = 1 tin + 1 copper, **steel** = 1 iron ore + 1 coal, **adamantium** = 1 ore + 1 coal, **orichalcum** = 1 ore + 3 coal, **dragon** = 1 ore + 5 coal. Smithing XP on success. **Pickaxe / axe craft:** woodworking bench shapes 1 log → 1 handle; anvil smiths 1 bar → 1 pickaxe head or axe head; **crafting bench** assembles matching-tier handle + head → pickaxe or axe (pine↔bronze … elder↔dragon). Gold bars are smeltable but have no tool recipes. Server-authoritative `START_CRAFT` / timer. Play errors (mine gates, full bag, …) show as temporary **toasts** at the top of the screen. More tree tiers / fishing / other stations later.
251**Spec:** **Mining:** LMB/RMB on ore boulder (states `tin-ore`, `copper-ore`, `iron-ore`, `silver-ore`, `gold-ore` … `dragon-ore`, `coal`). Uses the **best usable pickaxe in inventory** (or weapon slot) — tools need not be equipped. Tool rank ≥ associated bar rank and Mining ≥ mine gate; otherwise toast *"You need a pickaxe to mine this!"*. Duration `(rank×8s) − (toolRank×3s)` (min 0.5s). Attack shove animation, **no** swipe FX; while swinging, the gather tool's **equip sprite** is shown in the weapon overlay (even if a different weapon is equipped). Awards Mining XP (`rank×5`). On success the node becomes **exhausted** (plain `boulder` sprite, not mineable) for `10s × associated bar rank`, then restores its ore state via runtime `CHUNK_DELTA`. Hovering an active ore/tree/plant node shows a cursor tooltip (`resourceNodeDisplayName`). Outdoor blocks may also use **optional seasonal overlays** (e.g. boulder / ore `*-winter` only — other seasons keep the base sprite). **Woodcutting:** LMB/RMB / **Chop** on outdoor tree blocks (**pine** today). Best usable **axe** in inventory/weapon; Woodcutting + axe tier gates match mining (pine = rank 1). Same duration/exhaust curves. Success grants a **pine log**, stamps **`Felled by <name>`**, awards Woodcutting XP, and sets a **seasonal stump** (`summer-stump` / `fall-stump` / `winter-stump` — required for every tree type). Calendar season still drives stump look while exhausted; after exhaust the live tree returns. Tree / flower / herb **regrow** uses the four-way growth season (spring Mar–May, summer Jun–Aug, fall Sep–Nov, winter Dec–Feb): **summer & fall** keep base exhaust time, **winter** doubles it, **spring** is 25% faster (`×0.75`). **Herbalism (plants):** **Flower** nodes need **no tool** (~1s); each flower block carries a fixed colour tint (chosen on respawn / editor place) and picking yields that colour, stamps **`Picked by <name>`**. **Cotton plant** needs **no tool** (RMB Pick / LMB); yields cotton fibre. Both exhaust ~15s then respawn. **Smelting:** furnace block opens craft UI; duration `rank×2s` by output bar tier. Recipes 1 ore → 1 bar except **bronze** = 1 tin + 1 copper, **steel** = 1 iron ore + 1 coal, **adamantium** = 1 ore + 1 coal, **orichalcum** = 1 ore + 3 coal, **dragon** = 1 ore + 5 coal. Smithing XP on success. **Pickaxe / axe craft:** woodworking bench shapes 1 log → 1 handle; anvil smiths 1 bar → 1 pickaxe head or axe head; **crafting bench** assembles matching-tier handle + head → pickaxe or axe (pine↔bronze … elder↔dragon). **Ranged craft:** woodworking → arrow shafts / unstrung bows; anvil → arrow tips; spinning wheel → bowstring from yarn; crafting bench → feather + shaft + tip → arrow, and unstrung bow + bowstring → bow (wood + matching cloth). Gold bars are smeltable but have no tool recipes. Server-authoritative `START_CRAFT` / timer; craft panel supports **Craft**, **Craft X**, and **Craft all** with a progress bar that restarts on each continuing batch step. Play errors (mine gates, full bag, …) show as temporary **toasts** at the top of the screen. More tree tiers / fishing / other stations later.
252**Code:** `shared/definitions/gathering.js`, `shared/definitions/tiles.js` (`resourceNodeDisplayName`, `isChopableTreeBlock`, `isPickablePlantBlock`), `shared/world/season.js` (`treeStumpStateForSeason`, `growthSeasonIdAt`, `scaleRegrowDurationMs`), `server/src/gathering/service.js`, `server/src/crafting/service.js`, `shared/crafting/stationRecipes.js`, `client/src/play/main.js`, `client/src/render/worldView.js` (`spawnGatherSwing`), tests in `server/tests/mining.test.js`, `server/tests/woodcutting.test.js`, `server/tests/crafting.test.js`, `server/tests/season.test.js`
252**Code:** `shared/definitions/gathering.js`, `shared/definitions/tiles.js` (`resourceNodeDisplayName`, `isChopableTreeBlock`, `isPickablePlantBlock`), `shared/definitions/rangedItems.js`, `shared/crafting/tierRecipes.js`, `shared/world/season.js` (`treeStumpStateForSeason`, `growthSeasonIdAt`, `scaleRegrowDurationMs`), `server/src/gathering/service.js`, `server/src/crafting/service.js`, `shared/crafting/stationRecipes.js`, `client/src/play/main.js`, `client/src/play/crafting.js`, `client/src/render/worldView.js` (`spawnGatherSwing`), tests in `server/tests/mining.test.js`, `server/tests/woodcutting.test.js`, `server/tests/crafting.test.js`, `server/tests/ranged.test.js`, `server/tests/season.test.js`
253
253
254## Cloth, dyes, and tailoring
254## Cloth, dyes, and tailoring
255
255
@@ -265,7 +265,7 @@ Each entry is a short note on behaviour and where the code lives. Update this fi
265## Crafting stations
265## Crafting stations
266
266
267**Status:** partial (furnace, anvil, woodworking, crafting, spinning wheel, loom, tailor bench live)
267**Status:** partial (furnace, anvil, woodworking, crafting, spinning wheel, loom, tailor bench live)
268**Spec:** Furnace / anvil / woodworking-bench / crafting-bench / spinning-wheel / loom / tailor-bench blocks + adjacency craft panel. Recipes in `stationRecipes.js`. Furnace/anvil/woodworking/crafting craft timer = `smeltingDurationMs` (`rank × 2s`) when `xpMaterial` is set; other stations still use `CRAFT_DURATION_MS` (2s) / UI/dev only (`__craftDev`). Woodworking shapes components (handles); crafting bench joins finished parts (pickaxe/axe head + handle). Spinning wheel / loom / tailor use Tailoring. **Anvil**, **woodworking**, and **tailor** craft UIs use a material dropdown so tier variants share one recipe cell (plant clippers = 1 bar per metal tier). **Hard rule (all stations + cauldron, player and scripts):** items in station slots are never committed out of the inventory — slots are a reservation/view over the bag (**client-side UI**; even if it looks like mats sit in the station, they do not). Server soft-tracks steps/claims only and consumes on successful craft/brew. Closing the UI, cancelling, or dying mid-craft/brew cannot destroy reserved mats. Station progress is **per player**, not tile-global. See `.cursor/rules/station-inventory.mdc`.
268**Spec:** Furnace / anvil / woodworking-bench / crafting-bench / spinning-wheel / loom / tailor-bench blocks + adjacency craft panel. Recipes in `stationRecipes.js`. Furnace/anvil/woodworking/crafting craft timer = `smeltingDurationMs` (`rank × 2s`) when `xpMaterial` is set; other stations still use `CRAFT_DURATION_MS` (2s) / UI/dev only (`__craftDev`). Woodworking shapes components (handles, shafts, unstrung bows); crafting bench joins finished parts (pickaxe/axe head + handle, arrows, strung bows). Spinning wheel / loom / tailor use Tailoring. **Anvil**, **woodworking**, **spinning wheel**, **loom**, and **tailor** craft UIs use a single-axis material dropdown so tier variants share one recipe cell. **Crafting bench** alone shows **paired metal/wood labels** (e.g. `Bronze/Pine`) because it mixes metal tools with wood bows on the same tier rank. **Hard rule (all stations + cauldron, player and scripts):** items in station slots are never committed out of the inventory — slots are a reservation/view over the bag (**client-side UI**; even if it looks like mats sit in the station, they do not). Server soft-tracks steps/claims only and consumes on successful craft/brew. Closing the UI, cancelling, or dying mid-craft/brew cannot destroy reserved mats. Station progress is **per player**, not tile-global. See `.cursor/rules/station-inventory.mdc`.
269**TODO:** oven/campfire burn; dedicated station sprites where still placeholder.
269**TODO:** oven/campfire burn; dedicated station sprites where still placeholder.
270**Code:** `shared/definitions/craftingStations.js`, `shared/definitions/tiles.js`, `server/src/crafting/service.js`, `client/src/play/crafting.js`
270**Code:** `shared/definitions/craftingStations.js`, `shared/definitions/tiles.js`, `server/src/crafting/service.js`, `client/src/play/crafting.js`
271
271
@@ -315,8 +315,8 @@ Use later when deciding which ingredients fit which potions. Tiers: **2 / 3 / 3
315## Inventory, items, equipment, ground drops
315## Inventory, items, equipment, ground drops
316
316
317**Status:** full
317**Status:** full
318**Spec:** 32-slot inventory, stacking, equipment slots (head, chest, legs, boots, weapon, **offhand** for shields) with a separate `equipSprite` overlay on the body, carried currency, player drops that last `groundItemDespawnDurationMs` (default 10 minutes). Pickup requires standing on the tile. Inventory is private UI state; nearby clients see ground items and worn overlays. New characters start with paper, apples, a stick, a cloth shirt, and coins. Placeholder item/equipment PNGs until real art exists. Right-click bag items for Send / Equip / Drop / Eat (food); paper can be written into unique **letter** instances (signed on Save; only the signer may edit). Equipping always takes **one** item from a stack (never the whole stack); unequipping returns one item and merges into an existing compatible inventory stack when stack rules allow. Equip enforces tier min-skill gates. Eating food heals (see Health skill).
318**Spec:** 32-slot inventory, stacking, equipment slots (head, chest, legs, boots, weapon, **offhand** for shields/arrows) with a separate `equipSprite` overlay on the body, carried currency, player drops that last `groundItemDespawnDurationMs` (default 10 minutes). Pickup requires standing on the tile. Inventory is private UI state; nearby clients see ground items and worn overlays. **Equip draw order (back → front):** boots → chest → weapon → legs → hair (if visible) → head → offhand — so weapons sit above the shirt but under trousers/skirts (legs may cover shirt hem; art should avoid bad waist overlap). New characters receive world **Starter Equipment** / inventory, then creation clothing dyes on top (see **Characters**). Right-click bag items for Send / Equip / Drop / Eat (food; apples, eggs, …); paper can be written into unique **letter** instances (signed on Save; only the signer may edit). Equipping always takes **one** item from a stack (never the whole stack); unequipping returns one item and merges into an existing compatible inventory stack when stack rules allow. Equip enforces tier min-skill gates. Eating food heals (see Health skill).
319**Code:** `shared/definitions/items.js`, `shared/items/inventory.js`, `server/src/items/bags.js`, `client/src/play/inventory.js`
319**Code:** `shared/definitions/items.js` (`EQUIPMENT_DRAW_ORDER`), `shared/appearance/hair.js` (`composeAppearanceLayers`), `shared/items/inventory.js`, `server/src/items/bags.js`, `client/src/play/inventory.js`
320
320
321## Proximity chat
321## Proximity chat
322
322
docs/SCRIPTS.md +1 −1
@@ -299,7 +299,7 @@ Implementation: share the same validation path as the real command; skip the mut
299 299
300 300 | Statement | Meaning |
301 301 |-----------|---------|
302 | `attack` | Attack the targeted mob (player Attack intent). Does **not** wait for the kill by itself — use `wait until target dead or 60` (§6.13). |
302 | `attack` | Attack the targeted mob (player Attack intent). Uses the equipped weapon’s mode (**melee** or **ranged** bow + offhand arrows). Does **not** wait for the kill by itself — use `wait until target dead or 60` (§6.13). |
303 303 | `stop attack` | Cancel the current attack engage (player cancel-attack). |
304 304 | `buy "Feather" 10` | Buy quantity from targeted shop mob. Fails if no shop, not in range, can’t afford, or not stocked. |
305 305 | `sell "Soft leather" 5` | Sell quantity to targeted shop mob (if it buys). |
@@ -299,7 +299,7 @@ Implementation: share the same validation path as the real command; skip the mut
299
299
300| Statement | Meaning |
300| Statement | Meaning |
301|-----------|---------|
301|-----------|---------|
302| `attack` | Attack the targeted mob (player Attack intent). Does **not** wait for the kill by itself — use `wait until target dead or 60` (§6.13). |
302| `attack` | Attack the targeted mob (player Attack intent). Uses the equipped weapon’s mode (**melee** or **ranged** bow + offhand arrows). Does **not** wait for the kill by itself — use `wait until target dead or 60` (§6.13). |
303| `stop attack` | Cancel the current attack engage (player cancel-attack). |
303| `stop attack` | Cancel the current attack engage (player cancel-attack). |
304| `buy "Feather" 10` | Buy quantity from targeted shop mob. Fails if no shop, not in range, can’t afford, or not stocked. |
304| `buy "Feather" 10` | Buy quantity from targeted shop mob. Fails if no shop, not in range, can’t afford, or not stocked. |
305| `sell "Soft leather" 5` | Sell quantity to targeted shop mob (if it buys). |
305| `sell "Soft leather" 5` | Sell quantity to targeted shop mob (if it buys). |
tile_mmo_server_technical_design_v0.6.md +10 −7
@@ -1689,15 +1689,18 @@ Overlays are not baked into the body art.
1689 1689 draw order (back → front, default)
1690 1690 1. body / mob base
1691 1691 2. boots
1692 3. legs
1693 4. chest
1694 5. head
1695 6. off-hand
1696 7. weapon
1692 3. chest
1693 4. weapon
1694 5. legs
1695 6. hair (if visible; inserted before headgear)
1696 7. head
1697 8. off-hand
1697 1698 ```
1698 1699
1699 Slot draw order is data so a cloak or a two-handed sprite can be inserted
1700 without a renderer rewrite. Overlay sprites use the same automatic pivot
1700 Slot draw order is data (`EQUIPMENT_DRAW_ORDER`) so a cloak or a two-handed sprite can be inserted
1701 without a renderer rewrite. Weapon sits above chest and under legs so bows/weapons
1702 read between shirt and trousers; clothing art should avoid bad waist overlap.
1703 Overlay sprites use the same automatic pivot
1701 1704 as other world art (horizontal centre, 8 pixels from the bottom).
1702 1705
1703 1706 Equipment items stay in dedicated **equipment slots**, not in the 32
@@ -1689,15 +1689,18 @@ Overlays are not baked into the body art.
1689draw order (back → front, default)
1689draw order (back → front, default)
1690 1. body / mob base
1690 1. body / mob base
1691 2. boots
1691 2. boots
1692 3. legs
1692 3. chest
1693 4. chest
1693 4. weapon
1694 5. head
1694 5. legs
1695 6. off-hand
1695 6. hair (if visible; inserted before headgear)
1696 7. weapon
1696 7. head
1697 8. off-hand
1697```
1698```
1698
1699
1699Slot draw order is data so a cloak or a two-handed sprite can be inserted
1700Slot draw order is data (`EQUIPMENT_DRAW_ORDER`) so a cloak or a two-handed sprite can be inserted
1700without a renderer rewrite. Overlay sprites use the same automatic pivot
1701without a renderer rewrite. Weapon sits above chest and under legs so bows/weapons
1702read between shirt and trousers; clothing art should avoid bad waist overlap.
1703Overlay sprites use the same automatic pivot
1701as other world art (horizontal centre, 8 pixels from the bottom).
1704as other world art (horizontal centre, 8 pixels from the bottom).
1702
1705
1703Equipment items stay in dedicated **equipment slots**, not in the 32
1706Equipment items stay in dedicated **equipment slots**, not in the 32