@nayan-ui/games 1.19.0 → 1.20.0

package/src/games/shared/EngineMeshCache.ts

@@ -0,0 +1,15 @@
+// Keep only recipe identity here. The engine owns durable storage, validation and recovery.
+// Completed records have no expiry/eviction; this cache skips entire expensive JS factories.
+import { ProceduralCache } from '@nayan-ui/engine';
+import { PROCEDURAL_CACHE_VERSION } from './ProceduralCacheVersion';
+
+let cache: ProceduralCache | undefined;
+
+/** Product recipe revisioning is separate from the engine's geometry/storage format. */
+export function cacheGameAsset<T>(key: string, build: () => T): T {
+  cache ??= new ProceduralCache(PROCEDURAL_CACHE_VERSION);
+  return cache.get(key, build);
+}
+export const flushProceduralCache = async () => {
+  await cache?.flush();
+};

package/src/games/shared/EngineMeshes.ts

@@ -0,0 +1,10 @@
+// The engine owns mesh hashing, preparation, registration and persistent storage in Rust.
+// Factory caches additionally skip JS model construction. Ratio 1 preserves the
+// authored surfaces, normals, colours and UV seams while welding and improving GPU cache reuse.
+import { createShape, type Geometry, type Model, type ShapeOptions } from '@nayan-ui/engine';
+
+export function createGameMesh(geometry: Geometry, options: ShapeOptions = {}): Model {
+  return createShape(geometry, { ...options, optimize: options.optimize ?? true });
+}
+
+export { cacheGameAsset } from './EngineMeshCache';

package/src/games/shared/EngineRacingChase.ts

@@ -0,0 +1,21 @@
+import type { Camera, Vec3 } from '@nayan-ui/engine';
+
+type Vector = [number, number, number];
+export const createChase = () => ({
+  eye: [6, 3, 6] as Vector,
+  target: [0, 0.2, 0] as Vector,
+  initialized: false
+});
+export type Chase = ReturnType<typeof createChase>;
+
+/** Filter camera offsets only: translation stays locked to the exact displayed car pose. */
+export function updateChase(chase: Chase, camera: Camera, anchor: Vec3, eye: Vec3, target: Vec3, dt: number) {
+  const k = chase.initialized ? 1 - Math.exp(-Math.max(0, dt) * 7) : 1;
+  for (let axis = 0; axis < 3; axis++) {
+    chase.eye[axis] = chase.eye[axis]! + (eye[axis]! - chase.eye[axis]!) * k;
+    chase.target[axis] = chase.target[axis]! + (target[axis]! - chase.target[axis]!) * k;
+    camera.eye[axis] = anchor[axis]! + chase.eye[axis]!;
+    camera.target[axis] = anchor[axis]! + chase.target[axis]!;
+  }
+  chase.initialized = true;
+}

package/src/games/shared/EngineRacingHandling.ts

@@ -0,0 +1,48 @@
+/** Responsive lane targeting with filtered input and an analytically damped movement curve. */
+export type SteeringState = { d: number; target: number; lateral: number; steeringGoal?: number };
+export function stepSteering(state: SteeringState, goal: number, dt: number, maxSpeed = 9, response = 10.5, playing = true) {
+  if (dt <= 0) return;
+  if (!playing) {
+    const stopped = state.lateral * Math.exp(-response * 2 * dt);
+    state.d += (state.lateral - stopped) / (response * 2);
+    state.lateral = stopped;
+    state.steeringGoal = state.d;
+    return;
+  }
+  let filtered = state.steeringGoal ?? state.d;
+  let remaining = dt;
+  // Small input-filter steps keep keyboard, pointer and irregular display frames consistent.
+  // Position/velocity use the closed-form critically damped solution rather than Euler correction.
+  while (remaining > 1e-9) {
+    const h = Math.min(remaining, 1 / 240);
+    filtered = goal + (filtered - goal) * Math.exp(-22 * h);
+    const error = state.d - filtered;
+    const coefficient = state.lateral + response * error;
+    const decay = Math.exp(-response * h);
+    let position = filtered + (error + coefficient * h) * decay;
+    let velocity = (state.lateral - response * coefficient * h) * decay;
+    if (Math.abs(velocity) > maxSpeed) {
+      velocity = Math.sign(velocity) * maxSpeed;
+      position = state.d + (state.lateral + velocity) * 0.5 * h;
+    }
+    state.d = position;
+    state.lateral = velocity;
+    remaining -= h;
+  }
+  state.steeringGoal = filtered;
+}
+
+/** Closing speed across the road: moving away or travelling alongside does not trigger a wreck. */
+export function sideImpactSpeed(playerLateral: number, trafficLateral: number, offset: number) {
+  return Math.max(0, (playerLateral - trafficLateral) * (Math.sign(offset) || 1));
+}
+
+/** Ease the displayed yaw and lean independently so quick input changes do not snap the body. */
+export function smoothSteeringPose(pose: { yaw: number; roll: number }, lateral: number, speed: number, dt: number) {
+  const blend = 1 - Math.exp(-Math.max(0, dt) * 18);
+  const yaw = Math.max(-0.22, Math.min(0.22, Math.atan2(lateral, Math.max(8, speed)) * 0.55));
+  const roll = Math.max(-0.035, Math.min(0.035, lateral * 0.004));
+  const yawStep = (yaw - pose.yaw) * blend;
+  pose.yaw += Math.max(-0.9 * dt, Math.min(0.9 * dt, yawStep));
+  pose.roll += (roll - pose.roll) * blend;
+}

package/src/games/shared/EngineReadyContext.ts

@@ -0,0 +1,4 @@
+import { createContext } from 'react';
+
+/** Asset loaders warm the engine before mounting a game, so it can draw immediately. */
+export const EngineReadyContext = createContext(false);

package/src/games/shared/EngineTilt.ts

@@ -0,0 +1,44 @@
+// A board seen from a little in front of straight down, for the engine's tabletop games: an
+// orthographic camera leaning back `tilt` radians over a board lying in the world's XY plane (x right,
+// y up the board, z up off it), one world unit per view point, so the board's depth and the pieces
+// standing on it read as 3D while it keeps its shape. The board's centre (the world origin) lands at
+// view point (width / 2, centerY).
+import type { Camera, Entity, World } from '@nayan-ui/engine';
+
+export type TiltView = { width: number; height: number; centerY: number; tilt: number };
+
+const EYE_DISTANCE = 240; // within the camera's 0.1..500 depth range for anything on or near the board
+
+/** Where a world point appears in the view. */
+export function project(v: TiltView, x: number, y: number, z = 0): [number, number] {
+  return [v.width / 2 + x, v.centerY - (y * Math.cos(v.tilt) + z * Math.sin(v.tilt))];
+}
+
+/** The world point at height `z` under a view point (a finger on the board). */
+export function unproject(v: TiltView, sx: number, sy: number, z = 0): [number, number] {
+  return [sx - v.width / 2, (v.centerY - sy - z * Math.sin(v.tilt)) / Math.cos(v.tilt)];
+}
+
+/** Points the camera so the board lands where the view puts it. */
+export function aimTilted(camera: Camera, v: TiltView) {
+  const k = v.centerY - v.height / 2;
+  const up = [0, Math.cos(v.tilt), Math.sin(v.tilt)] as const;
+  const back = [0, -Math.sin(v.tilt), Math.cos(v.tilt)] as const;
+  camera.target = [0, up[1] * k, up[2] * k];
+  camera.eye = [0, camera.target[1] + back[1] * EYE_DISTANCE, camera.target[2] + back[2] * EYE_DISTANCE];
+  camera.ortho = v.height / 2;
+}
+
+/**
+ * Lays a game backdrop (shared/EngineBackdrop, drawn from its top-left) flat `depth` below the board,
+ * stretched so it fills the view from its top-left as the original screens drew it. Lying flat, it faces
+ * up (+z) like the board, so a front light keeps its exact colors.
+ */
+export function placeTiltedBackdrop(world: World, backdrop: Entity, v: TiltView, depth: number) {
+  const k = v.centerY - v.height / 2;
+  const cos = Math.cos(v.tilt);
+  world.set(backdrop, {
+    position: [-v.width / 2, (v.height / 2 + k + depth * Math.sin(v.tilt)) / cos, -depth],
+    scale: [1, 1 / cos, 1]
+  });
+}

package/src/games/shared/EngineTouchSurface.tsx

@@ -0,0 +1,103 @@
+import { memo, useCallback, useEffect, useRef } from 'react';
+import { type GestureResponderEvent, Platform, StyleSheet, View, type ViewStyle } from 'react-native';
+
+export interface EngineContact {
+  identifier: number;
+  pageX: number;
+  pageY: number;
+  timeStamp: number;
+}
+interface EngineTouchSurfaceProps {
+  enabled: boolean;
+  insets: { top: number; bottom: number };
+  onStart: (contact: EngineContact) => void;
+  onMove: (contact: EngineContact) => void;
+  onEnd: (contact: EngineContact) => void;
+  onCancel: () => void;
+}
+interface PointerContact {
+  isTrusted?: boolean;
+  pointerId: number;
+  button: number;
+  pageX: number;
+  pageY: number;
+  timeStamp: number;
+  currentTarget: { setPointerCapture(id: number): void };
+}
+
+/** Host adapter for simultaneous contacts until GameView exposes raw multi-touch itself. */
+export const EngineTouchSurface = memo(function EngineTouchSurface({ enabled, insets, onStart, onMove, onEnd, onCancel }: EngineTouchSurfaceProps) {
+  const contacts = useRef(new Set<number>());
+  const cancel = useCallback(() => {
+    contacts.current.clear();
+    onCancel();
+  }, [onCancel]);
+  useEffect(() => {
+    if (!enabled) cancel();
+  }, [enabled, cancel]);
+  useEffect(() => () => cancel(), [cancel]);
+  useEffect(() => {
+    if (Platform.OS !== 'web') return;
+    const hide = () => {
+      if (document.hidden) cancel();
+    };
+    window.addEventListener('blur', cancel);
+    document.addEventListener('visibilitychange', hide);
+    return () => {
+      window.removeEventListener('blur', cancel);
+      document.removeEventListener('visibilitychange', hide);
+    };
+  }, [cancel]);
+  const pointerContact = (event: PointerContact): EngineContact => ({
+    identifier: event.pointerId,
+    pageX: event.pageX,
+    pageY: event.pageY,
+    timeStamp: event.timeStamp
+  });
+  const nativeContacts = (event: GestureResponderEvent, phase: 'start' | 'move' | 'end') => {
+    if (!enabled && phase !== 'end') return;
+    const touches = phase === 'move' ? event.nativeEvent.touches : event.nativeEvent.changedTouches;
+    for (const touch of touches) {
+      const contact = { identifier: touch.identifier, pageX: touch.pageX, pageY: touch.pageY, timeStamp: event.timeStamp };
+      if (phase === 'start') onStart(contact);
+      else if (phase === 'move') onMove(contact);
+      else onEnd(contact);
+    }
+  };
+  return (
+    <View
+      collapsable={false}
+      pointerEvents={enabled ? 'auto' : 'none'}
+      style={[styles.surface, insets, Platform.OS === 'web' ? ({ touchAction: 'none' } as ViewStyle) : null]}
+      {...(Platform.OS === 'web'
+        ? {
+            onPointerDown: (value: unknown) => {
+              const event = value as PointerContact;
+              if (!enabled || event.button !== 0) return;
+              if (event.isTrusted !== false) event.currentTarget.setPointerCapture(event.pointerId);
+              contacts.current.add(event.pointerId);
+              onStart(pointerContact(event));
+            },
+            onPointerMove: (value: unknown) => {
+              if (enabled) onMove(pointerContact(value as PointerContact));
+            },
+            onPointerUp: (value: unknown) => {
+              const event = value as PointerContact;
+              contacts.current.delete(event.pointerId);
+              onEnd(pointerContact(event));
+            },
+            onPointerCancel: cancel,
+            onLostPointerCapture: (value: unknown) => {
+              if (contacts.current.has((value as PointerContact).pointerId)) cancel();
+            }
+          }
+        : {
+            onTouchStart: (event: GestureResponderEvent) => nativeContacts(event, 'start'),
+            onTouchMove: (event: GestureResponderEvent) => nativeContacts(event, 'move'),
+            onTouchEnd: (event: GestureResponderEvent) => nativeContacts(event, 'end'),
+            onTouchCancel: cancel
+          })}
+    />
+  );
+});
+const styles = StyleSheet.create({ surface: { position: 'absolute', top: 0, right: 0, bottom: 0, left: 0 } });

package/src/games/shared/EngineUtils.ts

@@ -0,0 +1,52 @@
+// Helpers shared by the Nayan engine games: theme colors as engine colors, and lighting that keeps
+// flat UI surfaces at their exact theme color.
+import type { Color, Light } from '@nayan-ui/engine';
+
+const HEX = /^#([0-9a-f]{6})([0-9a-f]{2})?$/i;
+const RGBA = /^rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)\s*(?:,\s*([\d.]+)\s*)?\)$/i;
+
+/** A theme color ('#RRGGBB', '#RRGGBBAA', 'rgb(a)(…)' or 'transparent') as an engine color, 0..1. */
+export function toColor(css: string, alpha = 1): Color {
+  const hex = HEX.exec(css);
+  if (hex) {
+    const n = parseInt(hex[1]!, 16);
+    const a = hex[2] ? parseInt(hex[2], 16) / 255 : 1;
+    return [((n >> 16) & 255) / 255, ((n >> 8) & 255) / 255, (n & 255) / 255, a * alpha];
+  }
+  const rgba = RGBA.exec(css);
+  if (rgba) return [Number(rgba[1]) / 255, Number(rgba[2]) / 255, Number(rgba[3]) / 255, (rgba[4] === undefined ? 1 : Number(rgba[4])) * alpha];
+  return [0, 0, 0, 0];
+}
+
+/** A theme color's RGB, for GameView's `background`. */
+export function toRgb(css: string): readonly [number, number, number] {
+  const [r, g, b] = toColor(css);
+  return [r, g, b];
+}
+
+/**
+ * A light whose brightness is set so a surface facing the camera (normal +z) is lit at exactly 1: flat
+ * panels, lines and masks show their theme color unchanged, while rounded shapes keep their shading
+ * (lighter toward the light, darker away). Mirrors the engine's shading: ambient × hemisphere (0.8 for
+ * a sideways normal) plus diffuse. Shadows are off: these are flat, point-sized board scenes.
+ */
+export function frontLight(direction: [number, number, number], ambient: number): Light {
+  const [x, y, z] = direction;
+  const facing = z / Math.hypot(x, y, z);
+  const k = 1 / (ambient * 0.8 + (1 - ambient) * facing);
+  return { direction, ambient, shadows: false, color: [k, k, k] };
+}
+
+export { MAX_GAME_WIDTH, gameWidthFor } from './EngineGameWidth';
+
+/**
+ * How long (game seconds) a new board's intro stays due. The screen is laid out again a few frames in,
+ * once the header's real height is measured, and the board rebuilt for it should play the intro again
+ * rather than appear at rest: keep `intro` set until the intro has run this long (`introPlayed`).
+ */
+const INTRO_REPLAY_TIME = 0.5;
+
+/** Ages a due intro by `dt`; once it's played long enough, clears `intro` so later rebuilds show the board at rest. */
+export function introPlayed(g: { intro: boolean; introAge: number }, dt: number) {
+  if (g.intro && g.introAge >= 0 && (g.introAge += dt) >= INTRO_REPLAY_TIME) g.intro = false;
+}

package/src/games/shared/GameActivity.ts

@@ -0,0 +1,13 @@
+import { createContext, useContext, useLayoutEffect } from 'react';
+import type { GameProps } from '../../services/UtilsService';
+
+/** Hosts own navigation; the library reports play state without depending on a navigator. */
+export const GamePlayingContext = createContext<GameProps['onPlayingChange']>(undefined);
+
+export function useGamePlaying(playing: boolean) {
+  const changed = useContext(GamePlayingContext);
+  useLayoutEffect(() => {
+    changed?.(playing);
+    return () => changed?.(false);
+  }, [changed, playing]);
+}

package/src/games/shared/GameLoading.tsx

@@ -0,0 +1,202 @@
+import { memo, useCallback, useEffect, useRef, useState } from 'react';
+import { AccessibilityInfo, ActivityIndicator, type LayoutChangeEvent, Pressable, StyleSheet, Text, View } from 'react-native';
+import { type Font, GameView, isEngineAvailable, warmUpEngine } from '@nayan-ui/engine';
+import { GAMES_METADATA } from '../../services/GamesMetadata';
+import { resolveGameTheme } from '../../services/ThemeService';
+import type { GAME_IDS, GameThemeMode } from '../../services/UtilsService';
+import { loadHudFonts } from './EngineHud';
+import { EngineLoading, LOADING_LIGHT, loadingLook, loadingPlacement } from './EngineLoading';
+import { useGameResource } from './useGameResource';
+
+interface GameLoadingProps {
+  gameId: GAME_IDS;
+  theme?: GameThemeMode;
+  label?: string;
+  error?: boolean;
+  message?: string;
+  onRetry?: () => void;
+  offset?: number;
+  visible?: boolean;
+}
+interface LoadingViewProps extends GameLoadingProps {
+  font: Font;
+  width: number;
+  height: number;
+  reducedMotion: boolean;
+  onFailure: () => void;
+}
+const LoadingView = memo(function LoadingView({
+  gameId,
+  theme,
+  font,
+  width,
+  height,
+  offset = 0,
+  label = 'Getting ready',
+  error = false,
+  message,
+  onRetry,
+  visible = true,
+  reducedMotion,
+  onFailure
+}: LoadingViewProps) {
+  const scene = useGameResource(
+    () => new EngineLoading(gameId, theme, font),
+    (value) => () => value.dispose()
+  );
+  useEffect(() => scene.layout(width, height, offset), [scene, width, height, offset]);
+  useEffect(
+    () => scene.setStatus({ label, error, message, retry: !!onRetry, reducedMotion }),
+    [scene, label, error, message, onRetry, reducedMotion]
+  );
+  const update = useCallback((dt: number) => scene.update(dt), [scene]);
+  const retry = useRef(onRetry);
+  retry.current = onRetry;
+  const tap = useCallback(
+    (x: number, y: number) => {
+      const box = scene.retryBounds;
+      if (error && x >= box.left && x <= box.left + box.width && y >= box.top && y <= box.top + box.height) retry.current?.();
+    },
+    [scene, error]
+  );
+  // This transparent control supplies keyboard/screen-reader access; all visible pixels are engine-drawn.
+  const { retryBounds } = loadingPlacement(width, height, offset);
+  return (
+    <>
+      <GameView
+        source={scene.world}
+        camera={scene.camera}
+        light={LOADING_LIGHT}
+        background={scene.clearColor}
+        onUpdate={update}
+        paused={!visible}
+        onTap={tap}
+        onError={onFailure}
+        style={StyleSheet.absoluteFill}
+      />
+      {visible && error && onRetry && (
+        <Pressable accessibilityRole="button" accessibilityLabel="Try again" onPress={onRetry} style={{ position: 'absolute', ...retryBounds }} />
+      )}
+    </>
+  );
+});
+
+/** Shared engine loading world; only engine-unavailable/bootstrap failures use the text fallback. */
+export const GameLoading = memo(function GameLoading({
+  gameId,
+  theme,
+  label = 'Getting ready',
+  error = false,
+  message,
+  onRetry,
+  offset = 0,
+  visible = true
+}: GameLoadingProps) {
+  const colors = resolveGameTheme(theme);
+  const look = loadingLook(gameId, theme);
+  const title = GAMES_METADATA[gameId].title;
+  const [size, setSize] = useState<{ width: number; height: number } | null>(null);
+  const [font, setFont] = useState<Font | null>(null);
+  const [failed, setFailed] = useState(false);
+  const [reducedMotion, setReducedMotion] = useState(true);
+  useEffect(() => {
+    let alive = true;
+    void AccessibilityInfo.isReduceMotionEnabled().then(
+      (value) => {
+        if (alive) setReducedMotion(value);
+      },
+      () => {}
+    );
+    const subscription = AccessibilityInfo.addEventListener('reduceMotionChanged', setReducedMotion);
+    return () => {
+      alive = false;
+      subscription.remove();
+    };
+  }, []);
+  useEffect(() => {
+    if (font || !visible || !isEngineAvailable || failed) return;
+    let alive = true;
+    void warmUpEngine()
+      .then(loadHudFonts)
+      .then(
+        (fonts) => {
+          if (alive) setFont(fonts.semi);
+        },
+        () => {
+          if (alive) setFailed(true);
+        }
+      );
+    return () => {
+      alive = false;
+    };
+  }, [font, visible, failed]);
+  const layout = useCallback((event: LayoutChangeEvent) => {
+    const { width, height } = event.nativeEvent.layout;
+    setSize((old) => (old?.width === width && old.height === height ? old : { width, height }));
+  }, []);
+  const failure = useCallback(() => setFailed(true), []);
+  const ready = !!font && !!size && size.width > 0 && size.height > 0 && !failed;
+  return (
+    <View
+      testID="game-loading"
+      style={[styles.root, { backgroundColor: look.colours.sky }]}
+      onLayout={layout}
+      accessible={!error}
+      accessibilityLiveRegion="polite"
+      accessibilityRole={error ? 'alert' : 'progressbar'}
+      accessibilityState={{ busy: !error }}
+      accessibilityLabel={`${title}. ${error ? (message ?? 'Unable to prepare this game') : label}`}>
+      {ready ? (
+        <LoadingView
+          key={`${gameId}:${theme}`}
+          gameId={gameId}
+          theme={theme}
+          font={font}
+          width={size.width}
+          height={size.height}
+          label={label}
+          error={error}
+          message={message}
+          onRetry={onRetry}
+          offset={offset}
+          visible={visible}
+          reducedMotion={reducedMotion}
+          onFailure={failure}
+        />
+      ) : (
+        visible && (
+          <View style={[styles.fallback, { paddingTop: offset }]}>
+            <View testID="game-loading-art" accessible={false} style={styles.art}>
+              <View style={[styles.tile, { backgroundColor: look.colours.second, left: 8, top: 26, transform: [{ rotate: '-16deg' }] }]} />
+              <View style={[styles.tile, { backgroundColor: look.colours.horizon, right: 8, top: 26, transform: [{ rotate: '16deg' }] }]} />
+              <View style={[styles.tile, { backgroundColor: look.colours.accent, left: 45, top: 8 }]} />
+            </View>
+            <Text style={[styles.title, { color: colors.TEXT }]}>{title}</Text>
+            {!error && <ActivityIndicator animating={!reducedMotion} hidesWhenStopped={false} color={look.colours.accent} style={styles.spinner} />}
+            <Text
+              accessibilityLiveRegion="polite"
+              accessibilityRole={error ? 'alert' : 'progressbar'}
+              style={[styles.label, { color: colors.TEXT_SUBTLE }]}>
+              {error ? (message ?? 'Unable to prepare this game.') : `${label}…`}
+            </Text>
+            {error && onRetry && (
+              <Pressable accessibilityRole="button" onPress={onRetry} style={[styles.retry, { backgroundColor: colors.SOLID }]}>
+                <Text style={{ color: colors.ON_SOLID }}>Try again</Text>
+              </Pressable>
+            )}
+          </View>
+        )
+      )}
+    </View>
+  );
+});
+const styles = StyleSheet.create({
+  root: { flex: 1 },
+  fallback: { flex: 1, justifyContent: 'center', alignItems: 'center', padding: 24 },
+  art: { width: 144, height: 104, marginBottom: 24 },
+  tile: { position: 'absolute', width: 54, height: 54, borderRadius: 14, borderWidth: 2, borderColor: '#ffffff55' },
+  spinner: { marginTop: 20 },
+  title: { fontSize: 24, fontWeight: '600', textAlign: 'center' },
+  label: { fontSize: 16, marginTop: 12, textAlign: 'center' },
+  retry: { marginTop: 20, paddingHorizontal: 20, paddingVertical: 12, borderRadius: 12 }
+});

package/src/games/shared/GameLoadingTransition.tsx

@@ -0,0 +1,61 @@
+import { memo, type ReactNode, useEffect, useRef, useState } from 'react';
+import { AccessibilityInfo, Animated, Platform, StyleSheet, View } from 'react-native';
+
+interface GameLoadingTransitionProps {
+  ready: boolean;
+  loader: ReactNode;
+  children: ReactNode;
+}
+
+/** Keep the loading surface over the first game frame, then release it after fading. */
+export const GameLoadingTransition = memo(function GameLoadingTransition({ ready, loader, children }: GameLoadingTransitionProps) {
+  const [visible, setVisible] = useState(!ready);
+  const opacity = useRef(new Animated.Value(1)).current;
+  useEffect(() => {
+    if (!ready) {
+      opacity.setValue(1);
+      setVisible(true);
+      return;
+    }
+    if (!visible) return;
+    let active = true;
+    let frame = 0;
+    let animation: Animated.CompositeAnimation | undefined;
+    void AccessibilityInfo.isReduceMotionEnabled()
+      .catch(() => false)
+      .then((reduced) => {
+        if (!active) return;
+        // Give the mounted world time to draw beneath the loading surface.
+        frame = requestAnimationFrame(() => {
+          frame = requestAnimationFrame(() => {
+            if (!active) return;
+            animation = Animated.timing(opacity, { toValue: 0, duration: reduced ? 0 : 160, useNativeDriver: Platform.OS !== 'web' });
+            animation.start(({ finished }) => {
+              if (active && finished) setVisible(false);
+            });
+          });
+        });
+      });
+    return () => {
+      active = false;
+      cancelAnimationFrame(frame);
+      animation?.stop();
+    };
+  }, [ready, visible, opacity]);
+  return (
+    <View style={styles.root}>
+      {ready && children}
+      {(visible || !ready) && (
+        <Animated.View
+          pointerEvents={ready ? 'none' : 'auto'}
+          accessibilityElementsHidden={ready}
+          importantForAccessibility={ready ? 'no-hide-descendants' : 'auto'}
+          style={[StyleSheet.absoluteFill, { opacity: ready ? opacity : 1 }]}>
+          {loader}
+        </Animated.View>
+      )}
+    </View>
+  );
+});
+
+const styles = StyleSheet.create({ root: { flex: 1 } });

package/src/games/shared/ProceduralCacheVersion.ts

@@ -0,0 +1,2 @@
+// Generated from model sources and the engine ABI; do not edit.
+export const PROCEDURAL_CACHE_VERSION = '6db8360ff38ef1524ff6b80f67938974';