@reicek/neataptic-ts 0.1.21 → 0.1.23

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

@@ -0,0 +1,204 @@
+import {
+  FLAPPY_GROUND_GRID_MIN_VERTICAL_LINE_COUNT,
+  FLAPPY_GROUND_GRID_PULSE_VISIBLE_VIEWPORT_INSET_PX,
+  FLAPPY_GROUND_GRID_SCROLL_OFFSET_QUANTIZATION_DECIMALS,
+  FLAPPY_GROUND_GRID_SCROLL_RATIO,
+  FLAPPY_GROUND_GRID_TARGET_VERTICAL_LINE_SPACING_PX,
+  FLAPPY_GROUND_GRID_VERTICAL_PULSE_END_RATIO,
+  FLAPPY_GROUND_GRID_VERTICAL_PULSE_START_RATIO,
+} from './playback.background.ground-grid.constants';
+import { resolvePlaybackGroundGridPipeConnectionProfile } from './playback.background.ground-grid.math.utils';
+import { positiveModulo } from '../../playback.starfield.utils';
+import type {
+  PlaybackGroundGridAnchorBounds,
+  PlaybackGroundGridAnchorBoundsInput,
+  PlaybackBackgroundGroundGridSceneContext,
+  PlaybackGroundGridPulsePath,
+  PlaybackGroundGridVerticalCycleContext,
+  PlaybackGroundGridVerticalSceneMetrics,
+} from './playback.background.ground-grid.types';
+
+/**
+ * Builds the static scene metrics reused across one viewport-sized grid layout.
+ *
+ * @param sceneContext - Lower-band geometry for the current viewport.
+ * @returns Stable anchor bounds and lane spacing for vertical-ray reuse.
+ */
+export function buildPlaybackGroundGridVerticalSceneMetrics(
+  sceneContext: PlaybackBackgroundGroundGridSceneContext,
+): PlaybackGroundGridVerticalSceneMetrics {
+  const visibleAnchorBounds = resolvePlaybackGroundGridAnchorBounds({
+    horizonLeftXPx: 0,
+    horizonRightXPx: sceneContext.visibleWorldWidthPx,
+    sceneContext,
+  });
+  const pipeConnectionProfile = resolvePlaybackGroundGridPipeConnectionProfile(
+    sceneContext.lowerBandBottomYPx,
+  );
+  const retainedWidthRatioAtPipeConnection =
+    resolvePlaybackGroundGridRetainedWidthRatioAtYPx(
+      sceneContext.lowerBandBottomYPx,
+      sceneContext.vanishingPointYPx,
+      pipeConnectionProfile.pipeFloorYPx,
+    );
+  const safeLaneSpacingPx = Math.max(
+    1,
+    FLAPPY_GROUND_GRID_TARGET_VERTICAL_LINE_SPACING_PX /
+      Math.max(Number.EPSILON, retainedWidthRatioAtPipeConnection),
+  );
+  const totalVisibleLaneCount = Math.max(
+    FLAPPY_GROUND_GRID_MIN_VERTICAL_LINE_COUNT,
+    Math.ceil(visibleAnchorBounds.anchorSpanPx / safeLaneSpacingPx) + 1,
+  );
+
+  return {
+    visibleAnchorBounds,
+    totalVisibleLaneCount,
+    safeLaneSpacingPx,
+  };
+}
+
+/**
+ * Resolves the wrapped vertical-geometry cycle for the current scroll value.
+ *
+ * @param safeLaneSpacingPx - Stable lane spacing used by current viewport metrics.
+ * @param lowerBandBottomYPx - Lower edge of the visible ground-grid band.
+ * @param scrollBasePx - Shared world scroll used for parallax motion.
+ * @returns Quantized wrapped offset and safe lane spacing for cache lookups.
+ */
+export function resolvePlaybackGroundGridVerticalCycleContext(
+  safeLaneSpacingPx: number,
+  lowerBandBottomYPx: number,
+  scrollBasePx: number,
+): PlaybackGroundGridVerticalCycleContext {
+  const pipeConnectionProfile =
+    resolvePlaybackGroundGridPipeConnectionProfile(lowerBandBottomYPx);
+  const wrappedOffsetPx = positiveModulo(
+    scrollBasePx *
+      FLAPPY_GROUND_GRID_SCROLL_RATIO *
+      pipeConnectionProfile.matchedRayScrollRatio,
+    safeLaneSpacingPx,
+  );
+  const wrappedOffsetPrecisionScale = Math.pow(
+    10,
+    FLAPPY_GROUND_GRID_SCROLL_OFFSET_QUANTIZATION_DECIMALS,
+  );
+
+  return {
+    wrappedOffsetPx:
+      Math.round(wrappedOffsetPx * wrappedOffsetPrecisionScale) /
+      wrappedOffsetPrecisionScale,
+    safeLaneSpacingPx,
+  };
+}
+
+/**
+ * Projects one visible horizontal span back onto the floor anchor line.
+ *
+ * @param input - Visible span bounds and scene geometry.
+ * @returns Bottom-anchor bounds required to cover the chosen projected span.
+ */
+export function resolvePlaybackGroundGridAnchorBounds(
+  input: PlaybackGroundGridAnchorBoundsInput,
+): PlaybackGroundGridAnchorBounds {
+  const leftAnchorXPx = projectPlaybackGroundGridProjectedXToAnchorX({
+    projectedXPx: input.horizonLeftXPx,
+    projectedYPx: input.sceneContext.alignedHorizonYPx,
+    sceneContext: input.sceneContext,
+  });
+  const rightAnchorXPx = projectPlaybackGroundGridProjectedXToAnchorX({
+    projectedXPx: input.horizonRightXPx,
+    projectedYPx: input.sceneContext.alignedHorizonYPx,
+    sceneContext: input.sceneContext,
+  });
+
+  return {
+    leftAnchorXPx,
+    rightAnchorXPx,
+    anchorSpanPx: Math.max(1, rightAnchorXPx - leftAnchorXPx),
+  };
+}
+
+/**
+ * Resolves whether one vertical pulse path is safely visible in the viewport.
+ *
+ * @param pulsePath - Candidate vertical pulse path.
+ * @param sceneContext - Current lower-band scene geometry.
+ * @returns True when the pulse midpoint stays inside the visible ground band.
+ */
+export function isPlaybackGroundGridVerticalPulsePathVisible(
+  pulsePath: PlaybackGroundGridPulsePath,
+  sceneContext: PlaybackBackgroundGroundGridSceneContext,
+): boolean {
+  const midTravelRatio =
+    FLAPPY_GROUND_GRID_VERTICAL_PULSE_START_RATIO +
+    (FLAPPY_GROUND_GRID_VERTICAL_PULSE_END_RATIO -
+      FLAPPY_GROUND_GRID_VERTICAL_PULSE_START_RATIO) *
+      0.5;
+  const pulseMidpointXPx =
+    pulsePath.startXPx +
+    (pulsePath.endXPx - pulsePath.startXPx) * midTravelRatio;
+  const visibleLeftXPx = FLAPPY_GROUND_GRID_PULSE_VISIBLE_VIEWPORT_INSET_PX;
+  const visibleRightXPx =
+    sceneContext.visibleWorldWidthPx -
+    FLAPPY_GROUND_GRID_PULSE_VISIBLE_VIEWPORT_INSET_PX;
+
+  return (
+    pulseMidpointXPx >= visibleLeftXPx && pulseMidpointXPx <= visibleRightXPx
+  );
+}
+
+/**
+ * Projects one visible x-position at an arbitrary y-level to the anchor line.
+ *
+ * @param input - Projected target and scene geometry.
+ * @returns Bottom anchor x-position whose ray reaches the projected point.
+ */
+function projectPlaybackGroundGridProjectedXToAnchorX(input: {
+  projectedXPx: number;
+  projectedYPx: number;
+  sceneContext: PlaybackBackgroundGroundGridSceneContext;
+}): number {
+  const verticalProjectionDenominatorPx =
+    input.projectedYPx - input.sceneContext.vanishingPointYPx;
+  if (Math.abs(verticalProjectionDenominatorPx) < Number.EPSILON) {
+    return input.projectedXPx;
+  }
+
+  const verticalProjectionRatio =
+    (input.sceneContext.lowerBandBottomYPx -
+      input.sceneContext.vanishingPointYPx) /
+    verticalProjectionDenominatorPx;
+  return (
+    input.sceneContext.vanishingPointXPx +
+    (input.projectedXPx - input.sceneContext.vanishingPointXPx) *
+      verticalProjectionRatio
+  );
+}
+
+/**
+ * Resolves how much adjacent-ray spacing remains at one projected y-position.
+ *
+ * Perspective rays linearly collapse toward the vanishing point, so the local
+ * lane width at any y-position is just the bottom-anchor spacing multiplied by
+ * the remaining width ratio between the bottom edge and the vanishing point.
+ *
+ * @param lowerBandBottomYPx - Bottom edge of the visible ground band.
+ * @param vanishingPointYPx - Shared vanishing-point y-position.
+ * @param targetYPx - Projected y-position whose retained width should be measured.
+ * @returns Width-retention ratio in the inclusive `[0, 1]` range.
+ */
+function resolvePlaybackGroundGridRetainedWidthRatioAtYPx(
+  lowerBandBottomYPx: number,
+  vanishingPointYPx: number,
+  targetYPx: number,
+): number {
+  const verticalTravelPx = vanishingPointYPx - lowerBandBottomYPx;
+  if (Math.abs(verticalTravelPx) < Number.EPSILON) {
+    return 1;
+  }
+
+  const interpolationRatio =
+    (targetYPx - lowerBandBottomYPx) / verticalTravelPx;
+  return Math.max(0, Math.min(1, 1 - interpolationRatio));
+}

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

@@ -0,0 +1,49 @@
+import {
+  resolvePlaybackGroundGridHorizontalGeometry,
+  resolvePlaybackGroundGridVerticalGeometry,
+} from './playback.background.ground-grid.geometry.utils';
+import { resolvePlaybackGroundGridPulse } from './playback.background.ground-grid.pulse.utils';
+import type {
+  PlaybackBackgroundGroundGridSceneContext,
+  PlaybackGroundGridGeometry,
+  PlaybackGroundGridHorizontalGeometry,
+  PlaybackGroundGridVerticalGeometry,
+} from './playback.background.ground-grid.types';
+
+/**
+ * Builds the line geometry for the neon ground grid.
+ *
+ * @param sceneContext - Lower-band geometry for the current viewport.
+ * @param frameIndex - Current deterministic playback frame index.
+ * @param scrollBasePx - Shared world scroll used for parallax motion.
+ * @returns Horizontal depth bands and perspective rays for the current frame.
+ */
+export function resolvePlaybackGroundGridGeometry(
+  sceneContext: PlaybackBackgroundGroundGridSceneContext,
+  frameIndex: number,
+  scrollBasePx: number,
+): PlaybackGroundGridGeometry {
+  // Step 1: Resolve and cache the fixed horizontal depth bands for the lower plane.
+  const horizontalGeometry: PlaybackGroundGridHorizontalGeometry =
+    resolvePlaybackGroundGridHorizontalGeometry(sceneContext);
+
+  // Step 2: Resolve and cache the moving perspective rays within one wrapped cycle.
+  const verticalGeometry: PlaybackGroundGridVerticalGeometry =
+    resolvePlaybackGroundGridVerticalGeometry(sceneContext, scrollBasePx);
+
+  // Step 3: Resolve one visible pulse above the grid lines.
+  const pulse = resolvePlaybackGroundGridPulse({
+    frameIndex,
+    horizontalPulsePaths: horizontalGeometry.preferredHorizontalPulsePaths,
+    sceneContext,
+    verticalPulsePaths: verticalGeometry.verticalPulsePaths,
+    visibleVerticalPulsePaths: verticalGeometry.visibleVerticalPulsePaths,
+  });
+
+  // Step 4: Return the pure geometry bundle used by the canvas renderer.
+  return {
+    horizontalLineBatches: horizontalGeometry.horizontalLineBatches,
+    pulse,
+    verticalLineBatches: verticalGeometry.verticalLineBatches,
+  };
+}

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

@@ -0,0 +1,313 @@
+import {
+  FLAPPY_GROUND_GRID_HORIZONTAL_LINE_COUNT,
+  FLAPPY_GROUND_GRID_TARGET_VERTICAL_LINE_SPACING_PX,
+  FLAPPY_GROUND_GRID_TARGET_VERTICAL_SEGMENT_HEIGHT_PX,
+  FLAPPY_GROUND_GRID_VERTICAL_OVERFLOW_COUNT,
+} from './playback.background.ground-grid.constants';
+import {
+  resolvePlaybackGroundGridDepthCurve,
+  resolvePlaybackGroundGridDepthFromHorizonDistance,
+  resolvePlaybackGroundGridLineAlpha,
+  resolvePlaybackGroundGridLineBlur,
+  resolvePlaybackGroundGridLineThickness,
+} from './playback.background.ground-grid.math.utils';
+import {
+  ensureGroundGridViewportCacheValidity,
+  resolveCachedGroundGridHorizontalGeometry,
+  resolveCachedGroundGridVerticalGeometry,
+  resolveCachedGroundGridVerticalSceneMetrics,
+  resolveGroundGridSceneCacheKey,
+  resolveGroundGridVerticalCycleCacheKey,
+} from './playback.background.ground-grid.cache.services';
+import {
+  groupPlaybackGroundGridSegmentsByStyle,
+  resolvePlaybackGroundGridPreferredHorizontalPulsePaths,
+} from './playback.background.ground-grid.geometry.batch.utils';
+import {
+  buildPlaybackGroundGridVerticalSceneMetrics,
+  isPlaybackGroundGridVerticalPulsePathVisible,
+  resolvePlaybackGroundGridVerticalCycleContext,
+} from './playback.background.ground-grid.geometry.layout.utils';
+import type {
+  PlaybackBackgroundGroundGridSceneContext,
+  PlaybackGroundGridHorizontalGeometry,
+  PlaybackGroundGridHorizontalGeometryFactory,
+  PlaybackGroundGridLineSegment,
+  PlaybackGroundGridPulsePath,
+  PlaybackGroundGridSegmentBatch,
+  PlaybackGroundGridVerticalGeometry,
+  PlaybackGroundGridVerticalRayInput,
+  PlaybackGroundGridVerticalSceneMetrics,
+} from './playback.background.ground-grid.types';
+
+/**
+ * Resolves cached screen-horizontal depth bands for the lower neon plane.
+ *
+ * @param sceneContext - Lower-band geometry for the current viewport.
+ * @returns Ordered far-to-near line segments and pulse subsets.
+ */
+export function resolvePlaybackGroundGridHorizontalGeometry(
+  sceneContext: PlaybackBackgroundGroundGridSceneContext,
+): PlaybackGroundGridHorizontalGeometry {
+  ensureGroundGridViewportCacheValidity(sceneContext);
+  const sceneCacheKey = resolveGroundGridSceneCacheKey(sceneContext);
+
+  return resolveCachedGroundGridHorizontalGeometry(sceneCacheKey, () =>
+    buildPlaybackGroundGridHorizontalGeometry(sceneContext),
+  );
+}
+
+/**
+ * Resolves cached perspective rays that converge to the centered horizon point.
+ *
+ * @param sceneContext - Lower-band geometry for the current viewport.
+ * @param scrollBasePx - Shared world scroll used for parallax motion.
+ * @returns Wrapped left-to-right perspective rays and pulse subsets.
+ */
+export function resolvePlaybackGroundGridVerticalGeometry(
+  sceneContext: PlaybackBackgroundGroundGridSceneContext,
+  scrollBasePx: number,
+): PlaybackGroundGridVerticalGeometry {
+  ensureGroundGridViewportCacheValidity(sceneContext);
+
+  const sceneCacheKey = resolveGroundGridSceneCacheKey(sceneContext);
+  const verticalSceneMetrics = resolveCachedGroundGridVerticalSceneMetrics(
+    sceneCacheKey,
+    () => buildPlaybackGroundGridVerticalSceneMetrics(sceneContext),
+  );
+  const verticalCycleContext = resolvePlaybackGroundGridVerticalCycleContext(
+    verticalSceneMetrics.safeLaneSpacingPx,
+    sceneContext.lowerBandBottomYPx,
+    scrollBasePx,
+  );
+  const cycleCacheKey = resolveGroundGridVerticalCycleCacheKey(
+    sceneCacheKey,
+    verticalCycleContext.wrappedOffsetPx,
+  );
+
+  return resolveCachedGroundGridVerticalGeometry(cycleCacheKey, () =>
+    buildPlaybackGroundGridVerticalGeometry(
+      sceneContext,
+      verticalSceneMetrics,
+      verticalCycleContext.wrappedOffsetPx,
+    ),
+  );
+}
+
+/**
+ * Builds the screen-horizontal depth bands for the lower neon plane.
+ *
+ * @param sceneContext - Lower-band geometry for the current viewport.
+ * @returns Ordered far-to-near line segments and pulse subsets.
+ */
+function buildPlaybackGroundGridHorizontalGeometry(
+  sceneContext: PlaybackBackgroundGroundGridSceneContext,
+): PlaybackGroundGridHorizontalGeometry {
+  const maximumDistanceToHorizonPx = Math.max(
+    1,
+    sceneContext.lowerBandBottomYPx - sceneContext.alignedHorizonYPx,
+  );
+  const horizontalLines = new Array<PlaybackGroundGridLineSegment>(
+    FLAPPY_GROUND_GRID_HORIZONTAL_LINE_COUNT,
+  );
+
+  for (
+    let lineIndex = 0;
+    lineIndex < FLAPPY_GROUND_GRID_HORIZONTAL_LINE_COUNT;
+    lineIndex += 1
+  ) {
+    // Step 1: Resolve normalized depth so the first line hugs the horizon.
+    const depthRatio =
+      (lineIndex + 1) / FLAPPY_GROUND_GRID_HORIZONTAL_LINE_COUNT;
+    const curvedDepthRatio = resolvePlaybackGroundGridDepthCurve(depthRatio);
+    const lineYPx =
+      sceneContext.lowerBandTopYPx +
+      curvedDepthRatio * sceneContext.lowerBandHeightPx;
+    const thicknessDepthRatio =
+      resolvePlaybackGroundGridDepthFromHorizonDistance(
+        lineYPx - sceneContext.alignedHorizonYPx,
+        maximumDistanceToHorizonPx,
+      );
+
+    // Step 2: Strengthen the near lines while softening the far ones.
+    horizontalLines[lineIndex] = {
+      startXPx: 0,
+      startYPx: lineYPx,
+      endXPx: sceneContext.visibleWorldWidthPx,
+      endYPx: lineYPx,
+      alpha: resolvePlaybackGroundGridLineAlpha(depthRatio),
+      blurPx: resolvePlaybackGroundGridLineBlur(depthRatio),
+      thicknessPx: resolvePlaybackGroundGridLineThickness(thicknessDepthRatio),
+    };
+  }
+
+  return {
+    horizontalLineBatches:
+      groupPlaybackGroundGridSegmentsByStyle(horizontalLines),
+    horizontalLines,
+    preferredHorizontalPulsePaths:
+      resolvePlaybackGroundGridPreferredHorizontalPulsePaths(horizontalLines),
+  };
+}
+
+/**
+ * Builds the perspective rays that converge to the centered horizon point.
+ *
+ * @param sceneContext - Lower-band geometry for the current viewport.
+ * @param safeLaneSpacingPx - Stable lane spacing used for ray anchors.
+ * @param wrappedOffsetPx - Wrapped offset used for cache reuse and ray placement.
+ * @returns Wrapped left-to-right perspective rays and pulse subsets.
+ */
+function buildPlaybackGroundGridVerticalGeometry(
+  sceneContext: PlaybackBackgroundGroundGridSceneContext,
+  verticalSceneMetrics: PlaybackGroundGridVerticalSceneMetrics,
+  wrappedOffsetPx: number,
+): PlaybackGroundGridVerticalGeometry {
+  const firstAnchorXPx =
+    verticalSceneMetrics.visibleAnchorBounds.leftAnchorXPx -
+    FLAPPY_GROUND_GRID_VERTICAL_OVERFLOW_COUNT *
+      verticalSceneMetrics.safeLaneSpacingPx -
+    wrappedOffsetPx;
+  const totalRayCount =
+    verticalSceneMetrics.totalVisibleLaneCount +
+    FLAPPY_GROUND_GRID_VERTICAL_OVERFLOW_COUNT * 2 +
+    1;
+  const maximumLateralDistancePx =
+    Math.max(
+      Math.abs(
+        verticalSceneMetrics.visibleAnchorBounds.leftAnchorXPx -
+          sceneContext.vanishingPointXPx,
+      ),
+      Math.abs(
+        verticalSceneMetrics.visibleAnchorBounds.rightAnchorXPx -
+          sceneContext.vanishingPointXPx,
+      ),
+    ) +
+    FLAPPY_GROUND_GRID_VERTICAL_OVERFLOW_COUNT *
+      verticalSceneMetrics.safeLaneSpacingPx;
+  const maximumDistanceToHorizonPx = Math.max(
+    1,
+    sceneContext.lowerBandBottomYPx - sceneContext.alignedHorizonYPx,
+  );
+  const verticalSegmentCount = Math.max(
+    6,
+    Math.ceil(
+      maximumDistanceToHorizonPx /
+        FLAPPY_GROUND_GRID_TARGET_VERTICAL_SEGMENT_HEIGHT_PX,
+    ),
+  );
+  const verticalPulsePaths = new Array<PlaybackGroundGridPulsePath>(
+    totalRayCount,
+  );
+  const verticalLineSegments = new Array<PlaybackGroundGridLineSegment>(
+    totalRayCount * verticalSegmentCount,
+  );
+  const visibleVerticalPulsePaths: PlaybackGroundGridPulsePath[] = [];
+  let segmentWriteIndex = 0;
+
+  for (let rayIndex = 0; rayIndex < totalRayCount; rayIndex += 1) {
+    // Step 1: Resolve the bottom anchor and its centered strength.
+    const anchorXPx =
+      firstAnchorXPx + rayIndex * verticalSceneMetrics.safeLaneSpacingPx;
+    const lateralDistancePx = Math.abs(
+      anchorXPx - sceneContext.vanishingPointXPx,
+    );
+    const centeredStrength =
+      1 - Math.min(1, lateralDistancePx / maximumLateralDistancePx);
+    const lineDepthRatio = 0.45 + centeredStrength * 0.55;
+    const verticalPulsePath: PlaybackGroundGridPulsePath = {
+      orientation: 'vertical',
+      startXPx: anchorXPx,
+      startYPx: sceneContext.lowerBandBottomYPx,
+      endXPx: sceneContext.vanishingPointXPx,
+      endYPx: sceneContext.vanishingPointYPx,
+      thicknessPx: resolvePlaybackGroundGridLineThickness(1),
+    };
+
+    verticalPulsePaths[rayIndex] = verticalPulsePath;
+    if (
+      isPlaybackGroundGridVerticalPulsePathVisible(
+        verticalPulsePath,
+        sceneContext,
+      )
+    ) {
+      visibleVerticalPulsePaths.push(verticalPulsePath);
+    }
+
+    segmentWriteIndex = appendPlaybackGroundGridVerticalLineSegments(
+      verticalLineSegments,
+      segmentWriteIndex,
+      {
+        ...verticalPulsePath,
+        lineDepthRatio,
+        maximumDistanceToHorizonPx,
+        sceneContext,
+        verticalSegmentCount,
+      },
+    );
+  }
+
+  return {
+    verticalLineBatches:
+      groupPlaybackGroundGridSegmentsByStyle(verticalLineSegments),
+    verticalPulsePaths,
+    visibleVerticalPulsePaths,
+  };
+}
+
+/**
+ * Appends tapered style segments for one perspective ray.
+ *
+ * @param targetSegments - Target line-segment buffer.
+ * @param startIndex - Current insertion index within the target buffer.
+ * @param input - Geometry and depth context for one ray.
+ * @returns Next insertion index after all ray segments have been written.
+ */
+function appendPlaybackGroundGridVerticalLineSegments(
+  targetSegments: PlaybackGroundGridLineSegment[],
+  startIndex: number,
+  input: PlaybackGroundGridVerticalRayInput,
+): number {
+  const rayDeltaXPx = input.endXPx - input.startXPx;
+  const rayDeltaYPx = input.endYPx - input.startYPx;
+  let writeIndex = startIndex;
+
+  for (
+    let segmentIndex = 0;
+    segmentIndex < input.verticalSegmentCount;
+    segmentIndex += 1
+  ) {
+    // Step 1: Resolve the interpolation bounds for this sub-segment.
+    const segmentStartRatio = segmentIndex / input.verticalSegmentCount;
+    const segmentEndRatio = (segmentIndex + 1) / input.verticalSegmentCount;
+    const segmentMidpointRatio = (segmentStartRatio + segmentEndRatio) * 0.5;
+    const segmentStartXPx = input.startXPx + rayDeltaXPx * segmentStartRatio;
+    const segmentStartYPx = input.startYPx + rayDeltaYPx * segmentStartRatio;
+    const segmentEndXPx = input.startXPx + rayDeltaXPx * segmentEndRatio;
+    const segmentEndYPx = input.startYPx + rayDeltaYPx * segmentEndRatio;
+
+    // Step 2: Resolve style from the segment midpoint distance to the horizon.
+    const segmentMidpointYPx =
+      input.startYPx + rayDeltaYPx * segmentMidpointRatio;
+    const segmentDepthRatio = resolvePlaybackGroundGridDepthFromHorizonDistance(
+      segmentMidpointYPx - input.sceneContext.alignedHorizonYPx,
+      input.maximumDistanceToHorizonPx,
+    );
+    const combinedAlphaDepthRatio =
+      segmentDepthRatio * 0.7 + input.lineDepthRatio * 0.3;
+
+    // Step 3: Append the tapered segment so the ray narrows toward the horizon.
+    targetSegments[writeIndex] = {
+      startXPx: segmentStartXPx,
+      startYPx: segmentStartYPx,
+      endXPx: segmentEndXPx,
+      endYPx: segmentEndYPx,
+      alpha: resolvePlaybackGroundGridLineAlpha(combinedAlphaDepthRatio),
+      blurPx: resolvePlaybackGroundGridLineBlur(segmentDepthRatio),
+      thicknessPx: resolvePlaybackGroundGridLineThickness(segmentDepthRatio),
+    };
+    writeIndex += 1;
+  }
+
+  return writeIndex;
+}

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

@@ -0,0 +1,81 @@
+import {
+  FLAPPY_GROUND_GRID_FOG_ALPHA,
+  FLAPPY_GROUND_GRID_FOG_HEIGHT_RATIO,
+} from './playback.background.ground-grid.constants';
+import { FLAPPY_BACKGROUND_COMPOSITE_SOURCE_OVER } from '../playback.background.constants';
+import {
+  resolveCachedGroundGridFogGradient,
+  resolveGroundGridSceneCacheKey,
+} from './playback.background.ground-grid.cache.services';
+import type {
+  PlaybackBackgroundGroundGridResolvedScene,
+  PlaybackGroundGridPulse,
+} from './playback.background.ground-grid.types';
+
+/**
+ * Draws the lower-band atmospheric wash behind the neon line work.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param resolvedScene - Geometry and style for the current viewport.
+ * @returns Nothing.
+ */
+export function drawGroundGridFog(
+  context: CanvasRenderingContext2D,
+  resolvedScene: PlaybackBackgroundGroundGridResolvedScene,
+): void {
+  const fogHeightPx =
+    resolvedScene.sceneContext.lowerBandHeightPx *
+    FLAPPY_GROUND_GRID_FOG_HEIGHT_RATIO;
+  const sceneCacheKey = resolveGroundGridSceneCacheKey(
+    resolvedScene.sceneContext,
+  );
+  const fogGradient = resolveCachedGroundGridFogGradient(
+    context,
+    sceneCacheKey,
+    resolvedScene.sceneContext,
+    resolvedScene.style.fogColor,
+  );
+
+  context.save();
+  context.globalAlpha = FLAPPY_GROUND_GRID_FOG_ALPHA;
+  context.fillStyle = fogGradient;
+  context.fillRect(
+    0,
+    resolvedScene.sceneContext.lowerBandTopYPx,
+    resolvedScene.sceneContext.visibleWorldWidthPx,
+    fogHeightPx,
+  );
+  context.restore();
+}
+
+/**
+ * Draws one pulse square above the grid lines and below gameplay entities.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param pulse - Visible pulse square for the current frame.
+ * @param fillColor - Core neon fill color.
+ * @returns Nothing.
+ */
+export function drawGroundGridPulse(
+  context: CanvasRenderingContext2D,
+  pulse: PlaybackGroundGridPulse | null,
+  fillColor: string,
+): void {
+  if (!pulse) {
+    return;
+  }
+
+  const halfSizePx = pulse.sizePx * 0.5;
+
+  context.save();
+  context.globalCompositeOperation = FLAPPY_BACKGROUND_COMPOSITE_SOURCE_OVER;
+  context.fillStyle = fillColor;
+  context.globalAlpha = pulse.alpha;
+  context.fillRect(
+    pulse.centerXPx - halfSizePx,
+    pulse.centerYPx - halfSizePx,
+    pulse.sizePx,
+    pulse.sizePx,
+  );
+  context.restore();
+}

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

@@ -0,0 +1,33 @@
+import { FLAPPY_PIPE_SPEED_PX_PER_FRAME } from '../../../../constants/constants.pipes';
+import { FLAPPY_GROUND_GRID_SCROLL_RATIO } from './playback.background.ground-grid.constants';
+import { resolvePlaybackGroundGridPipeConnectionProfile } from './playback.background.ground-grid.math.utils';
+
+describe('resolvePlaybackGroundGridPipeConnectionProfile', () => {
+  it('places the lower-pipe floor above the bottom edge', () => {
+    const pipeConnectionProfile =
+      resolvePlaybackGroundGridPipeConnectionProfile(512);
+
+    expect(pipeConnectionProfile.pipeFloorYPx).toBeLessThan(512);
+  });
+
+  it('matches perspective-ray motion to pipe speed at the connection line', () => {
+    const visibleWorldHeightPx = 512;
+    const pipeConnectionProfile =
+      resolvePlaybackGroundGridPipeConnectionProfile(visibleWorldHeightPx);
+    const lowerBandBottomYPx = visibleWorldHeightPx;
+    const vanishingPointYPx = visibleWorldHeightPx * 0.5;
+    const interpolationRatio =
+      (pipeConnectionProfile.pipeFloorYPx - lowerBandBottomYPx) /
+      (vanishingPointYPx - lowerBandBottomYPx);
+    const localRaySpeedPxPerFrame =
+      FLAPPY_PIPE_SPEED_PX_PER_FRAME *
+      FLAPPY_GROUND_GRID_SCROLL_RATIO *
+      pipeConnectionProfile.matchedRayScrollRatio *
+      (1 - interpolationRatio);
+
+    expect(localRaySpeedPxPerFrame).toBeCloseTo(
+      FLAPPY_PIPE_SPEED_PX_PER_FRAME,
+      6,
+    );
+  });
+});