the-beacon/GENOME.md

GENOME.md — the-beacon

Codebase analysis generated 2026-04-13. Sovereign AI idle game — browser-based.

Project Overview

The Beacon is a browser-based idle/incremental game inspired by Universal Paperclips, themed around the Timmy Foundation's real journey building sovereign AI. The core divergence from Paperclips: the goal is not maximization — it is faithfulness. "Can you grow powerful without losing your purpose?"

Static HTML/JS — no build step, no dependencies, no framework. Open index.html in any browser.

6,033 lines of JavaScript across 11 files. 1 HTML file with embedded CSS (~300 lines). 3 test files (2 Node.js, 1 Python).

Architecture

index.html (UI + embedded CSS + inline JS ~5000L)
    |
    +-- js/engine.js      (1590L) Core game loop, tick, resources, buildings, projects, events
    +-- js/data.js        (944L)  Building definitions, project trees, event tables, phase data
    +-- js/render.js      (390L)  DOM rendering, UI updates, resource displays
    +-- js/combat.js      (359L)  Canvas boid-flocking combat visualization
    +-- js/sound.js       (401L)  Web Audio API ambient drone, phase-aware sound
    +-- js/dismantle.js   (570L)  The Dismantle sequence (late-game narrative)
    +-- js/main.js        (223L)  Initialization, game loop start, auto-save, help overlay
    +-- 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
    +-- js/emergent-mechanics.js  Emergent game mechanics from player behavior

    CI scripts (not browser runtime):
    +-- scripts/guardrails.sh  Static analysis guardrails for game logic
    +-- scripts/smoke.mjs      Playwright smoke tests

    Reference prototypes (NOT loaded by runtime):
    +-- docs/reference/npc-logic-prototype.js    NPC state machine prototype
    +-- docs/reference/guardrails-prototype.js   Stat validation prototype

Entry Points

index.html

The single entry point. Loads all JS files, contains all HTML structure and inline CSS. Open directly in browser — no server required.

js/main.js — Initialization

initGame() sets initial state, starts the 10Hz tick loop (setInterval(tick, 100)), triggers tutorial for new games, loads saved games, starts ambient sound.

js/engine.js — Game Loop

The tick() function runs every 100ms. Each tick:

1. Accumulate resources (code, compute, knowledge, users, impact, rescues, ops, trust, creativity, harmony)
2. Process buildings and their rate multipliers
3. Check phase transitions (Phase 1→6 based on total code thresholds)
4. Trigger random events (corruption events, alignment events, wizard events)
5. Update boosts, debuffs, and cooldowns
6. Call render() to update UI

Data Flow

User clicks "WRITE CODE" / presses SPACE
    |
    v
G.code += 1 (or more with auto-clickers, combos, boosts)
    |
    v
tick() accumulates all passive rates from buildings
    |
    v
updateRates() recalculates based on:
  - Building counts × base rates × boost multipliers
  - Harmony (Timmy's multiplier, Pact drain/gain)
  - Bilbo randomness (burst/vanish per tick)
  - Active debuffs
    |
    v
Phase check: totalCode thresholds → unlock new content
    |
    v
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