@reicek/neataptic-ts 0.1.21 → 0.1.23

package/test/examples/flappy_bird/browser-entry/playback/frame-render/playback.frame-render.service.ts

@@ -0,0 +1,113 @@
+import {
+  FLAPPY_BIRD_RADIUS_PX,
+  FLAPPY_BIRD_X_PX,
+} from '../../../constants/constants';
+import type {
+  PopulationRenderState,
+  TrailState,
+} from '../../browser-entry.types';
+import { resolveChampionBirdIndex } from '../playback.render.utils';
+import { pushChampionTrailPoint } from '../playback.trail.utils';
+import {
+  beginPlaybackFrameViewportTransform,
+  finalizePlaybackFrameCanvas,
+  preparePlaybackFrameCanvas,
+  renderPlaybackFrameBackground,
+  renderPlaybackFrameBirds,
+  renderPlaybackFramePipes,
+  renderPlaybackFrameTrails,
+  resolvePlaybackFrameSceneContext,
+} from './playback.frame-render.services';
+import {
+  drawTrail,
+  renderPlaybackBird,
+  resolvePlaybackTrailStyle,
+} from './playback.frame-render.utils';
+
+/**
+ * High-level frame-render orchestration for playback.
+ *
+ * This boundary coordinates one visual frame of the playback experience. It
+ * resolves the scene, prepares the canvas, paints the background and entities,
+ * and maintains the short champion trail used for motion emphasis.
+ */
+
+/**
+ * Draws one simulation frame for the current population state.
+ *
+ * The render order matters: background first, then pipes, then birds, then
+ * trails and overlays that should visually sit on top.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param renderState - Mutable simulation state snapshot.
+ * @param trailState - Leader trail render cache.
+ * @returns Nothing.
+ */
+export function renderPopulationFrame(
+  context: CanvasRenderingContext2D,
+  renderState: PopulationRenderState,
+  trailState: TrailState,
+): void {
+  // Step 1: Resolve scene geometry and champion render state.
+  const sceneContext = resolvePlaybackFrameSceneContext(context, renderState);
+
+  // Step 2: Reset canvas state and enter the viewport transform.
+  preparePlaybackFrameCanvas(context);
+  beginPlaybackFrameViewportTransform(context, sceneContext);
+
+  // Step 3: Draw the split background, pipes, birds, and trails in order.
+  renderPlaybackFrameBackground(context, renderState, sceneContext);
+  renderPlaybackFramePipes(context, renderState, sceneContext);
+  renderPlaybackFrameBirds(
+    context,
+    renderState,
+    sceneContext,
+    renderPlaybackBird,
+  );
+  renderPlaybackFrameTrails(
+    context,
+    renderState,
+    trailState,
+    sceneContext,
+    resolvePlaybackTrailStyle,
+    drawTrail,
+  );
+
+  // Step 4: Restore the caller canvas state after viewport-space drawing.
+  finalizePlaybackFrameCanvas(context);
+}
+
+/**
+ * Updates the trail cache from the latest frame snapshot.
+ *
+ * The renderer intentionally keeps only a short champion trail instead of full
+ * history for every bird, which keeps the visual emphasis clear and the per-frame
+ * work small.
+ *
+ * @param trailState - Mutable trail state.
+ * @param renderState - Current render state.
+ * @returns Nothing.
+ */
+export function updateTrailState(
+  trailState: TrailState,
+  renderState: PopulationRenderState,
+): void {
+  // Step 1: Resolve the current champion so only one short trail is retained.
+  const championBirdIndex = resolveChampionBirdIndex(renderState);
+
+  // Step 2: Reset all non-champion trails to avoid per-frame trail work.
+  renderState.birds.forEach((bird, birdIndex) => {
+    if (!trailState.birdTrailsY[birdIndex]) {
+      trailState.birdTrailsY[birdIndex] = [];
+    }
+    const birdTrail = trailState.birdTrailsY[birdIndex];
+
+    if (bird.done || birdIndex !== championBirdIndex) {
+      birdTrail.length = 0;
+      return;
+    }
+
+    // Step 3: Keep a short trail only for the current champion bird.
+    pushChampionTrailPoint(birdTrail, renderState.frameIndex, bird.yPx);
+  });
+}

package/test/examples/flappy_bird/browser-entry/playback/frame-render/playback.frame-render.services.ts

@@ -0,0 +1,35 @@
+import type {
+  PopulationRenderState,
+  TrailState,
+} from '../../browser-entry.types';
+import {
+  beginPlaybackFrameViewportTransform,
+  finalizePlaybackFrameCanvas,
+  preparePlaybackFrameCanvas,
+} from './playback.frame-render.canvas.services';
+import {
+  renderPlaybackFrameBackground,
+  renderPlaybackFrameBirds,
+  renderPlaybackFramePipes,
+  renderPlaybackFrameTrails,
+} from './playback.frame-render.entity.services';
+import { resolvePlaybackFrameSceneContext } from './playback.frame-render.scene.services';
+import type {
+  PlaybackBirdRenderer,
+  PlaybackFrameSceneContext,
+  PlaybackTrailRenderer,
+  PlaybackTrailRenderStyle,
+  PlaybackTrailStyleResolver,
+} from './playback.frame-render.types';
+export {
+  beginPlaybackFrameViewportTransform,
+  finalizePlaybackFrameCanvas,
+  preparePlaybackFrameCanvas,
+} from './playback.frame-render.canvas.services';
+export {
+  renderPlaybackFrameBackground,
+  renderPlaybackFrameBirds,
+  renderPlaybackFramePipes,
+  renderPlaybackFrameTrails,
+} from './playback.frame-render.entity.services';
+export { resolvePlaybackFrameSceneContext } from './playback.frame-render.scene.services';

package/test/examples/flappy_bird/browser-entry/playback/frame-render/playback.frame-render.trail.utils.ts

@@ -0,0 +1,248 @@
+import {
+  FLAPPY_NEON_PALETTE,
+  FLAPPY_NON_CHAMPION_OPACITY,
+  FLAPPY_PIPE_SPEED_PX_PER_FRAME,
+  FLAPPY_TRAIL_LINE_WIDTH_PX,
+  FLAPPY_TRAIL_MIN_HORIZONTAL_SEGMENT_PX,
+  FLAPPY_TRAIL_MIN_VERTICAL_SEGMENT_PX,
+  FLAPPY_TRAIL_OPACITY_FACTOR,
+} from '../../../constants/constants';
+import type { TrailPoint } from '../../browser-entry.types';
+import {
+  resolveEdgeOpacityFactor,
+  resolveTrailLifetimeOpacityFactor,
+} from '../playback.trail.utils';
+import type { PlaybackEdgeBounds } from '../playback.types';
+import type { PlaybackTrailRenderStyle } from './playback.frame-render.types';
+
+/**
+ * Detailed trail-painting helpers for playback frames.
+ *
+ * Trails are rendered as stepped segments with both lifetime fading and edge
+ * fading so motion remains legible without overwhelming the scene.
+ */
+
+/**
+ * Resolves the trail style used for one bird's stepped trail.
+ *
+ * Champion trails are emphasized while non-champion trails, when present, are
+ * intentionally subdued.
+ *
+ * @param birdIndex - Index of the bird being rendered.
+ * @param championBirdIndex - Champion index for the current frame.
+ * @returns Base opacity and color for the bird trail.
+ */
+export function resolvePlaybackTrailStyle(
+  birdIndex: number,
+  championBirdIndex: number,
+): PlaybackTrailRenderStyle {
+  const isChampionBird = birdIndex === championBirdIndex;
+  return {
+    baseOpacity:
+      (isChampionBird ? 1 : FLAPPY_NON_CHAMPION_OPACITY) *
+      FLAPPY_TRAIL_OPACITY_FACTOR,
+    trailColor: isChampionBird
+      ? FLAPPY_NEON_PALETTE.trail
+      : FLAPPY_NEON_PALETTE.nonChampionBird,
+  };
+}
+
+/**
+ * Draws the stepped trail history for one active bird.
+ *
+ * The stepped shape makes the trajectory feel more schematic and readable than a
+ * perfectly smooth spline, which fits the overall instrument-panel aesthetic.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param trailPoints - Cached per-frame trail points for one bird.
+ * @param color - Stroke color for the trail.
+ * @param anchorX - Bird anchor x-position in world space.
+ * @param baseOpacity - Base opacity before edge and lifetime fading.
+ * @param edgeBounds - Visible world bounds used for edge fading.
+ * @returns Nothing.
+ */
+export function drawTrail(
+  context: CanvasRenderingContext2D,
+  trailPoints: TrailPoint[],
+  color: string,
+  anchorX: number,
+  baseOpacity: number,
+  edgeBounds: PlaybackEdgeBounds,
+): void {
+  if (trailPoints.length === 0) {
+    return;
+  }
+
+  const latestTrailFrameIndex = trailPoints.at(-1)?.frameIndex ?? 0;
+  const firstTrailPoint = trailPoints[0];
+  const firstTrailFrameOffset = Math.max(
+    0,
+    latestTrailFrameIndex - firstTrailPoint.frameIndex,
+  );
+  let previousXPosition =
+    anchorX - firstTrailFrameOffset * FLAPPY_PIPE_SPEED_PX_PER_FRAME;
+  let previousYPosition = firstTrailPoint.yPx;
+  let previousFrameOffset = firstTrailFrameOffset;
+  const maximumTrailFrameOffset = Math.max(1, firstTrailFrameOffset);
+
+  const previousGlobalAlpha = context.globalAlpha;
+  context.strokeStyle = color;
+  context.lineWidth = FLAPPY_TRAIL_LINE_WIDTH_PX;
+
+  trailPoints.slice(1).forEach((trailPoint) => {
+    const frameOffset = Math.max(
+      0,
+      latestTrailFrameIndex - trailPoint.frameIndex,
+    );
+    const nextXPosition =
+      anchorX - frameOffset * FLAPPY_PIPE_SPEED_PX_PER_FRAME;
+    const nextYPosition = trailPoint.yPx;
+
+    const horizontalDeltaPx = nextXPosition - previousXPosition;
+    const horizontalDirection = Math.sign(horizontalDeltaPx) || 1;
+    const steppedHorizontalLengthPx = Math.max(
+      Math.abs(horizontalDeltaPx),
+      FLAPPY_TRAIL_MIN_HORIZONTAL_SEGMENT_PX,
+    );
+    const steppedHorizontalXPosition =
+      previousXPosition + horizontalDirection * steppedHorizontalLengthPx;
+    drawTrailSegmentWithEdgeFade(
+      context,
+      previousXPosition,
+      previousYPosition,
+      steppedHorizontalXPosition,
+      previousYPosition,
+      baseOpacity,
+      edgeBounds,
+      previousFrameOffset,
+      frameOffset,
+      maximumTrailFrameOffset,
+    );
+    previousXPosition = steppedHorizontalXPosition;
+
+    const verticalDeltaPx = nextYPosition - previousYPosition;
+    if (verticalDeltaPx !== 0) {
+      const verticalDirection = Math.sign(verticalDeltaPx);
+      const steppedVerticalLengthPx = Math.max(
+        Math.abs(verticalDeltaPx),
+        FLAPPY_TRAIL_MIN_VERTICAL_SEGMENT_PX,
+      );
+      const steppedVerticalYPosition =
+        previousYPosition + verticalDirection * steppedVerticalLengthPx;
+      drawTrailSegmentWithEdgeFade(
+        context,
+        previousXPosition,
+        previousYPosition,
+        steppedHorizontalXPosition,
+        steppedVerticalYPosition,
+        baseOpacity,
+        edgeBounds,
+        previousFrameOffset,
+        frameOffset,
+        maximumTrailFrameOffset,
+      );
+      previousYPosition = steppedVerticalYPosition;
+    }
+
+    drawTrailSegmentWithEdgeFade(
+      context,
+      previousXPosition,
+      previousYPosition,
+      steppedHorizontalXPosition,
+      nextYPosition,
+      baseOpacity,
+      edgeBounds,
+      previousFrameOffset,
+      frameOffset,
+      maximumTrailFrameOffset,
+    );
+    previousYPosition = nextYPosition;
+
+    drawTrailSegmentWithEdgeFade(
+      context,
+      previousXPosition,
+      previousYPosition,
+      nextXPosition,
+      nextYPosition,
+      baseOpacity,
+      edgeBounds,
+      previousFrameOffset,
+      frameOffset,
+      maximumTrailFrameOffset,
+    );
+    previousXPosition = nextXPosition;
+    previousYPosition = nextYPosition;
+    previousFrameOffset = frameOffset;
+  });
+
+  context.globalAlpha = previousGlobalAlpha;
+}
+
+/**
+ * Draws one trail segment with combined edge and lifetime fading.
+ *
+ * Two independent fade signals are combined here: old segments dim over time,
+ * and segments near the viewport edge fade to avoid harsh clipping.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param startXPx - Segment start x-position.
+ * @param startYPx - Segment start y-position.
+ * @param endXPx - Segment end x-position.
+ * @param endYPx - Segment end y-position.
+ * @param baseOpacity - Base opacity before fade factors.
+ * @param edgeBounds - Visible world bounds used for edge fading.
+ * @param startFrameOffset - Relative age of the segment start.
+ * @param endFrameOffset - Relative age of the segment end.
+ * @param maximumTrailFrameOffset - Oldest visible trail age.
+ * @returns Nothing.
+ */
+function drawTrailSegmentWithEdgeFade(
+  context: CanvasRenderingContext2D,
+  startXPx: number,
+  startYPx: number,
+  endXPx: number,
+  endYPx: number,
+  baseOpacity: number,
+  edgeBounds: PlaybackEdgeBounds,
+  startFrameOffset: number,
+  endFrameOffset: number,
+  maximumTrailFrameOffset: number,
+): void {
+  const segmentLengthPx = Math.hypot(endXPx - startXPx, endYPx - startYPx);
+  if (segmentLengthPx === 0 || baseOpacity <= 0) {
+    return;
+  }
+
+  const startOpacityFactor = resolveEdgeOpacityFactor(
+    startXPx,
+    startYPx,
+    edgeBounds,
+  );
+  const endOpacityFactor = resolveEdgeOpacityFactor(endXPx, endYPx, edgeBounds);
+  const edgeOpacityFactor = Math.min(startOpacityFactor, endOpacityFactor);
+
+  const startLifetimeOpacityFactor = resolveTrailLifetimeOpacityFactor(
+    startFrameOffset,
+    maximumTrailFrameOffset,
+  );
+  const endLifetimeOpacityFactor = resolveTrailLifetimeOpacityFactor(
+    endFrameOffset,
+    maximumTrailFrameOffset,
+  );
+  const lifetimeOpacityFactor = Math.min(
+    startLifetimeOpacityFactor,
+    endLifetimeOpacityFactor,
+  );
+
+  const segmentOpacity =
+    baseOpacity * edgeOpacityFactor * lifetimeOpacityFactor;
+  if (segmentOpacity <= 0) {
+    return;
+  }
+
+  context.globalAlpha = segmentOpacity;
+  context.beginPath();
+  context.moveTo(startXPx, startYPx);
+  context.lineTo(endXPx, endYPx);
+  context.stroke();
+}

package/test/examples/flappy_bird/browser-entry/playback/frame-render/playback.frame-render.types.ts

@@ -0,0 +1,103 @@
+import { resolveWorldViewport } from '../../browser-entry.viewport.utils';
+import type { TrailPoint } from '../../browser-entry.types';
+import type { PlaybackEdgeBounds } from '../playback.types';
+import type { PlaybackBirdRenderStyle } from '../playback.render.utils';
+
+/**
+ * Local type contracts for playback frame rendering.
+ *
+ * These types are extracted from the broader frame renderer so scene state,
+ * bird geometry, and trail styling can evolve behind a dedicated module
+ * boundary.
+ *
+ * Together they describe the inputs and intermediate state needed to paint one
+ * world-space frame on the browser canvas.
+ */
+
+/**
+ * Shared scene contract used by one playback frame render pass.
+ *
+ * This collects the camera, viewport, and champion metadata that multiple frame
+ * render helpers need during the same paint pass.
+ */
+export type PlaybackFrameSceneContext = {
+  viewport: ReturnType<typeof resolveWorldViewport>;
+  visibleWorldWidthPx: number;
+  visibleWorldHeightPx: number;
+  cameraLeftPx: number;
+  championBirdIndex: number;
+  edgeBounds: PlaybackEdgeBounds;
+};
+
+/**
+ * Pixel-aligned square geometry used by bird paint helpers.
+ *
+ * Bird geometry is resolved once so the detailed bird renderer can reuse a
+ * stable square body box across glow and fill passes.
+ */
+export type PlaybackBirdGeometry = {
+  birdSideLengthPx: number;
+  birdLeftPx: number;
+  birdTopPx: number;
+};
+
+/**
+ * Resolved opacity and color for one bird trail render pass.
+ *
+ * Trails use a lighter-weight style record than birds because they only need a
+ * base opacity plus stroke color.
+ */
+export type PlaybackTrailRenderStyle = {
+  baseOpacity: number;
+  trailColor: string;
+};
+
+/**
+ * Bird body renderer contract used by frame-render orchestration helpers.
+ *
+ * Keeping the renderer as an injected function makes the high-level frame pass
+ * independent from the detailed bird-paint implementation.
+ */
+export type PlaybackBirdRenderer = (
+  context: CanvasRenderingContext2D,
+  birdYPx: number,
+  birdIndex: number,
+  championBirdIndex: number,
+) => void;
+
+/**
+ * Trail style resolver used by frame-render orchestration helpers.
+ *
+ * This lets orchestration ask for champion-vs-non-champion trail styling
+ * without embedding color policy directly in the frame pass.
+ */
+export type PlaybackTrailStyleResolver = (
+  birdIndex: number,
+  championBirdIndex: number,
+) => PlaybackTrailRenderStyle;
+
+/**
+ * Trail segment renderer used by frame-render orchestration helpers.
+ *
+ * The detailed trail painter owns edge fading and stepped segments; the frame
+ * orchestration only decides when to call it.
+ */
+export type PlaybackTrailRenderer = (
+  context: CanvasRenderingContext2D,
+  trailPoints: TrailPoint[],
+  color: string,
+  anchorX: number,
+  baseOpacity: number,
+  edgeBounds: PlaybackEdgeBounds,
+) => void;
+
+/**
+ * Bird-paint input shared by the bird render helper module.
+ *
+ * This combines geometry and style into one small input object for lower-level
+ * drawing helpers.
+ */
+export type PlaybackBirdPaintInput = {
+  birdGeometry: PlaybackBirdGeometry;
+  birdRenderStyle: PlaybackBirdRenderStyle;
+};

package/test/examples/flappy_bird/browser-entry/playback/frame-render/playback.frame-render.utils.ts

@@ -0,0 +1,11 @@
+export {
+  drawChampionPlaybackBirdGlow,
+  drawPlaybackBirdBody,
+  renderPlaybackBird,
+  resolvePlaybackBirdBodyGlowBlur,
+  resolvePlaybackBirdGeometry,
+} from './playback.frame-render.bird.utils';
+export {
+  drawTrail,
+  resolvePlaybackTrailStyle,
+} from './playback.frame-render.trail.utils';

package/test/examples/flappy_bird/browser-entry/playback/playback.constants.ts

@@ -1,4 +1,4 @@
-import type { StarTile } from './playback.types';
+import type { StarTile } from './playback.starfield.types';
 
 /**
  * Shared in-memory cache for pre-rendered parallax starfield tiles.

package/test/examples/flappy_bird/browser-entry/playback/playback.frame-render.service.ts

@@ -0,0 +1,10 @@
+/**
+ * Compatibility facade for playback frame rendering.
+ *
+ * Older imports still reach the frame renderer through this file while the
+ * implementation now lives in the dedicated frame-render folder.
+ */
+export {
+  renderPopulationFrame,
+  updateTrailState,
+} from './frame-render/playback.frame-render.service';