andy/dflike
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update CLAUDE.md and README.md for NPC stats system

Browse Source 
- 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 <noreply@anthropic.com>
This commit is contained in:
root
2026-03-07 14:49:02 +00:00
parent 7d196524d6
commit 458fd99495
2 changed files with 54 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+12 -3
View File
@@ -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
README.md
+42 -2
View File
@@ -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 |