@reicek/neataptic-ts 0.1.21 → 0.1.23

package/test/examples/flappy_bird/flappy-evolution-worker/flappy-evolution-worker.simulation.frame.service.ts

@@ -0,0 +1,378 @@
+import { clamp } from '../browser-entry/browser-entry.math.utils';
+import {
+  commitObservationMemoryStep,
+  resolveFlapDecision,
+  resolveObservationVector,
+} from '../browser-entry/browser-entry.observation.utils';
+import {
+  resolveNextSpawnGapCenterY,
+  resolveNextSpawnGapSize,
+  resolveNextSpawnIntervalFrames,
+} from '../browser-entry/browser-entry.spawn.utils';
+import type { RngLike } from '../browser-entry/browser-entry.types';
+import { resolvePipeSpawnXPx } from '../browser-entry/browser-entry.viewport.utils';
+import type { SharedDifficultyProfile } from '../flappy.simulation.shared.utils';
+import { FLAPPY_BIRD_VIEWPORT_X_RATIO } from '../constants/constants';
+import {
+  FLAPPY_BIRD_RADIUS_PX,
+  FLAPPY_BIRD_X_PX,
+  FLAPPY_PIPE_COLLISION_ENTRANCE_EXPAND_PX,
+  FLAPPY_PIPE_COLLISION_SIDE_EXPAND_PX,
+  FLAPPY_CONTROL_SUBSTEPS_PER_FRAME,
+  FLAPPY_ENABLE_RUNTIME_INSTRUMENTATION,
+  FLAPPY_FLAP_VELOCITY_PX_PER_FRAME,
+  FLAPPY_GRAVITY_PX_PER_FRAME2,
+  FLAPPY_MAX_FALL_SPEED_PX_PER_FRAME,
+  FLAPPY_PIPE_WIDTH_PX,
+} from '../constants/constants';
+import type {
+  WorkerPlaybackState,
+  WorkerPopulationBird,
+  WorkerPopulationPipe,
+} from './flappy-evolution-worker.types';
+import type { WorkerPlaybackFrameContext } from './flappy-evolution-worker.simulation.types';
+
+/**
+ * Advances the whole population simulation by one logical frame.
+ *
+ * Educational note:
+ * One logical frame is internally split into smaller control substeps so the
+ * worker can make flap decisions, apply gravity, move pipes, spawn new pipes,
+ * and resolve collisions with better numerical stability than a single large
+ * integration jump.
+ *
+ * This function is the main simulation ownership boundary for the folder.
+ * The companion `simulation.utils` file creates initial state; this service is
+ * responsible for mutating that state over time.
+ *
+ * @param renderState - Mutable simulation state.
+ * @param rng - Deterministic random source for spawn variation.
+ * @param difficultyProfile - Active dynamic difficulty profile.
+ * @returns Number of policy activation calls made in this frame.
+ */
+export function stepWorkerPopulationFrame(
+  renderState: WorkerPlaybackState,
+  rng: RngLike,
+  difficultyProfile: SharedDifficultyProfile,
+): number {
+  const controlSubstepCount = Math.max(1, FLAPPY_CONTROL_SUBSTEPS_PER_FRAME);
+  const frameContext: WorkerPlaybackFrameContext = {
+    renderState,
+    rng,
+    difficultyProfile,
+    controlSubstepDelta: 1 / controlSubstepCount,
+    cameraLeftXPx: resolveCameraLeftXPx(renderState.visibleWorldWidthPx),
+    birdLeftXPx: FLAPPY_BIRD_X_PX - FLAPPY_BIRD_RADIUS_PX,
+    birdRightXPx: FLAPPY_BIRD_X_PX + FLAPPY_BIRD_RADIUS_PX,
+  };
+  let activationCallsThisFrame = 0;
+
+  // Step 1: Advance the per-frame survival counters for living birds.
+  incrementLivingBirdFrameCounters(renderState);
+
+  for (
+    let controlSubstepIndex = 0;
+    controlSubstepIndex < controlSubstepCount;
+    controlSubstepIndex++
+  ) {
+    // Step 2: Resolve one control/physics/collision substep.
+    activationCallsThisFrame += runWorkerPopulationControlSubstep(frameContext);
+  }
+
+  // Step 3: Publish the completed logical frame index.
+  renderState.frameIndex += 1;
+  return activationCallsThisFrame;
+}
+
+/**
+ * Resolves the current left-edge of the visible world in world-space pixels.
+ *
+ * @param visibleWorldWidthPx - Current visible world width.
+ * @returns Left edge x-position in world coordinates.
+ */
+function resolveCameraLeftXPx(visibleWorldWidthPx: number): number {
+  const clampedVisibleWorldWidthPx = Math.max(1, visibleWorldWidthPx);
+  const desiredBirdScreenXPx =
+    clampedVisibleWorldWidthPx * FLAPPY_BIRD_VIEWPORT_X_RATIO;
+  return FLAPPY_BIRD_X_PX - desiredBirdScreenXPx;
+}
+
+/**
+ * Increments survival counters for birds that remain active at frame start.
+ *
+ * @param renderState - Mutable playback state.
+ * @returns Nothing.
+ */
+function incrementLivingBirdFrameCounters(
+  renderState: WorkerPlaybackState,
+): void {
+  renderState.birds.forEach((bird) => {
+    if (bird.done) {
+      return;
+    }
+
+    bird.framesSurvived += 1;
+  });
+}
+
+/**
+ * Advances one control substep of the worker playback simulation.
+ *
+ * @param frameContext - Shared frame context for this logical frame.
+ * @returns Number of activation calls performed in the substep.
+ */
+function runWorkerPopulationControlSubstep(
+  frameContext: WorkerPlaybackFrameContext,
+): number {
+  const activationCallsThisSubstep = resolveBirdControlActions(frameContext);
+
+  advanceBirdPhysics(frameContext);
+  advancePipes(frameContext);
+  spawnPipeIfNeeded(frameContext);
+  resolveBirdTerminationAndProgress(frameContext);
+
+  return activationCallsThisSubstep;
+}
+
+/**
+ * Runs policy evaluation and commits the resulting observation memory updates.
+ *
+ * @param frameContext - Shared frame context for this logical frame.
+ * @returns Number of activation calls performed in the substep.
+ */
+function resolveBirdControlActions(
+  frameContext: WorkerPlaybackFrameContext,
+): number {
+  const { difficultyProfile, renderState } = frameContext;
+  let activationCallsThisSubstep = 0;
+
+  renderState.birds.forEach((bird) => {
+    if (bird.done) {
+      return;
+    }
+
+    const observation = resolveObservationVector(
+      bird.yPx,
+      bird.velocityYPxPerFrame,
+      renderState.pipes,
+      renderState.visibleWorldWidthPx,
+      renderState.visibleWorldHeightPx,
+      difficultyProfile,
+      renderState.lastSpawnedPipeSpawnIntervalFrames,
+      bird.observationMemoryState,
+    );
+    const outputs = bird.network.activate(observation.observationVector);
+    if (FLAPPY_ENABLE_RUNTIME_INSTRUMENTATION) {
+      activationCallsThisSubstep += 1;
+    }
+
+    const shouldFlap = resolveFlapDecision(outputs);
+    commitObservationMemoryStep(
+      bird.observationMemoryState,
+      observation.observationFeatures,
+      shouldFlap,
+    );
+
+    if (shouldFlap) {
+      bird.velocityYPxPerFrame = FLAPPY_FLAP_VELOCITY_PX_PER_FRAME;
+    }
+  });
+
+  return activationCallsThisSubstep;
+}
+
+/**
+ * Integrates bird velocity and vertical motion for one control substep.
+ *
+ * @param frameContext - Shared frame context for this logical frame.
+ * @returns Nothing.
+ */
+function advanceBirdPhysics(frameContext: WorkerPlaybackFrameContext): void {
+  const { controlSubstepDelta, renderState } = frameContext;
+
+  renderState.birds.forEach((bird) => {
+    if (bird.done) {
+      return;
+    }
+
+    bird.velocityYPxPerFrame = clamp(
+      bird.velocityYPxPerFrame +
+        FLAPPY_GRAVITY_PX_PER_FRAME2 * controlSubstepDelta,
+      -Infinity,
+      FLAPPY_MAX_FALL_SPEED_PX_PER_FRAME,
+    );
+    bird.yPx += bird.velocityYPxPerFrame * controlSubstepDelta;
+  });
+}
+
+/**
+ * Advances all visible pipes and culls those that have left the camera window.
+ *
+ * @param frameContext - Shared frame context for this logical frame.
+ * @returns Nothing.
+ */
+function advancePipes(frameContext: WorkerPlaybackFrameContext): void {
+  const { controlSubstepDelta, difficultyProfile, renderState, cameraLeftXPx } =
+    frameContext;
+  const pipeTravelDistancePx =
+    difficultyProfile.pipeSpeedPxPerFrame * controlSubstepDelta;
+
+  renderState.cumulativePipeTravelPx += pipeTravelDistancePx;
+
+  renderState.pipes.forEach((pipe) => {
+    pipe.xPx -= pipeTravelDistancePx;
+  });
+
+  renderState.pipes = renderState.pipes.filter(
+    (pipe) => pipe.xPx + FLAPPY_PIPE_WIDTH_PX > cameraLeftXPx,
+  );
+}
+
+/**
+ * Spawns a new pipe when the substep budget crosses the spawn boundary.
+ *
+ * @param frameContext - Shared frame context for this logical frame.
+ * @returns Nothing.
+ */
+function spawnPipeIfNeeded(frameContext: WorkerPlaybackFrameContext): void {
+  const { controlSubstepDelta, difficultyProfile, renderState, rng } =
+    frameContext;
+
+  renderState.framesUntilNextPipeSpawn -= controlSubstepDelta;
+  if (renderState.framesUntilNextPipeSpawn > 0) {
+    return;
+  }
+
+  const nextGapSizePx = resolveNextSpawnGapSize(
+    renderState.lastSpawnedPipeGapPx,
+    difficultyProfile,
+    rng,
+  );
+  const nextSpawnIntervalFrames = resolveNextSpawnIntervalFrames(
+    renderState.lastSpawnedPipeSpawnIntervalFrames,
+    difficultyProfile,
+  );
+  const nextGapCenterYPx = resolveNextSpawnGapCenterY(
+    renderState.lastSpawnedPipeGapCenterYPx,
+    rng,
+    renderState.visibleWorldHeightPx,
+  );
+
+  renderState.pipes.push({
+    id: renderState.nextPipeId++,
+    xPx: resolvePipeSpawnXPx(renderState.visibleWorldWidthPx),
+    gapCenterYPx: nextGapCenterYPx,
+    gapSizePx: nextGapSizePx,
+  });
+  renderState.lastSpawnedPipeGapPx = nextGapSizePx;
+  renderState.lastSpawnedPipeGapCenterYPx = nextGapCenterYPx;
+  renderState.lastSpawnedPipeSpawnIntervalFrames = nextSpawnIntervalFrames;
+  renderState.framesUntilNextPipeSpawn += nextSpawnIntervalFrames;
+}
+
+/**
+ * Resolves bird deaths and passed-pipe progress after motion is applied.
+ *
+ * @param frameContext - Shared frame context for this logical frame.
+ * @returns Nothing.
+ */
+function resolveBirdTerminationAndProgress(
+  frameContext: WorkerPlaybackFrameContext,
+): void {
+  const { renderState } = frameContext;
+
+  renderState.birds.forEach((bird) => {
+    if (bird.done) {
+      return;
+    }
+
+    if (resolveBirdOutOfBounds(bird, renderState.visibleWorldHeightPx)) {
+      bird.done = true;
+      bird.doneReason = 'out_of_bounds';
+      return;
+    }
+
+    for (const pipe of renderState.pipes) {
+      if (resolveBirdCollisionAgainstPipe(bird, pipe, frameContext)) {
+        bird.done = true;
+        bird.doneReason = 'collision';
+        break;
+      }
+
+      commitPassedPipeProgress(bird, pipe);
+    }
+  });
+}
+
+/**
+ * Resolves whether a bird has exceeded the vertical play area.
+ *
+ * @param bird - Mutable bird state.
+ * @param visibleWorldHeightPx - Current visible world height.
+ * @returns `true` when the bird is outside the vertical bounds.
+ */
+function resolveBirdOutOfBounds(
+  bird: WorkerPopulationBird,
+  visibleWorldHeightPx: number,
+): boolean {
+  const birdTop = bird.yPx - FLAPPY_BIRD_RADIUS_PX;
+  const birdBottom = bird.yPx + FLAPPY_BIRD_RADIUS_PX;
+
+  return birdTop <= 0 || birdBottom >= visibleWorldHeightPx;
+}
+
+/**
+ * Resolves whether a bird collides with one pipe corridor during this substep.
+ *
+ * @param bird - Mutable bird state.
+ * @param pipe - Pipe candidate to test.
+ * @param frameContext - Shared frame context for this logical frame.
+ * @returns `true` when the bird overlaps the pipe body instead of the gap.
+ */
+function resolveBirdCollisionAgainstPipe(
+  bird: WorkerPopulationBird,
+  pipe: WorkerPopulationPipe,
+  frameContext: WorkerPlaybackFrameContext,
+): boolean {
+  const { birdLeftXPx, birdRightXPx } = frameContext;
+  const birdTop = bird.yPx - FLAPPY_BIRD_RADIUS_PX;
+  const birdBottom = bird.yPx + FLAPPY_BIRD_RADIUS_PX;
+  const pipeLeft = pipe.xPx - FLAPPY_PIPE_COLLISION_SIDE_EXPAND_PX;
+  const pipeRight =
+    pipe.xPx + FLAPPY_PIPE_WIDTH_PX + FLAPPY_PIPE_COLLISION_SIDE_EXPAND_PX;
+  const overlapsHorizontally =
+    birdRightXPx >= pipeLeft && birdLeftXPx <= pipeRight;
+
+  if (!overlapsHorizontally) {
+    return false;
+  }
+
+  const gapHalf = pipe.gapSizePx * 0.5;
+  const gapTop =
+    pipe.gapCenterYPx - gapHalf + FLAPPY_PIPE_COLLISION_ENTRANCE_EXPAND_PX;
+  const gapBottom =
+    pipe.gapCenterYPx + gapHalf - FLAPPY_PIPE_COLLISION_ENTRANCE_EXPAND_PX;
+
+  return !(birdTop >= gapTop && birdBottom <= gapBottom);
+}
+
+/**
+ * Commits one passed-pipe progress increment for a bird when eligible.
+ *
+ * @param bird - Mutable bird state.
+ * @param pipe - Pipe candidate to mark as passed.
+ * @returns Nothing.
+ */
+function commitPassedPipeProgress(
+  bird: WorkerPopulationBird,
+  pipe: WorkerPopulationPipe,
+): void {
+  const pipeRight =
+    pipe.xPx + FLAPPY_PIPE_WIDTH_PX + FLAPPY_PIPE_COLLISION_SIDE_EXPAND_PX;
+  if (pipeRight >= FLAPPY_BIRD_X_PX || bird.passedPipeIds.has(pipe.id)) {
+    return;
+  }
+
+  bird.passedPipeIds.add(pipe.id);
+  bird.pipesPassed += 1;
+}

package/test/examples/flappy_bird/flappy-evolution-worker/flappy-evolution-worker.simulation.types.ts

@@ -0,0 +1,22 @@
+import type { RngLike } from '../browser-entry/browser-entry.types';
+import type { SharedDifficultyProfile } from '../flappy.simulation.shared.utils';
+import type { WorkerPlaybackState } from './flappy-evolution-worker.types';
+
+/**
+ * Shared mutable inputs for one worker playback frame simulation pass.
+ *
+ * Educational note:
+ * The frame service computes several derived geometry values once per logical
+ * frame and threads them through the substep helpers in this context object.
+ * That keeps the top-level simulation flow declarative while avoiding repeated
+ * argument sprawl across helper calls.
+ */
+export interface WorkerPlaybackFrameContext {
+  renderState: WorkerPlaybackState;
+  rng: RngLike;
+  difficultyProfile: SharedDifficultyProfile;
+  controlSubstepDelta: number;
+  cameraLeftXPx: number;
+  birdLeftXPx: number;
+  birdRightXPx: number;
+}

package/test/examples/flappy_bird/flappy-evolution-worker/flappy-evolution-worker.simulation.utils.ts

@@ -1,52 +1,35 @@
 import type Network from '../../../../src/architecture/network';
-import { clamp } from '../browser-entry/browser-entry.math.utils';
 import {
-  commitObservationMemoryStep,
-  resolveFlapDecision,
-  resolveObservationVector,
-} from '../browser-entry/browser-entry.observation.utils';
-import {
-  createBirdColor,
-  resolveDifficultyProfile,
-  resolveNextSpawnGapCenterY,
   resolveNextSpawnGapSize,
   resolveNextSpawnIntervalFrames,
   sampleGapCenterY,
 } from '../browser-entry/browser-entry.spawn.utils';
 import type { RngLike } from '../browser-entry/browser-entry.types';
 import { resolvePipeSpawnXPx } from '../browser-entry/browser-entry.viewport.utils';
-import { createSharedObservationMemoryState } from '../flappy.simulation.shared.utils';
-import { FLAPPY_BIRD_VIEWPORT_X_RATIO } from '../constants/constants';
 import {
-  FLAPPY_BIRD_RADIUS_PX,
-  FLAPPY_BIRD_X_PX,
-  FLAPPY_PIPE_COLLISION_ENTRANCE_EXPAND_PX,
-  FLAPPY_PIPE_COLLISION_SIDE_EXPAND_PX,
-  FLAPPY_CONTROL_SUBSTEPS_PER_FRAME,
-  FLAPPY_ENABLE_RUNTIME_INSTRUMENTATION,
-  FLAPPY_FLAP_VELOCITY_PX_PER_FRAME,
-  FLAPPY_GRAVITY_PX_PER_FRAME2,
-  FLAPPY_MAX_FALL_SPEED_PX_PER_FRAME,
-  FLAPPY_PIPE_WIDTH_PX,
-} from '../constants/constants';
+  createSharedObservationMemoryState,
+  resolveAdaptiveDifficultyProfile,
+} from '../flappy.simulation.shared.utils';
 import type { WorkerPlaybackState } from './flappy-evolution-worker.types';
 
-/**
- * Resolves the current left-edge of the visible world in world-space pixels.
- *
- * @param visibleWorldWidthPx - Current visible world width.
- * @returns Left edge x-position in world coordinates.
- */
-function resolveCameraLeftXPx(visibleWorldWidthPx: number): number {
-  const clampedVisibleWorldWidthPx = Math.max(1, visibleWorldWidthPx);
-  const desiredBirdScreenXPx =
-    clampedVisibleWorldWidthPx * FLAPPY_BIRD_VIEWPORT_X_RATIO;
-  return FLAPPY_BIRD_X_PX - desiredBirdScreenXPx;
-}
-
 /**
  * Creates initial playback state for a population of networks.
  *
+ * Educational note:
+ * This is the ownership boundary for worker playback initialization. The frame
+ * simulation service mutates the returned state on every step, but only this
+ * helper decides how a fresh population is placed into the world at time zero.
+ *
+ * @example
+ * ```ts
+ * const playbackState = createWorkerPopulationRenderState(
+ *   currentPopulation,
+ *   rng,
+ *   1280,
+ *   720,
+ * );
+ * ```
+ *
  * @param networks - Population to visualize.
  * @param rng - Deterministic random source.
  * @param initialVisibleWorldWidthPx - Initial viewport width from host.
@@ -59,7 +42,7 @@ export function createWorkerPopulationRenderState(
   initialVisibleWorldWidthPx: number,
   initialVisibleWorldHeightPx: number,
 ): WorkerPlaybackState {
-  const initialDifficultyProfile = resolveDifficultyProfile(0);
+  const initialDifficultyProfile = resolveAdaptiveDifficultyProfile(0, 1);
   const initialGapCenterYPx = sampleGapCenterY(
     rng,
     initialVisibleWorldHeightPx,
@@ -76,7 +59,6 @@ export function createWorkerPopulationRenderState(
 
   const birds = networks.map((network, networkIndex) => ({
     network,
-    color: createBirdColor(networkIndex, networks.length),
     observationMemoryState: createSharedObservationMemoryState(),
     yPx: initialVisibleWorldHeightPx * 0.5,
     velocityYPxPerFrame: 0,
@@ -88,6 +70,7 @@ export function createWorkerPopulationRenderState(
 
   return {
     frameIndex: 0,
+    cumulativePipeTravelPx: 0,
     visibleWorldWidthPx: initialVisibleWorldWidthPx,
     visibleWorldHeightPx: initialVisibleWorldHeightPx,
     nextPipeId: 2,
@@ -106,169 +89,3 @@ export function createWorkerPopulationRenderState(
     birds,
   };
 }
-
-/**
- * Advances the whole population simulation by one logical frame.
- *
- * @param renderState - Mutable simulation state.
- * @param rng - Deterministic random source for spawn variation.
- * @param difficultyProfile - Active dynamic difficulty profile.
- * @returns Number of policy activation calls made in this frame.
- */
-export function stepWorkerPopulationFrame(
-  renderState: WorkerPlaybackState,
-  rng: RngLike,
-  difficultyProfile: {
-    pipeGapPx: number;
-    pipeSpeedPxPerFrame: number;
-    pipeSpawnIntervalFrames: number;
-  },
-): number {
-  const controlSubstepCount = Math.max(1, FLAPPY_CONTROL_SUBSTEPS_PER_FRAME);
-  const controlSubstepDelta = 1 / controlSubstepCount;
-  let activationCallsThisFrame = 0;
-
-  renderState.birds.forEach((bird) => {
-    if (bird.done) return;
-    bird.framesSurvived += 1;
-  });
-
-  for (
-    let controlSubstepIndex = 0;
-    controlSubstepIndex < controlSubstepCount;
-    controlSubstepIndex++
-  ) {
-    renderState.birds.forEach((bird) => {
-      if (bird.done) return;
-
-      const observation = resolveObservationVector(
-        bird.yPx,
-        bird.velocityYPxPerFrame,
-        renderState.pipes,
-        renderState.visibleWorldWidthPx,
-        renderState.visibleWorldHeightPx,
-        difficultyProfile,
-        renderState.lastSpawnedPipeSpawnIntervalFrames,
-        bird.observationMemoryState,
-      );
-      const outputs = bird.network.activate(
-        observation.observationVector,
-      ) as unknown;
-      if (FLAPPY_ENABLE_RUNTIME_INSTRUMENTATION) {
-        activationCallsThisFrame += 1;
-      }
-      const shouldFlap = resolveFlapDecision(outputs);
-      commitObservationMemoryStep(
-        bird.observationMemoryState,
-        observation.observationFeatures,
-        shouldFlap,
-      );
-
-      if (shouldFlap) {
-        bird.velocityYPxPerFrame = FLAPPY_FLAP_VELOCITY_PX_PER_FRAME;
-      }
-    });
-
-    renderState.birds.forEach((bird) => {
-      if (bird.done) return;
-
-      bird.velocityYPxPerFrame = clamp(
-        bird.velocityYPxPerFrame +
-          FLAPPY_GRAVITY_PX_PER_FRAME2 * controlSubstepDelta,
-        -Infinity,
-        FLAPPY_MAX_FALL_SPEED_PX_PER_FRAME,
-      );
-      bird.yPx += bird.velocityYPxPerFrame * controlSubstepDelta;
-    });
-
-    renderState.pipes.forEach((pipe) => {
-      pipe.xPx -= difficultyProfile.pipeSpeedPxPerFrame * controlSubstepDelta;
-    });
-
-    const cameraLeftXPx = resolveCameraLeftXPx(renderState.visibleWorldWidthPx);
-    renderState.pipes = renderState.pipes.filter(
-      (pipe) => pipe.xPx + FLAPPY_PIPE_WIDTH_PX > cameraLeftXPx,
-    );
-
-    renderState.framesUntilNextPipeSpawn -= controlSubstepDelta;
-    if (renderState.framesUntilNextPipeSpawn <= 0) {
-      const nextGapSizePx = resolveNextSpawnGapSize(
-        renderState.lastSpawnedPipeGapPx,
-        difficultyProfile,
-        rng,
-      );
-      const nextSpawnIntervalFrames = resolveNextSpawnIntervalFrames(
-        renderState.lastSpawnedPipeSpawnIntervalFrames,
-        difficultyProfile,
-      );
-      const nextGapCenterYPx = resolveNextSpawnGapCenterY(
-        renderState.lastSpawnedPipeGapCenterYPx,
-        rng,
-        renderState.visibleWorldHeightPx,
-      );
-      renderState.pipes.push({
-        id: renderState.nextPipeId++,
-        xPx: resolvePipeSpawnXPx(renderState.visibleWorldWidthPx),
-        gapCenterYPx: nextGapCenterYPx,
-        gapSizePx: nextGapSizePx,
-      });
-      renderState.lastSpawnedPipeGapPx = nextGapSizePx;
-      renderState.lastSpawnedPipeGapCenterYPx = nextGapCenterYPx;
-      renderState.lastSpawnedPipeSpawnIntervalFrames = nextSpawnIntervalFrames;
-      renderState.framesUntilNextPipeSpawn += nextSpawnIntervalFrames;
-    }
-
-    renderState.birds.forEach((bird) => {
-      if (bird.done) return;
-
-      const birdTop = bird.yPx - FLAPPY_BIRD_RADIUS_PX;
-      const birdBottom = bird.yPx + FLAPPY_BIRD_RADIUS_PX;
-
-      if (birdTop <= 0 || birdBottom >= renderState.visibleWorldHeightPx) {
-        bird.done = true;
-        bird.doneReason = 'out_of_bounds';
-        return;
-      }
-
-      const birdLeft = FLAPPY_BIRD_X_PX - FLAPPY_BIRD_RADIUS_PX;
-      const birdRight = FLAPPY_BIRD_X_PX + FLAPPY_BIRD_RADIUS_PX;
-
-      for (const pipe of renderState.pipes) {
-        const pipeLeft = pipe.xPx - FLAPPY_PIPE_COLLISION_SIDE_EXPAND_PX;
-        const pipeRight =
-          pipe.xPx +
-          FLAPPY_PIPE_WIDTH_PX +
-          FLAPPY_PIPE_COLLISION_SIDE_EXPAND_PX;
-        const overlapsHorizontally =
-          birdRight >= pipeLeft && birdLeft <= pipeRight;
-
-        if (overlapsHorizontally) {
-          const gapHalf = pipe.gapSizePx * 0.5;
-          const gapTop =
-            pipe.gapCenterYPx -
-            gapHalf +
-            FLAPPY_PIPE_COLLISION_ENTRANCE_EXPAND_PX;
-          const gapBottom =
-            pipe.gapCenterYPx +
-            gapHalf -
-            FLAPPY_PIPE_COLLISION_ENTRANCE_EXPAND_PX;
-          const isInsideGap = birdTop >= gapTop && birdBottom <= gapBottom;
-
-          if (!isInsideGap) {
-            bird.done = true;
-            bird.doneReason = 'collision';
-            break;
-          }
-        }
-
-        if (pipeRight < FLAPPY_BIRD_X_PX && !bird.passedPipeIds.has(pipe.id)) {
-          bird.passedPipeIds.add(pipe.id);
-          bird.pipesPassed += 1;
-        }
-      }
-    });
-  }
-
-  renderState.frameIndex += 1;
-  return activationCallsThisFrame;
-}