@reicek/neataptic-ts 0.1.21 → 0.1.23

package/test/examples/flappy_bird/README.md

@@ -1,28 +1,46 @@
 # Flappy Bird (NeatapticTS)
 
-This is a tiny Flappy Bird–style neuroevolution demo built **only** with this repo’s NeatapticTS implementation.
+This folder is the repo's most complete end-to-end neuroevolution example.
 
-Goal: provide a quick, repeatable way to exercise the NEAT pipeline (population creation, evaluation, mutation/crossover, speciation) on a classic control problem.
+It uses a Flappy Bird-style control problem to exercise the full NeatapticTS pipeline:
 
-The trainer now prioritizes **faster convergence** and **more stable generation quality** by using shared-seed, multi-stage evaluation.
+- deterministic environment stepping,
+- observation construction,
+- rollout evaluation and fitness shaping,
+- staged population-level selection,
+- browser playback and visualization,
+- worker-based simulation and snapshot transport.
 
-## Run
+If you want one place in the repository that shows how NEAT training, deterministic evaluation, browser rendering, and educational visualization fit together, start here.
 
-From the repo root:
+## What This Example Is For
+
+This example is not just a game clone. It is a compact systems demo for the library.
+
+At a high level, it answers four practical questions:
+
+1. How do you wire a NEAT population into a repeatable control problem?
+2. How do you reduce luck so selection pressure reflects policy quality instead of lucky seeds?
+3. How do you replay evolved behavior in the browser without moving the full simulation onto the main thread?
+4. How do you expose the evolved network structure in a way that is useful for learning and debugging?
+
+The current trainer emphasizes faster convergence and more stable generation quality by using shared-seed, multi-stage evaluation rather than one-rollout-per-genome scoring.
+
+## Quick Start
+
+Run training from the repo root:
 
 ```bash
 npx ts-node test/examples/flappy_bird/trainFlappyBird.ts
 ```
 
-You should see generation logs like:
+You should see logs like:
 
 - `gen=1 best=... pipes=... frames=...`
 
-The trainer does not stop on a fixed generation count. It keeps evolving until you close it (`Ctrl+C` in terminal).
-
-## Run in browser (local)
+Training runs continuously until you stop it with `Ctrl+C`.
 
-From the repo root:
+Run the browser demo locally from the repo root:
 
 ```bash
 npm run start:local-server
@@ -34,89 +52,176 @@ Then open:
 
 Notes:
 
-- this page loads bundles from `docs/assets`, so run `npm run docs` after code changes,
-- if port `8080` is in use, adjust the script/port accordingly.
-
-## How it works
-
-- Population is set to `50` to widen exploration while preserving strong winners (`elitism = 10`).
-- Mutation now uses annealing (`0.70 -> 0.25` rate, `2 -> 1` amount over early generations):
-  - early generations explore aggressively,
-  - later generations refine and stabilize.
-
-- Evaluation is now **population-level** and deterministic per generation:
-  1. quick screen on all genomes (`3` shared seeds, shorter rollout, early-stop heuristic),
-  2. full pass on top subset (`8` shared seeds),
-  3. final reevaluation of top candidates (`32` shared seeds).
-
-  This removes most per-genome luck while keeping runtime practical.
-
-- The bird has a fixed `x` position.
-- Pipes move left at a constant speed.
-- Difficulty ramps adaptively with progress (gap narrows, pipes speed up, spawn interval shortens).
-- A generation-level curriculum controls difficulty scale:
-  - very easy fixed profile in early generations,
-  - smooth ramp,
-  - full adaptive difficulty in later generations.
-- Pipe gaps are randomized but structured: each run starts around `40%` wider than the current hardest target, then each new spawned pipe shrinks a few pixels until reaching the current hardest gap.
-- Each genome’s network receives 38 inputs (temporal memory layout):
-  1. current frame core features (12 values):
-     - bird y, vertical velocity,
-     - distance/delta to next gap,
-     - next gap top/bottom,
-     - distance/delta to second gap,
-     - next-gap clearance,
-     - required vertical velocity to next-gap center,
-     - entry urgency,
-     - one-flap reachability at entry.
-  2. previous frame core features (same 12 values).
-  3. two-frames-ago core features (same 12 values).
-  4. last action channel (`1` flap, `0` no flap).
-  5. recent flap-rate channel (mean action over a fixed recent window).
-
-  Temporal stacking still provides short-term memory, while the leaner core keeps
-  focus on centerline tracking and staying away from corridor edges.
-
-- The network outputs 2 values (`no flap`, `flap`); we flap when `output[1] > output[0]`.
-- Fitness is now composed from normalized channels with caps to reduce domination by one term:
-  - survival,
-  - pipe progress,
-  - dense shaping,
-  - terminal shaping.
-
-Dense shaping rewards still include:
-
-- staying aligned with the next gap,
-- reducing horizontal distance to the next pipe,
-- improving centering toward the gap,
-- keeping positive corridor clearance,
-- pre-aligning toward the second upcoming gap,
-- maintaining controllable vertical velocity.
-
-The trainer logs robust distribution statistics each generation (`mean`, `median`, `p90`, `std`) in addition to best score.
-
-In browser playback, the demo renders the full generation population (not only the top bird):
-
-- only living birds are shown (eliminated birds are removed immediately),
-- each bird has a distinct color,
-- the current leader is highlighted.
+- the page loads bundles from `docs/assets`, so run `npm run docs` after code changes,
+- if port `8080` is busy, adjust the local server configuration.
+
+## Folder Map
+
+The folder is split by responsibility rather than by one giant "game" module.
+
+- `browser-entry/`: main-thread browser runtime, HUD, playback renderer, network visualization, viewport/layout helpers, and host-side worker wiring.
+- `constants/`: shared visual, training, environment, and playback constants used across multiple boundaries.
+- `environment/`: deterministic Flappy world state, stepping, collision/progress accounting, and observation bridge helpers.
+- `evaluation/`: rollout execution and fitness aggregation for one genome or a shared-seed batch.
+- `flappy-evolution-worker/`: browser worker runtime that owns evolution, playback simulation, and packed snapshot transport.
+- `simulation-shared/`: shared simulation-facing math and feature logic reused across environment, trainer, and browser paths.
+- `trainer/`: Node-side training orchestration, staged evaluation plans, annealed mutation scheduling, and generation logging.
+- `flappyEnvironment.ts`: compatibility-facing environment entrypoint.
+- `flappyEvaluation.ts`: compatibility-facing evaluation entrypoint.
+- `flappyEvolution.worker.ts`: worker entry used by browser bundling.
+- `trainFlappyBird.ts`: simplest Node entrypoint for starting training.
+- `index.html`: local browser shell for the interactive demo.
+- `index.ts`: aggregated example-facing exports.
+- `rng.ts`: deterministic RNG utilities shared by environment and evaluation flows.
+
+## How The Split Works
+
+The cleanest way to understand this example is to treat it as three layers plus two bridges.
+
+### 1. Simulation layer
+
+This is the deterministic game world.
+
+- `environment/` owns the mutable episode state and how one frame advances.
+- `simulation-shared/` owns logic that must stay consistent across training and playback, especially observation semantics.
+- `constants/` supplies the fixed knobs that shape the world and visual presentation.
+
+This layer should be understandable without knowing anything about the browser UI.
+
+### 2. Evaluation and training layer
+
+This is the evolutionary side.
+
+- `evaluation/` answers: "How good was this network on one or many deterministic rollouts?"
+- `trainer/` answers: "How should the population be evaluated, ranked, mutated, and logged across generations?"
+
+The important architectural choice here is that evaluation is population-aware, not just genome-local. Genomes are compared on shared seeds in stages:
+
+1. quick screen across the full population,
+2. fuller pass on a narrowed subset,
+3. reevaluation of top candidates.
+
+That keeps runtime practical while reducing the amount of selection luck caused by random rollout variation.
+
+### 3. Browser presentation layer
+
+This is the educational and visual side.
+
+- `browser-entry/host/` owns page setup and canvas/container lifecycle.
+- `browser-entry/runtime/` owns browser-side orchestration.
+- `browser-entry/worker-channel/` and `browser-entry/playback/worker-channel/` own message-level communication with the worker.
+- `browser-entry/playback/` owns frame reconstruction, background/trail rendering, snapshot handling, and live playback pacing.
+- `browser-entry/network-view/` and `browser-entry/visualization/` own the live network drawing and legend semantics.
+
+This layer is intentionally thin on simulation authority. The browser renders and explains; it does not become the source of truth for evolution.
+
+### 4. Worker bridge
 
-The stats panel is split horizontally:
+The browser does not evolve or simulate the population on the main thread.
 
-- left side shows current/best run metrics,
-- right side shows a full network drawing of the active best genome.
+- `flappy-evolution-worker/` owns worker-local NEAT runtime setup, generation requests, playback simulation, and packed frame snapshots.
 
-Browser runtime behavior:
+That split keeps the UI responsive while still allowing rich playback and HUD updates.
 
-- heavy evolution/evaluation and playback simulation run in a Web Worker,
+### 5. Compatibility bridge
+
+The root files such as `flappyEnvironment.ts`, `flappyEvaluation.ts`, and `index.ts` act as stable shelves for consumers or older imports that should not need to know the current folder layout.
+
+## Execution Paths
+
+There are two main ways through this codebase.
+
+### Training path
+
+1. `trainFlappyBird.ts` starts the trainer.
+2. `trainer/` resolves generation-level evaluation and mutation policy.
+3. `evaluation/` runs deterministic rollouts against the environment.
+4. `environment/` steps the world and returns episode outcomes.
+5. The trainer logs robust generation statistics and evolves the population again.
+
+### Browser path
+
+1. `index.html` loads the browser bundle.
+2. `browser-entry/` initializes the host UI and worker connection.
+3. `flappy-evolution-worker/` evolves or simulates playback off-thread.
+4. The worker posts packed snapshots and generation summaries back to the browser.
+5. `browser-entry/playback/` reconstructs frames, renders the flock, and updates the HUD.
+6. `browser-entry/network-view/` renders the active best network for inspection.
+
+## Core Design Choices
+
+Several choices are worth knowing before you read deeper.
+
+- Determinism matters. The episode runner is deterministic when seeded, and the trainer uses shared seed batches per generation for fairer comparison.
+- The observation vector is intentionally temporal. Each network receives 38 inputs composed from current, previous, and two-frames-ago feature slices, plus action-memory channels.
+- The network output is simple: two competing action scores, `no flap` and `flap`, with flap chosen when `output[1] > output[0]`.
+- Fitness is intentionally decomposed. It combines survival, progress, dense shaping, and terminal shaping so score inspection is more informative than a single opaque reward.
+- Playback is population-level. The browser can render the whole generation population, not just one best bird.
+- Visualization is educational, not decorative only. The network panel exposes node bias, connection magnitude/sign, disabled edges, and a legend so people can inspect what evolution is building.
+
+## Observation And Fitness Summary
+
+The policy sees a compact but structured 38-input view of the world:
+
+1. current-frame core features,
+2. previous-frame core features,
+3. two-frames-ago core features,
+4. last action,
+5. recent flap-rate memory.
+
+Those core features focus on corridor geometry and control urgency rather than raw scene detail:
+
+- bird vertical position and velocity,
+- distance and delta to the next gap,
+- next gap bounds,
+- distance and delta to the second gap,
+- next-gap clearance,
+- required vertical velocity toward the next-gap center,
+- entry urgency,
+- one-flap reachability at entry.
+
+Fitness then combines normalized channels with caps so one lucky dimension does not dominate selection:
+
+- survival,
+- pipe progress,
+- dense shaping,
+- terminal shaping.
+
+Dense shaping still rewards staying aligned to the next gap, approaching the next pipe productively, maintaining clearance, and preparing for the second upcoming gap.
+
+## Browser Runtime At A Glance
+
+In browser playback:
+
+- heavy evolution, evaluation, and playback simulation run in a Web Worker,
 - the main thread focuses on rendering and lightweight snapshot handoff,
-- HUD counter updates are throttled (every 10 frames).
+- HUD counter updates are throttled,
+- only living birds remain visible,
+- each bird has a distinct color,
+- the current leader is highlighted,
+- the right-hand panel renders the active best network.
+
+The background and playback renderer are also deliberately split into sub-boundaries such as `background/`, `frame-render/`, `snapshot/`, `trail/`, and `worker-channel/` so rendering concerns do not collapse into one monolithic canvas file.
+
+## Recommended Reading Order
+
+If you are new to this example, read in this order:
+
+1. this README for the high-level map,
+2. `trainer/README.md` to understand the evolutionary loop,
+3. `evaluation/README.md` to understand rollout and scoring,
+4. `environment/README.md` to understand the deterministic world,
+5. `browser-entry/README.md` to understand the browser runtime,
+6. `flappy-evolution-worker/README.md` to understand the worker protocol and playback transport.
+
+If you only care about one use case:
+
+- training and fitness tuning: start with `trainer/` and `evaluation/`,
+- environment or control-problem changes: start with `environment/` and `simulation-shared/`,
+- browser playback or UI work: start with `browser-entry/` and `flappy-evolution-worker/`.
 
-Visualization semantics:
+## Why This Example Matters In The Repo
 
-- each node is a square, with the node bias printed inside,
-- each connection line is colored by connection weight range,
-- disabled connections are rendered as faint dashed lines,
-- an in-canvas neon legend explains both bias and weight color ranges.
+This example is one of the clearest demonstrations of the repository's broader direction from the interactive examples plan: educational, inspectable examples that show both how the library is used and why particular architectural boundaries exist.
 
-The episode runner remains deterministic when a seed is provided. Training now uses **shared seed batches per generation** (instead of per-genome private seeds) for fairer comparisons.
+It is not the smallest example in the repository, but it is likely the best one for understanding how NeatapticTS is intended to feel in a real application.