@reicek/neataptic-ts 0.1.21 → 0.1.23

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

@@ -0,0 +1,184 @@
+import { FLAPPY_NEON_PALETTE } from '../../../constants/constants';
+import { resolveStarfieldTiles } from '../playback.starfield.service';
+import type { StarTileImage } from '../playback.starfield.types';
+import { positiveModulo } from '../playback.starfield.utils';
+import { resolveCachedPlaybackTileCoverageCount } from './playback.background.cache.services';
+import {
+  FLAPPY_BACKGROUND_COMPOSITE_SOURCE_OVER,
+  FLAPPY_BACKGROUND_TILE_ROW_BUFFER_COUNT,
+  FLAPPY_BACKGROUND_TILE_ROW_START_INDEX,
+  FLAPPY_BACKGROUND_TRANSPARENT_SHADOW_COLOR,
+} from './playback.background.constants';
+import type {
+  PlaybackBackgroundRequest,
+  PlaybackBackgroundSceneContext,
+  PlaybackHorizonLineRequest,
+} from './playback.background.types';
+
+/**
+ * Paints the base background fill for the currently visible viewport.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param sceneContext - Derived scene geometry and style contract.
+ * @returns Nothing.
+ */
+export function paintPlaybackBackgroundBase(
+  context: CanvasRenderingContext2D,
+  sceneContext: PlaybackBackgroundSceneContext,
+): void {
+  // Step 1: Reset canvas paint state to a predictable base pass.
+  context.globalAlpha = 1;
+  context.globalCompositeOperation = FLAPPY_BACKGROUND_COMPOSITE_SOURCE_OVER;
+  context.shadowBlur = 0;
+  context.shadowColor = FLAPPY_BACKGROUND_TRANSPARENT_SHADOW_COLOR;
+  context.fillStyle = FLAPPY_NEON_PALETTE.background;
+
+  // Step 2: Fill only the currently visible world-space viewport.
+  context.fillRect(
+    sceneContext.viewportLeftXPx,
+    0,
+    sceneContext.visibleWorldWidthPx,
+    sceneContext.visibleWorldHeightPx,
+  );
+}
+
+/**
+ * Draws the starfield parallax clipped to the upper sky band.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param sceneContext - Derived scene geometry and style contract.
+ * @param request - Narrow render input required for background composition.
+ * @returns Nothing.
+ */
+export function drawPlaybackBackgroundSky(
+  context: CanvasRenderingContext2D,
+  sceneContext: PlaybackBackgroundSceneContext,
+  request: PlaybackBackgroundRequest,
+): void {
+  // Step 1: Constrain star drawing to the sky band above the horizon.
+  context.save();
+  context.beginPath();
+  context.rect(
+    sceneContext.viewportLeftXPx,
+    0,
+    sceneContext.visibleWorldWidthPx,
+    sceneContext.skyHeightPx,
+  );
+  context.clip();
+  context.globalCompositeOperation = FLAPPY_BACKGROUND_COMPOSITE_SOURCE_OVER;
+
+  // Step 2: Draw each cached starfield layer with its own parallax offset.
+  const starfieldTiles = resolveStarfieldTiles(sceneContext.skyHeightPx);
+  for (const starfieldTile of starfieldTiles) {
+    const scrollOffsetPx = request.scrollBasePx * starfieldTile.scrollRatio;
+    drawPlaybackTiledImageRow(
+      context,
+      sceneContext.viewportLeftXPx,
+      starfieldTile.image,
+      starfieldTile.tileWidthPx,
+      sceneContext.visibleWorldWidthPx,
+      scrollOffsetPx,
+    );
+  }
+
+  // Step 3: Restore the caller's unclipped canvas state.
+  context.restore();
+}
+
+/**
+ * Draws the glowing horizon divider across the visible viewport.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param sceneContext - Derived scene geometry and style contract.
+ * @returns Nothing.
+ */
+export function drawPlaybackBackgroundHorizon(
+  context: CanvasRenderingContext2D,
+  sceneContext: PlaybackBackgroundSceneContext,
+): void {
+  // Step 1: Delegate the divider rendering to the dedicated horizon helper.
+  drawPlaybackHorizonLine(context, {
+    viewportLeftXPx: sceneContext.viewportLeftXPx,
+    visibleWorldWidthPx: sceneContext.visibleWorldWidthPx,
+    alignedHorizonYPx: sceneContext.alignedHorizonYPx,
+    horizonStyle: sceneContext.horizonStyle,
+  });
+}
+
+/**
+ * Draws a horizontally tiled image strip across the visible width.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param startXPx - Leftmost visible world x-position for the tiled strip.
+ * @param tile - Pre-rendered tile image reused across the sky band.
+ * @param tileWidthPx - Width of one repeated tile in pixels.
+ * @param visibleWidthPx - Current visible width that must be fully covered.
+ * @param offsetPx - Parallax scroll offset used to wrap tile placement.
+ * @returns Nothing.
+ */
+function drawPlaybackTiledImageRow(
+  context: CanvasRenderingContext2D,
+  startXPx: number,
+  tile: StarTileImage,
+  tileWidthPx: number,
+  visibleWidthPx: number,
+  offsetPx: number,
+): void {
+  // Step 1: Normalize the scroll offset so tile placement stays bounded.
+  const normalizedOffsetPx = positiveModulo(offsetPx, tileWidthPx);
+  const maximumTileIndex = resolveCachedPlaybackTileCoverageCount(
+    tileWidthPx,
+    () =>
+      Math.ceil(visibleWidthPx / tileWidthPx) +
+      FLAPPY_BACKGROUND_TILE_ROW_BUFFER_COUNT,
+  );
+
+  // Step 2: Draw enough repeated tiles to cover the visible strip.
+  for (
+    let tileIndex = FLAPPY_BACKGROUND_TILE_ROW_START_INDEX;
+    tileIndex <= maximumTileIndex;
+    tileIndex += 1
+  ) {
+    const tileLeftPx = startXPx + tileIndex * tileWidthPx - normalizedOffsetPx;
+    context.drawImage(tile as unknown as CanvasImageSource, tileLeftPx, 0);
+  }
+}
+
+/**
+ * Draws the glowing horizon divider using the provided neon style.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param request - Width, aligned y-position, and style for the divider.
+ * @returns Nothing.
+ */
+function drawPlaybackHorizonLine(
+  context: CanvasRenderingContext2D,
+  request: PlaybackHorizonLineRequest,
+): void {
+  // Step 1: Draw the outer glow pass to establish the neon bloom.
+  context.globalCompositeOperation = FLAPPY_BACKGROUND_COMPOSITE_SOURCE_OVER;
+  context.strokeStyle = request.horizonStyle.lineColor;
+  context.lineWidth = request.horizonStyle.lineThicknessPx;
+  context.shadowColor = request.horizonStyle.glowColor;
+  context.shadowBlur = request.horizonStyle.glowBlurPx;
+  context.globalAlpha = request.horizonStyle.glowAlpha;
+  context.beginPath();
+  context.moveTo(request.viewportLeftXPx, request.alignedHorizonYPx);
+  context.lineTo(
+    request.viewportLeftXPx + request.visibleWorldWidthPx,
+    request.alignedHorizonYPx,
+  );
+  context.stroke();
+
+  // Step 2: Restore a crisp core line after the glow pass.
+  context.shadowBlur = 0;
+  context.shadowColor = FLAPPY_BACKGROUND_TRANSPARENT_SHADOW_COLOR;
+  context.globalAlpha = 1;
+  context.beginPath();
+  context.moveTo(request.viewportLeftXPx, request.alignedHorizonYPx);
+  context.lineTo(
+    request.viewportLeftXPx + request.visibleWorldWidthPx,
+    request.alignedHorizonYPx,
+  );
+  context.stroke();
+}

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

@@ -0,0 +1,64 @@
+import {
+  ensurePlaybackBackgroundViewportCacheValidity,
+  resolveCachedPlaybackBackgroundLayout,
+} from './playback.background.cache.services';
+import type {
+  PlaybackBackgroundRequest,
+  PlaybackBackgroundSceneContext,
+} from './playback.background.types';
+import {
+  resolveAlignedHorizonYPx,
+  resolvePlaybackBackgroundLayout,
+  resolvePlaybackHorizonStyle,
+  resolveSafeBackgroundDimension,
+} from './playback.background.utils';
+
+/**
+ * Resolves the derived scene contract required by the background passes.
+ *
+ * @param request - Narrow render input required for background composition.
+ * @returns Immutable scene context shared by the private render helpers.
+ */
+export function resolvePlaybackBackgroundSceneContext(
+  request: PlaybackBackgroundRequest,
+): PlaybackBackgroundSceneContext {
+  // Step 1: Clamp viewport dimensions into render-safe pixel values.
+  const visibleWorldWidthPx = resolveSafeBackgroundDimension(
+    request.visibleWorldWidthPx,
+  );
+  const visibleWorldHeightPx = resolveSafeBackgroundDimension(
+    request.visibleWorldHeightPx,
+  );
+  ensurePlaybackBackgroundViewportCacheValidity(
+    visibleWorldWidthPx,
+    visibleWorldHeightPx,
+  );
+
+  // Step 2: Resolve the vertical sky-ground split and horizon style.
+  const backgroundLayout = resolveCachedPlaybackBackgroundLayout(
+    visibleWorldHeightPx,
+    () => resolvePlaybackBackgroundLayout(visibleWorldHeightPx),
+  );
+  const horizonStyle = resolvePlaybackHorizonStyle();
+  const alignedHorizonYPx = resolveAlignedHorizonYPx(
+    backgroundLayout.horizonYPx,
+    horizonStyle.lineThicknessPx,
+  );
+  const vanishingPointXPx = request.viewportLeftXPx + visibleWorldWidthPx * 0.5;
+  const vanishingPointYPx = visibleWorldHeightPx * 0.5;
+
+  // Step 3: Return a compact context object for the remaining passes.
+  return {
+    viewportLeftXPx: request.viewportLeftXPx,
+    visibleWorldWidthPx,
+    visibleWorldHeightPx,
+    skyHeightPx: backgroundLayout.skyHeightPx,
+    lowerBandTopYPx: backgroundLayout.lowerBandTopYPx,
+    lowerBandHeightPx: backgroundLayout.lowerBandHeightPx,
+    lowerBandBottomYPx: backgroundLayout.lowerBandBottomYPx,
+    alignedHorizonYPx,
+    vanishingPointXPx,
+    vanishingPointYPx,
+    horizonStyle,
+  };
+}

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

@@ -0,0 +1,6 @@
+export {
+  drawPlaybackBackgroundHorizon,
+  drawPlaybackBackgroundSky,
+  paintPlaybackBackgroundBase,
+} from './playback.background.draw.services';
+export { resolvePlaybackBackgroundSceneContext } from './playback.background.scene.services';

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

@@ -0,0 +1,53 @@
+import { renderPlaybackBackgroundGroundGrid } from './ground-grid/playback.background.ground-grid';
+import {
+  drawPlaybackBackgroundHorizon,
+  drawPlaybackBackgroundSky,
+  paintPlaybackBackgroundBase,
+  resolvePlaybackBackgroundSceneContext,
+} from './playback.background.services';
+import type { PlaybackBackgroundRequest } from './playback.background.types';
+
+/**
+ * Draws the layered playback background.
+ *
+ * The composition keeps the top two-thirds for the neon starfield, fills the
+ * lower band with a TRON-like perspective ground grid, and separates both
+ * regions with a glowing horizon divider.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param request - Narrow render input required for background composition.
+ * @returns Nothing.
+ *
+ * @example
+ * ```ts
+ * renderPlaybackBackground(context, {
+ *   viewportLeftXPx: cameraLeftPx,
+ *   visibleWorldWidthPx: 288,
+ *   visibleWorldHeightPx: 512,
+ *   frameIndex,
+ *   scrollBasePx: frameIndex * pipeSpeedPxPerFrame,
+ * });
+ * ```
+ */
+export function renderPlaybackBackground(
+  context: CanvasRenderingContext2D,
+  request: PlaybackBackgroundRequest,
+): void {
+  // Step 1: Resolve the scene contracts needed by the background passes.
+  const backgroundSceneContext = resolvePlaybackBackgroundSceneContext(request);
+
+  // Step 2: Paint the shared base fill behind all background layers.
+  paintPlaybackBackgroundBase(context, backgroundSceneContext);
+
+  // Step 3: Render the sky-only starfield inside the horizon clip band.
+  drawPlaybackBackgroundSky(context, backgroundSceneContext, request);
+
+  // Step 4: Render the lower-band neon grid beneath the horizon seam.
+  renderPlaybackBackgroundGroundGrid(context, backgroundSceneContext, {
+    frameIndex: request.frameIndex,
+    scrollBasePx: request.scrollBasePx,
+  });
+
+  // Step 5: Draw the horizon divider above the sky and ground layers.
+  drawPlaybackBackgroundHorizon(context, backgroundSceneContext);
+}

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

@@ -0,0 +1,105 @@
+/**
+ * Minimal render input required to draw the playback background.
+ *
+ * The background is intentionally treated as a deterministic camera effect
+ * rather than a gameplay-aware renderer. By restricting the contract to
+ * viewport geometry, frame index, and scroll position, the module can create a
+ * stable neon sky-ground composition without coupling itself to bird state,
+ * pipe arrays, or trail caches.
+ *
+ * @example
+ * ```ts
+ * const request: PlaybackBackgroundRequest = {
+ *   viewportLeftXPx: cameraLeftPx,
+ *   visibleWorldWidthPx: 288,
+ *   visibleWorldHeightPx: 512,
+ *   frameIndex,
+ *   scrollBasePx: frameIndex * pipeSpeedPxPerFrame,
+ * };
+ * ```
+ */
+export type PlaybackBackgroundRequest = {
+  viewportLeftXPx: number;
+  visibleWorldWidthPx: number;
+  visibleWorldHeightPx: number;
+  frameIndex: number;
+  scrollBasePx: number;
+};
+
+/**
+ * Derived scene contract shared by the playback background render passes.
+ *
+ * This is the background module's precomputed staging area. The scene service
+ * resolves the sky/lower-band split, vanishing point, and horizon styling once
+ * so the draw passes can stay orchestration-first and avoid repeating geometry
+ * math every frame.
+ */
+export type PlaybackBackgroundSceneContext = {
+  viewportLeftXPx: number;
+  visibleWorldWidthPx: number;
+  visibleWorldHeightPx: number;
+  skyHeightPx: number;
+  lowerBandTopYPx: number;
+  lowerBandHeightPx: number;
+  lowerBandBottomYPx: number;
+  alignedHorizonYPx: number;
+  vanishingPointXPx: number;
+  vanishingPointYPx: number;
+  horizonStyle: PlaybackHorizonStyle;
+};
+
+/**
+ * Resolved vertical scene split used by playback background composition.
+ *
+ * The layout fixes the classic synthwave composition used by this demo: a tall
+ * sky band for layered starfield parallax and a compressed lower strip for the
+ * perspective grid. Caching this structure by viewport size keeps redraws cheap
+ * when the scene is otherwise stable.
+ */
+export type PlaybackBackgroundLayout = {
+  skyHeightPx: number;
+  lowerBandTopYPx: number;
+  lowerBandHeightPx: number;
+  lowerBandBottomYPx: number;
+  horizonYPx: number;
+  horizonThicknessPx: number;
+};
+
+/**
+ * Zero-argument builder used to lazily construct one cached background layout.
+ *
+ * The cache service accepts a factory instead of raw data so callers can defer
+ * the slightly more expensive layout computation until a viewport-size cache
+ * miss actually occurs.
+ */
+export type PlaybackBackgroundLayoutFactory = () => PlaybackBackgroundLayout;
+
+/**
+ * Neon styling contract for the horizon divider line.
+ *
+ * The horizon is rendered as both a crisp divider and a glow source, much like
+ * the luminous skyline separator common in synthwave and TRON-inspired poster
+ * art. Keeping those paint properties bundled makes it easier to reason about
+ * the horizon as one semantic effect instead of a pile of canvas state.
+ */
+export type PlaybackHorizonStyle = {
+  lineColor: string;
+  glowColor: string;
+  glowAlpha: number;
+  glowBlurPx: number;
+  lineThicknessPx: number;
+};
+
+/**
+ * Draw request for the horizon divider line.
+ *
+ * This narrow contract is the final handoff from layout math to the canvas
+ * stroke helper: world-space x extents, the pixel-snapped y position, and the
+ * resolved glow style needed for both line passes.
+ */
+export type PlaybackHorizonLineRequest = {
+  viewportLeftXPx: number;
+  visibleWorldWidthPx: number;
+  alignedHorizonYPx: number;
+  horizonStyle: PlaybackHorizonStyle;
+};

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

@@ -0,0 +1,100 @@
+import {
+  FLAPPY_BACKGROUND_HORIZON_STYLE,
+  FLAPPY_BACKGROUND_HORIZON_HALF_THICKNESS_MULTIPLIER,
+  FLAPPY_BACKGROUND_HORIZON_LINE_THICKNESS_PX,
+  FLAPPY_BACKGROUND_MIN_VIEWPORT_DIMENSION_PX,
+  FLAPPY_BACKGROUND_ODD_STROKE_ALIGNMENT_OFFSET_PX,
+  FLAPPY_BACKGROUND_ODD_STROKE_DIVISOR,
+  FLAPPY_BACKGROUND_SKY_HEIGHT_RATIO,
+} from './playback.background.constants';
+import type {
+  PlaybackBackgroundLayout,
+  PlaybackHorizonStyle,
+} from './playback.background.types';
+
+/**
+ * Resolves the vertical split between the starfield sky and the future ground.
+ *
+ * @param visibleWorldHeightPx - Current visible world height in pixels.
+ * @returns Stable scene layout for the current frame.
+ */
+export function resolvePlaybackBackgroundLayout(
+  visibleWorldHeightPx: number,
+): PlaybackBackgroundLayout {
+  // Step 1: Clamp the viewport height so follow-up math stays render-safe.
+  const safeVisibleWorldHeightPx =
+    resolveSafeBackgroundDimension(visibleWorldHeightPx);
+
+  // Step 2: Reserve the top segment for the current starfield parallax.
+  const skyHeightPx = Math.max(
+    FLAPPY_BACKGROUND_MIN_VIEWPORT_DIMENSION_PX,
+    Math.round(safeVisibleWorldHeightPx * FLAPPY_BACKGROUND_SKY_HEIGHT_RATIO),
+  );
+  const horizonThicknessPx = FLAPPY_BACKGROUND_HORIZON_LINE_THICKNESS_PX;
+  const lowerBandTopYPx = skyHeightPx;
+  const lowerBandBottomYPx = safeVisibleWorldHeightPx;
+  const lowerBandHeightPx = Math.max(
+    FLAPPY_BACKGROUND_MIN_VIEWPORT_DIMENSION_PX,
+    lowerBandBottomYPx - lowerBandTopYPx,
+  );
+  const horizonYPx = Math.max(
+    0,
+    lowerBandTopYPx -
+      horizonThicknessPx * FLAPPY_BACKGROUND_HORIZON_HALF_THICKNESS_MULTIPLIER,
+  );
+
+  // Step 3: Return an explicit layout object so render code stays declarative.
+  return {
+    skyHeightPx,
+    lowerBandTopYPx,
+    lowerBandHeightPx,
+    lowerBandBottomYPx,
+    horizonYPx,
+    horizonThicknessPx,
+  };
+}
+
+/**
+ * Resolves the neon paint settings for the horizon divider.
+ *
+ * @returns Reusable draw style for both the glow and crisp line passes.
+ */
+export function resolvePlaybackHorizonStyle(): PlaybackHorizonStyle {
+  // Step 1: Reuse one frozen style object so horizon drawing stays allocation-free.
+  return FLAPPY_BACKGROUND_HORIZON_STYLE;
+}
+
+/**
+ * Resolves pixel-snapped horizon positioning for crisp canvas strokes.
+ *
+ * @param horizonYPx - Logical horizon centerline in pixels.
+ * @param lineThicknessPx - Stroke thickness in pixels.
+ * @returns Pixel-snapped y-position for the stroke.
+ */
+export function resolveAlignedHorizonYPx(
+  horizonYPx: number,
+  lineThicknessPx: number,
+): number {
+  // Step 1: Offset odd-width strokes onto half pixels for crisp rasterization.
+  const oddStrokeAlignmentOffsetPx =
+    lineThicknessPx % FLAPPY_BACKGROUND_ODD_STROKE_DIVISOR === 1
+      ? FLAPPY_BACKGROUND_ODD_STROKE_ALIGNMENT_OFFSET_PX
+      : 0;
+
+  // Step 2: Return the aligned horizon position.
+  return horizonYPx + oddStrokeAlignmentOffsetPx;
+}
+
+/**
+ * Clamps a background dimension into a render-safe positive integer.
+ *
+ * @param dimensionPx - Candidate viewport dimension in pixels.
+ * @returns Positive integer dimension suitable for canvas math.
+ */
+export function resolveSafeBackgroundDimension(dimensionPx: number): number {
+  // Step 1: Round sub-pixel measurements and enforce a positive floor.
+  return Math.max(
+    FLAPPY_BACKGROUND_MIN_VIEWPORT_DIMENSION_PX,
+    Math.round(dimensionPx),
+  );
+}