From 458fd9949512260d23ab435103cb893c948b804d Mon Sep 17 00:00:00 2001 From: root Date: Sat, 7 Mar 2026 14:49:02 +0000 Subject: [PATCH] docs: update CLAUDE.md and README.md for NPC stats system - Fix stale test count (29 -> 86) and system order in CLAUDE.md - Add new key entry points for stat system files - Add shared build command - Document stat conventions (3d6, modifiers, drift, wire protocol) - Add NPC Stats section to README with stat descriptions and effects - Add Game Constants table pointing to shared/src/constants.ts - Update follow mode description with stats display Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 15 ++++++++++++--- README.md | 44 ++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 54 insertions(+), 5 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 76a43f6..007bd0c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -16,10 +16,11 @@ Multiplayer NPC simulation game (Dwarf Fortress-inspired). Server-authoritative - `npm install` -- install all workspace dependencies - `npm -w server run dev` -- start server (port 3001) -- `npm -w server run test` -- run server tests (29 tests) +- `npm -w server run test` -- run server tests (86 tests) - `npm -w server run test:watch` -- run server tests in watch mode - `npm -w client run dev` -- start client dev server (port 3000) - `npm -w client run build` -- build client for production +- `npx -w shared tsc` -- rebuild shared types (required after modifying shared/src/) ## Tooling @@ -34,6 +35,10 @@ Multiplayer NPC simulation game (Dwarf Fortress-inspired). Server-authoritative - `server/src/game/GameLoop.ts` -- tick loop orchestration - `server/src/spawner/appearanceGenerator.ts` -- NPC appearance + portrait feature generation - `server/src/spawner/nameGenerator.ts` -- NPC name generation +- `server/src/spawner/statGenerator.ts` -- 3d6 stat generation for NPCs +- `server/src/systems/statHelpers.ts` -- getEffectiveStat (base + modifiers, clamped 3-18) +- `server/src/systems/statModifierSystem.ts` -- modifier decay and needs-based modifiers +- `server/src/systems/socialSystem.ts` -- NPC social interaction phases and stat integration - `client/src/main.ts` -- Phaser game bootstrap - `client/src/scenes/GameScene.ts` -- main game scene (camera/avatar/follow modes) - `client/src/sprites/CharacterCompositor.ts` -- sprite layer compositing @@ -52,5 +57,9 @@ Multiplayer NPC simulation game (Dwarf Fortress-inspired). Server-authoritative - Portrait assets are in `chars/baseman/accessories/portraits/` organized by skin folder (skin01-07) - Sprite skin `shape00_skinXX` maps to portrait folder `skin{XX+1}`, base file `skin{XX}.png` - Shared types ensure client/server protocol agreement -- Systems run in order: needsDecay -> npcBrain -> movement -> broadcast -- Follow mode shows EarthBound-styled NPC info panel with live-updating needs bars +- Systems run in order: statModifier -> needsDecay -> npcBrain -> social -> movement -> broadcast +- Follow mode shows EarthBound-styled NPC info panel with live-updating needs bars and stats +- NPC stats use 3d6 generation (range 3-18, bell curve): 5 physical (STR/DEX/CON/INT/PER) + 5 personality (SOC/COU/CUR/EMP/TMP) +- Stats have transient modifiers (needs-based permanent + event-based decaying); effective value = base + modifiers, clamped 3-18 +- Base stats are floats (drift slowly from experience); `getEffectiveStat` floors to int for gameplay use +- Wire protocol sends effective (computed) stats only; modifiers stay server-side diff --git a/README.md b/README.md index 4560eab..1c6aa75 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # DFlike -A multiplayer browser game inspired by Dwarf Fortress. Watch autonomous NPCs with needs-driven AI wander, eat, and rest in a shared world. Connect as an observer or take control of an avatar. +A multiplayer browser game inspired by Dwarf Fortress. Watch autonomous NPCs with needs-driven AI wander, eat, rest, and socialize in a shared world. Each NPC has unique stats (physical and personality) that influence their behavior, needs, and social interactions. Connect as an observer or take control of an avatar. ## Architecture @@ -49,8 +49,9 @@ Open http://localhost:3000. Open multiple tabs for multiplayer. In follow mode, the camera tracks an NPC and a panel slides in from the right showing: - Composited character portrait (layered from skin + accessories + facial features) - NPC name (randomly generated fantasy names) -- Current activity (Wandering, Eating, Resting, Idle) +- Current activity (Wandering, Eating, Resting, Socializing, Idle) - Live-updating needs bars (Hunger, Energy) with color-coded fill levels +- NPC stats in a two-column grid (STR, DEX, CON, INT, PER / SOC, COU, CUR, EMP, TMP) The panel uses an EarthBound/SNES RPG-inspired aesthetic with doubled borders, pixel font, and smooth slide transitions. @@ -258,6 +259,44 @@ VITE_SERVER_URL=https://game.example.com | Client (dev) | 3000 | TCP | | Client (prod) | 80 | TCP | +## NPC Stats + +Each NPC is generated with 10 stats using 3d6 rolls (range 3-18, bell curve centered at ~10.5): + +| Physical | Personality | +|----------|-------------| +| **Strength** -- physical tasks | **Sociability** -- social initiation, cooldown | +| **Dexterity** -- movement, precision | **Courage** -- exploration, threat response | +| **Constitution** -- needs decay rate | **Curiosity** -- wander variety, distance | +| **Intelligence** -- learning/drift rate | **Empathy** -- social outcome bias | +| **Perception** -- awareness radius | **Temperament** -- emotional stability | + +Stats influence gameplay systems: +- **Constitution** scales hunger/energy decay rates +- **Perception** extends or shrinks the social awareness radius +- **Sociability** reduces social interaction cooldowns +- **Empathy** biases social interactions toward positive outcomes + +Stats also have **transient modifiers** (e.g., low hunger debuffs Intelligence) and **baseline drift** (tiny permanent shifts from experience over time). + +## Game Constants + +All tunable game constants live in `shared/src/constants.ts`: + +| Constant | Default | Purpose | +|----------|---------|---------| +| `MAX_NPC_COUNT` | 50 | Maximum NPCs in the world | +| `TICK_RATE` | 10 | Server ticks per second | +| `WORLD_WIDTH` / `WORLD_HEIGHT` | 64 | World size in tiles | +| `MOVE_SPEED` | 0.75 | NPC movement speed (tiles/tick) | +| `HUNGER_DECAY_PER_TICK` | 0.05 | Hunger drain rate | +| `ENERGY_DECAY_PER_TICK` | 0.03 | Energy drain rate | +| `HUNGER_THRESHOLD` | 30 | Below this, NPC seeks food | +| `ENERGY_THRESHOLD` | 20 | Below this, NPC seeks rest | +| `AWARENESS_RADIUS` | 5 | Base social detection range (tiles) | +| `SOCIAL_GLOBAL_COOLDOWN` | 50 | Ticks between social interactions | +| `SOCIAL_PAIR_COOLDOWN` | 300 | Ticks before same pair can interact again | + ## Development Commands | Command | Description | @@ -269,3 +308,4 @@ VITE_SERVER_URL=https://game.example.com | `npm -w server run test:watch` | Run server tests in watch mode | | `npm -w client run dev` | Start client dev server | | `npm -w client run build` | Build client for production | +| `npx -w shared tsc` | Rebuild shared types |