@reicek/neataptic-ts 0.1.21 → 0.1.23

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

@@ -0,0 +1,201 @@
+import {
+  FLAPPY_GROUND_GRID_DEPTH_CURVE_EXPONENT,
+  FLAPPY_GROUND_GRID_HORIZONTAL_LINE_COUNT,
+  FLAPPY_GROUND_GRID_MAX_ALPHA,
+  FLAPPY_GROUND_GRID_MAX_BLUR_PX,
+  FLAPPY_GROUND_GRID_MAX_THICKNESS_PX,
+  FLAPPY_GROUND_GRID_MIN_ALPHA,
+  FLAPPY_GROUND_GRID_MIN_BLUR_PX,
+  FLAPPY_GROUND_GRID_MIN_THICKNESS_PX,
+  FLAPPY_GROUND_GRID_PIPE_CONNECTION_LINE_OFFSET_FROM_BOTTOM,
+  FLAPPY_GROUND_GRID_SCROLL_RATIO,
+} from './playback.background.ground-grid.constants';
+import { resolvePlaybackBackgroundLayout } from '../playback.background.utils';
+
+const cachedPipeConnectionProfileByHeight = new Map<
+  number,
+  PlaybackGroundGridPipeConnectionProfile
+>();
+
+/**
+ * Small point value used when interpolating positions along one grid ray.
+ */
+export type PlaybackGroundGridPoint = {
+  xPx: number;
+  yPx: number;
+};
+
+/**
+ * Shared pipe-floor projection resolved from the lower ground-grid geometry.
+ */
+export type PlaybackGroundGridPipeConnectionProfile = {
+  pipeFloorYPx: number;
+  matchedRayScrollRatio: number;
+};
+
+/**
+ * Maps a normalized depth ratio into a stronger synthwave spacing curve.
+ *
+ * @param depthRatio - Normalized 0..1 depth where 0 is far and 1 is near.
+ * @returns Curved depth ratio used for line placement and styling.
+ */
+export function resolvePlaybackGroundGridDepthCurve(
+  depthRatio: number,
+): number {
+  return Math.pow(depthRatio, FLAPPY_GROUND_GRID_DEPTH_CURVE_EXPONENT);
+}
+
+/**
+ * Resolves neon alpha for one line based on its normalized depth.
+ *
+ * @param depthRatio - Normalized 0..1 depth where 0 is far and 1 is near.
+ * @returns Opacity for the rendered line.
+ */
+export function resolvePlaybackGroundGridLineAlpha(depthRatio: number): number {
+  return (
+    FLAPPY_GROUND_GRID_MIN_ALPHA +
+    (FLAPPY_GROUND_GRID_MAX_ALPHA - FLAPPY_GROUND_GRID_MIN_ALPHA) * depthRatio
+  );
+}
+
+/**
+ * Resolves glow blur for one line based on its normalized depth.
+ *
+ * @param depthRatio - Normalized 0..1 depth where 0 is far and 1 is near.
+ * @returns Blur radius for the rendered line.
+ */
+export function resolvePlaybackGroundGridLineBlur(depthRatio: number): number {
+  return (
+    FLAPPY_GROUND_GRID_MAX_BLUR_PX -
+    (FLAPPY_GROUND_GRID_MAX_BLUR_PX - FLAPPY_GROUND_GRID_MIN_BLUR_PX) *
+      depthRatio
+  );
+}
+
+/**
+ * Resolves stroke thickness for one line based on its normalized depth.
+ *
+ * @param depthRatio - Normalized 0..1 depth where 0 is far and 1 is near.
+ * @returns Stroke width in pixels.
+ */
+export function resolvePlaybackGroundGridLineThickness(
+  depthRatio: number,
+): number {
+  return (
+    FLAPPY_GROUND_GRID_MIN_THICKNESS_PX +
+    (FLAPPY_GROUND_GRID_MAX_THICKNESS_PX -
+      FLAPPY_GROUND_GRID_MIN_THICKNESS_PX) *
+      depthRatio
+  );
+}
+
+/**
+ * Resolves normalized depth from a vertical distance away from the horizon.
+ *
+ * @param distanceToHorizonPx - Vertical distance from the vanishing horizon.
+ * @param maximumDistanceToHorizonPx - Largest visible vertical horizon distance.
+ * @returns Normalized 0..1 depth where 0 is at the horizon and 1 is nearest.
+ */
+export function resolvePlaybackGroundGridDepthFromHorizonDistance(
+  distanceToHorizonPx: number,
+  maximumDistanceToHorizonPx: number,
+): number {
+  if (maximumDistanceToHorizonPx <= 0) {
+    return 0;
+  }
+
+  return Math.min(
+    1,
+    Math.max(0, distanceToHorizonPx / maximumDistanceToHorizonPx),
+  );
+}
+
+/**
+ * Resolves the shared lower-pipe floor and matched grid-ray scroll ratio.
+ *
+ * The lower pipe is visually clipped to the first usable horizontal grid band
+ * above the bottom edge. The returned scroll ratio then speeds up the moving
+ * perspective rays so their lateral motion matches the pipe speed exactly at
+ * that same projected height.
+ *
+ * @param visibleWorldHeightPx - Current visible world height in pixels.
+ * @returns Pipe-floor y-position plus the matching vertical-ray scroll ratio.
+ */
+export function resolvePlaybackGroundGridPipeConnectionProfile(
+  visibleWorldHeightPx: number,
+): PlaybackGroundGridPipeConnectionProfile {
+  const cachedProfile =
+    cachedPipeConnectionProfileByHeight.get(visibleWorldHeightPx);
+  if (cachedProfile) {
+    return cachedProfile;
+  }
+
+  // Step 1: Resolve the lower-band layout used by both the grid and pipe illusion.
+  const backgroundLayout =
+    resolvePlaybackBackgroundLayout(visibleWorldHeightPx);
+  const connectionLineIndex = Math.max(
+    0,
+    FLAPPY_GROUND_GRID_HORIZONTAL_LINE_COUNT -
+      FLAPPY_GROUND_GRID_PIPE_CONNECTION_LINE_OFFSET_FROM_BOTTOM -
+      1,
+  );
+  const depthRatio =
+    (connectionLineIndex + 1) / FLAPPY_GROUND_GRID_HORIZONTAL_LINE_COUNT;
+  const curvedDepthRatio = resolvePlaybackGroundGridDepthCurve(depthRatio);
+  const pipeFloorYPx =
+    backgroundLayout.lowerBandTopYPx +
+    curvedDepthRatio * backgroundLayout.lowerBandHeightPx;
+
+  // Step 2: Resolve how much anchor motion survives at the projected floor height.
+  const vanishingPointYPx = Math.max(0, visibleWorldHeightPx * 0.5);
+  const verticalTravelPx =
+    vanishingPointYPx - backgroundLayout.lowerBandBottomYPx;
+  const interpolationRatio =
+    Math.abs(verticalTravelPx) < Number.EPSILON
+      ? 0
+      : (pipeFloorYPx - backgroundLayout.lowerBandBottomYPx) / verticalTravelPx;
+  const clampedInterpolationRatio = Math.min(
+    0.999,
+    Math.max(0, interpolationRatio),
+  );
+
+  // Step 3: Return the floor height and the ray-scroll multiplier needed there.
+  const pipeConnectionProfile = {
+    pipeFloorYPx,
+    matchedRayScrollRatio:
+      1 /
+      Math.max(
+        Number.EPSILON,
+        FLAPPY_GROUND_GRID_SCROLL_RATIO * (1 - clampedInterpolationRatio),
+      ),
+  };
+
+  cachedPipeConnectionProfileByHeight.set(
+    visibleWorldHeightPx,
+    pipeConnectionProfile,
+  );
+  return pipeConnectionProfile;
+}
+
+/**
+ * Interpolates one point along a perspective ray.
+ *
+ * @param startXPx - Bottom anchor x-position.
+ * @param startYPx - Bottom anchor y-position.
+ * @param endXPx - Vanishing-point x-position.
+ * @param endYPx - Vanishing-point y-position.
+ * @param interpolationRatio - Normalized 0..1 position along the ray.
+ * @returns Interpolated point on the perspective ray.
+ */
+export function interpolatePlaybackGroundGridPoint(
+  startXPx: number,
+  startYPx: number,
+  endXPx: number,
+  endYPx: number,
+  interpolationRatio: number,
+): PlaybackGroundGridPoint {
+  return {
+    xPx: startXPx + (endXPx - startXPx) * interpolationRatio,
+    yPx: startYPx + (endYPx - startYPx) * interpolationRatio,
+  };
+}

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

@@ -0,0 +1,171 @@
+import { FLAPPY_GROUND_GRID_VERTICAL_OVERFLOW_COUNT } from './playback.background.ground-grid.constants';
+import { interpolatePlaybackGroundGridPoint } from './playback.background.ground-grid.math.utils';
+import type {
+  PlaybackGroundGridPulsePath,
+  PlaybackGroundGridVerticalPulseContinuationState,
+} from './playback.background.ground-grid.types';
+
+const cachedVerticalPulseContinuationBySlot = new Map<
+  number,
+  PlaybackGroundGridVerticalPulseContinuationState
+>();
+
+/**
+ * Resolves the current vertical pulse path while preserving per-slot continuity.
+ *
+ * A vertical pulse should stay attached to one moving ray for its whole
+ * lifetime, even though the frame-local ray array is rebuilt as scroll wraps.
+ * This helper first prefers the nearest continuation of the previous frame's
+ * pulse position, then falls back to deterministic slot-based selection.
+ *
+ * @param verticalPulsePaths - Full vertical ray paths for the current frame.
+ * @param visibleVerticalPulsePaths - Visible subset preferred for on-screen pulses.
+ * @param pulseSlotIndex - Zero-based pulse slot index.
+ * @param frameIndex - Current deterministic frame index.
+ * @param travelProgressRatio - Current travel ratio along the chosen line.
+ * @param resolveUnitHash - Deterministic unit-hash helper used for fallback picks.
+ * @returns Vertical pulse path, or null when none are available.
+ */
+export function resolvePlaybackGroundGridVerticalPulseSelection(input: {
+  verticalPulsePaths: readonly PlaybackGroundGridPulsePath[];
+  visibleVerticalPulsePaths: readonly PlaybackGroundGridPulsePath[];
+  pulseSlotIndex: number;
+  frameIndex: number;
+  travelProgressRatio: number;
+  resolveUnitHash: (seed: number, salt: number) => number;
+}): PlaybackGroundGridPulsePath | null {
+  if (input.verticalPulsePaths.length === 0) {
+    return null;
+  }
+
+  trimCachedVerticalPulseContinuationState(input.pulseSlotIndex);
+
+  const candidatePulsePaths = resolveStableVerticalPulsePathCandidates(
+    input.verticalPulsePaths,
+    input.visibleVerticalPulsePaths,
+  );
+  const continuedPulsePath = resolveContinuedVerticalPulsePath({
+    candidatePulsePaths,
+    pulseSlotIndex: input.pulseSlotIndex,
+    frameIndex: input.frameIndex,
+    travelProgressRatio: input.travelProgressRatio,
+  });
+  if (continuedPulsePath) {
+    return continuedPulsePath;
+  }
+
+  const selectedPathIndex = Math.min(
+    candidatePulsePaths.length - 1,
+    Math.floor(
+      input.resolveUnitHash(input.pulseSlotIndex, 23) *
+        candidatePulsePaths.length,
+    ),
+  );
+  return candidatePulsePaths[selectedPathIndex];
+}
+
+/**
+ * Stores the resolved pulse center for continuation on the next frame.
+ *
+ * @param pulseSlotIndex - Zero-based pulse slot index.
+ * @param continuationState - Latest visible pulse position for the slot.
+ * @returns Nothing.
+ */
+export function rememberPlaybackGroundGridVerticalPulseSelection(
+  pulseSlotIndex: number,
+  continuationState: PlaybackGroundGridVerticalPulseContinuationState,
+): void {
+  cachedVerticalPulseContinuationBySlot.set(pulseSlotIndex, continuationState);
+}
+
+/**
+ * Resolves the nearest continued vertical pulse path for an active slot.
+ *
+ * @param input - Continuation input for the current frame.
+ * @returns Continued pulse path when one can be matched, otherwise null.
+ */
+function resolveContinuedVerticalPulsePath(input: {
+  candidatePulsePaths: readonly PlaybackGroundGridPulsePath[];
+  pulseSlotIndex: number;
+  frameIndex: number;
+  travelProgressRatio: number;
+}): PlaybackGroundGridPulsePath | null {
+  const cachedContinuationState = cachedVerticalPulseContinuationBySlot.get(
+    input.pulseSlotIndex,
+  );
+  if (!cachedContinuationState) {
+    return null;
+  }
+
+  if (input.frameIndex <= cachedContinuationState.frameIndex) {
+    return null;
+  }
+
+  let closestPulsePath: PlaybackGroundGridPulsePath | null = null;
+  let closestDistanceSquared = Number.POSITIVE_INFINITY;
+
+  for (const candidatePulsePath of input.candidatePulsePaths) {
+    const candidateCenter = interpolatePlaybackGroundGridPoint(
+      candidatePulsePath.startXPx,
+      candidatePulsePath.startYPx,
+      candidatePulsePath.endXPx,
+      candidatePulsePath.endYPx,
+      input.travelProgressRatio,
+    );
+    const deltaXPx = candidateCenter.xPx - cachedContinuationState.centerXPx;
+    const deltaYPx = candidateCenter.yPx - cachedContinuationState.centerYPx;
+    const distanceSquared = deltaXPx * deltaXPx + deltaYPx * deltaYPx;
+
+    if (distanceSquared < closestDistanceSquared) {
+      closestDistanceSquared = distanceSquared;
+      closestPulsePath = candidatePulsePath;
+    }
+  }
+
+  return closestPulsePath;
+}
+
+/**
+ * Trims cached continuation state so only the current or previous pulse slots remain.
+ *
+ * @param currentPulseSlotIndex - Pulse slot currently being resolved.
+ * @returns Nothing.
+ */
+function trimCachedVerticalPulseContinuationState(
+  currentPulseSlotIndex: number,
+): void {
+  for (const cachedPulseSlotIndex of cachedVerticalPulseContinuationBySlot.keys()) {
+    if (cachedPulseSlotIndex < currentPulseSlotIndex - 1) {
+      cachedVerticalPulseContinuationBySlot.delete(cachedPulseSlotIndex);
+    }
+  }
+}
+
+/**
+ * Resolves a stable vertical pulse-candidate set for one frame.
+ *
+ * @param verticalPulsePaths - Full vertical ray paths for the current frame.
+ * @param visibleVerticalPulsePaths - Midpoint-visible subset used as fallback.
+ * @returns Stable candidate set for deterministic vertical pulse selection.
+ */
+function resolveStableVerticalPulsePathCandidates(
+  verticalPulsePaths: readonly PlaybackGroundGridPulsePath[],
+  visibleVerticalPulsePaths: readonly PlaybackGroundGridPulsePath[],
+): readonly PlaybackGroundGridPulsePath[] {
+  const stableCandidatePaths = verticalPulsePaths.slice(
+    FLAPPY_GROUND_GRID_VERTICAL_OVERFLOW_COUNT,
+    Math.max(
+      FLAPPY_GROUND_GRID_VERTICAL_OVERFLOW_COUNT,
+      verticalPulsePaths.length - FLAPPY_GROUND_GRID_VERTICAL_OVERFLOW_COUNT,
+    ),
+  );
+  if (stableCandidatePaths.length > 0) {
+    return stableCandidatePaths;
+  }
+
+  if (visibleVerticalPulsePaths.length > 0) {
+    return visibleVerticalPulsePaths;
+  }
+
+  return verticalPulsePaths;
+}

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

@@ -0,0 +1,124 @@
+import {
+  FLAPPY_GROUND_GRID_APPROX_FRAME_DURATION_MS,
+  FLAPPY_GROUND_GRID_PULSE_INTERVAL_MS,
+  FLAPPY_GROUND_GRID_PULSE_LIFETIME_MS,
+  FLAPPY_GROUND_GRID_UNSIGNED_NORMALIZATION_DIVISOR,
+  FLAPPY_GROUND_GRID_VERTICAL_PULSE_END_RATIO,
+  FLAPPY_GROUND_GRID_VERTICAL_PULSE_START_RATIO,
+} from './playback.background.ground-grid.constants';
+import type {
+  PlaybackGroundGridPulseOrientation,
+  PlaybackGroundGridPulsePath,
+  PlaybackGroundGridPulseTimingState,
+  PlaybackGroundGridPulseTravelRatioInput,
+} from './playback.background.ground-grid.types';
+
+/**
+ * Resolves timing state for the currently active deterministic pulse slot.
+ *
+ * @param frameIndex - Current deterministic playback frame index.
+ * @returns Pulse timing state, or null when no pulse is active in this frame.
+ */
+export function resolvePlaybackGroundGridPulseTiming(
+  frameIndex: number,
+): PlaybackGroundGridPulseTimingState | null {
+  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;
+  if (pulseElapsedMs > FLAPPY_GROUND_GRID_PULSE_LIFETIME_MS) {
+    return null;
+  }
+
+  return {
+    pulseSlotIndex,
+    pulseElapsedMs,
+    lifetimeProgressRatio:
+      pulseElapsedMs / FLAPPY_GROUND_GRID_PULSE_LIFETIME_MS,
+  };
+}
+
+/**
+ * Resolves pulse orientation for one deterministic pulse slot.
+ *
+ * @param pulseSlotIndex - Zero-based pulse slot index.
+ * @returns Horizontal or vertical pulse travel orientation.
+ */
+export function resolvePlaybackGroundGridPulseOrientation(
+  pulseSlotIndex: number,
+): PlaybackGroundGridPulseOrientation {
+  return resolvePlaybackGroundGridUnitHash(pulseSlotIndex, 11) >= 0.5
+    ? 'horizontal'
+    : 'vertical';
+}
+
+/**
+ * Selects one thick-enough horizontal band for the current pulse slot.
+ *
+ * @param horizontalPulsePaths - Cached horizontal pulse paths eligible for travel.
+ * @param pulseSlotIndex - Zero-based pulse slot index.
+ * @returns Horizontal pulse path, or null when none are suitable.
+ */
+export function resolvePlaybackGroundGridHorizontalPulsePath(
+  horizontalPulsePaths: readonly PlaybackGroundGridPulsePath[],
+  pulseSlotIndex: number,
+): PlaybackGroundGridPulsePath | null {
+  if (horizontalPulsePaths.length === 0) {
+    return null;
+  }
+
+  const selectedLineIndex = Math.min(
+    horizontalPulsePaths.length - 1,
+    Math.floor(
+      resolvePlaybackGroundGridUnitHash(pulseSlotIndex, 17) *
+        horizontalPulsePaths.length,
+    ),
+  );
+  return horizontalPulsePaths[selectedLineIndex];
+}
+
+/**
+ * Resolves the pulse travel ratio along its chosen line.
+ *
+ * @param input - Pulse timing direction and orientation.
+ * @returns Normalized 0..1 travel ratio along the chosen line.
+ */
+export function resolvePlaybackGroundGridPulseTravelRatio(
+  input: PlaybackGroundGridPulseTravelRatioInput,
+): number {
+  const baseTravelProgressRatio = input.directionIsForward
+    ? input.lifetimeProgressRatio
+    : 1 - input.lifetimeProgressRatio;
+  if (input.orientation === 'horizontal') {
+    return baseTravelProgressRatio;
+  }
+
+  return (
+    FLAPPY_GROUND_GRID_VERTICAL_PULSE_START_RATIO +
+    (FLAPPY_GROUND_GRID_VERTICAL_PULSE_END_RATIO -
+      FLAPPY_GROUND_GRID_VERTICAL_PULSE_START_RATIO) *
+      baseTravelProgressRatio
+  );
+}
+
+/**
+ * Resolves a deterministic unit-interval hash from a slot index and salt.
+ *
+ * @param seed - Slot-local seed value.
+ * @param salt - Small integer salt used to pick a stable random stream.
+ * @returns Stable random value in the range 0..1.
+ */
+export function resolvePlaybackGroundGridUnitHash(
+  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) / FLAPPY_GROUND_GRID_UNSIGNED_NORMALIZATION_DIVISOR
+  );
+}