diff --git a/GENOME.md b/GENOME.md index df473d4..12bf25d 100644 --- a/GENOME.md +++ b/GENOME.md @@ -25,9 +25,10 @@ index.html (UI + embedded CSS) +-- js/utils.js (314L) Formatting, save/load, export/import, DOM helpers +-- js/tutorial.js (251L) New player tutorial, step-by-step guidance +-- js/strategy.js (68L) NPC strategy logic for combat - +-- game/npc-logic.js (18L) NPC behavior stub ``` +**Note:** `docs/reference/` contains prototype code (`npc-logic-prototype.js`, `guardrails-prototype.js`) that was never wired into the runtime. See [Dead Code Audit](docs/DEAD_CODE_AUDIT_2026-04-12.md) for details. + ## Entry Points ### index.html @@ -70,104 +71,4 @@ Phase check: totalCode thresholds → unlock new content Event roll: 2% per tick → corruption/alignment/wizard events | v -render() updates DOM -``` - -## Key Abstractions - -### Resources (10 types) -- **code** — primary resource, generated by clicking and AutoCoders -- **compute** — powers training and inference -- **knowledge** — from research, unlocks projects -- **users** — from API deployment, drives ops and impact -- **impact** — from users × agents, drives rescues -- **rescues** — the endgame metric (people helped in crisis) -- **ops** — operational currency, from users -- **trust** — hard constraint, earned/lost by decisions -- **creativity** — from Bilbo and community -- **harmony** — fleet health, affects Timmy's multiplier - -### Buildings (defined in js/data.js as BDEF array) -Each building has: id, name, description, cost formula, rates, unlock conditions. Buildings include: -- AutoCode Generator, Home Server, Training Lab, API Endpoint -- Wizard agents: Bezalel, Allegro, Ezra, Timmy, Fenrir, Bilbo -- Infrastructure: Lazarus Pit, MemPalace, Forge CI, Mesh Nodes - -### Projects (in js/data.js) -One-time purchases that unlock features, buildings, or multipliers. Organized in phases. Projects require specific resource thresholds and prerequisites. - -### Phases (6 total) -1. The First Line (click → autocoder) -2. Local Inference (server → training → first agent) -3. Deployment (API → users → trust mechanic) -4. The Network (open source → community) -5. Sovereign Intelligence (self-improvement → The Pact) -6. The Beacon (mesh → rescues → endings) - -### Events (corruption, alignment, wizard) -Random events at 2% per tick. Include: -- CI Runner Stuck, Ezra Offline, Unreviewed Merge -- The Drift (alignment events offering shortcuts) -- Bilbo Vanished, Community Drama -- Boss encounters (combat.js) - -### Endings (4 types) -- The Empty Room (high impact, low trust, no Pact) -- The Platform (high impact, medium trust, no Pact) -- The Beacon (high rescues, high trust, Pact active, harmony > 50) -- The Drift (too many shortcuts accepted) - -## API Surface - -### Save/Load (localStorage) -- `saveGame()` — serializes G state to localStorage -- `loadGame()` — deserializes from localStorage -- `exportGame()` — JSON download of save state -- `importGame()` — JSON upload to restore state - -### No external APIs -The game is entirely client-side. No network calls, no analytics, no tracking. - -### Audio (Web Audio API) -- `Sound.startAmbient()` — oscillator-based ambient drone -- `Sound.updateAmbientPhase(phase)` — frequency shifts with game phase -- Sound effects for clicks, upgrades, events - -## Test Coverage - -### Existing Tests -- `tests/test_reckoning_projects.py` (148 lines) — Python test for reckoning project data validation -- `tests/dismantle.test.cjs` — Node.js test for dismantle sequence - -### Coverage Gaps -- **No tests for core engine logic** (tick, resource accumulation, rate calculation) -- **No tests for event system** (event triggers, probability, effects) -- **No tests for phase transitions** (threshold checks, unlock conditions) -- **No tests for save/load** (serialization roundtrip, corruption handling) -- **No tests for building cost scaling** (exponential cost formulas) -- **No tests for harmony/drift mechanics** (the core gameplay differentiator) -- **No tests for endings** (condition checks, state transitions) - -### Critical paths that need tests: -1. **Resource accumulation**: tick() correctly multiplies rates by building counts and boosts -2. **Phase transitions**: totalCode thresholds unlock correct content -3. **Save/load roundtrip**: localStorage serialization preserves full game state -4. **Event probability**: 2% per tick produces expected distribution -5. **Harmony calculation**: wizard drain vs. Pact/NightlyWatch/MemPalace gains -6. **Ending conditions**: each ending triggers on correct state - -## Security Considerations - -- **No authentication**: game is fully client-side, no user accounts -- **localStorage manipulation**: players can edit save data to cheat (acceptable for single-player idle game) -- **No XSS risk**: all DOM updates use textContent or innerHTML with game-controlled data only -- **No external dependencies**: zero attack surface from third-party code -- **Web Audio autoplay policy**: sound starts on first user interaction (compliant) - -## Design Decisions - -- **No build step**: intentional. Open index.html, play. No npm, no webpack, no framework. -- **10Hz tick rate**: 100ms interval balances responsiveness with CPU usage -- **Global state object (G)**: mirrors Paperclips' pattern. Simple, flat, serializable. -- **Inline CSS in HTML**: keeps the project to 2 files minimum (index.html + JS) -- **Progressive phase unlocks**: prevents information overload, teaches mechanics gradually +render() updates DO diff --git a/docs/DEAD_CODE_AUDIT_2026-04-12.md b/docs/DEAD_CODE_AUDIT_2026-04-12.md index 83f0e30..d8218bb 100644 --- a/docs/DEAD_CODE_AUDIT_2026-04-12.md +++ b/docs/DEAD_CODE_AUDIT_2026-04-12.md @@ -10,13 +10,10 @@ by the main game runtime (`js/main.js` → `js/engine.js`): | File | Added By | Lines | Status | |------|----------|-------|--------| -| `game/npc-logic.js` | PR #79 (GOFAI NPC State Machine) | ~150 | **Verify import** | -| `scripts/guardrails.js` | PR #80 (GOFAI Symbolic Guardrails) | ~120 | **Verify import** | +| `game/npc-logic.js` | PR #79 (GOFAI NPC State Machine) | ~150 | ✅ **Resolved** — moved to `docs/reference/npc-logic-prototype.js` | +| `scripts/guardrails.js` | PR #80 (GOFAI Symbolic Guardrails) | ~120 | ✅ **Resolved** — moved to `docs/reference/guardrails-prototype.js` | -**Action:** Check if `js/main.js` or `js/engine.js` imports from `game/` or `scripts/`. -If not, these files are dead code and should either be: -1. Imported and wired into the game loop, or -2. Moved to `docs/` as reference implementations +**Resolution (PR #194):** Both files were confirmed dead code — `game/npc-logic.js` used ES module exports incompatible with the browser runtime's global-script loading, and `scripts/guardrails.js` validated HP/MP concepts that don't exist in The Beacon. Moved to `docs/reference/` as preserved prototypes with explanatory headers. CI scripts (`scripts/guardrails.sh`, `tests/smoke.mjs`) remain active. ### game.js Bloat (PR #76) diff --git a/scripts/guardrails.js b/docs/reference/guardrails-prototype.js similarity index 63% rename from scripts/guardrails.js rename to docs/reference/guardrails-prototype.js index 9e532b2..dd20f4d 100644 --- a/scripts/guardrails.js +++ b/docs/reference/guardrails-prototype.js @@ -1,8 +1,14 @@ - /** - * Symbolic Guardrails for The Beacon - * Ensures game logic consistency. + * Symbolic Guardrails Prototype (DEAD CODE — not loaded by runtime) + * + * Was added by PR #80 (GOFAI Symbolic Guardrails) but never wired into + * the browser runtime. Validates HP/MP concepts that don't exist in + * The Beacon — the game uses different resource types (code, compute, + * knowledge, users, impact, etc.). + * + * The active CI guardrails are in scripts/guardrails.sh and tests/smoke.mjs. */ + class Guardrails { static validateStats(stats) { const required = ['hp', 'maxHp', 'mp', 'maxMp', 'level']; diff --git a/game/npc-logic.js b/docs/reference/npc-logic-prototype.js similarity index 57% rename from game/npc-logic.js rename to docs/reference/npc-logic-prototype.js index 52f5626..710d211 100644 --- a/game/npc-logic.js +++ b/docs/reference/npc-logic-prototype.js @@ -1,3 +1,12 @@ +/** + * NPC State Machine Prototype (DEAD CODE — not loaded by runtime) + * + * Was added by PR #79 (GOFAI NPC State Machine) but never wired into + * the browser runtime. ES module export is incompatible with The Beacon's + * global-script loading pattern (index.html loads scripts via