@reicek/neataptic-ts 0.1.21 → 0.1.23

package/test/examples/flappy_bird/browser-entry/playback/background/ground-grid/playback.background.ground-grid.pulse.utils.test.ts

@@ -0,0 +1,279 @@
+import {
+  FLAPPY_GROUND_GRID_APPROX_FRAME_DURATION_MS,
+  FLAPPY_GROUND_GRID_PULSE_INTERVAL_MS,
+  FLAPPY_GROUND_GRID_PULSE_LIFETIME_MS,
+  FLAPPY_GROUND_GRID_VERTICAL_PULSE_END_RATIO,
+  FLAPPY_GROUND_GRID_VERTICAL_PULSE_START_RATIO,
+} from './playback.background.ground-grid.constants';
+import { resolvePlaybackGroundGridPulse } from './playback.background.ground-grid.pulse.utils';
+import type {
+  PlaybackBackgroundGroundGridSceneContext,
+  PlaybackGroundGridPulsePath,
+} from './playback.background.ground-grid.types';
+
+describe('resolvePlaybackGroundGridPulse', () => {
+  it('keeps a vertical spark on the same ray when visible vertical candidates shift', () => {
+    const sceneContext = createSceneContext();
+    const verticalPulsePaths = createVerticalPulsePaths();
+    const startingFrameIndex = findVerticalPulseFrameIndex(
+      sceneContext,
+      verticalPulsePaths,
+    );
+    const firstPulse = resolvePlaybackGroundGridPulse({
+      frameIndex: startingFrameIndex,
+      horizontalPulsePaths: [],
+      sceneContext,
+      verticalPulsePaths,
+      visibleVerticalPulsePaths: verticalPulsePaths.slice(1, 3),
+    });
+    const secondPulse = resolvePlaybackGroundGridPulse({
+      frameIndex: startingFrameIndex + 1,
+      horizontalPulsePaths: [],
+      sceneContext,
+      verticalPulsePaths,
+      visibleVerticalPulsePaths: verticalPulsePaths.slice(2, 4),
+    });
+
+    expect(firstPulse).not.toBeNull();
+  });
+
+  it('continues the same vertical spark trajectory when edge visibility changes', () => {
+    const sceneContext = createSceneContext();
+    const verticalPulsePaths = createVerticalPulsePaths();
+    const startingFrameIndex = findVerticalPulseFrameIndex(
+      sceneContext,
+      verticalPulsePaths,
+    );
+    const firstPulse = resolvePlaybackGroundGridPulse({
+      frameIndex: startingFrameIndex,
+      horizontalPulsePaths: [],
+      sceneContext,
+      verticalPulsePaths,
+      visibleVerticalPulsePaths: verticalPulsePaths.slice(1, 3),
+    });
+    const secondPulse = resolvePlaybackGroundGridPulse({
+      frameIndex: startingFrameIndex + 1,
+      horizontalPulsePaths: [],
+      sceneContext,
+      verticalPulsePaths,
+      visibleVerticalPulsePaths: verticalPulsePaths.slice(2, 4),
+    });
+
+    expect(secondPulse).not.toBeNull();
+  });
+
+  it('moves the vertical spark only by the expected per-frame delta', () => {
+    const sceneContext = createSceneContext();
+    const verticalPulsePaths = createVerticalPulsePaths();
+    const startingFrameIndex = findVerticalPulseFrameIndex(
+      sceneContext,
+      verticalPulsePaths,
+    );
+    const firstPulse = resolvePlaybackGroundGridPulse({
+      frameIndex: startingFrameIndex,
+      horizontalPulsePaths: [],
+      sceneContext,
+      verticalPulsePaths,
+      visibleVerticalPulsePaths: verticalPulsePaths.slice(1, 3),
+    });
+    const secondPulse = resolvePlaybackGroundGridPulse({
+      frameIndex: startingFrameIndex + 1,
+      horizontalPulsePaths: [],
+      sceneContext,
+      verticalPulsePaths,
+      visibleVerticalPulsePaths: verticalPulsePaths.slice(2, 4),
+    });
+
+    const stablePath = resolveClosestPulsePath(
+      firstPulse!,
+      verticalPulsePaths,
+      resolveVerticalTravelProgressRatio(startingFrameIndex),
+    );
+    const expectedNextCenterXPx = interpolatePathXPx(
+      stablePath,
+      resolveVerticalTravelProgressRatio(startingFrameIndex + 1),
+    );
+
+    expect(secondPulse!.centerXPx).toBeCloseTo(expectedNextCenterXPx, 6);
+  });
+
+  it('keeps a vertical spark continuous across wrapped ray lists', () => {
+    const sceneContext = createSceneContext();
+    const startingFrameIndex = findVerticalPulseFrameIndex(sceneContext, [
+      createVerticalPulsePath(40),
+      createVerticalPulsePath(140),
+      createVerticalPulsePath(240),
+      createVerticalPulsePath(340),
+      createVerticalPulsePath(440),
+    ]);
+    const firstVerticalPulsePaths = [
+      createVerticalPulsePath(-260),
+      createVerticalPulsePath(-160),
+      createVerticalPulsePath(-60),
+      createVerticalPulsePath(40),
+      createVerticalPulsePath(140),
+    ];
+    const secondVerticalPulsePaths = [
+      createVerticalPulsePath(60),
+      createVerticalPulsePath(160),
+      createVerticalPulsePath(260),
+      createVerticalPulsePath(360),
+      createVerticalPulsePath(460),
+    ];
+    const firstPulse = resolvePlaybackGroundGridPulse({
+      frameIndex: startingFrameIndex,
+      horizontalPulsePaths: [],
+      sceneContext,
+      verticalPulsePaths: firstVerticalPulsePaths,
+      visibleVerticalPulsePaths: firstVerticalPulsePaths,
+    });
+    const secondPulse = resolvePlaybackGroundGridPulse({
+      frameIndex: startingFrameIndex + 1,
+      horizontalPulsePaths: [],
+      sceneContext,
+      verticalPulsePaths: secondVerticalPulsePaths,
+      visibleVerticalPulsePaths: secondVerticalPulsePaths,
+    });
+
+    expect(
+      Math.abs(secondPulse!.centerXPx - firstPulse!.centerXPx),
+    ).toBeLessThan(140);
+  });
+});
+
+function findVerticalPulseFrameIndex(
+  sceneContext: PlaybackBackgroundGroundGridSceneContext,
+  verticalPulsePaths: readonly PlaybackGroundGridPulsePath[],
+): number {
+  for (let frameIndex = 0; frameIndex < 4_000; frameIndex += 1) {
+    const pulse = resolvePlaybackGroundGridPulse({
+      frameIndex,
+      horizontalPulsePaths: [],
+      sceneContext,
+      verticalPulsePaths,
+      visibleVerticalPulsePaths: verticalPulsePaths,
+    });
+    if (pulse) {
+      return frameIndex;
+    }
+  }
+
+  throw new Error(
+    'Expected to find a vertical pulse frame for the test fixture.',
+  );
+}
+
+function resolveVerticalTravelProgressRatio(frameIndex: number): number {
+  const currentTimeMs =
+    frameIndex * FLAPPY_GROUND_GRID_APPROX_FRAME_DURATION_MS;
+  const pulseSlotIndex = Math.floor(
+    currentTimeMs / FLAPPY_GROUND_GRID_PULSE_INTERVAL_MS,
+  );
+  const pulseElapsedMs =
+    currentTimeMs - pulseSlotIndex * FLAPPY_GROUND_GRID_PULSE_INTERVAL_MS;
+  const lifetimeProgressRatio =
+    pulseElapsedMs / FLAPPY_GROUND_GRID_PULSE_LIFETIME_MS;
+  const directionIsForward = resolveTestUnitHash(pulseSlotIndex, 29) >= 0.5;
+  const baseTravelProgressRatio = directionIsForward
+    ? lifetimeProgressRatio
+    : 1 - lifetimeProgressRatio;
+
+  return (
+    FLAPPY_GROUND_GRID_VERTICAL_PULSE_START_RATIO +
+    (FLAPPY_GROUND_GRID_VERTICAL_PULSE_END_RATIO -
+      FLAPPY_GROUND_GRID_VERTICAL_PULSE_START_RATIO) *
+      baseTravelProgressRatio
+  );
+}
+
+function resolveClosestPulsePath(
+  pulse: { centerXPx: number; centerYPx: number },
+  verticalPulsePaths: readonly PlaybackGroundGridPulsePath[],
+  travelProgressRatio: number,
+): PlaybackGroundGridPulsePath {
+  let closestPath = verticalPulsePaths[0];
+  let closestDistanceSq = Number.POSITIVE_INFINITY;
+
+  for (const verticalPulsePath of verticalPulsePaths) {
+    const centerXPx = interpolatePathXPx(
+      verticalPulsePath,
+      travelProgressRatio,
+    );
+    const centerYPx = interpolatePathYPx(
+      verticalPulsePath,
+      travelProgressRatio,
+    );
+    const deltaXPx = centerXPx - pulse.centerXPx;
+    const deltaYPx = centerYPx - pulse.centerYPx;
+    const distanceSq = deltaXPx * deltaXPx + deltaYPx * deltaYPx;
+    if (distanceSq < closestDistanceSq) {
+      closestDistanceSq = distanceSq;
+      closestPath = verticalPulsePath;
+    }
+  }
+
+  return closestPath;
+}
+
+function interpolatePathXPx(
+  pulsePath: PlaybackGroundGridPulsePath,
+  travelProgressRatio: number,
+): number {
+  return (
+    pulsePath.startXPx +
+    (pulsePath.endXPx - pulsePath.startXPx) * travelProgressRatio
+  );
+}
+
+function interpolatePathYPx(
+  pulsePath: PlaybackGroundGridPulsePath,
+  travelProgressRatio: number,
+): number {
+  return (
+    pulsePath.startYPx +
+    (pulsePath.endYPx - pulsePath.startYPx) * travelProgressRatio
+  );
+}
+
+function resolveTestUnitHash(seed: number, salt: number): number {
+  let hashedValue = (seed + 1) ^ Math.imul(salt + 1, 374_761_393);
+  hashedValue = Math.imul(hashedValue ^ (hashedValue >>> 13), 1_274_126_177);
+  hashedValue ^= hashedValue >>> 16;
+  return (hashedValue >>> 0) / 0x1_0000_0000;
+}
+
+function createSceneContext(): PlaybackBackgroundGroundGridSceneContext {
+  return {
+    viewportOffsetXPx: 0,
+    visibleWorldWidthPx: 640,
+    alignedHorizonYPx: 220,
+    lowerBandTopYPx: 220,
+    lowerBandHeightPx: 260,
+    lowerBandBottomYPx: 480,
+    vanishingPointXPx: 320,
+    vanishingPointYPx: 220,
+  };
+}
+
+function createVerticalPulsePaths(): readonly PlaybackGroundGridPulsePath[] {
+  return [
+    createVerticalPulsePath(60),
+    createVerticalPulsePath(160),
+    createVerticalPulsePath(260),
+    createVerticalPulsePath(360),
+    createVerticalPulsePath(460),
+  ];
+}
+
+function createVerticalPulsePath(
+  startXPx: number,
+): PlaybackGroundGridPulsePath {
+  return {
+    orientation: 'vertical',
+    startXPx,
+    startYPx: 480,
+    endXPx: 320,
+    endYPx: 220,
+    thicknessPx: 2,
+  };
+}

package/test/examples/flappy_bird/browser-entry/playback/background/ground-grid/playback.background.ground-grid.pulse.utils.ts

@@ -0,0 +1,132 @@
+import {
+  FLAPPY_GROUND_GRID_PULSE_ALPHA,
+  FLAPPY_GROUND_GRID_PULSE_MAX_SIZE_PX,
+  FLAPPY_GROUND_GRID_PULSE_MIN_SIZE_PX,
+} from './playback.background.ground-grid.constants';
+import {
+  interpolatePlaybackGroundGridPoint,
+  resolvePlaybackGroundGridDepthFromHorizonDistance,
+  resolvePlaybackGroundGridLineThickness,
+} from './playback.background.ground-grid.math.utils';
+import {
+  rememberPlaybackGroundGridVerticalPulseSelection,
+  resolvePlaybackGroundGridVerticalPulseSelection,
+} from './playback.background.ground-grid.pulse.selection.utils';
+import {
+  resolvePlaybackGroundGridHorizontalPulsePath,
+  resolvePlaybackGroundGridPulseOrientation,
+  resolvePlaybackGroundGridPulseTiming,
+  resolvePlaybackGroundGridPulseTravelRatio,
+  resolvePlaybackGroundGridUnitHash,
+} from './playback.background.ground-grid.pulse.timing.utils';
+import type {
+  PlaybackBackgroundGroundGridSceneContext,
+  PlaybackGroundGridPulse,
+  PlaybackGroundGridPulseInput,
+  PlaybackGroundGridPulsePath,
+  PlaybackGroundGridPulseTrackThicknessInput,
+} from './playback.background.ground-grid.types';
+
+/**
+ * Resolves one rare, deterministic pulse square for the current frame.
+ *
+ * @param input - Current frame timing and visible pulse path candidates.
+ * @returns Visible pulse square, or null when the current slot is inactive.
+ */
+export function resolvePlaybackGroundGridPulse(
+  input: PlaybackGroundGridPulseInput,
+): PlaybackGroundGridPulse | null {
+  const pulseTiming = resolvePlaybackGroundGridPulseTiming(input.frameIndex);
+  if (!pulseTiming) {
+    return null;
+  }
+
+  const pulseOrientation = resolvePlaybackGroundGridPulseOrientation(
+    pulseTiming.pulseSlotIndex,
+  );
+
+  const directionIsForward =
+    resolvePlaybackGroundGridUnitHash(pulseTiming.pulseSlotIndex, 29) >= 0.5;
+  const travelProgressRatio = resolvePlaybackGroundGridPulseTravelRatio({
+    directionIsForward,
+    lifetimeProgressRatio: pulseTiming.lifetimeProgressRatio,
+    orientation: pulseOrientation,
+  });
+  const selectedPulsePath =
+    pulseOrientation === 'horizontal'
+      ? resolvePlaybackGroundGridHorizontalPulsePath(
+          input.horizontalPulsePaths,
+          pulseTiming.pulseSlotIndex,
+        )
+      : resolvePlaybackGroundGridVerticalPulseSelection({
+          verticalPulsePaths: input.verticalPulsePaths,
+          visibleVerticalPulsePaths: input.visibleVerticalPulsePaths,
+          pulseSlotIndex: pulseTiming.pulseSlotIndex,
+          frameIndex: input.frameIndex,
+          travelProgressRatio,
+          resolveUnitHash: resolvePlaybackGroundGridUnitHash,
+        });
+  if (!selectedPulsePath) {
+    return null;
+  }
+
+  const pulseCenter = interpolatePlaybackGroundGridPoint(
+    selectedPulsePath.startXPx,
+    selectedPulsePath.startYPx,
+    selectedPulsePath.endXPx,
+    selectedPulsePath.endYPx,
+    travelProgressRatio,
+  );
+
+  if (pulseOrientation === 'vertical') {
+    rememberPlaybackGroundGridVerticalPulseSelection(
+      pulseTiming.pulseSlotIndex,
+      {
+        centerXPx: pulseCenter.xPx,
+        centerYPx: pulseCenter.yPx,
+        frameIndex: input.frameIndex,
+      },
+    );
+  }
+
+  const pulseTrackThicknessPx = resolvePlaybackGroundGridPulseTrackThickness({
+    pulseCenterYPx: pulseCenter.yPx,
+    pulsePath: selectedPulsePath,
+    sceneContext: input.sceneContext,
+  });
+
+  return {
+    centerXPx: pulseCenter.xPx,
+    centerYPx: pulseCenter.yPx,
+    sizePx: Math.max(
+      FLAPPY_GROUND_GRID_PULSE_MIN_SIZE_PX,
+      Math.min(FLAPPY_GROUND_GRID_PULSE_MAX_SIZE_PX, pulseTrackThicknessPx),
+    ),
+    alpha: FLAPPY_GROUND_GRID_PULSE_ALPHA,
+  };
+}
+
+/**
+ * Resolves the local track thickness at the pulse position.
+ *
+ * @param input - Pulse position, path, and scene geometry.
+ * @returns Thickness of the current line under the pulse.
+ */
+function resolvePlaybackGroundGridPulseTrackThickness(
+  input: PlaybackGroundGridPulseTrackThicknessInput,
+): number {
+  if (input.pulsePath.orientation === 'horizontal') {
+    return input.pulsePath.thicknessPx;
+  }
+
+  const maximumDistanceToHorizonPx = Math.max(
+    1,
+    input.sceneContext.lowerBandBottomYPx -
+      input.sceneContext.alignedHorizonYPx,
+  );
+  const depthRatio = resolvePlaybackGroundGridDepthFromHorizonDistance(
+    input.pulseCenterYPx - input.sceneContext.alignedHorizonYPx,
+    maximumDistanceToHorizonPx,
+  );
+  return resolvePlaybackGroundGridLineThickness(depthRatio);
+}

package/test/examples/flappy_bird/browser-entry/playback/background/ground-grid/playback.background.ground-grid.scene.services.ts

@@ -0,0 +1,26 @@
+import type {
+  PlaybackBackgroundGroundGridSceneContext,
+  PlaybackBackgroundGroundGridSourceScene,
+} from './playback.background.ground-grid.types';
+
+/**
+ * Resolves the shared scene context used by the ground-grid renderer.
+ *
+ * @param sceneContext - Lower-band geometry provided by the background module.
+ * @returns Narrow scene contract consumed by grid-specific helpers.
+ */
+export function resolvePlaybackGroundGridSceneContext(
+  sceneContext: PlaybackBackgroundGroundGridSourceScene,
+): PlaybackBackgroundGroundGridSceneContext {
+  return {
+    viewportOffsetXPx: sceneContext.viewportLeftXPx,
+    visibleWorldWidthPx: sceneContext.visibleWorldWidthPx,
+    alignedHorizonYPx: sceneContext.alignedHorizonYPx,
+    lowerBandTopYPx: sceneContext.lowerBandTopYPx,
+    lowerBandHeightPx: sceneContext.lowerBandHeightPx,
+    lowerBandBottomYPx: sceneContext.lowerBandBottomYPx,
+    vanishingPointXPx:
+      sceneContext.vanishingPointXPx - sceneContext.viewportLeftXPx,
+    vanishingPointYPx: sceneContext.vanishingPointYPx,
+  };
+}

package/test/examples/flappy_bird/browser-entry/playback/background/ground-grid/playback.background.ground-grid.services.ts

@@ -0,0 +1,65 @@
+import { FLAPPY_BACKGROUND_COMPOSITE_SOURCE_OVER } from '../playback.background.constants';
+import type {
+  PlaybackBackgroundGroundGridResolvedScene,
+  PlaybackGroundGridGeometry,
+} from './playback.background.ground-grid.types';
+import {
+  drawGroundGridSegmentBatch,
+  drawGroundGridSegmentBatches,
+} from './playback.background.ground-grid.batch.services';
+import {
+  drawGroundGridFog,
+  drawGroundGridPulse,
+} from './playback.background.ground-grid.layer.services';
+
+/**
+ * Draws the resolved neon ground grid inside the lower background band.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param resolvedScene - Geometry and style for the current viewport.
+ * @param geometry - Precomputed horizontal and vertical line segments.
+ * @returns Nothing.
+ */
+export function drawPlaybackGroundGrid(
+  context: CanvasRenderingContext2D,
+  resolvedScene: PlaybackBackgroundGroundGridResolvedScene,
+  geometry: PlaybackGroundGridGeometry,
+): void {
+  context.save();
+  context.translate(resolvedScene.sceneContext.viewportOffsetXPx, 0);
+  context.globalCompositeOperation = FLAPPY_BACKGROUND_COMPOSITE_SOURCE_OVER;
+  context.beginPath();
+  context.rect(
+    0,
+    resolvedScene.sceneContext.lowerBandTopYPx,
+    resolvedScene.sceneContext.visibleWorldWidthPx,
+    resolvedScene.sceneContext.lowerBandHeightPx,
+  );
+  context.clip();
+
+  drawGroundGridFog(context, resolvedScene);
+  drawGroundGridSegmentBatches(
+    context,
+    geometry.verticalLineBatches,
+    resolvedScene.style.lineColor,
+  );
+  drawGroundGridSegmentBatches(
+    context,
+    geometry.horizontalLineBatches,
+    resolvedScene.style.lineColor,
+  );
+  drawGroundGridPulse(
+    context,
+    geometry.pulse,
+    resolvedScene.style.pulseFillColor,
+  );
+  context.restore();
+}
+export {
+  drawGroundGridSegmentBatch,
+  drawGroundGridSegmentBatches,
+} from './playback.background.ground-grid.batch.services';
+export {
+  drawGroundGridFog,
+  drawGroundGridPulse,
+} from './playback.background.ground-grid.layer.services';

package/test/examples/flappy_bird/browser-entry/playback/background/ground-grid/playback.background.ground-grid.ts

@@ -0,0 +1,48 @@
+import { drawPlaybackGroundGrid } from './playback.background.ground-grid.services';
+import { FLAPPY_BACKGROUND_GROUND_GRID_STYLE } from './playback.background.ground-grid.constants';
+import type {
+  PlaybackBackgroundGroundGridRequest,
+  PlaybackBackgroundGroundGridResolvedScene,
+  PlaybackBackgroundGroundGridSourceScene,
+} from './playback.background.ground-grid.types';
+import {
+  resolvePlaybackGroundGridGeometry,
+  resolvePlaybackGroundGridSceneContext,
+} from './playback.background.ground-grid.utils';
+
+/**
+ * Draws the neon lower-band ground grid beneath the horizon.
+ *
+ * The grid is intentionally stylized rather than physically realistic: fixed
+ * horizontal depth bands compress toward the horizon, while moving perspective
+ * rays slide sideways but still converge to the centered vanishing point.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param sourceScene - Shared lower-band geometry from the background module.
+ * @param request - Shared parallax scroll input for the current frame.
+ * @returns Nothing.
+ */
+export function renderPlaybackBackgroundGroundGrid(
+  context: CanvasRenderingContext2D,
+  sourceScene: PlaybackBackgroundGroundGridSourceScene,
+  request: PlaybackBackgroundGroundGridRequest,
+): void {
+  // Step 1: Adapt the shared background scene into the narrow grid contract.
+  const sceneContext = resolvePlaybackGroundGridSceneContext(sourceScene);
+
+  // Step 2: Resolve theme-owned styling for the lower-band grid.
+  const resolvedScene: PlaybackBackgroundGroundGridResolvedScene = {
+    sceneContext,
+    style: FLAPPY_BACKGROUND_GROUND_GRID_STYLE,
+  };
+
+  // Step 3: Build all grid geometry before touching the canvas state.
+  const geometry = resolvePlaybackGroundGridGeometry(
+    sceneContext,
+    request.frameIndex,
+    request.scrollBasePx,
+  );
+
+  // Step 4: Draw the resolved lower-band neon grid.
+  drawPlaybackGroundGrid(context, resolvedScene, geometry);
+}