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

docs: update CLAUDE.md and README.md to reflect current project state

Browse Source 
Fix stale values (test count, cooldown constants, system execution order),
add missing subsystems (LLM, desires, pickup, invention, persistence),
and document newer features (thirst, productivity, day/night cycle,
industry/crafting, LLM configuration).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
root
2026-03-12 01:01:44 +00:00
parent 5b29549115
commit 513d35e0e5
2 changed files with 109 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
CLAUDE.md
View File

@@ -8,6 +8,9 @@ Multiplayer NPC simulation game (Dwarf Fortress-inspired). Server-authoritative
- `shared/` -- Types and constants (no runtime code)
- `server/` -- Node.js + Socket.io game server with ECS
- `server/src/llm/` -- LLM integration (backstory, narration, invention, thought generation)
- `server/src/services/` -- Runtime services (logging)
- `server/src/config/` -- Config and tuning values (relationship, industry, runtime constants)
- `client/` -- Phaser 3 + TypeScript renderer
- `chars/` -- Character sprite assets (do not modify)
- `saves/` -- SQLite save files (gitignored, one .db per region)
@@ -18,7 +21,7 @@ Multiplayer NPC simulation game (Dwarf Fortress-inspired). Server-authoritative
- `npm install` -- install all workspace dependencies
- `npm -w server run dev` -- start server (port 3001), loads existing save or creates new world
- `npm -w server run dev -- --new-world` -- start server with fresh world (overwrites save)
- `npm -w server run test` -- run server tests (408 tests)
- `npm -w server run test` -- run server 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
@@ -33,35 +36,62 @@ Multiplayer NPC simulation game (Dwarf Fortress-inspired). Server-authoritative
## Key Entry Points
**Core:**
- `server/src/main.ts` -- server startup, --new-world flag, graceful shutdown (SIGINT/SIGTERM)
- `server/src/game/GameLoop.ts` -- tick loop orchestration, save/load integration
- `shared/src/types.ts` -- protocol types
- `shared/src/constants.ts` -- game constants (incl. portrait slots, folder mapping)
**Persistence:**
- `server/src/persistence/database.ts` -- SQLite connection, schema creation, migration runner
- `server/src/persistence/saveManager.ts` -- orchestrates periodic saves, shutdown saves, load-on-startup
- `server/src/persistence/worldSerializer.ts` -- save/load map tiles and metadata
- `server/src/persistence/entitySerializer.ts` -- save/load entities, components, relationships, bonds
- `server/src/persistence/eventSerializer.ts` -- save/load narration, memory, stockpile, invention events
**Spawner:**
- `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
**Stats & Social:**
- `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
- `server/src/systems/relationshipSystem.ts` -- relationship delta calculation and despawn handling
- `server/src/systems/relationshipHelpers.ts` -- classify, getPartnerCap, getFriendCap, getEffectiveClassification
- `server/src/systems/bondRegistry.ts` -- mutual bond tracking between NPCs
- `server/src/config/relationshipConfig.ts` -- tuning values for relationship system (config-driven)
**Industry & Crafting:**
- `server/src/systems/industrySystem.ts` -- craft/build/gather decision tree
- `server/src/systems/craftingSystem.ts` -- input consumption, timer, output production
- `server/src/systems/buildingSystem.ts` -- structure creation with build progress
- `server/src/systems/dropoffSystem.ts` -- stockpile item deposit
- `server/src/systems/pickupSystem.ts` -- stockpile item retrieval for crafting
- `server/src/industry/recipeRegistry.ts` -- recipe registry with seed recipes
- `server/src/config/industryConfig.ts` -- tuning values for gathering, crafting, building
**LLM & AI:**
- `server/src/llm/llmService.ts` -- LLM client abstraction and request queuing
- `server/src/llm/backstoryGenerator.ts` -- NPC backstory and desire generation
- `server/src/llm/narrationService.ts` -- narration text generation
- `server/src/llm/eventMemoryService.ts` -- event memory management for LLM context
- `server/src/systems/inventionSystem.ts` -- LLM-driven recipe invention
- `server/src/systems/thoughtSystem.ts` -- NPC thought generation for followed entities
- `server/src/systems/desireGeneratorSystem.ts` -- LLM-driven desire generation
- `server/src/systems/desireFulfillmentSystem.ts` -- desire progress tracking and completion
**Config & Services:**
- `server/src/config/runtimeConstants.ts` -- runtime-adjustable game constants
- `server/src/services/logService.ts` -- structured logging service
**Client:**
- `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
- `client/src/sprites/PortraitCompositor.ts` -- portrait layer compositing (data URL output)
- `client/src/ui/NpcInfoPanel.ts` -- follow-mode NPC info panel (HTML/CSS overlay)
- `shared/src/types.ts` -- protocol types
- `shared/src/constants.ts` -- game constants (incl. portrait slots, folder mapping)
## Key Conventions
@@ -73,7 +103,7 @@ 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: statModifier -> needsDecay -> npcBrain -> social -> narration -> relationship -> industry -> gathering -> crafting -> building -> dropoff -> movement -> thought
- Systems run in order: statModifier -> needsDecay -> npcBrain -> social -> relationship -> desireFulfillment -> desireGenerator -> industry -> pickup -> gathering -> crafting -> building -> dropoff -> movement -> thought -> invention
- 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

80
README.md
View File

@@ -1,6 +1,6 @@
# DFlike
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.
A multiplayer browser game inspired by Dwarf Fortress. Watch autonomous NPCs with needs-driven AI wander, eat, drink, rest, forage, craft, and build in a shared world. Each NPC has unique stats (physical and personality) that influence their behavior, needs, and social interactions. NPCs form asymmetric relationships, invent new recipes via LLM-driven "eureka" moments, and develop backstories and thoughts. Connect as an observer or take control of an avatar.
## Architecture
@@ -12,8 +12,13 @@ A multiplayer browser game inspired by Dwarf Fortress. Watch autonomous NPCs wit
dflike/
shared/ -- Types and constants (no runtime code)
server/ -- Node.js + Socket.io game server with ECS
src/llm/ -- LLM integration (backstory, narration, invention, thoughts)
src/systems/ -- ECS systems (brain, social, industry, crafting, etc.)
src/config/ -- Tuning values (relationship, industry, runtime constants)
src/persistence/ -- SQLite save/load
client/ -- Phaser 3 + TypeScript renderer
chars/ -- Character sprite assets
saves/ -- SQLite save files (gitignored)
docs/ -- Design and implementation docs
```
@@ -30,6 +35,9 @@ npm install
# Copy character assets into the client public directory
cp -r chars client/public/assets/
# (Optional) Set up LLM features — see "LLM Configuration" section below
cp server/.env.example server/.env
# Terminal 1: Start server (port 3001)
npm -w server run dev
@@ -39,18 +47,38 @@ npm -w client run dev
Open http://localhost:3000. Open multiple tabs for multiplayer.
## LLM Configuration (Optional)
NPC backstories, thoughts, narration, and recipe invention are powered by LLM via [OpenRouter](https://openrouter.ai). These features degrade gracefully when no API key is set.
Copy the example env file and add your key:
```bash
cp server/.env.example server/.env
# Edit server/.env with your OpenRouter API key
```
| Variable | Default | Purpose |
|----------|---------|---------|
| `OPENROUTER_API_KEY` | _(none)_ | OpenRouter API key ([get one here](https://openrouter.ai/keys)) |
| `LLM_MODEL` | `arcee-ai/trinity-large-preview:free` | Primary model (free tier) |
| `LLM_FALLBACK_MODEL` | _(none)_ | Optional fallback on rate limit (HTTP 429) |
When the primary model is rate-limited, the system automatically switches to the fallback model (if configured) and reverts at the next UTC midnight.
## Controls
- **WASD / Arrow Keys** -- pan camera (camera mode), move avatar (avatar mode), or cycle NPCs (follow mode)
- **TAB** -- toggle between camera, avatar, and follow modes
- **1** -- toggle NPC highlight in follow mode
### Follow Mode
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, Socializing, Idle)
- Live-updating needs bars (Hunger, Energy) with color-coded fill levels
- Current activity (Wandering, Eating, Drinking, Sleeping, Foraging, Gathering, Crafting, Building, Idle)
- Live-updating needs bars (Hunger, Thirst, Energy, Productivity) with color-coded fill levels
- NPC stats in a two-column grid (STR, DEX, CON, INT, PER / SOC, COU, CUR, EMP, TMP)
- **Relations tab** showing relationships grouped by tier with slider visualization
@@ -312,6 +340,33 @@ NPCs form relationships through social interactions. Each relationship is tracke
All relationship tuning values are config-driven in `server/src/config/relationshipConfig.ts`, designed for future admin UI integration.
## Industry & Crafting
NPCs autonomously gather resources, craft items, and build structures.
**Workflow:** gather raw materials -> craft tools/items -> build structures -> deposit items at stockpiles
- **Gathering** -- NPCs forage for raw materials (wood, stone, berries) from map tiles
- **Crafting** -- Consumes input items, produces output items (40 tick base, modified by dexterity)
- **Building** -- Creates structure entities with build progress 0->1 (stockpiles, workbenches)
- **Dropoff/Pickup** -- NPCs deposit crafted items at stockpiles and retrieve materials for crafting
**Seed recipes:** `craft_wooden_axe`, `craft_hammer`, `build_stockpile`, `build_workbench`
**LLM Inventions:** NPCs with high intelligence and curiosity can have "eureka" moments, where the LLM generates novel recipes based on available materials and existing knowledge. Inventions are persisted and shared across all NPCs.
## Persistence
World state is saved to SQLite (`saves/default.db`) via better-sqlite3.
- **Event data** (narration, memory, stockpile, inventions) written to DB immediately on occurrence
- **Entity state** (NPCs, structures, relationships, bonds) batch-saved every 30 seconds
- **Graceful shutdown** (Ctrl-C) triggers a final save before exit
- **On startup**, loads from existing save or generates fresh world; `--new-world` flag forces fresh
- **Schema versioning** via `schema_version` in metadata table with migration runner
Transient state (movement paths, active interactions, goals) resets on load; NPCs resume from idle.
## Game Constants
All tunable game constants live in `shared/src/constants.ts`:
@@ -323,12 +378,27 @@ All tunable game constants live in `shared/src/constants.ts`:
| `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 |
| `THIRST_DECAY_PER_TICK` | 0.05 | Thirst drain rate |
| `ENERGY_DECAY_PER_TICK` | 0.03 | Energy drain rate |
| `PRODUCTIVITY_DECAY_PER_TICK` | 0.02 | Productivity drain rate |
| `HUNGER_THRESHOLD` | 30 | Below this, NPC seeks food |
| `THIRST_THRESHOLD` | 30 | Below this, NPC seeks water |
| `ENERGY_THRESHOLD` | 20 | Below this, NPC seeks rest |
| `PRODUCTIVITY_THRESHOLD` | 40 | Below this, NPC seeks productive work |
| `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 |
| `SOCIAL_GLOBAL_COOLDOWN` | 75 | Ticks between social interactions |
| `SOCIAL_PAIR_COOLDOWN` | 450 | Ticks before same pair can interact again |
**Day/Night Cycle:**
| Constant | Default | Purpose |
|----------|---------|---------|
| `DAY_HOURS` | 12 | Length of daytime |
| `NIGHT_HOURS` | 6 | Length of nighttime |
| `DAY_NIGHT_RATIO` | 2 | Day-to-night ratio |
| `SLEEP_WAKE_THRESHOLD` | 85 | Energy level at which sleeping NPCs wake |
| `SLEEP_VOLUNTARY_ENERGY_THRESHOLD` | 60 | Energy below which NPCs voluntarily sleep at night |
| `NAP_BUFFER` | 15 | Extra energy margin for daytime nap decisions |
## Development Commands