@reicek/neataptic-ts 0.1.21 → 0.1.23

package/test/examples/flappy_bird/simulation-shared/observation/README.md

@@ -0,0 +1,255 @@
+# simulation-shared/observation
+
+## simulation-shared/observation/observation.ts
+
+### observation
+
+Shared observation public entry.
+
+This focused boundary keeps observation feature assembly separate from
+observation-vector projection so browser, environment, and worker callers can
+depend on a smaller, clearer public surface.
+
+Conceptually, this folder is the "state representation" layer for the
+Flappy Bird example. Instead of learning directly from pixels, the agent sees
+a compact set of geometric and kinematic signals derived from the current
+world state. That makes the example easier to study, faster to evaluate, and
+closer to classic feature-engineering pipelines used in small control tasks.
+
+If you want background reading, the Wikipedia articles on "feature
+engineering" and "state space representation" give useful intuition for why
+this boundary exists at all.
+
+### resolveCoreObservationVectorFromFeatures
+
+`(features: import("test/examples/flappy_bird/simulation-shared/simulation-shared.types").SharedObservationFeatures) => number[]`
+
+Resolves the compact core vector used for temporal stacking.
+
+The core intentionally keeps directly observed kinematic and geometric
+channels while dropping derived one-step predictors that become redundant
+once short-term temporal memory is available.
+
+This is the representation used when the example wants a short history of raw
+observation slices. The idea is similar to frame stacking in reinforcement
+learning: a feed-forward policy can recover some sense of motion by looking
+at several recent compact frames at once.
+
+The Wikipedia article on "frame stacking" is a useful conceptual reference.
+
+Parameters:
+- `features` - - Structured observation features.
+
+Returns: Core per-frame vector.
+
+### resolveObservationFeatures
+
+`(input: import("test/examples/flappy_bird/simulation-shared/simulation-shared.types").SharedObservationInput) => import("test/examples/flappy_bird/simulation-shared/simulation-shared.types").SharedObservationFeatures`
+
+Builds the shared normalized observation feature set consumed by policies.
+
+Educational note:
+This helper stays focused on semantic feature assembly only. Projection into
+the canonical network vectors now lives in the neighboring vector module so
+observation policy and network-shape concerns can evolve independently.
+
+The features deliberately mix three kinds of signal:
+1. Current state, such as bird height and vertical velocity.
+2. Near-term geometry, such as gap bounds and upcoming-pipe distances.
+3. Simple forward-looking control hints, such as urgency and one-flap
+   reachability.
+
+This is a compact example of feature engineering for control. Instead of
+asking NEAT to rediscover basic geometry from raw sensory input, the example
+hands the network semantically meaningful signals and lets evolution focus on
+policy search.
+
+For broader context, the Wikipedia article on "feature engineering" is a
+good companion reference.
+
+Parameters:
+- `input` - - Observation input bundle.
+
+Returns: Structured observation features.
+
+### resolveObservationVectorFromFeatures
+
+`(features: import("test/examples/flappy_bird/simulation-shared/simulation-shared.types").SharedObservationFeatures) => number[]`
+
+Converts observation features to the canonical 12-value network input vector.
+
+Educational note:
+This module owns the network-shape projection so feature semantics can change
+independently from how the policy input is ordered.
+
+The 12-value vector is the compact feed-forward policy input used by the main
+evaluation and training flow. Its ordering is stable on purpose: once a
+network topology has evolved against one input layout, silent channel
+reshuffles would invalidate learned behavior.
+
+Parameters:
+- `features` - - Structured feature object.
+
+Returns: Ordered feature vector.
+
+### resolveUpcomingPipes
+
+`(pipes: import("test/examples/flappy_bird/simulation-shared/simulation-shared.types").SharedPipeLike[], birdCenterXPx: number, birdRadiusPx: number, pipeWidthPx: number) => [import("test/examples/flappy_bird/simulation-shared/simulation-shared.types").SharedPipeLike | undefined, import("test/examples/flappy_bird/simulation-shared/simulation-shared.types").SharedPipeLike | undefined]`
+
+Resolves the next two upcoming pipes in front of the bird.
+
+The observation pipeline only cares about the immediate near future, because
+Flappy Bird decisions are dominated by the next gap and the transition after
+it. Looking further ahead adds noise faster than it adds useful control
+signal.
+
+Parameters:
+- `pipes` - - Current pipe list.
+- `birdCenterXPx` - - Bird center x-position.
+- `birdRadiusPx` - - Bird radius.
+- `pipeWidthPx` - - Pipe width.
+
+Returns: Tuple of first and second upcoming pipes.
+
+## simulation-shared/observation/observation.vector.utils.ts
+
+### resolveCoreObservationVectorFromFeatures
+
+`(features: import("test/examples/flappy_bird/simulation-shared/simulation-shared.types").SharedObservationFeatures) => number[]`
+
+Resolves the compact core vector used for temporal stacking.
+
+The core intentionally keeps directly observed kinematic and geometric
+channels while dropping derived one-step predictors that become redundant
+once short-term temporal memory is available.
+
+This is the representation used when the example wants a short history of raw
+observation slices. The idea is similar to frame stacking in reinforcement
+learning: a feed-forward policy can recover some sense of motion by looking
+at several recent compact frames at once.
+
+The Wikipedia article on "frame stacking" is a useful conceptual reference.
+
+Parameters:
+- `features` - - Structured observation features.
+
+Returns: Core per-frame vector.
+
+### resolveObservationVectorFromFeatures
+
+`(features: import("test/examples/flappy_bird/simulation-shared/simulation-shared.types").SharedObservationFeatures) => number[]`
+
+Converts observation features to the canonical 12-value network input vector.
+
+Educational note:
+This module owns the network-shape projection so feature semantics can change
+independently from how the policy input is ordered.
+
+The 12-value vector is the compact feed-forward policy input used by the main
+evaluation and training flow. Its ordering is stable on purpose: once a
+network topology has evolved against one input layout, silent channel
+reshuffles would invalidate learned behavior.
+
+Parameters:
+- `features` - - Structured feature object.
+
+Returns: Ordered feature vector.
+
+## simulation-shared/observation/observation.features.utils.ts
+
+### clamp
+
+`(value: number, min: number, max: number) => number`
+
+Clamps a numeric value to the inclusive [min, max] interval.
+
+Observation synthesis normalizes many raw measurements, so this helper keeps
+derived channels inside their documented ranges.
+
+Parameters:
+- `value` - - Candidate value.
+- `min` - - Inclusive lower bound.
+- `max` - - Inclusive upper bound.
+
+Returns: Clamped value.
+
+### clamp01
+
+`(value: number) => number`
+
+Clamps a numeric value to the inclusive [0, 1] interval.
+
+This is used for channels that are naturally interpreted as normalized
+proportions or bounded progress values.
+
+Parameters:
+- `value` - - Candidate value.
+
+Returns: Value clamped between 0 and 1.
+
+### resolveObservationFeatures
+
+`(input: import("test/examples/flappy_bird/simulation-shared/simulation-shared.types").SharedObservationInput) => import("test/examples/flappy_bird/simulation-shared/simulation-shared.types").SharedObservationFeatures`
+
+Builds the shared normalized observation feature set consumed by policies.
+
+Educational note:
+This helper stays focused on semantic feature assembly only. Projection into
+the canonical network vectors now lives in the neighboring vector module so
+observation policy and network-shape concerns can evolve independently.
+
+The features deliberately mix three kinds of signal:
+1. Current state, such as bird height and vertical velocity.
+2. Near-term geometry, such as gap bounds and upcoming-pipe distances.
+3. Simple forward-looking control hints, such as urgency and one-flap
+   reachability.
+
+This is a compact example of feature engineering for control. Instead of
+asking NEAT to rediscover basic geometry from raw sensory input, the example
+hands the network semantically meaningful signals and lets evolution focus on
+policy search.
+
+For broader context, the Wikipedia article on "feature engineering" is a
+good companion reference.
+
+Parameters:
+- `input` - - Observation input bundle.
+
+Returns: Structured observation features.
+
+### resolvePredictedBirdYAtFrames
+
+`(startYPx: number, initialVerticalVelocityPxPerFrame: number, frameHorizon: number) => number`
+
+Predicts bird y-position after a frame horizon with constant gravity.
+
+This is a deliberately cheap forward model. It ignores richer control
+sequences and simply answers: "where would the bird be after N frames under
+the current physics assumption?" That small prediction is enough to build the
+reachability and urgency features used by the controller.
+
+Parameters:
+- `startYPx` - - Current bird y-position.
+- `initialVerticalVelocityPxPerFrame` - - Initial vertical velocity.
+- `frameHorizon` - - Predicted horizon in simulation frames.
+
+Returns: Predicted y-position.
+
+### resolveUpcomingPipes
+
+`(pipes: import("test/examples/flappy_bird/simulation-shared/simulation-shared.types").SharedPipeLike[], birdCenterXPx: number, birdRadiusPx: number, pipeWidthPx: number) => [import("test/examples/flappy_bird/simulation-shared/simulation-shared.types").SharedPipeLike | undefined, import("test/examples/flappy_bird/simulation-shared/simulation-shared.types").SharedPipeLike | undefined]`
+
+Resolves the next two upcoming pipes in front of the bird.
+
+The observation pipeline only cares about the immediate near future, because
+Flappy Bird decisions are dominated by the next gap and the transition after
+it. Looking further ahead adds noise faster than it adds useful control
+signal.
+
+Parameters:
+- `pipes` - - Current pipe list.
+- `birdCenterXPx` - - Bird center x-position.
+- `birdRadiusPx` - - Bird radius.
+- `pipeWidthPx` - - Pipe width.
+
+Returns: Tuple of first and second upcoming pipes.

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

@@ -0,0 +1,339 @@
+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_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.
+ *
+ * The observation pipeline only cares about the immediate near future, because
+ * Flappy Bird decisions are dominated by the next gap and the transition after
+ * it. Looking further ahead adds noise faster than it adds useful control
+ * signal.
+ *
+ * @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.
+ * @example
+ * ```ts
+ * const [nextPipe, secondPipe] = resolveUpcomingPipes(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.
+ *
+ * Educational note:
+ * This helper stays focused on semantic feature assembly only. Projection into
+ * the canonical network vectors now lives in the neighboring vector module so
+ * observation policy and network-shape concerns can evolve independently.
+ *
+ * The features deliberately mix three kinds of signal:
+ * 1. Current state, such as bird height and vertical velocity.
+ * 2. Near-term geometry, such as gap bounds and upcoming-pipe distances.
+ * 3. Simple forward-looking control hints, such as urgency and one-flap
+ *    reachability.
+ *
+ * This is a compact example of feature engineering for control. Instead of
+ * asking NEAT to rediscover basic geometry from raw sensory input, the example
+ * hands the network semantically meaningful signals and lets evolution focus on
+ * policy search.
+ *
+ * For broader context, the Wikipedia article on "feature engineering" is a
+ * good companion reference.
+ *
+ * @param input - Observation input bundle.
+ * @returns Structured observation features.
+ * @example
+ * ```ts
+ * const features = resolveObservationFeatures({
+ *   birdYPx: 120,
+ *   velocityYPxPerFrame: 2,
+ *   pipes,
+ *   visibleWorldWidthPx: 640,
+ *   difficultyProfile,
+ *   activeSpawnIntervalFrames: 90,
+ * });
+ *
+ * if (features.normalizedEntryUrgency > 0.8) {
+ *   // The bird is misaligned and running out of time to recover.
+ * }
+ * ```
+ */
+export function resolveObservationFeatures(
+  input: SharedObservationInput,
+): SharedObservationFeatures {
+  // Step 1: Resolve normalization and geometry defaults.
+  const worldHeightPx = input.worldHeightPx ?? FLAPPY_WORLD_HEIGHT_PX;
+  const maxFallSpeedPxPerFrame =
+    input.maxFallSpeedPxPerFrame ?? FLAPPY_MAX_FALL_SPEED_PX_PER_FRAME;
+  const birdCenterXPx = input.birdCenterXPx ?? FLAPPY_BIRD_X_PX;
+  const birdRadiusPx = input.birdRadiusPx ?? FLAPPY_BIRD_RADIUS_PX;
+  const pipeWidthPx = input.pipeWidthPx ?? FLAPPY_PIPE_WIDTH_PX;
+  const defaultGapSizePx = input.defaultGapSizePx ?? FLAPPY_PIPE_GAP_PX;
+  const normalizationEpsilon =
+    input.normalizationEpsilon ?? FLAPPY_SHARED_DEFAULT_NORMALIZATION_EPSILON;
+
+  // Step 2: Resolve next-pipe geometry used by all near-term features.
+  const [nextPipe, secondPipe] = resolveUpcomingPipes(
+    input.pipes,
+    birdCenterXPx,
+    birdRadiusPx,
+    pipeWidthPx,
+  );
+  const normalizedBirdY = clamp01(input.birdYPx / worldHeightPx);
+  const normalizedVelocity = clamp(
+    input.velocityYPxPerFrame / maxFallSpeedPxPerFrame,
+    -1,
+    1,
+  );
+
+  const distanceToNextPipePx = nextPipe
+    ? nextPipe.xPx + pipeWidthPx - birdCenterXPx
+    : input.visibleWorldWidthPx;
+  const normalizedDistanceToNextPipe = clamp01(
+    distanceToNextPipePx / input.visibleWorldWidthPx,
+  );
+
+  const nextGapCenterYPx = nextPipe?.gapCenterYPx ?? worldHeightPx * 0.5;
+  const nextGapHalfPx = (nextPipe?.gapSizePx ?? defaultGapSizePx) * 0.5;
+  const normalizedNextGapTop = clamp01(
+    (nextGapCenterYPx - nextGapHalfPx) / worldHeightPx,
+  );
+  const normalizedNextGapBottom = clamp01(
+    (nextGapCenterYPx + nextGapHalfPx) / worldHeightPx,
+  );
+  const normalizedDeltaToNextGap = clamp(
+    (input.birdYPx - nextGapCenterYPx) / worldHeightPx,
+    -1,
+    1,
+  );
+
+  const distanceToSecondPipePx = secondPipe
+    ? secondPipe.xPx + pipeWidthPx - birdCenterXPx
+    : input.visibleWorldWidthPx;
+  const normalizedDistanceToSecondPipe = clamp01(
+    distanceToSecondPipePx / input.visibleWorldWidthPx,
+  );
+
+  const secondGapCenterYPx = secondPipe?.gapCenterYPx ?? nextGapCenterYPx;
+  const normalizedDeltaToSecondGap = clamp(
+    (input.birdYPx - secondGapCenterYPx) / worldHeightPx,
+    -1,
+    1,
+  );
+
+  // Step 3: Resolve timing, clearance, and controllability signals.
+  const estimatedFramesToNextPipe =
+    distanceToNextPipePx /
+    Math.max(normalizationEpsilon, input.difficultyProfile.pipeSpeedPxPerFrame);
+  const normalizedTimeToNextPipe = clamp01(
+    1 -
+      estimatedFramesToNextPipe / Math.max(1, input.activeSpawnIntervalFrames),
+  );
+
+  const distanceToNextGapCenterPx = Math.abs(input.birdYPx - nextGapCenterYPx);
+  const normalizedNextGapClearance = clamp(
+    (nextGapHalfPx - distanceToNextGapCenterPx) / Math.max(1, nextGapHalfPx),
+    -1,
+    1,
+  );
+
+  const distanceToGapEntryPx = nextPipe
+    ? nextPipe.xPx - (birdCenterXPx + birdRadiusPx)
+    : input.visibleWorldWidthPx;
+  const distanceToGapExitPx = nextPipe
+    ? nextPipe.xPx + pipeWidthPx - (birdCenterXPx - birdRadiusPx)
+    : input.visibleWorldWidthPx;
+
+  const framesToGapEntry = Math.max(
+    0,
+    distanceToGapEntryPx /
+      Math.max(
+        normalizationEpsilon,
+        input.difficultyProfile.pipeSpeedPxPerFrame,
+      ),
+  );
+  const framesToGapExit = Math.max(
+    framesToGapEntry,
+    distanceToGapExitPx /
+      Math.max(
+        normalizationEpsilon,
+        input.difficultyProfile.pipeSpeedPxPerFrame,
+      ),
+  );
+
+  const normalizedFramesToGapEntry = clamp01(
+    framesToGapEntry / Math.max(1, input.activeSpawnIntervalFrames),
+  );
+  const normalizedFramesToGapExit = clamp01(
+    framesToGapExit / Math.max(1, input.activeSpawnIntervalFrames),
+  );
+
+  const requiredVerticalVelocityToNextGapPxPerFrame = clamp(
+    (nextGapCenterYPx - input.birdYPx) / Math.max(1, estimatedFramesToNextPipe),
+    -maxFallSpeedPxPerFrame,
+    maxFallSpeedPxPerFrame,
+  );
+  const normalizedRequiredVerticalVelocityToNextGap = clamp(
+    requiredVerticalVelocityToNextGapPxPerFrame / maxFallSpeedPxPerFrame,
+    -1,
+    1,
+  );
+
+  const requiredVerticalVelocityAtGapEntryPxPerFrame = clamp(
+    (nextGapCenterYPx - input.birdYPx) / Math.max(1, framesToGapEntry),
+    -maxFallSpeedPxPerFrame,
+    maxFallSpeedPxPerFrame,
+  );
+  const requiredVerticalVelocityAtGapExitPxPerFrame = clamp(
+    (nextGapCenterYPx - input.birdYPx) / Math.max(1, framesToGapExit),
+    -maxFallSpeedPxPerFrame,
+    maxFallSpeedPxPerFrame,
+  );
+  const normalizedRequiredVerticalVelocityAtGapEntry = clamp(
+    requiredVerticalVelocityAtGapEntryPxPerFrame / maxFallSpeedPxPerFrame,
+    -1,
+    1,
+  );
+  const normalizedRequiredVerticalVelocityAtGapExit = clamp(
+    requiredVerticalVelocityAtGapExitPxPerFrame / maxFallSpeedPxPerFrame,
+    -1,
+    1,
+  );
+
+  const normalizedEntryUrgency = clamp(
+    Math.abs(normalizedDeltaToNextGap) /
+      Math.max(normalizationEpsilon, normalizedFramesToGapEntry),
+    0,
+    1,
+  );
+
+  const predictedBirdYAtEntryWithoutFlap = resolvePredictedBirdYAtFrames(
+    input.birdYPx,
+    input.velocityYPxPerFrame,
+    framesToGapEntry,
+  );
+  const predictedBirdYAtEntryWithOneFlap = resolvePredictedBirdYAtFrames(
+    input.birdYPx,
+    FLAPPY_FLAP_VELOCITY_PX_PER_FRAME,
+    framesToGapEntry,
+  );
+  const noFlapEntryErrorPx = Math.abs(
+    predictedBirdYAtEntryWithoutFlap - nextGapCenterYPx,
+  );
+  const oneFlapEntryErrorPx = Math.abs(
+    predictedBirdYAtEntryWithOneFlap - nextGapCenterYPx,
+  );
+  const minimalEntryErrorPx = Math.min(noFlapEntryErrorPx, oneFlapEntryErrorPx);
+  const normalizedOneFlapReachabilityAtGapEntry =
+    minimalEntryErrorPx <= nextGapHalfPx ? 1 : 0;
+
+  const normalizedNextToSecondGapTransition = clamp(
+    (secondGapCenterYPx - nextGapCenterYPx) / worldHeightPx,
+    -1,
+    1,
+  );
+
+  // Step 4: Return the structured feature record consumed by both runtimes.
+  return {
+    normalizedBirdY,
+    normalizedVelocity,
+    normalizedDistanceToNextPipe,
+    normalizedDeltaToNextGap,
+    normalizedNextGapTop,
+    normalizedNextGapBottom,
+    normalizedDistanceToSecondPipe,
+    normalizedDeltaToSecondGap,
+    normalizedTimeToNextPipe,
+    normalizedNextGapClearance,
+    normalizedRequiredVerticalVelocityToNextGap,
+    normalizedNextToSecondGapTransition,
+    normalizedFramesToGapEntry,
+    normalizedFramesToGapExit,
+    normalizedRequiredVerticalVelocityAtGapEntry,
+    normalizedRequiredVerticalVelocityAtGapExit,
+    normalizedEntryUrgency,
+    normalizedOneFlapReachabilityAtGapEntry,
+  };
+}
+
+/**
+ * Predicts bird y-position after a frame horizon with constant gravity.
+ *
+ * This is a deliberately cheap forward model. It ignores richer control
+ * sequences and simply answers: "where would the bird be after N frames under
+ * the current physics assumption?" That small prediction is enough to build the
+ * reachability and urgency features used by the controller.
+ *
+ * @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.
+ *
+ * Observation synthesis normalizes many raw measurements, so this helper keeps
+ * derived channels inside their documented ranges.
+ *
+ * @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.
+ *
+ * This is used for channels that are naturally interpreted as normalized
+ * proportions or bounded progress values.
+ *
+ * @param value - Candidate value.
+ * @returns Value clamped between 0 and 1.
+ */
+function clamp01(value: number): number {
+  return clamp(value, 0, 1);
+}

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

@@ -0,0 +1,19 @@
+/**
+ * Shared observation public entry.
+ *
+ * This focused boundary keeps observation feature assembly separate from
+ * observation-vector projection so browser, environment, and worker callers can
+ * depend on a smaller, clearer public surface.
+ *
+ * Conceptually, this folder is the "state representation" layer for the
+ * Flappy Bird example. Instead of learning directly from pixels, the agent sees
+ * a compact set of geometric and kinematic signals derived from the current
+ * world state. That makes the example easier to study, faster to evaluate, and
+ * closer to classic feature-engineering pipelines used in small control tasks.
+ *
+ * If you want background reading, the Wikipedia articles on "feature
+ * engineering" and "state space representation" give useful intuition for why
+ * this boundary exists at all.
+ */
+export * from './observation.features.utils';
+export * from './observation.vector.utils';

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

@@ -0,0 +1,81 @@
+import type { SharedObservationFeatures } from '../simulation-shared.types';
+
+/**
+ * Converts observation features to the canonical 12-value network input vector.
+ *
+ * Educational note:
+ * This module owns the network-shape projection so feature semantics can change
+ * independently from how the policy input is ordered.
+ *
+ * The 12-value vector is the compact feed-forward policy input used by the main
+ * evaluation and training flow. Its ordering is stable on purpose: once a
+ * network topology has evolved against one input layout, silent channel
+ * reshuffles would invalidate learned behavior.
+ *
+ * @param features - Structured feature object.
+ * @returns Ordered feature vector.
+ * @example
+ * ```ts
+ * const features = resolveObservationFeatures(input);
+ * const networkInput = resolveObservationVectorFromFeatures(features);
+ * ```
+ */
+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 and geometric
+ * channels while dropping derived one-step predictors that become redundant
+ * once short-term temporal memory is available.
+ *
+ * This is the representation used when the example wants a short history of raw
+ * observation slices. The idea is similar to frame stacking in reinforcement
+ * learning: a feed-forward policy can recover some sense of motion by looking
+ * at several recent compact frames at once.
+ *
+ * The Wikipedia article on "frame stacking" is a useful conceptual reference.
+ *
+ * @param features - Structured observation features.
+ * @returns Core per-frame vector.
+ * @example
+ * ```ts
+ * const coreFrame = resolveCoreObservationVectorFromFeatures(features);
+ * observationMemoryState.previousCoreFrames.push(coreFrame);
+ * ```
+ */
+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,
+  ];
+}