@reicek/neataptic-ts 0.1.21 → 0.1.22

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

@@ -0,0 +1,178 @@
+import { FLAPPY_GROUND_GRID_FOG_HEIGHT_RATIO } from './playback.background.ground-grid.constants';
+import type {
+  PlaybackBackgroundGroundGridSceneContext,
+  PlaybackGroundGridHorizontalGeometry,
+  PlaybackGroundGridHorizontalGeometryFactory,
+  PlaybackGroundGridVerticalGeometry,
+  PlaybackGroundGridVerticalGeometryFactory,
+} from './playback.background.ground-grid.types';
+
+let cachedViewportSizeKey: string | null = null;
+let cachedFogGradientsByCanvas = new WeakMap<
+  HTMLCanvasElement,
+  Map<string, CanvasGradient>
+>();
+
+const cachedHorizontalGeometryBySceneKey = new Map<
+  string,
+  PlaybackGroundGridHorizontalGeometry
+>();
+const cachedVerticalGeometryByCycleKey = new Map<
+  string,
+  PlaybackGroundGridVerticalGeometry
+>();
+
+/**
+ * Ensures ground-grid caches only retain entries for the current viewport size.
+ *
+ * The ground grid is derived from viewport width and total scene height, so a
+ * page resize invalidates every cached geometry variant and fog gradient.
+ *
+ * @param sceneContext - Current lower-band scene geometry.
+ * @returns Stable viewport-size cache key for the current frame.
+ */
+export function ensureGroundGridViewportCacheValidity(
+  sceneContext: PlaybackBackgroundGroundGridSceneContext,
+): string {
+  const viewportSizeKey = resolveGroundGridViewportCacheKey(sceneContext);
+  if (cachedViewportSizeKey === viewportSizeKey) {
+    return viewportSizeKey;
+  }
+
+  cachedViewportSizeKey = viewportSizeKey;
+  cachedHorizontalGeometryBySceneKey.clear();
+  cachedVerticalGeometryByCycleKey.clear();
+  cachedFogGradientsByCanvas = new WeakMap<
+    HTMLCanvasElement,
+    Map<string, CanvasGradient>
+  >();
+  return viewportSizeKey;
+}
+
+/**
+ * Resolves the viewport-size cache key used by the ground-grid caches.
+ *
+ * @param sceneContext - Current lower-band scene geometry.
+ * @returns Cache key that changes whenever the page size changes.
+ */
+export function resolveGroundGridViewportCacheKey(
+  sceneContext: PlaybackBackgroundGroundGridSceneContext,
+): string {
+  return `${sceneContext.visibleWorldWidthPx}x${sceneContext.lowerBandBottomYPx}`;
+}
+
+/**
+ * Resolves the stable local-scene cache key for ground-grid geometry.
+ *
+ * @param sceneContext - Current lower-band scene geometry.
+ * @returns Scene key suitable for static horizontal and vertical cache entries.
+ */
+export function resolveGroundGridSceneCacheKey(
+  sceneContext: PlaybackBackgroundGroundGridSceneContext,
+): string {
+  return [
+    sceneContext.visibleWorldWidthPx,
+    sceneContext.alignedHorizonYPx,
+    sceneContext.lowerBandTopYPx,
+    sceneContext.lowerBandHeightPx,
+    sceneContext.lowerBandBottomYPx,
+    sceneContext.vanishingPointXPx,
+    sceneContext.vanishingPointYPx,
+  ].join(':');
+}
+
+/**
+ * Resolves the cache key for one wrapped vertical-geometry cycle.
+ *
+ * @param sceneCacheKey - Stable scene key for the active viewport.
+ * @param wrappedOffsetPx - Quantized wrapped offset within one lane cycle.
+ * @returns Cycle key used for vertical geometry reuse.
+ */
+export function resolveGroundGridVerticalCycleCacheKey(
+  sceneCacheKey: string,
+  wrappedOffsetPx: number,
+): string {
+  return `${sceneCacheKey}|offset:${wrappedOffsetPx}`;
+}
+
+/**
+ * Resolves cached horizontal geometry for one scene.
+ *
+ * @param sceneCacheKey - Stable scene key for the active viewport.
+ * @param factory - Lazy geometry builder used when the cache misses.
+ * @returns Cached horizontal geometry bundle for the scene.
+ */
+export function resolveCachedGroundGridHorizontalGeometry(
+  sceneCacheKey: string,
+  factory: PlaybackGroundGridHorizontalGeometryFactory,
+): PlaybackGroundGridHorizontalGeometry {
+  const cachedGeometry = cachedHorizontalGeometryBySceneKey.get(sceneCacheKey);
+  if (cachedGeometry) {
+    return cachedGeometry;
+  }
+
+  const resolvedGeometry = factory();
+  cachedHorizontalGeometryBySceneKey.set(sceneCacheKey, resolvedGeometry);
+  return resolvedGeometry;
+}
+
+/**
+ * Resolves cached vertical geometry for one scene and wrapped offset cycle.
+ *
+ * @param cycleCacheKey - Scene-and-offset cache key for the active frame.
+ * @param factory - Lazy geometry builder used when the cache misses.
+ * @returns Cached vertical geometry bundle for the cycle.
+ */
+export function resolveCachedGroundGridVerticalGeometry(
+  cycleCacheKey: string,
+  factory: PlaybackGroundGridVerticalGeometryFactory,
+): PlaybackGroundGridVerticalGeometry {
+  const cachedGeometry = cachedVerticalGeometryByCycleKey.get(cycleCacheKey);
+  if (cachedGeometry) {
+    return cachedGeometry;
+  }
+
+  const resolvedGeometry = factory();
+  cachedVerticalGeometryByCycleKey.set(cycleCacheKey, resolvedGeometry);
+  return resolvedGeometry;
+}
+
+/**
+ * Resolves a cached fog gradient for one canvas and local scene.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param sceneCacheKey - Stable scene key for the active viewport.
+ * @param sceneContext - Current lower-band scene geometry.
+ * @param fogColor - Theme-owned fog color token.
+ * @returns Cached fog gradient aligned to the lower-band scene.
+ */
+export function resolveCachedGroundGridFogGradient(
+  context: CanvasRenderingContext2D,
+  sceneCacheKey: string,
+  sceneContext: PlaybackBackgroundGroundGridSceneContext,
+  fogColor: string,
+): CanvasGradient {
+  const fogGradientKey = `${sceneCacheKey}|fog:${fogColor}`;
+  const canvas = context.canvas;
+  const cachedGradientsForCanvas =
+    cachedFogGradientsByCanvas.get(canvas) ?? new Map<string, CanvasGradient>();
+  const cachedGradient = cachedGradientsForCanvas.get(fogGradientKey);
+  if (cachedGradient) {
+    return cachedGradient;
+  }
+
+  const fogHeightPx =
+    sceneContext.lowerBandHeightPx * FLAPPY_GROUND_GRID_FOG_HEIGHT_RATIO;
+  const fogGradient = context.createLinearGradient(
+    0,
+    sceneContext.lowerBandTopYPx,
+    0,
+    sceneContext.lowerBandTopYPx + fogHeightPx,
+  );
+  fogGradient.addColorStop(0, fogColor);
+  fogGradient.addColorStop(1, 'rgba(0, 0, 0, 0)');
+
+  cachedGradientsForCanvas.set(fogGradientKey, fogGradient);
+  cachedFogGradientsByCanvas.set(canvas, cachedGradientsForCanvas);
+  return fogGradient;
+}

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

@@ -0,0 +1,107 @@
+import { FLAPPY_NEON_PALETTE } from '../../../../constants/constants';
+import type { PlaybackBackgroundGroundGridStyle } from './playback.background.ground-grid.types';
+
+/** Number of horizontal depth bands used by the neon ground grid. */
+export const FLAPPY_GROUND_GRID_HORIZONTAL_LINE_COUNT = 16;
+
+/** Target spacing between perspective-ray anchors at the bottom edge (pixels). */
+export const FLAPPY_GROUND_GRID_TARGET_VERTICAL_LINE_SPACING_PX = 320;
+
+/** Minimum visible perspective-ray count used on very narrow viewports. */
+export const FLAPPY_GROUND_GRID_MIN_VERTICAL_LINE_COUNT = 2;
+
+/** Extra off-screen perspective rays drawn for seamless wrap. */
+export const FLAPPY_GROUND_GRID_VERTICAL_OVERFLOW_COUNT = 1;
+
+/** Target screen-space height for one vertical-ray style segment (pixels). */
+export const FLAPPY_GROUND_GRID_TARGET_VERTICAL_SEGMENT_HEIGHT_PX = 24;
+
+/** Approximate playback frame duration used for deterministic pulse timing. */
+export const FLAPPY_GROUND_GRID_APPROX_FRAME_DURATION_MS = 1000 / 60;
+
+/** Interval between visible pulse events (milliseconds). */
+export const FLAPPY_GROUND_GRID_PULSE_INTERVAL_MS = 3000;
+
+/** Lifetime of one pulse as it travels across its chosen line (milliseconds). */
+export const FLAPPY_GROUND_GRID_PULSE_LIFETIME_MS = 1100;
+
+/** Glow blur applied behind each visible pulse square (pixels). */
+export const FLAPPY_GROUND_GRID_PULSE_GLOW_BLUR_PX = 8;
+
+/** Peak opacity used by visible pulse squares. */
+export const FLAPPY_GROUND_GRID_PULSE_ALPHA = 0.92;
+
+/** Smallest visible pulse square size (pixels). */
+export const FLAPPY_GROUND_GRID_PULSE_MIN_SIZE_PX = 1;
+
+/** Largest visible pulse square size (pixels). */
+export const FLAPPY_GROUND_GRID_PULSE_MAX_SIZE_PX = 6;
+
+/** Earliest progress ratio allowed for vertical pulse travel. */
+export const FLAPPY_GROUND_GRID_VERTICAL_PULSE_START_RATIO = 0.14;
+
+/** Latest progress ratio allowed for vertical pulse travel. */
+export const FLAPPY_GROUND_GRID_VERTICAL_PULSE_END_RATIO = 0.62;
+
+/** Minimum horizontal line thickness eligible for pulse travel. */
+export const FLAPPY_GROUND_GRID_PULSE_MIN_ELIGIBLE_THICKNESS_PX = 1.5;
+
+/** Earliest eligible slice of horizontal lines used for visible pulse picks. */
+export const FLAPPY_GROUND_GRID_PULSE_PREFERRED_HORIZONTAL_START_RATIO = 0.4;
+
+/** Horizontal inset that keeps vertical pulse picks away from clipped edges. */
+export const FLAPPY_GROUND_GRID_PULSE_VISIBLE_VIEWPORT_INSET_PX = 24;
+
+/** Size multiplier used for the soft glow halo behind one pulse square. */
+export const FLAPPY_GROUND_GRID_PULSE_GLOW_SIZE_MULTIPLIER = 2.4;
+
+/** Alpha ratio used for the soft glow halo behind one pulse square. */
+export const FLAPPY_GROUND_GRID_PULSE_GLOW_ALPHA_RATIO = 0.45;
+
+/** Normalization divisor used for deterministic pulse hash generation. */
+export const FLAPPY_GROUND_GRID_UNSIGNED_NORMALIZATION_DIVISOR = 0x1_0000_0000;
+
+/** Non-linear exponent used to compress depth lines toward the horizon. */
+export const FLAPPY_GROUND_GRID_DEPTH_CURVE_EXPONENT = 2.35;
+
+/** Scroll ratio applied to the moving vertical perspective rays. */
+export const FLAPPY_GROUND_GRID_SCROLL_RATIO = 0.16;
+
+/** Minimum alpha used by the farthest horizontal depth lines. */
+export const FLAPPY_GROUND_GRID_MIN_ALPHA = 0.12;
+
+/** Maximum alpha used by the nearest depth and perspective lines. */
+export const FLAPPY_GROUND_GRID_MAX_ALPHA = 0.58;
+
+/** Blur radius used by the farthest depth lines near the horizon. */
+export const FLAPPY_GROUND_GRID_MAX_BLUR_PX = 6;
+
+/** Blur radius used by the nearest depth lines at the bottom edge. */
+export const FLAPPY_GROUND_GRID_MIN_BLUR_PX = 0;
+
+/** Minimum stroke width used by far depth lines. */
+export const FLAPPY_GROUND_GRID_MIN_THICKNESS_PX = 1;
+
+/** Maximum stroke width used by near depth lines. */
+export const FLAPPY_GROUND_GRID_MAX_THICKNESS_PX = 3;
+
+/** Height ratio reserved for the subtle lower-band neon fog wash. */
+export const FLAPPY_GROUND_GRID_FOG_HEIGHT_RATIO = 0.45;
+
+/** Peak opacity used by the lower-band neon fog wash. */
+export const FLAPPY_GROUND_GRID_FOG_ALPHA = 0.24;
+
+/**
+ * Frozen neon style bundle reused by the playback ground-grid renderer.
+ *
+ * The values stay theme-owned but are materialized once so the renderer does
+ * not allocate a new style object during every frame.
+ */
+export const FLAPPY_BACKGROUND_GROUND_GRID_STYLE: PlaybackBackgroundGroundGridStyle =
+  Object.freeze({
+    lineColor: FLAPPY_NEON_PALETTE.groundGridLine,
+    glowColor: FLAPPY_NEON_PALETTE.groundGridGlow,
+    fogColor: FLAPPY_NEON_PALETTE.groundGridFog,
+    pulseFillColor: FLAPPY_NEON_PALETTE.groundGridPulseFill,
+    pulseGlowColor: FLAPPY_NEON_PALETTE.groundGridPulseGlow,
+  });