@reicek/neataptic-ts 0.1.21 → 0.1.23

package/test/examples/flappy_bird/simulation-shared/simulation-shared.constants.ts

@@ -7,5 +7,8 @@ export const FLAPPY_SHARED_DEFAULT_DIFFICULTY_SCALE = 1;
 
 /**
  * Small positive epsilon used to guard divisions in normalized timing features.
+ *
+ * The epsilon avoids unstable divide-by-zero behavior when distances or speeds
+ * collapse toward zero during normalization.
  */
 export const FLAPPY_SHARED_DEFAULT_NORMALIZATION_EPSILON = 0.001;

package/test/examples/flappy_bird/simulation-shared/simulation-shared.control.utils.ts

@@ -1,6 +1,12 @@
 /**
  * Resolves flap/no-flap decision from network outputs.
  *
+ * Educational note:
+ * The shared control layer accepts both two-output competitive policies
+ * (`no flap` vs `flap`) and simpler single-output thresholded policies. That
+ * flexibility makes the helper reusable across experiments without forcing every
+ * caller to reshape its outputs first.
+ *
  * @param rawOutputs - Activation output payload.
  * @param flapThreshold - Scalar threshold for single-output policies.
  * @returns True when flap should trigger.

package/test/examples/flappy_bird/simulation-shared/simulation-shared.difficulty.utils.ts

@@ -14,6 +14,15 @@ import type { SharedDifficultyProfile } from './simulation-shared.types';
 /**
  * Resolves adaptive difficulty profile from passed-pipe progress.
  *
+ * Educational note:
+ * Difficulty is ramped as a smooth profile rather than as a sequence of hard
+ * level jumps. That keeps the task readable for humans and less noisy for
+ * evolution.
+ *
+ * The idea is closely related to curriculum learning: easier versions of the
+ * task dominate early, then the example interpolates toward the harder target
+ * settings as progress increases.
+ *
  * @param pipesPassed - Number of passed pipes.
  * @param difficultyScale - Curriculum scale in `[0, 1]`.
  * @returns Active difficulty profile.

package/test/examples/flappy_bird/simulation-shared/simulation-shared.errors.ts

@@ -1,9 +1,18 @@
-/** Prefix used when formatting unexpected shared-simulation errors. */
+/**
+ * Prefix used when formatting unexpected shared-simulation errors.
+ *
+ * A stable prefix makes logs easier to scan when multiple Flappy subsystems are
+ * emitting diagnostics.
+ */
 export const FLAPPY_SHARED_SIMULATION_ERROR_PREFIX = 'Shared simulation error:';
 
 /**
  * Formats unknown shared-simulation errors for stable logs.
  *
+ * Shared utilities are used from several runtime contexts, so this helper keeps
+ * the error surface human-readable even when the thrown value is not an
+ * `Error` instance.
+ *
  * @param error - Unknown error value.
  * @returns Readable error message.
  */

package/test/examples/flappy_bird/simulation-shared/simulation-shared.memory.utils.ts

@@ -12,6 +12,11 @@ import type {
 /**
  * Creates an empty temporal observation memory state.
  *
+ * @example
+ * ```ts
+ * const memoryState = createSharedObservationMemoryState();
+ * ```
+ *
  * @returns Fresh mutable memory buffers for one bird/controller.
  */
 export function createSharedObservationMemoryState(): SharedObservationMemoryState {
@@ -24,6 +29,12 @@ export function createSharedObservationMemoryState(): SharedObservationMemorySta
 /**
  * Builds the temporal policy input vector (stacked observation + action memory).
  *
+ * Educational note:
+ * This helper turns an interpretable feature object into the exact flat vector a
+ * feed-forward network consumes. That is why the output layout is documented so
+ * explicitly: changing the order would change the meaning of every trained
+ * weight in the policy.
+ *
  * Output layout:
  * 1) current core observation frame
  * 2) previous core frames (newest to oldest) with zero padding
@@ -60,6 +71,10 @@ export function resolveTemporalObservationVector(
 /**
  * Commits one observation-action step into temporal memory.
  *
+ * The memory update happens after the decision is made so the next step can see
+ * both the recent observation context and the action history that produced the
+ * current trajectory.
+ *
  * @param observationMemoryState - Mutable temporal memory for the active bird.
  * @param features - Structured observation features used for the decision.
  * @param didFlap - Decision taken at this step.
@@ -93,6 +108,9 @@ export function commitSharedObservationMemoryStep(
 /**
  * Resolves previous core frames (newest-first) with deterministic zero padding.
  *
+ * Zero padding keeps the policy input width stable during the first few frames
+ * of an episode before enough history has accumulated.
+ *
  * @param observationMemoryState - Mutable temporal memory for the active bird.
  * @returns Previous core frame list with fixed target length.
  */

package/test/examples/flappy_bird/simulation-shared/simulation-shared.observation.utils.ts

@@ -1,406 +1,11 @@
-import {
-  FLAPPY_BIRD_RADIUS_PX,
-  FLAPPY_BIRD_X_PX,
-  FLAPPY_FLAP_VELOCITY_PX_PER_FRAME,
-  FLAPPY_GRAVITY_PX_PER_FRAME2,
-  FLAPPY_MAX_FALL_SPEED_PX_PER_FRAME,
-  FLAPPY_MIN_PIPE_RECOVERY_FRAMES,
-  FLAPPY_PIPE_GAP_PX,
-  FLAPPY_PIPE_WIDTH_PX,
-  FLAPPY_WORLD_HEIGHT_PX,
-} from '../constants/constants';
-import { FLAPPY_SHARED_DEFAULT_NORMALIZATION_EPSILON } from './simulation-shared.constants';
-import type {
-  SharedObservationFeatures,
-  SharedObservationInput,
-  SharedPipeLike,
-} from './simulation-shared.types';
-
 /**
- * Resolves the next two upcoming pipes in front of the bird.
+ * Shared observation compatibility façade.
  *
- * @param pipes - Current pipe list.
- * @param birdCenterXPx - Bird center x-position.
- * @param birdRadiusPx - Bird radius.
- * @param pipeWidthPx - Pipe width.
- * @returns Tuple of first and second upcoming pipes.
- */
-export function resolveUpcomingPipes(
-  pipes: SharedPipeLike[],
-  birdCenterXPx = FLAPPY_BIRD_X_PX,
-  birdRadiusPx = FLAPPY_BIRD_RADIUS_PX,
-  pipeWidthPx = FLAPPY_PIPE_WIDTH_PX,
-): [SharedPipeLike | undefined, SharedPipeLike | undefined] {
-  const birdFrontX = birdCenterXPx - birdRadiusPx;
-  const upcomingPipes = pipes.filter(
-    (pipe) => pipe.xPx + pipeWidthPx >= birdFrontX,
-  );
-  return [upcomingPipes[0], upcomingPipes[1]];
-}
-
-/**
- * Builds the shared normalized observation feature set consumed by policies.
- *
- * @param input - Observation input bundle.
- * @returns Structured observation features.
- */
-export function resolveObservationFeatures(
-  input: SharedObservationInput,
-): SharedObservationFeatures {
-  /**
-   * Effective world height used for all vertical normalization.
-   *
-   * Why it matters: scaling by a stable height keeps feature magnitudes
-   * comparable across episodes and prevents value drift when display sizes vary.
-   */
-  const worldHeightPx = input.worldHeightPx ?? FLAPPY_WORLD_HEIGHT_PX;
-  /**
-   * Maximum downward speed used to normalize velocity-like channels.
-   *
-   * Why it matters: velocity channels become dimensionless and bounded in [-1, 1],
-   * making policy optimization numerically easier.
-   */
-  const maxFallSpeedPxPerFrame =
-    input.maxFallSpeedPxPerFrame ?? FLAPPY_MAX_FALL_SPEED_PX_PER_FRAME;
-  /** Bird center x-position used to measure forward distances to pipes. */
-  const birdCenterXPx = input.birdCenterXPx ?? FLAPPY_BIRD_X_PX;
-  /** Bird collision radius used by upcoming-pipe selection and entry/exit timing. */
-  const birdRadiusPx = input.birdRadiusPx ?? FLAPPY_BIRD_RADIUS_PX;
-  /** Pipe width used for distance-to-entry/exit and visibility checks. */
-  const pipeWidthPx = input.pipeWidthPx ?? FLAPPY_PIPE_WIDTH_PX;
-  /** Default gap size fallback when no upcoming pipe is available yet. */
-  const defaultGapSizePx = input.defaultGapSizePx ?? FLAPPY_PIPE_GAP_PX;
-  /**
-   * Small denominator guard used in time/urgency calculations.
-   *
-   * Why it matters: avoids division by zero and explosive values when
-   * speed or time-to-event become extremely small.
-   */
-  const normalizationEpsilon =
-    input.normalizationEpsilon ?? FLAPPY_SHARED_DEFAULT_NORMALIZATION_EPSILON;
-
-  /** First and second upcoming pipes used for near-term and lookahead guidance. */
-  const [nextPipe, secondPipe] = resolveUpcomingPipes(
-    input.pipes,
-    birdCenterXPx,
-    birdRadiusPx,
-    pipeWidthPx,
-  );
-  /** Bird y-position normalized to [0, 1]. */
-  const normalizedBirdY = clamp01(input.birdYPx / worldHeightPx);
-  /** Bird vertical velocity normalized to [-1, 1]. */
-  const normalizedVelocity = clamp(
-    input.velocityYPxPerFrame / maxFallSpeedPxPerFrame,
-    -1,
-    1,
-  );
-
-  /** Forward distance from bird to the next pipe corridor (pixels). */
-  const distanceToNextPipePx = nextPipe
-    ? nextPipe.xPx + pipeWidthPx - birdCenterXPx
-    : input.visibleWorldWidthPx;
-  /** Next-pipe forward distance normalized to [0, 1]. */
-  const normalizedDistanceToNextPipe = clamp01(
-    distanceToNextPipePx / input.visibleWorldWidthPx,
-  );
-
-  /** Next gap center y-position (fallback to mid-world when absent). */
-  const nextGapCenterYPx = nextPipe?.gapCenterYPx ?? worldHeightPx * 0.5;
-  /** Half-gap height for clearance and boundary calculations. */
-  const nextGapHalfPx = (nextPipe?.gapSizePx ?? defaultGapSizePx) * 0.5;
-  /** Normalized top boundary of the next gap opening. */
-  const normalizedNextGapTop = clamp01(
-    (nextGapCenterYPx - nextGapHalfPx) / worldHeightPx,
-  );
-  /** Normalized bottom boundary of the next gap opening. */
-  const normalizedNextGapBottom = clamp01(
-    (nextGapCenterYPx + nextGapHalfPx) / worldHeightPx,
-  );
-  /** Signed bird-to-next-gap-center vertical offset normalized to [-1, 1]. */
-  const normalizedDeltaToNextGap = clamp(
-    (input.birdYPx - nextGapCenterYPx) / worldHeightPx,
-    -1,
-    1,
-  );
-
-  /** Forward distance from bird to the second upcoming pipe (pixels). */
-  const distanceToSecondPipePx = secondPipe
-    ? secondPipe.xPx + pipeWidthPx - birdCenterXPx
-    : input.visibleWorldWidthPx;
-  /** Second-pipe forward distance normalized to [0, 1]. */
-  const normalizedDistanceToSecondPipe = clamp01(
-    distanceToSecondPipePx / input.visibleWorldWidthPx,
-  );
-
-  /** Second gap center y-position (fallback to next center when absent). */
-  const secondGapCenterYPx = secondPipe?.gapCenterYPx ?? nextGapCenterYPx;
-  /** Signed bird-to-second-gap-center vertical offset normalized to [-1, 1]. */
-  const normalizedDeltaToSecondGap = clamp(
-    (input.birdYPx - secondGapCenterYPx) / worldHeightPx,
-    -1,
-    1,
-  );
-
-  /** Estimated frames until reaching the next pipe (continuous-time approximation). */
-  const estimatedFramesToNextPipe =
-    distanceToNextPipePx /
-    Math.max(normalizationEpsilon, input.difficultyProfile.pipeSpeedPxPerFrame);
-  /** Urgency-like proximity to next pipe in [0, 1], where 1 means imminent. */
-  const normalizedTimeToNextPipe = clamp01(
-    1 -
-      estimatedFramesToNextPipe / Math.max(1, input.activeSpawnIntervalFrames),
-  );
-
-  /** Absolute vertical distance from bird to next gap center (pixels). */
-  const distanceToNextGapCenterPx = Math.abs(input.birdYPx - nextGapCenterYPx);
-  /** Signed clearance relative to half-gap height, normalized to [-1, 1]. */
-  const normalizedNextGapClearance = clamp(
-    (nextGapHalfPx - distanceToNextGapCenterPx) / Math.max(1, nextGapHalfPx),
-    -1,
-    1,
-  );
-
-  /** Horizontal distance to the gap entry plane (pixels). */
-  const distanceToGapEntryPx = nextPipe
-    ? nextPipe.xPx - (birdCenterXPx + birdRadiusPx)
-    : input.visibleWorldWidthPx;
-  /** Horizontal distance to the gap exit plane (pixels). */
-  const distanceToGapExitPx = nextPipe
-    ? nextPipe.xPx + pipeWidthPx - (birdCenterXPx - birdRadiusPx)
-    : input.visibleWorldWidthPx;
-
-  /** Frames until gap entry; clamped to non-negative values. */
-  const framesToGapEntry = Math.max(
-    0,
-    distanceToGapEntryPx /
-      Math.max(
-        normalizationEpsilon,
-        input.difficultyProfile.pipeSpeedPxPerFrame,
-      ),
-  );
-  /**
-   * Frames until gap exit; never smaller than entry time.
-   *
-   * Why it matters: captures tube traversal duration, which is crucial for
-   * wide-pipe timing and potential two-flap planning.
-   */
-  const framesToGapExit = Math.max(
-    framesToGapEntry,
-    distanceToGapExitPx /
-      Math.max(
-        normalizationEpsilon,
-        input.difficultyProfile.pipeSpeedPxPerFrame,
-      ),
-  );
-
-  /** Frames-to-entry normalized to [0, 1] using spawn-interval scale. */
-  const normalizedFramesToGapEntry = clamp01(
-    framesToGapEntry / Math.max(1, input.activeSpawnIntervalFrames),
-  );
-  /** Frames-to-exit normalized to [0, 1] using spawn-interval scale. */
-  const normalizedFramesToGapExit = clamp01(
-    framesToGapExit / Math.max(1, input.activeSpawnIntervalFrames),
-  );
-
-  /** Required mean vertical velocity to center at next-pipe contact window. */
-  const requiredVerticalVelocityToNextGapPxPerFrame = clamp(
-    (nextGapCenterYPx - input.birdYPx) / Math.max(1, estimatedFramesToNextPipe),
-    -maxFallSpeedPxPerFrame,
-    maxFallSpeedPxPerFrame,
-  );
-  /** Required velocity-to-next-gap channel normalized to [-1, 1]. */
-  const normalizedRequiredVerticalVelocityToNextGap = clamp(
-    requiredVerticalVelocityToNextGapPxPerFrame / maxFallSpeedPxPerFrame,
-    -1,
-    1,
-  );
-
-  /** Required mean vertical velocity to center precisely at gap entry. */
-  const requiredVerticalVelocityAtGapEntryPxPerFrame = clamp(
-    (nextGapCenterYPx - input.birdYPx) / Math.max(1, framesToGapEntry),
-    -maxFallSpeedPxPerFrame,
-    maxFallSpeedPxPerFrame,
-  );
-  /** Required mean vertical velocity to remain centered by gap exit. */
-  const requiredVerticalVelocityAtGapExitPxPerFrame = clamp(
-    (nextGapCenterYPx - input.birdYPx) / Math.max(1, framesToGapExit),
-    -maxFallSpeedPxPerFrame,
-    maxFallSpeedPxPerFrame,
-  );
-  /** Entry-target velocity normalized to [-1, 1]. */
-  const normalizedRequiredVerticalVelocityAtGapEntry = clamp(
-    requiredVerticalVelocityAtGapEntryPxPerFrame / maxFallSpeedPxPerFrame,
-    -1,
-    1,
-  );
-  /** Exit-target velocity normalized to [-1, 1]. */
-  const normalizedRequiredVerticalVelocityAtGapExit = clamp(
-    requiredVerticalVelocityAtGapExitPxPerFrame / maxFallSpeedPxPerFrame,
-    -1,
-    1,
-  );
-
-  /**
-   * Centering urgency in [0, 1]: large offset with little time-to-entry yields
-   * stronger urgency.
-   */
-  const normalizedEntryUrgency = clamp(
-    Math.abs(normalizedDeltaToNextGap) /
-      Math.max(normalizationEpsilon, normalizedFramesToGapEntry),
-    0,
-    1,
-  );
-
-  /** Predicted entry y-position if no flap occurs before entry. */
-  const predictedBirdYAtEntryWithoutFlap = resolvePredictedBirdYAtFrames(
-    input.birdYPx,
-    input.velocityYPxPerFrame,
-    framesToGapEntry,
-  );
-  /** Predicted entry y-position if one immediate flap occurs before entry. */
-  const predictedBirdYAtEntryWithOneFlap = resolvePredictedBirdYAtFrames(
-    input.birdYPx,
-    FLAPPY_FLAP_VELOCITY_PX_PER_FRAME,
-    framesToGapEntry,
-  );
-  /** Entry centering error (pixels) under no-flap trajectory. */
-  const noFlapEntryErrorPx = Math.abs(
-    predictedBirdYAtEntryWithoutFlap - nextGapCenterYPx,
-  );
-  /** Entry centering error (pixels) under one-flap trajectory. */
-  const oneFlapEntryErrorPx = Math.abs(
-    predictedBirdYAtEntryWithOneFlap - nextGapCenterYPx,
-  );
-  /** Best (minimum) entry error among one-step action hypotheses. */
-  const minimalEntryErrorPx = Math.min(noFlapEntryErrorPx, oneFlapEntryErrorPx);
-  /** Binary reachability feature: 1 when entry center is recoverable within <=1 flap. */
-  const normalizedOneFlapReachabilityAtGapEntry =
-    minimalEntryErrorPx <= nextGapHalfPx ? 1 : 0;
-
-  /** Signed centerline transition from next gap to second gap, normalized to [-1, 1]. */
-  const normalizedNextToSecondGapTransition = clamp(
-    (secondGapCenterYPx - nextGapCenterYPx) / worldHeightPx,
-    -1,
-    1,
-  );
-
-  return {
-    normalizedBirdY,
-    normalizedVelocity,
-    normalizedDistanceToNextPipe,
-    normalizedDeltaToNextGap,
-    normalizedNextGapTop,
-    normalizedNextGapBottom,
-    normalizedDistanceToSecondPipe,
-    normalizedDeltaToSecondGap,
-    normalizedTimeToNextPipe,
-    normalizedNextGapClearance,
-    normalizedRequiredVerticalVelocityToNextGap,
-    normalizedNextToSecondGapTransition,
-    normalizedFramesToGapEntry,
-    normalizedFramesToGapExit,
-    normalizedRequiredVerticalVelocityAtGapEntry,
-    normalizedRequiredVerticalVelocityAtGapExit,
-    normalizedEntryUrgency,
-    normalizedOneFlapReachabilityAtGapEntry,
-  };
-}
-
-/**
- * Converts observation features to the canonical 12-value network input vector.
- *
- * @param features - Structured feature object.
- * @returns Ordered feature vector.
- */
-export function resolveObservationVectorFromFeatures(
-  features: SharedObservationFeatures,
-): number[] {
-  return [
-    features.normalizedBirdY,
-    features.normalizedVelocity,
-    features.normalizedDistanceToNextPipe,
-    features.normalizedDeltaToNextGap,
-    features.normalizedNextGapTop,
-    features.normalizedNextGapBottom,
-    features.normalizedDistanceToSecondPipe,
-    features.normalizedDeltaToSecondGap,
-    features.normalizedTimeToNextPipe,
-    features.normalizedNextGapClearance,
-    features.normalizedRequiredVerticalVelocityToNextGap,
-    features.normalizedNextToSecondGapTransition,
-  ];
-}
-
-/**
- * Resolves the compact core vector used for temporal stacking.
- *
- * The core intentionally keeps directly observed kinematic/geometric channels
- * and drops derived one-step predictors that become redundant once temporal
- * context is available.
- *
- * @param features - Structured observation features.
- * @returns Core per-frame vector.
- */
-export function resolveCoreObservationVectorFromFeatures(
-  features: SharedObservationFeatures,
-): number[] {
-  return [
-    features.normalizedBirdY,
-    features.normalizedVelocity,
-    features.normalizedDistanceToNextPipe,
-    features.normalizedDeltaToNextGap,
-    features.normalizedNextGapTop,
-    features.normalizedNextGapBottom,
-    features.normalizedDistanceToSecondPipe,
-    features.normalizedDeltaToSecondGap,
-    features.normalizedNextGapClearance,
-    features.normalizedRequiredVerticalVelocityToNextGap,
-    features.normalizedEntryUrgency,
-    features.normalizedOneFlapReachabilityAtGapEntry,
-  ];
-}
-
-/**
- * Predicts bird y-position after a frame horizon with constant gravity.
- *
- * This lightweight estimate is used for reachability signals only.
- *
- * @param startYPx - Current bird y-position.
- * @param initialVerticalVelocityPxPerFrame - Initial vertical velocity.
- * @param frameHorizon - Predicted horizon in simulation frames.
- * @returns Predicted y-position.
- */
-function resolvePredictedBirdYAtFrames(
-  startYPx: number,
-  initialVerticalVelocityPxPerFrame: number,
-  frameHorizon: number,
-): number {
-  const safeFrameHorizon = Math.max(0, frameHorizon);
-  return (
-    startYPx +
-    initialVerticalVelocityPxPerFrame * safeFrameHorizon +
-    0.5 * FLAPPY_GRAVITY_PX_PER_FRAME2 * safeFrameHorizon * safeFrameHorizon
-  );
-}
-
-/**
- * Clamps a numeric value to the inclusive `[min, max]` interval.
- *
- * @param value - Candidate value.
- * @param min - Inclusive lower bound.
- * @param max - Inclusive upper bound.
- * @returns Clamped value.
- */
-function clamp(value: number, min: number, max: number): number {
-  return Math.min(max, Math.max(min, value));
-}
-
-/**
- * Clamps a numeric value to the inclusive `[0, 1]` interval.
+ * The observation implementation now lives under `simulation-shared/observation/`
+ * so feature synthesis and vector projection can evolve behind a focused module
+ * boundary. This file stays as the stable import path for existing callers.
  *
- * @param value - Candidate value.
- * @returns Value clamped between 0 and 1.
+ * That split keeps the high-level import path simple while allowing the
+ * observation subsystem to grow into its own documented folder.
  */
-function clamp01(value: number): number {
-  return clamp(value, 0, 1);
-}
+export * from './observation/observation';

package/test/examples/flappy_bird/simulation-shared/simulation-shared.spawn.utils.ts

@@ -17,46 +17,72 @@ import type {
 /**
  * Samples a random gap center y-position.
  *
+ * The sampled center is bounded so the resulting pipe gap always remains inside
+ * the visible play area.
+ *
  * @param rng - Deterministic RNG.
+ * @param maximumGapCenterYPx - Optional inclusive upper bound for smaller viewports.
  * @returns Sampled y-position.
  */
-export function sampleGapCenterY(rng: SharedRngLike): number {
+export function sampleGapCenterY(
+  rng: SharedRngLike,
+  maximumGapCenterYPx: number = FLAPPY_PIPE_GAP_CENTER_MAX_Y_PX,
+): number {
+  const boundedMaximumGapCenterYPx = Math.max(
+    FLAPPY_PIPE_GAP_CENTER_MIN_Y_PX,
+    maximumGapCenterYPx,
+  );
   return rng.nextInt(
     FLAPPY_PIPE_GAP_CENTER_MIN_Y_PX,
-    FLAPPY_PIPE_GAP_CENTER_MAX_Y_PX,
+    boundedMaximumGapCenterYPx,
   );
 }
 
 /**
  * Resolves next gap center with bounded per-pipe delta.
  *
+ * Educational note:
+ * Consecutive gaps are deliberately constrained to avoid unfair zig-zag jumps.
+ * The environment should still be challenging, but it should not demand an
+ * impossible vertical correction from one pipe to the next.
+ *
  * @param previousGapCenterYPx - Previous spawn gap center.
  * @param rng - Deterministic RNG.
+ * @param maximumGapCenterYPx - Optional inclusive upper bound for smaller viewports.
  * @returns Next gap center y-position.
  */
 export function resolveNextSpawnGapCenterY(
   previousGapCenterYPx: number,
   rng: SharedRngLike,
+  maximumGapCenterYPx: number = FLAPPY_PIPE_GAP_CENTER_MAX_Y_PX,
 ): number {
-  const sampledGapCenterYPx = sampleGapCenterY(rng);
+  const boundedMaximumGapCenterYPx = Math.max(
+    FLAPPY_PIPE_GAP_CENTER_MIN_Y_PX,
+    maximumGapCenterYPx,
+  );
+  const sampledGapCenterYPx = sampleGapCenterY(rng, boundedMaximumGapCenterYPx);
   const minimumGapCenterYPx = Math.max(
     FLAPPY_PIPE_GAP_CENTER_MIN_Y_PX,
     previousGapCenterYPx - FLAPPY_PIPE_GAP_CENTER_MAX_DELTA_PX,
   );
-  const maximumGapCenterYPx = Math.min(
-    FLAPPY_PIPE_GAP_CENTER_MAX_Y_PX,
+  const clampedMaximumGapCenterYPx = Math.min(
+    boundedMaximumGapCenterYPx,
     previousGapCenterYPx + FLAPPY_PIPE_GAP_CENTER_MAX_DELTA_PX,
   );
   return clampValue(
     sampledGapCenterYPx,
     minimumGapCenterYPx,
-    maximumGapCenterYPx,
+    clampedMaximumGapCenterYPx,
   );
 }
 
 /**
  * Resolves next spawn gap size using progressive shrink and jitter.
  *
+ * The gap starts wider than the current hardest target, then shrinks toward the
+ * active difficulty profile with a small amount of deterministic jitter so runs
+ * do not feel mechanically repetitive.
+ *
  * @param previousSpawnGapPx - Previous spawn gap size.
  * @param difficultyProfile - Active difficulty profile.
  * @param rng - Deterministic RNG.
@@ -94,6 +120,10 @@ export function resolveNextSpawnGapSize(
 /**
  * Resolves next spawn interval using progressive shrink.
  *
+ * This mirrors the gap-size logic: early pipes are spaced more generously, then
+ * spacing contracts toward the current difficulty target as the episode settles
+ * into its harder rhythm.
+ *
  * @param previousSpawnIntervalFrames - Previous spawn interval.
  * @param difficultyProfile - Active difficulty profile.
  * @returns Next spawn interval in frames.

package/test/examples/flappy_bird/{evaluation/evaluation.statistics.utils.ts → simulation-shared/simulation-shared.statistics.utils.ts}

@@ -1,4 +1,4 @@
-import { clampValue } from '../flappy.simulation.shared.utils';
+import { clampValue } from './simulation-shared.math.utils';
 
 /**
  * Computes arithmetic mean for numeric samples.
@@ -13,10 +13,13 @@ export function computeMean(values: readonly number[]): number {
     values.length
   );
 }
-
 /**
  * Computes population standard deviation.
  *
+ * This uses population variance rather than sample variance because the trainer
+ * is summarizing the whole evolved population for that generation, not estimating
+ * a larger hidden distribution from a subsample.
+ *
  * @param values - Numeric samples.
  * @param meanValue - Precomputed mean.
  * @returns Population standard deviation.
@@ -26,17 +29,22 @@ export function computePopulationStandardDeviation(
   meanValue: number,
 ): number {
   if (values.length === 0) return 0;
+
   const variance =
     values.reduce((accumulator, value) => {
-      const delta = value - meanValue;
-      return accumulator + delta * delta;
+      const deltaFromMean = value - meanValue;
+      return accumulator + deltaFromMean * deltaFromMean;
     }, 0) / values.length;
+
   return Math.sqrt(Math.max(0, variance));
 }
 
 /**
  * Computes percentile value via linear interpolation between nearest ranks.
  *
+ * Percentiles are useful in the trainer because they reveal whether strong
+ * performance is broad across the population or concentrated in a single outlier.
+ *
  * @param values - Numeric samples.
  * @param percentile - Percentile in [0, 1].
  * @returns Percentile value, or `Number.NaN` when `values` is empty.
@@ -46,16 +54,29 @@ export function computePercentile(
   percentile: number,
 ): number {
   if (values.length === 0) return Number.NaN;
-  const sortedValues = values.toSorted(
-    (leftValue, rightValue) => leftValue - rightValue,
-  );
+
+  const sortedValues = values.toSorted(compareNumbersAscending);
   const clampedPercentile = clampValue(percentile, 0, 1);
   const rawIndex = clampedPercentile * (sortedValues.length - 1);
   const lowerIndex = Math.floor(rawIndex);
   const upperIndex = Math.ceil(rawIndex);
-  const interpolation = rawIndex - lowerIndex;
+  const interpolationWeight = rawIndex - lowerIndex;
 
   const lowerValue = sortedValues[lowerIndex] ?? sortedValues[0] ?? Number.NaN;
   const upperValue = sortedValues[upperIndex] ?? lowerValue;
-  return lowerValue + (upperValue - lowerValue) * interpolation;
+  return lowerValue + (upperValue - lowerValue) * interpolationWeight;
+}
+
+/**
+ * Compares two numeric values in ascending order.
+ *
+ * @param leftValue - Left numeric value.
+ * @param rightValue - Right numeric value.
+ * @returns Comparator delta for `Array.prototype.toSorted`.
+ */
+function compareNumbersAscending(
+  leftValue: number,
+  rightValue: number,
+): number {
+  return leftValue - rightValue;
 }