@reicek/neataptic-ts 0.1.21 → 0.1.22

package/test/examples/flappy_bird/constants/constants.network-view.ts

@@ -41,9 +41,15 @@ export const FLAPPY_NETWORK_GRAPH_RIGHT_PADDING_PX = 20;
 /** Graph-bottom padding for network visualization content. */
 export const FLAPPY_NETWORK_GRAPH_BOTTOM_PADDING_PX = 18;
 
+/** Minimum drawable graph dimension after padding is removed. */
+export const FLAPPY_NETWORK_MIN_DRAWABLE_SIZE_PX = 1;
+
 /** Gap between graph body and floating legend panel. */
 export const FLAPPY_NETWORK_LEGEND_GRAPH_GAP_PX = 10;
 
+/** Ratio used to decide whether the legend occupies the right half of the canvas. */
+export const FLAPPY_NETWORK_LEGEND_RIGHT_SIDE_THRESHOLD_RATIO = 0.5;
+
 /** Inner node-layout padding inside drawable network region. */
 export const FLAPPY_NETWORK_NODE_LAYOUT_PADDING_PX = 2;
 
@@ -161,6 +167,9 @@ export const FLAPPY_NETWORK_HEADER_FONT_SIZE_PX = 11;
 /** Extra pixel allowance above label baseline for minimum node-height readability. */
 export const FLAPPY_NETWORK_MIN_NODE_HEIGHT_LABEL_EXTRA_PX = 4;
 
+/** Minimum fit-based node height before width and label constraints are applied. */
+export const FLAPPY_NETWORK_MIN_NODE_FIT_HEIGHT_PX = 4;
+
 /**
  * Layer-fit divisor used when deriving max node height from dense layer stacks.
  *
@@ -215,3 +224,18 @@ export const FLAPPY_NETWORK_INPUT_GROUP_LABEL_FONT_WEIGHT = 700;
 
 /** Text color for vertical input-group labels on neon backgrounds. */
 export const FLAPPY_NETWORK_INPUT_GROUP_LABEL_TEXT_COLOR = '#000000';
+
+/** Placeholder label used when the network has no hidden layers. */
+export const FLAPPY_NETWORK_EMPTY_HIDDEN_LAYER_LABEL = '-';
+
+/** Prefix used when hidden-layer counts are inferred rather than declared. */
+export const FLAPPY_NETWORK_INFERRED_HIDDEN_LAYER_PREFIX = '~';
+
+/** Separator used between hidden-layer sizes inside architecture labels. */
+export const FLAPPY_NETWORK_HIDDEN_LAYER_SEPARATOR = ' - ';
+
+/** Separator used between architecture columns in the compact header label. */
+export const FLAPPY_NETWORK_ARCHITECTURE_COLUMN_SEPARATOR = ' | ';
+
+/** Line separator used by the two-line architecture label block. */
+export const FLAPPY_NETWORK_ARCHITECTURE_LINE_SEPARATOR = '\n';

package/test/examples/flappy_bird/constants/constants.palette.ts

@@ -22,6 +22,13 @@ export const FLAPPY_NEON_PALETTE = {
   hudAccent: '#ff9a2e',
   hudPanelBackground: '#000000',
   hudPanelBorder: '#0fb5ff',
+  horizonLine: '#0a8ea0',
+  horizonGlow: 'rgba(10, 142, 160, 0.95)',
+  groundGridLine: '#0a8ea0',
+  groundGridGlow: 'rgba(10, 142, 160, 0.9)',
+  groundGridFog: 'rgba(10, 142, 160, 0.55)',
+  groundGridPulseFill: '#8ef3ff',
+  groundGridPulseGlow: 'rgba(142, 243, 255, 0.92)',
 } as const;
 
 /** Neon bird palette for per-agent render color assignment. */

package/test/examples/flappy_bird/constants/constants.starfield.ts

@@ -10,6 +10,42 @@ import { FLAPPY_WORLD_HEIGHT_PX } from './constants.world';
 /** Width of one repeated starfield tile (pixels). */
 export const FLAPPY_STARFIELD_TILE_WIDTH_PX = 512;
 
+/** Minimum positive dimension allowed for generated starfield canvases. */
+export const FLAPPY_STARFIELD_MIN_DIMENSION_PX = 1;
+
+/** Zero pixel origin used for starfield canvas clears and draws. */
+export const FLAPPY_STARFIELD_ORIGIN_PX = 0;
+
+/** Canvas rendering context identifier used for starfield tile generation. */
+export const FLAPPY_STARFIELD_CANVAS_CONTEXT_ID = '2d';
+
+/** Composite mode used for normal starfield canvas drawing passes. */
+export const FLAPPY_STARFIELD_COMPOSITE_SOURCE_OVER = 'source-over';
+
+/** Transparent shadow reset value used after glow drawing. */
+export const FLAPPY_STARFIELD_TRANSPARENT_SHADOW_COLOR = 'transparent';
+
+/** Default fully opaque alpha restored after tile generation. */
+export const FLAPPY_STARFIELD_FULL_ALPHA = 1;
+
+/** Blur reset value used after the star glow pass. */
+export const FLAPPY_STARFIELD_NO_BLUR_PX = 0;
+
+/** Inclusive range offset used when converting size bounds into random spans. */
+export const FLAPPY_STARFIELD_INCLUSIVE_RANGE_OFFSET = 1;
+
+/** Divisor that normalizes unsigned 32-bit RNG state into the unit interval. */
+export const FLAPPY_STARFIELD_UNSIGNED_NORMALIZATION_DIVISOR = 0x1_0000_0000;
+
+/** Primary left-shift used by the xorshift32 random transition. */
+export const FLAPPY_STARFIELD_XORSHIFT_LEFT_SHIFT_PRIMARY = 13;
+
+/** Middle right-shift used by the xorshift32 random transition. */
+export const FLAPPY_STARFIELD_XORSHIFT_RIGHT_SHIFT = 17;
+
+/** Final left-shift used by the xorshift32 random transition. */
+export const FLAPPY_STARFIELD_XORSHIFT_LEFT_SHIFT_FINAL = 5;
+
 /** Height of one repeated starfield tile (pixels). */
 export const FLAPPY_STARFIELD_TILE_HEIGHT_PX = FLAPPY_WORLD_HEIGHT_PX;
 
@@ -17,10 +53,49 @@ export const FLAPPY_STARFIELD_TILE_HEIGHT_PX = FLAPPY_WORLD_HEIGHT_PX;
 export const FLAPPY_STARFIELD_CYAN_FILL_STYLE = 'rgba(95, 255, 255, 1)';
 
 /** Horizontal scroll ratio for the farthest parallax layer. */
-export const FLAPPY_STARFIELD_FAR_SCROLL_RATIO = 0.08;
+export const FLAPPY_STARFIELD_FAR_SCROLL_RATIO = 0.03;
 
 /** Horizontal scroll ratio for the middle parallax layer. */
-export const FLAPPY_STARFIELD_MID_SCROLL_RATIO = 0.12;
+export const FLAPPY_STARFIELD_MID_SCROLL_RATIO = 0.04;
 
 /** Horizontal scroll ratio for the nearest parallax layer. */
-export const FLAPPY_STARFIELD_NEAR_SCROLL_RATIO = 0.18;
+export const FLAPPY_STARFIELD_NEAR_SCROLL_RATIO = 0.05;
+
+/**
+ * Declarative layer specs for the default starfield parallax bands.
+ *
+ * Keeping the layer recipe in data form makes it easier to swap the lower
+ * segment to a different parallax family without changing the tile builder.
+ */
+export const FLAPPY_STARFIELD_LAYER_SPECS = [
+  {
+    seed: 1_337,
+    scrollRatio: FLAPPY_STARFIELD_FAR_SCROLL_RATIO,
+    starCount: 35,
+    minSizePx: 1,
+    maxSizePx: 2,
+    minAlpha: 0.08,
+    maxAlpha: 0.22,
+    blurPx: 4,
+  },
+  {
+    seed: 2_777,
+    scrollRatio: FLAPPY_STARFIELD_MID_SCROLL_RATIO,
+    starCount: 28,
+    minSizePx: 1,
+    maxSizePx: 3,
+    minAlpha: 0.1,
+    maxAlpha: 0.28,
+    blurPx: 6,
+  },
+  {
+    seed: 4_242,
+    scrollRatio: FLAPPY_STARFIELD_NEAR_SCROLL_RATIO,
+    starCount: 23,
+    minSizePx: 2,
+    maxSizePx: 4,
+    minAlpha: 0.12,
+    maxAlpha: 0.34,
+    blurPx: 8,
+  },
+] as const;

package/test/examples/flappy_bird/environment/README.md

@@ -0,0 +1,143 @@
+# environment
+
+## environment/environment.types.ts
+
+### FlappyBird
+
+Bird kinematic state for one simulation frame.
+
+### FlappyDifficultyScale
+
+Difficulty scale used by the curriculum scheduler.
+
+- `0` means easiest profile (wide gaps, slower pipes).
+- `1` means fully adaptive profile based on passed pipes.
+
+### FlappyGameState
+
+Full simulation state for one Flappy episode.
+
+### FlappyObservationFeatures
+
+Structured observation features used to build the neural-network input vector.
+
+Re-exported from shared simulation utilities so trainer and browser paths
+stay synchronized as the observation schema evolves.
+
+### FlappyPipe
+
+Pipe obstacle definition.
+
+Pipes move from right to left. The bird scores once per pipe when the pipe
+completely crosses the bird x-position.
+
+## environment/environment.constants.ts
+
+### FLAPPY_ENVIRONMENT_DEFAULT_CONTROL_SUBSTEPS_PER_FRAME
+
+### FLAPPY_ENVIRONMENT_DEFAULT_DIFFICULTY_SCALE
+
+### FLAPPY_ENVIRONMENT_MAX_FRAMES_PER_EPISODE
+
+## environment/environment.step.service.ts
+
+### stepFlappyState
+
+`(state: import("test/examples/flappy_bird/environment/environment.types").FlappyGameState, rng: import("test/examples/flappy_bird/rng").FlappyRng, flap: boolean, difficultyScale: number) => void`
+
+Advance the simulation by one frame.
+
+Parameters:
+
+- `state` - - Mutable state object to update in-place.
+- `rng` - - Random source used to spawn pipes.
+- `flap` - - If true, applies an upward velocity impulse.
+- `difficultyScale` - - Curriculum difficulty scale in [0, 1].
+
+### stepFlappyStateWithControlSubsteps
+
+`(state: import("test/examples/flappy_bird/environment/environment.types").FlappyGameState, rng: import("test/examples/flappy_bird/rng").FlappyRng, shouldFlapForSubstep: () => boolean, difficultyScale: number, controlSubstepsPerFrame: number) => void`
+
+Advance one logical frame using multiple control/physics substeps.
+
+This allows policies to react multiple times before `frameIndex` advances,
+improving responsiveness in high-difficulty scenarios.
+
+Parameters:
+
+- `state` - - Mutable state object to update in-place.
+- `rng` - - Random source used to spawn pipes.
+- `shouldFlapForSubstep` - - Callback deciding flap action per substep.
+- `difficultyScale` - - Curriculum difficulty scale in [0, 1].
+- `controlSubstepsPerFrame` - - Number of substeps to run this frame.
+
+Returns: Nothing.
+
+## environment/environment.state.service.ts
+
+### createInitialFlappyState
+
+`(rng: import("test/examples/flappy_bird/rng").FlappyRng) => import("test/examples/flappy_bird/environment/environment.types").FlappyGameState`
+
+Create a fresh Flappy Bird episode state.
+
+Parameters:
+
+- `rng` - - Random source used to generate initial pipe configuration.
+
+Returns: Initial state for one deterministic rollout.
+
+## environment/environment.collision.utils.ts
+
+### updateCollisionAndProgressState
+
+`(state: import("test/examples/flappy_bird/environment/environment.types").FlappyGameState) => void`
+
+Apply out-of-bounds, pipe-collision, and pass-credit rules for one substep.
+
+Parameters:
+
+- `state` - - Mutable simulation state to update in-place.
+
+## environment/environment.observation.utils.ts
+
+### getFlappyObservation
+
+`(state: import("test/examples/flappy_bird/environment/environment.types").FlappyGameState, difficultyScale: number) => number[]`
+
+Generate the network observation vector for the current state.
+
+Observation (12 numbers):
+
+1.  bird y position normalized to [0, 1]
+2.  bird vertical velocity normalized to [-1, 1]
+3.  distance to next pipe normalized to [0, 1]
+4.  delta (bird y - gap center y) normalized to [-1, 1]
+5.  next pipe gap top normalized to [0, 1]
+6.  next pipe gap bottom normalized to [0, 1]
+7.  distance to second pipe normalized to [0, 1]
+8.  delta to second gap center normalized to [-1, 1]
+9.  time-to-next-pipe closeness normalized to [0, 1]
+10. signed clearance relative to next gap normalized to [-1, 1]
+11. required vertical velocity toward next gap center normalized to [-1, 1]
+12. gap-center transition (next to second) normalized to [-1, 1]
+
+Parameters:
+
+- `state` - - Current state.
+- `difficultyScale` - - Curriculum difficulty scale in [0, 1].
+
+Returns: Input vector for the neural network.
+
+### getFlappyObservationFeatures
+
+`(state: import("test/examples/flappy_bird/environment/environment.types").FlappyGameState, difficultyScale: number) => import("test/examples/flappy_bird/simulation-shared/simulation-shared.types").SharedObservationFeatures`
+
+Resolve structured observation features for policy input and reward shaping.
+
+Parameters:
+
+- `state` - - Current state.
+- `difficultyScale` - - Curriculum difficulty scale in [0, 1].
+
+Returns: Named feature object.

package/test/examples/flappy_bird/environment/environment.observation.utils.ts

@@ -61,7 +61,7 @@ export function getFlappyObservationFeatures(
   state: FlappyGameState,
   difficultyScale: FlappyDifficultyScale = FLAPPY_ENVIRONMENT_DEFAULT_DIFFICULTY_SCALE,
 ): FlappyObservationFeatures {
-  const difficultyProfile = resolveDifficultyProfile(
+  const difficultyProfile = resolveAdaptiveDifficultyProfile(
     state.pipesPassed,
     difficultyScale,
   );
@@ -84,21 +84,3 @@ export function getFlappyObservationFeatures(
     normalizationEpsilon: FLAPPY_NORMALIZATION_EPSILON,
   });
 }
-
-/**
- * Resolves adaptive difficulty parameters from current progress.
- *
- * @param pipesPassed - Number of pipes passed by the active bird.
- * @param difficultyScale - Curriculum difficulty scale in [0, 1].
- * @returns Runtime difficulty profile.
- */
-function resolveDifficultyProfile(
-  pipesPassed: number,
-  difficultyScale: FlappyDifficultyScale = FLAPPY_ENVIRONMENT_DEFAULT_DIFFICULTY_SCALE,
-): {
-  pipeGapPx: number;
-  pipeSpeedPxPerFrame: number;
-  pipeSpawnIntervalFrames: number;
-} {
-  return resolveAdaptiveDifficultyProfile(pipesPassed, difficultyScale);
-}

package/test/examples/flappy_bird/environment/environment.step.service.ts

@@ -70,7 +70,7 @@ export function stepFlappyStateWithControlSubsteps(
 ): void {
   if (state.done) return;
 
-  const difficultyProfile = resolveDifficultyProfile(
+  const difficultyProfile = resolveAdaptiveDifficultyProfile(
     state.pipesPassed,
     difficultyScale,
   );
@@ -105,12 +105,12 @@ export function stepFlappyStateWithControlSubsteps(
 
     state.framesUntilNextPipeSpawn -= substepDelta;
     if (state.framesUntilNextPipeSpawn <= 0) {
-      const nextGapSizePx = resolveLocalNextSpawnGapSize(
+      const nextGapSizePx = resolveNextSpawnGapSize(
         state.lastSpawnedPipeGapPx,
         difficultyProfile,
         rng,
       );
-      const nextSpawnIntervalFrames = resolveLocalNextSpawnIntervalFrames(
+      const nextSpawnIntervalFrames = resolveNextSpawnIntervalFrames(
         state.lastSpawnedPipeSpawnIntervalFrames,
         difficultyProfile,
       );
@@ -145,66 +145,3 @@ export function stepFlappyStateWithControlSubsteps(
     state.doneReason = 'timeout';
   }
 }
-
-/**
- * Resolves adaptive difficulty parameters from current progress.
- *
- * @param pipesPassed - Number of pipes passed by the active bird.
- * @param difficultyScale - Curriculum difficulty scale in [0, 1].
- * @returns Runtime difficulty profile.
- */
-function resolveDifficultyProfile(
-  pipesPassed: number,
-  difficultyScale: FlappyDifficultyScale = FLAPPY_ENVIRONMENT_DEFAULT_DIFFICULTY_SCALE,
-): {
-  pipeGapPx: number;
-  pipeSpeedPxPerFrame: number;
-  pipeSpawnIntervalFrames: number;
-} {
-  return resolveAdaptiveDifficultyProfile(pipesPassed, difficultyScale);
-}
-
-/**
- * Resolve the next spawned pipe gap with progressive wide-to-hard shrink and jitter.
- *
- * @param previousSpawnGapPx - Most recently spawned gap size.
- * @param difficultyProfile - Current adaptive profile.
- * @param rng - Random source.
- * @returns Gap size for the next pipe.
- */
-function resolveLocalNextSpawnGapSize(
-  previousSpawnGapPx: number | undefined,
-  difficultyProfile: {
-    pipeGapPx: number;
-    pipeSpeedPxPerFrame: number;
-    pipeSpawnIntervalFrames: number;
-  },
-  rng: FlappyRng,
-): number {
-  return resolveNextSpawnGapSize(
-    previousSpawnGapPx,
-    difficultyProfile as SharedDifficultyProfile,
-    rng,
-  );
-}
-
-/**
- * Resolve the next spawned pipe interval with progressive wide-to-hard shrink.
- *
- * @param previousSpawnIntervalFrames - Most recently spawned interval.
- * @param difficultyProfile - Current adaptive profile.
- * @returns Spawn interval for the next pipe.
- */
-function resolveLocalNextSpawnIntervalFrames(
-  previousSpawnIntervalFrames: number | undefined,
-  difficultyProfile: {
-    pipeGapPx: number;
-    pipeSpeedPxPerFrame: number;
-    pipeSpawnIntervalFrames: number;
-  },
-): number {
-  return resolveNextSpawnIntervalFrames(
-    previousSpawnIntervalFrames,
-    difficultyProfile as SharedDifficultyProfile,
-  );
-}

package/test/examples/flappy_bird/evaluation/README.md

@@ -0,0 +1,130 @@
+# evaluation
+
+## evaluation/evaluation.types.ts
+
+### FlappyEpisodeResult
+
+Summary metrics for a single Flappy episode rollout.
+
+### FlappyNetworkLike
+
+Minimal network contract required by Flappy evaluation.
+
+### FlappyRolloutOptions
+
+Runtime controls for one rollout evaluation.
+
+### FlappySeedBatchEvaluation
+
+Aggregate statistics from evaluating one network across shared seeds.
+
+## evaluation/evaluation.constants.ts
+
+### evaluation.constants
+
+Default difficulty scale for rollouts when caller does not provide one.
+
+### FLAPPY_EVALUATION_DEFAULT_DIFFICULTY_SCALE
+
+### FLAPPY_EVALUATION_DEFAULT_EARLY_TERMINATION_CONSECUTIVE_FRAMES
+
+### FLAPPY_EVALUATION_DEFAULT_EARLY_TERMINATION_GRACE_FRAMES
+
+### FLAPPY_EVALUATION_DEFAULT_PIPE_PROGRESS_TARGET
+
+### FLAPPY_EVALUATION_DENSE_SHAPING_FRAMES_NORMALIZER
+
+### FLAPPY_EVALUATION_NORMALIZED_DENSE_WEIGHT
+
+### FLAPPY_EVALUATION_NORMALIZED_PROGRESS_WEIGHT
+
+### FLAPPY_EVALUATION_NORMALIZED_SURVIVAL_WEIGHT
+
+### FLAPPY_EVALUATION_NORMALIZED_TERMINAL_WEIGHT
+
+### FLAPPY_EVALUATION_ROBUST_STDDEV_PENALTY
+
+### FLAPPY_EVALUATION_SEED_MIX_MULTIPLIER_A
+
+### FLAPPY_EVALUATION_SEED_MIX_MULTIPLIER_B
+
+### FLAPPY_EVALUATION_SEED_MIX_XOR_SALT
+
+### FLAPPY_EVALUATION_UNRECOVERABLE_ABOVE_GAP_DELTA
+
+### FLAPPY_EVALUATION_UNRECOVERABLE_BELOW_GAP_DELTA
+
+### FLAPPY_EVALUATION_UNRECOVERABLE_CLEARANCE_THRESHOLD
+
+### FLAPPY_EVALUATION_UNRECOVERABLE_FALLING_VELOCITY
+
+### FLAPPY_EVALUATION_UNRECOVERABLE_RISING_VELOCITY
+
+## evaluation/evaluation.rollout.service.ts
+
+### evaluation.rollout.service
+
+Public rollout compatibility facade.
+
+Keeping this file at the evaluation layer preserves the established import
+path while the actual rollout orchestration lives behind the dedicated
+rollout-owned module boundary.
+
+### rolloutEpisode
+
+`(network: import("test/examples/flappy_bird/evaluation/evaluation.types").FlappyNetworkLike, rolloutOptions: import("test/examples/flappy_bird/evaluation/evaluation.types").FlappyRolloutOptions) => import("test/examples/flappy_bird/evaluation/evaluation.types").FlappyEpisodeResult`
+
+Roll out an episode and return details.
+
+Parameters:
+
+- `network` - - Genome/network to evaluate.
+- `rolloutOptions` - - Optional rollout controls.
+
+Returns: Episode result details.
+
+## evaluation/evaluation.seed.utils.ts
+
+### mixGenomeEvaluationSeed
+
+`(genomeId: number) => number`
+
+Mixes a genome identifier into a stable uint32 rollout seed.
+
+This keeps evaluation deterministic per genome while still spreading nearby
+genome ids across the RNG state space to reduce correlated rollouts.
+
+Parameters:
+
+- `genomeId` - - Genome id from NEAT bookkeeping.
+
+Returns: Mixed uint32 seed.
+
+## evaluation/evaluation.fitness.utils.ts
+
+### evaluateFlappyFitness
+
+`(network: import("test/examples/flappy_bird/evaluation/evaluation.types").FlappyNetworkLike, rolloutOptions: import("test/examples/flappy_bird/evaluation/evaluation.types").FlappyRolloutOptions) => number`
+
+Evaluate a network on a single deterministic Flappy Bird episode.
+
+Parameters:
+
+- `network` - - Genome/network to evaluate.
+- `rolloutOptions` - - Optional rollout controls.
+
+Returns: Fitness score (higher is better).
+
+### evaluateFlappyFitnessAcrossSeeds
+
+`(network: import("test/examples/flappy_bird/evaluation/evaluation.types").FlappyNetworkLike, sharedSeeds: readonly number[], rolloutOptions: import("test/examples/flappy_bird/evaluation/evaluation.types").FlappyRolloutOptions) => import("test/examples/flappy_bird/evaluation/evaluation.types").FlappySeedBatchEvaluation`
+
+Evaluate a network on a shared batch of deterministic seeds.
+
+Parameters:
+
+- `network` - - Genome/network to evaluate.
+- `sharedSeeds` - - Shared deterministic seeds used for all genomes.
+- `rolloutOptions` - - Optional rollout controls.
+
+Returns: Robust aggregate metrics for selection/ranking.

package/test/examples/flappy_bird/evaluation/evaluation.fitness.utils.ts

@@ -9,7 +9,7 @@ import {
   computeMean,
   computePercentile,
   computePopulationStandardDeviation,
-} from './evaluation.statistics.utils';
+} from '../flappy.simulation.shared.utils';
 
 /**
  * Evaluate a network on a single deterministic Flappy Bird episode.