synthesis/PROGRESS.md

# Synthesis — Development Progress

> **Last updated:** 2026-02-12  
> **Current phase:** Phase 11 ✅ → Great Cycle Complete

---

## Completed

### Phase 0: Project Setup ✅
- [x] Game Design Document (`synthesis-gdd.md`)
- [x] Engine analysis and tech stack selection (`engine-analysis.md`)
- [x] npm project + dependencies (Phaser 3, bitECS, TypeScript, Vite, Vitest)
- [x] TypeScript strict config
- [x] Vite config (HMR, chunk splitting)
- [x] Phaser config (1280x720, pixel-art, arcade physics, top-down)
- [x] BootScene with title screen
- [x] Cursor rules (6 rules: project context, agent workflow, ECS, chemistry, Phaser, data)
- [x] Implementation plan (`IMPLEMENTATION-PLAN.md`)
- [x] Progress tracking (this file)

### Phase 1: Chemistry Engine ✅
- [x] 1.1 Types and interfaces (`src/chemistry/types.ts`)
- [x] 1.2 Element data — 20 real elements (`src/data/elements.json`)
- [x] 1.3 Element registry with lookup by symbol/number (`src/chemistry/elements.ts`)
- [x] 1.4 Reaction engine — O(1) lookup, condition checking, failure reasons (`src/chemistry/engine.ts`)
- [x] 1.5 Reaction data — 34 real reactions (`src/data/reactions.json`)
- [x] 1.6 Compound data — 25 compounds with game effects (`src/data/compounds.json`)
- [x] 1.7 Unit tests — 35 passing (`tests/chemistry.test.ts`)

### Phase 2: ECS Foundation ✅
- [x] 2.1 World setup — bitECS world + time tracking (`src/ecs/world.ts`)
- [x] 2.2 Core components — Position, Velocity, SpriteRef, Health, ChemicalComposition (`src/ecs/components.ts`)
- [x] 2.3 Movement system — velocity-based + bounce (`src/ecs/systems/movement.ts`)
- [x] 2.4 Phaser ↔ bitECS sync bridge — polling-based, creates/destroys/syncs sprites (`src/ecs/bridge.ts`)
- [x] 2.5 Entity factory — createGameEntity/removeGameEntity (`src/ecs/factory.ts`)
- [x] 2.6 Health/damage system — damage, healing, death detection (`src/ecs/systems/health.ts`)
- [x] 2.7 Visual test — 20 colored circles bouncing at 60fps, GameScene (`src/scenes/GameScene.ts`)
- [x] Unit tests — 39 passing (`tests/ecs.test.ts`)

### Phase 3: World Generation ✅
- [x] 3.1 Tilemap system — canvas tileset with per-pixel variation + Phaser tilemap (`src/world/tilemap.ts`)
- [x] 3.2 Biome data — Catalytic Wastes: 8 tile types (`src/data/biomes.json`)
- [x] 3.3 Noise generation — simplex-noise, seeded PRNG (mulberry32), deterministic (`src/world/noise.ts`)
- [x] 3.4 World generator — elevation noise → base terrain, detail noise → overlays (`src/world/generator.ts`)
- [x] 3.5 Resource placement — geysers on acid-shallow zones, mineral veins on ground (`src/world/generator.ts`)
- [x] 3.6 Camera — WASD movement, mouse wheel zoom (0.5x–3x), bounds clamping (`src/world/camera.ts`)
- [x] 3.7 Minimap — canvas-based 160x160 overview, viewport indicator, border (`src/world/minimap.ts`)
- [x] Unit tests — 21 passing (`tests/world.test.ts`)

### Phase 4: Player Systems ✅
- [x] 4.1 Player entity + WASD controller (`src/player/input.ts`, `src/player/collision.ts`, `src/player/spawn.ts`, `src/player/factory.ts`)
- [x] 4.2 Inventory — weight-based, element stacking, AMU mass from registries (`src/player/inventory.ts`)
- [x] 4.3 Element collection from world objects — resource entities, proximity interaction, E key (`src/player/interaction.ts`, `src/world/resources.ts`)
- [x] 4.4 Crafting — chemistry engine integration, inventory consume/produce, condition checking (`src/player/crafting.ts`)
- [x] 4.5 Projectile system — throw elements toward mouse, lifetime + tile collision (`src/player/projectile.ts`)
- [x] 4.6 Quick slots — 4 hotkeys, auto-assign on pickup, active slot for throw (`src/player/quickslots.ts`)
- [x] 4.7 HUD — UIScene overlay: health bar, quick slots, inventory info, controls hint (`src/scenes/UIScene.ts`)
- [x] Unit tests — 39 player + 28 inventory + 12 interaction + 11 crafting + 13 projectile + 15 quickslots + 8 UI = 126 tests (222 total)

### Phase 5: Creatures & Ecology ✅
- [x] 5.1 Creature data — 3 species: Crystallids, Acidophiles, Reagents (`src/data/creatures.json`)
- [x] 5.2 AI behavior — FSM: idle → wander → feed → flee → attack (`src/creatures/ai.ts`)
- [x] 5.3 Metabolism — energy drain, feeding from resources, starvation damage (`src/creatures/metabolism.ts`)
- [x] 5.4 Population dynamics — counting, reproduction, initial spawning (`src/creatures/population.ts`)
- [x] 5.5 Life cycle — egg → youth → mature → aging → natural death (`src/creatures/lifecycle.ts`)
- [x] 5.6 Interaction — projectile collision (armor), observation, creature→player melee (`src/creatures/interaction.ts`)
- [x] 5.7 Ecosystem test — populations fluctuate, don't die out (`tests/ecosystem.test.ts`)
- [x] 5.8 GameScene integration — all creature systems in update loop, debug overlay
- [x] ECS components: Creature, AI, Metabolism, LifeCycle (`src/ecs/components.ts`)
- [x] Species registry with string/numeric ID lookup (`src/creatures/types.ts`)
- [x] Creature factory (`src/creatures/factory.ts`)
- [x] Unit tests — 51 creature + 16 interaction + 5 ecosystem = 72 tests (293 total)

### Phase 6: Run Cycle ✅
- [x] 6.1 Spore Cradle — CradleScene: school selection UI, floating spore particles, meta display (`src/scenes/CradleScene.ts`)
- [x] 6.2 Death trigger — player death → camera fade → DeathScene transition (`src/scenes/GameScene.ts`)
- [x] 6.3 Death animation — body decomposes into real elements (65% O, 18% C, 10% H...), element labels, Mycelium threads absorbing particles (`src/scenes/DeathScene.ts`)
- [x] 6.4 Moment Between — WebGL Mandelbrot/Julia hybrid shader with morphing + zoom, canvas fallback for non-WebGL (`src/scenes/FractalScene.ts`)
- [x] 6.5 Meta-progression — Codex (permanent knowledge), spores (currency), run history, IndexedDB persistence (`src/run/meta.ts`, `src/run/persistence.ts`)
- [x] 6.6 Run phases — state machine: Awakening → Exploration → Escalation → Crisis → Resolution, auto-advance on timers (`src/run/state.ts`)
- [x] 6.7 Escalation — creature speed/aggro/damage multipliers, reaction instability, environmental damage at high entropy (`src/run/escalation.ts`)
- [x] 6.8 Crisis: Chemical Plague — chain reaction poisons atmosphere, progressive player damage, toxic green tint overlay, CaO neutralization mechanics (`src/run/crisis.ts`)
- [x] 6.9 School: Alchemist — starting kit (H×5, O×5, C×3, Na×3, S×2, Fe×2), chemical equilibrium principle (`src/data/schools.json`)
- [x] Scene flow: BootScene → CradleScene → GameScene → DeathScene → FractalScene → CradleScene (full loop verified)
- [x] Texture cleanup for multi-run support (tilemap + minimap textures removed before recreation)
- [x] Unit tests — 42 run-cycle + 14 escalation = 56 tests (349 total)

### Phase 7: Mycelium ✅
- [x] 7.1 Mycelium Graph — persistent knowledge network (nodes, edges, deposit/strengthen/query) (`src/mycelium/graph.ts`)
- [x] 7.2 Fungal Nodes — ECS entities on world map, glowing bioluminescent spots, pulsing animation (`src/mycelium/nodes.ts`)
- [x] 7.3 Knowledge Recording — deposit run discoveries into Mycelium (auto on death + manual at nodes) (`src/mycelium/knowledge.ts`)
- [x] 7.4 Knowledge Extraction — memory flashes from past runs, weighted by node strength, Russian text templates (`src/mycelium/knowledge.ts`)
- [x] 7.5 Mycosis — visual distortion (tint overlay) on prolonged fungal node contact, reveals hidden info at threshold (`src/mycelium/mycosis.ts`)
- [x] 7.6 Spore Shop — Cradle integration: spend spores for starting bonuses (extra health, elements, knowledge boost) (`src/mycelium/shop.ts`)
- [x] ECS component: FungalNode (nodeIndex, glowPhase, interactRange) (`src/ecs/components.ts`)
- [x] Data: mycelium config, spore bonuses, memory templates (`src/data/mycelium.json`)
- [x] MetaState extended with MyceliumGraphData, IndexedDB persistence updated
- [x] GameScene integration: node spawning, glow rendering, E-key interaction, mycosis overlay, memory flash display
- [x] CradleScene integration: spore shop UI, Mycelium stats display, purchased effects passed to GameScene
- [x] Unit tests — 36 passing (`tests/mycelium.test.ts`) (385 total)

### Phase 8: First Archont — Ouroboros ✅
- [x] 8.1 Ouroboros entity — Boss data JSON, BossData type, Boss ECS component, entity factory (`src/boss/factory.ts`, `src/data/bosses.json`)
- [x] 8.2 Pattern mechanics — 4-phase cyclical AI: Coil → Spray → Lash → Digest, escalating difficulty (10% faster per cycle, caps at 5), regeneration + armor systems (`src/boss/ai.ts`)
- [x] 8.3 Arena — circular generated room (21×21 tiles), acid pools, crystal walls, 4 mineral deposits, boss center / player south spawn (`src/boss/arena.ts`)
- [x] 8.4 Multiple solutions — 3 real-chemistry victory paths: NaOH acid-base neutralization (3× dmg during Spray), direct damage during Digest vulnerability, Hg catalyst poisoning (permanently reduces regen+armor) (`src/boss/victory.ts`)
- [x] 8.5 Reward — Archont's Memory lore entry in Codex, spore reward (100 base, +50% chemical, +100% catalytic), CodexEntry type extended with 'boss' (`src/boss/reward.ts`)
- [x] BossArenaScene — full boss fight scene with phase-based attacks (Coil: chase, Spray: rotating acid projectiles, Lash: area sweep, Digest: immobile+vulnerable), boss health bar + phase indicator, victory/death handling (`src/scenes/BossArenaScene.ts`)
- [x] GameScene integration — Resolution phase completion triggers arena transition, inventory/quickslots/health carried over
- [x] Scene flow extended: GameScene → BossArenaScene → DeathScene (on death or victory)
- [x] Unit tests — 70 passing (`tests/boss.test.ts`) (455 total)

### Phase 9: Biome Expansion ✅
- [x] 9.1 New elements — 20 additional real elements (Li, B, F, Ne, Ar, Ti, Cr, Mn, Co, Ni, As, Br, Ag, I, Ba, W, Pt, Pb, Bi, U) → 40 total
- [x] 9.2 New compounds — 39 new compounds (acids, salts, oxides, organics) → 64 total
- [x] 9.3 New reactions — 85 new reactions (synthesis, combustion, acid-base, redox, decomposition, replacement) → 119 total
- [x] 9.4 Kinetic Mountains biome — physics/mechanics themed: chasms, gear floors, magnetic fields, steam vents, ore deposits
- [x] 9.5 Verdant Forests biome — biology/ecology themed: bogs, toxic blooms, ancient trees, mycelium carpet, herb patches
- [x] 9.6 Biome selection — CradleScene biome picker UI, biomeId passed to GameScene, generic world generator
- [x] 9.7 New creatures — 6 species: Pendulums/Mechanoids/Resonators (mountains), Symbiotes/Mimics/Spore-bearers (forests)
- [x] 9.8 World generator genericized — tile lookup by property (interactive/resource) instead of hardcoded names
- [x] Chemistry types extended — `actinide` element category for Uranium
- [x] Species types extended — `biome` field, `SpeciesId` enum expanded (0–8)
- [x] GameScene filters creatures by selected biome
- [x] Unit tests — 32 new tests (487 total)

### Phase 10: Schools ✅
- [x] 10.1 SchoolData type extended — `bonuses`, `unlockCondition`, `ResolvedSchoolBonuses` interface (`src/run/types.ts`)
- [x] 10.2 3 new schools — Mechanic, Naturalist, Navigator with real science principles (`src/data/schools.json`)
- [x] 10.3 School unlock system — data-driven conditions: elements_discovered, creatures_discovered, runs_completed (`src/run/meta.ts`)
- [x] 10.4 School bonuses resolver — `getSchoolBonuses()` returns complete multiplier set with defaults (`src/run/meta.ts`)
- [x] 10.5 Bonus integration — movement speed (Navigator), projectile damage (Mechanic), creature aggro range (Naturalist), reaction efficiency (Alchemist)
- [x] 10.6 CradleScene updated — all 4 schools displayed, locked schools grayed out with lock icon + unlock hint, bonus indicators shown
- [x] 10.7 System signatures updated — `playerInputSystem`, `aiSystem`, `creatureProjectileSystem` accept optional multiplier params
- [x] Unit tests — 24 new tests (511 total): school data, unlock conditions (cumulative, multi-school, persistence), bonuses per school

### Phase 11: Great Cycle ✅
- [x] 11.1 GreatCycleState types — CycleTheme enum, RunTrace, GreatCycleState, CycleWorldModifiers (`src/run/types.ts`)
- [x] 11.2 Great Cycle engine — cycle tracking, theme resolution, trace recording, renewal, world modifiers (`src/run/cycle.ts`)
- [x] 11.3 MetaState extended — `greatCycle` field, persistence updated, RunState extended with biomeId/worldSeed/deathPosition
- [x] 11.4 Run trace recording — death position, school, biome, discoveries saved per run via `applyRunResults`
- [x] 11.5 World trace placement — WorldTrace ECS component, death site markers (dark red), discovery markers (blue), glow animation (`src/world/traces.ts`)
- [x] 11.6 Cycle narrative data — 6 themes with Russian lore fragments, cradle quotes, renewal messages (`src/data/cycle-narrative.json`)
- [x] 11.7 RenewalScene — special scene between great cycles: Mycelium particles, staged text reveals, cycle transition, lore, maturation display (`src/scenes/RenewalScene.ts`)
- [x] 11.8 Mycelium maturation — strengthens all nodes on renewal, caps at 1.0, cumulative across cycles
- [x] 11.9 CradleScene integration — "Великий Цикл N: Тема | Ран X/7", narrative quote per theme
- [x] 11.10 UIScene integration — cycle info bar + run phase display below health
- [x] 11.11 GameScene integration — world trace spawning, trace glow rendering, death position recording, cycle info to registry
- [x] 11.12 Scene flow extended — Fractal → RenewalScene (on 7th run) → Cradle, or Fractal → Cradle (normal)
- [x] Unit tests — 51 new tests (562 total): cycle init, themes, traces, advancement, renewal, world modifiers, narrative data, full integration

---

## In Progress

_None — Phase 11 complete_

---

## Up Next: Phase 12+

_(See IMPLEMENTATION-PLAN.md for Beyond Vertical Slice)_

---

## Blockers

None

---

## Session Log

| # | Date | Phase | Summary |
|---|------|-------|---------|
| 1 | 2026-02-12 | Phase 0 | Project setup: GDD, engine analysis, npm init, Phaser config, BootScene, cursor rules, plan |
| 2 | 2026-02-12 | Phase 1 | Chemistry engine: 20 elements, 25 compounds, 34 reactions, engine with O(1) lookup + educational failures, 35 tests passing |
| 3 | 2026-02-12 | Phase 2 | ECS foundation: world + time, 5 components, movement + bounce + health systems, Phaser bridge (polling sync), entity factory, GameScene with 20 bouncing circles at 60fps, 39 tests passing |
| 4 | 2026-02-12 | Phase 3 | World generation: simplex noise (seeded), 80x80 tilemap with 8 tile types, Catalytic Wastes biome, camera WASD+zoom, minimap with viewport indicator, 21 tests passing (95 total) |
| 5 | 2026-02-12 | Phase 4 | Player systems: WASD movement + tile collision, weight-based inventory, resource collection, crafting via chemistry engine, projectile throw, 4 quick slots, UIScene HUD overlay (health bar, slots, inventory), 126 new tests (222 total) |
| 6 | 2026-02-12 | Phase 5 | Creatures & Ecology: 3 species (Crystallid/Acidophile/Reagent), FSM AI (idle/wander/feed/flee/attack), metabolism (energy drain/feeding/starvation), life cycle (egg→youth→mature→aging→death), population dynamics, projectile-creature collision with armor, creature→player melee, ecosystem simulation test, 72 new tests (293 total) |
| 7 | 2026-02-12 | Phase 6 | Run Cycle: full roguelike loop (Cradle→Game→Death→Fractal→Cradle), school selection (Alchemist), meta-progression (Codex/spores/IndexedDB), run phases with auto-advance, escalation effects (creature aggression/env damage), Chemical Plague crisis with neutralization, death animation (real body composition), WebGL fractal shader, 56 new tests (349 total) |
| 8 | 2026-02-12 | Phase 7 | Mycelium: persistent knowledge graph (nodes/edges/strength), fungal node ECS entities with glow animation, knowledge deposit (auto on death + manual at nodes), memory flash extraction (weighted by strength, Russian templates), mycosis visual effect (tint overlay + reveal threshold), spore shop in Cradle (5 bonuses: health/elements/knowledge), MetaState+IndexedDB persistence updated, GameScene+CradleScene integration, 36 new tests (385 total) |
| 9 | 2026-02-12 | Phase 8 | Ouroboros boss fight: 4-phase cyclical AI (Coil/Spray/Lash/Digest) with escalating difficulty, 3 chemistry-based victory paths (NaOH neutralization, direct damage, Hg catalyst poison), circular arena generator, BossArenaScene with attacks+collision+UI, Archont's Memory lore reward, CodexEntry extended, GameScene Resolution→arena trigger, 70 new tests (455 total) |
| 10 | 2026-02-12 | Phase 9 | Biome expansion: +20 elements (40 total), +39 compounds (64 total), +85 reactions (119 total), 2 new biomes (Kinetic Mountains + Verdant Forests), biome selection in CradleScene, 6 new creature species (3 per new biome), generic world generator, 32 new tests (487 total) |
| 11 | 2026-02-12 | Phase 10 | Schools: +3 schools (Mechanic/Naturalist/Navigator), data-driven unlock system (elements/creatures/runs), school bonuses (projectile dmg, movement speed, aggro range, reaction efficiency), CradleScene shows locked schools with hints, system multiplier params, 24 new tests (511 total) |
| 12 | 2026-02-12 | Phase 11 | Great Cycle: 7-run macro cycles with traces between runs, GreatCycleState (cycle number/theme/traces), RunTrace recording (death position/school/biome/discoveries), WorldTrace ECS entities (death markers + discovery sites with glow), RenewalScene (Mycelium particles/staged text/cycle transition), 6 narrative themes (Awakening→Synthesis) with Russian lore, Mycelium maturation on renewal, CradleScene+UIScene+GameScene cycle display, 51 new tests (562 total) |