rn-gamekit 0.1.0 → 0.2.1

package/src/react/sprites/GameWorld2D.tsx

@@ -1,14 +1,18 @@
 /**
- * `GameWorld2D` — the viewport transform group (T7.6).
+ * `GameWorld2D` — the viewport + camera transform group (T7.6, T12.5).
  *
- * Applies the resolved viewport offset/scale exactly once to all child
- * sprites. It adds no camera state, subscribes no React per frame, and is
- * not a camera API. Raw Skia nodes may be nested inside.
+ * Applies the resolved viewport offset/scale to all child sprites, and —
+ * when the game opts into a camera — composes the presented camera
+ * transform BEFORE the viewport. The group's element list maps world ->
+ * surface directly; `GameLayer2D` children consume the same camera through
+ * the world context and apply only their parallax correction, so layers
+ * never double-apply the camera.
  */
-import type { ReactNode } from 'react';
+import { createContext, useContext, type ReactNode } from 'react';
 import { Group } from '@shopify/react-native-skia';
 import { useDerivedValue, type SharedValue } from 'react-native-reanimated';
 
+import type { CameraCut2D } from '../../camera2d';
 import type { ResolvedViewport2D } from '../../viewport2d/types';
 
 /**
@@ -33,14 +37,116 @@ export function viewportTransform(viewport: ResolvedViewport2D | undefined): rea
   ];
 }
 
+/**
+ * The composed camera + viewport transform (T12.5).
+ *
+ * Skia applies the element list last-first, so the list below is the
+ * forward mapping `surface = viewport(L + rotate(P - C, -R) * Z)`:
+ * translate(-C) -> scale(Z) -> rotate(-R) -> translate(L) -> viewport.
+ */
+export function cameraViewportTransform2D(
+  camera: CameraCut2D | undefined,
+  viewport: ResolvedViewport2D | undefined,
+): readonly (
+  | { readonly translateX: number }
+  | { readonly translateY: number }
+  | { readonly scaleX: number }
+  | { readonly scaleY: number }
+  | { readonly rotate: number }
+)[] {
+  'worklet';
+  if (camera === undefined || viewport === undefined) {
+    return [];
+  }
+  const { center, zoom, rotationRadians } = camera.camera;
+  const view = viewport.visibleLogicalBounds;
+  const logicalX = view.x + view.width / 2;
+  const logicalY = view.y + view.height / 2;
+  return [
+    { translateX: viewport.offsetX },
+    { translateY: viewport.offsetY },
+    { scaleX: viewport.scale },
+    { scaleY: viewport.scale },
+    { translateX: logicalX },
+    { translateY: logicalY },
+    { rotate: -rotationRadians },
+    { scaleX: zoom },
+    { scaleY: zoom },
+    { translateX: -center.x },
+    { translateY: -center.y },
+  ];
+}
+
+/**
+ * The parallax correction for one layer (T12.5).
+ *
+ * A layer with factor p draws with the camera whose effective center is
+ * `C' = L + (C - L) * p` per axis. Since zoom and rotation apply fully at
+ * every factor, the correction relative to the parent camera is exactly a
+ * translation by `(C - L) * (1 - p)` in world units.
+ */
+export function layerParallaxTransform2D(
+  camera: CameraCut2D | undefined,
+  viewport: ResolvedViewport2D | undefined,
+  parallaxX: number,
+  parallaxY: number,
+): readonly ({ readonly translateX: number } | { readonly translateY: number })[] {
+  'worklet';
+  if (camera === undefined || viewport === undefined) {
+    return [];
+  }
+  const view = viewport.visibleLogicalBounds;
+  const logicalX = view.x + view.width / 2;
+  const logicalY = view.y + view.height / 2;
+  const dx = (camera.camera.center.x - logicalX) * (1 - parallaxX);
+  const dy = (camera.camera.center.y - logicalY) * (1 - parallaxY);
+  const elements: ({ readonly translateX: number } | { readonly translateY: number })[] = [];
+  if (dx !== 0) {
+    elements.push({ translateX: dx });
+  }
+  if (dy !== 0) {
+    elements.push({ translateY: dy });
+  }
+  return elements;
+}
+
+/** The camera + viewport context provided by `GameWorld2D`. */
+export interface GameWorldContextValue {
+  readonly viewport: SharedValue<ResolvedViewport2D | undefined>;
+  readonly camera: SharedValue<CameraCut2D | undefined> | undefined;
+}
+
+export const GameWorldContext = createContext<GameWorldContextValue | null>(null);
+
 export function GameWorld2D({
   viewport,
+  camera,
   children,
 }: {
   /** The resolved viewport shared value supplied to the renderer. */
   readonly viewport: SharedValue<ResolvedViewport2D | undefined>;
+  /** The presented camera shared value (T12.5); absent keeps the viewport-only path. */
+  readonly camera?: SharedValue<CameraCut2D | undefined> | undefined;
   readonly children: ReactNode;
 }) {
-  const transform = useDerivedValue(() => viewportTransform(viewport.value));
-  return <Group transform={transform as never}>{children}</Group>;
+  const transform = useDerivedValue(() =>
+    camera === undefined
+      ? viewportTransform(viewport.value)
+      : cameraViewportTransform2D(camera.value, viewport.value),
+  );
+  const context = { viewport, camera };
+  return (
+    <GameWorldContext.Provider value={context}>
+      <Group transform={transform as never}>{children}</Group>
+    </GameWorldContext.Provider>
+  );
+}
+
+/** Consume the world context; throws outside `GameWorld2D`. */
+export function useGameWorldContext(): GameWorldContextValue {
+  const context = useContext(GameWorldContext);
+  if (context === null) {
+    throw new Error('GameLayer2D must be rendered inside a GameWorld2D');
+  }
+  return context;
 }

package/src/react/sprites/Sprite.tsx

@@ -17,10 +17,13 @@ import { useRectBuffer, useRSXformBuffer } from '@shopify/react-native-skia';
 import type { LoadedImage, LoadedSpriteSheet } from '../../assets/types';
 import {
   computeSpriteRsxform,
-  resolveSpriteFrameRect,
   spriteGroupCorrection,
-  type SpriteTransformInput,
 } from './spriteTransform';
+import {
+  applySpriteFrameSelection,
+  materializeSpriteSelection,
+  selectSpriteFrameRect,
+} from './spriteSelection';
 
 export { resolveSpriteFrameRect, type SpriteFrameRect } from './spriteTransform';
 
@@ -82,91 +85,67 @@ export function Sprite({
   // Worklet-safe frame resolution: an explicit `frame` wins; otherwise the
   // clip + elapsed time select the frame (the clip/elapsed may be animated
   // shared values, so the resolution happens inside the rect modifier).
+  // The arithmetic lives in the shared selection contract — this modifier
+  // only adapts props into it (GS-ANIMATION-01).
   const resolveFrameRectWorklet = (
     rect: { setXYWH(x: number, y: number, width: number, height: number): void },
   ): void => {
     'worklet';
     const clipValue = typeof clip === 'string' ? clip : clip?.value;
     const elapsedValue = typeof elapsedMs === 'number' ? elapsedMs : elapsedMs?.value;
-    let name: string | undefined = typeof frame === 'string' ? frame : frame?.value;
-    if (name === undefined && source.descriptor.kind === 'sprite-sheet' && clipValue !== undefined) {
-      const sheet = source as LoadedSpriteSheet;
-      // R3: resolve the clip through the descriptor's animation table, then
-      // the returned frame name through the frame rectangles below.
-      const animation = sheet.descriptor.animations[clipValue];
-      if (animation !== undefined && animation.frames.length > 0) {
-        const duration = animation.frameDurationMs;
-        const count = animation.frames.length;
-        const index =
-          animation.mode === 'once'
-            ? Math.min(Math.floor((elapsedValue ?? 0) / duration), count - 1)
-            : Math.floor((elapsedValue ?? 0) / duration) % count;
-        name = animation.frames[index] ?? animation.frames[0];
-      }
-    }
-    const frameRect =
-      source.descriptor.kind === 'image'
-        ? { x: 0, y: 0, width: (source as LoadedImage).width, height: (source as LoadedImage).height }
-        : name === undefined
-          ? undefined
-          : (source as LoadedSpriteSheet).frames[name];
-    if (frameRect === undefined) {
-      if (name === undefined) {
-        // RF4: the selection has not been published yet (scene mismatch or a
-        // shared frame before its first value): present nothing, never throw.
-        rect.setXYWH(0, 0, 0, 0);
-        return;
-      }
-      throw new Error(
-        `frame ${JSON.stringify(name)} does not belong to this sprite sheet (loaded frames: ${Object.keys((source as LoadedSpriteSheet).frames).join(', ')})`,
-      );
-    }
-    rect.setXYWH(frameRect.x, frameRect.y, frameRect.width, frameRect.height);
-  };
-
-  const staticFrame = typeof frame === 'string' ? frame : undefined;
-  const frameSize = useMemo(() => resolveSpriteFrameRect(source, staticFrame), [source, staticFrame]);
-  const input: SpriteTransformInput = {
-    x,
-    y,
-    rotation,
-    scale,
-    flipX,
-    flipY,
-    anchorX: anchor.x,
-    anchorY: anchor.y,
-    frameWidth: frameSize.width,
-    frameHeight: frameSize.height,
+    const name: string | undefined = typeof frame === 'string' ? frame : frame?.value;
+    applySpriteFrameSelection(rect, source, {
+      ...(name === undefined ? {} : { frame: name }),
+      ...(clipValue === undefined ? {} : { clip: clipValue }),
+      ...(elapsedValue === undefined ? {} : { elapsedMs: elapsedValue }),
+    });
   };
 
   const rects = useRectBuffer(1, resolveFrameRectWorklet);
   const xforms = useRSXformBuffer(1, (xform) => {
     'worklet';
-    // RF4: resolve the selected frame's rectangle and dimensions in the same
-    // worklet update so the anchor math always uses the current frame size.
-    const name = typeof frame === 'string' ? frame : frame?.value;
-    let width = frameSize.width;
-    let height = frameSize.height;
-    if (name !== undefined && source.descriptor.kind === 'sprite-sheet') {
-      const rect = (source as LoadedSpriteSheet).frames[name];
-      if (rect !== undefined) {
-        width = rect.width;
-        height = rect.height;
-      }
-    }
+    // GS-SPRITE-03: the same shared selection the rect modifier resolves,
+    // so clip-driven frame changes reach the anchor math with current
+    // dimensions. Absent selection draws nothing; its transform is finite.
+    const resolved = selectSpriteFrameRect(
+      source,
+      materializeSpriteSelection(frame, clip, elapsedMs),
+    );
     const result = computeSpriteRsxform({
-      ...input,
-      frameWidth: width,
-      frameHeight: height,
+      x,
+      y,
+      rotation,
+      scale,
+      flipX,
+      flipY,
+      anchorX: anchor.x,
+      anchorY: anchor.y,
+      frameWidth: resolved?.width ?? 0,
+      frameHeight: resolved?.height ?? 0,
     });
     xform.set(result.scos, result.ssin, result.tx, result.ty);
   });
-  const groupTransform = useMemo(
-    () => spriteGroupCorrection(input) as unknown as Parameters<typeof Group>[0]['transform'],
-    // The correction reads animated values at draw time; the element list
-    // identity is stable (values are shared-value reads inside the group).
-    [anchor.x, anchor.y, frameSize.width, frameSize.height],
-  );
+  // GS-SPRITE-01: the correction depends on position, rotation, scale,
+  // flips, and the live frame dimensions, so it is derived on the UI
+  // runtime from live values — never memoized from React-render reads.
+  const groupTransform = useDerivedValue(() => {
+    const resolved = selectSpriteFrameRect(
+      source,
+      materializeSpriteSelection(frame, clip, elapsedMs),
+    );
+    return spriteGroupCorrection({
+      x,
+      y,
+      rotation,
+      scale,
+      flipX,
+      flipY,
+      anchorX: anchor.x,
+      anchorY: anchor.y,
+      frameWidth: resolved?.width ?? 0,
+      frameHeight: resolved?.height ?? 0,
+    });
+  }, [x, y, rotation, scale, flipX, flipY, frame, clip, elapsedMs, source, anchor.x, anchor.y]);
   const colors = useMemo(() => (tint === undefined ? undefined : [tint]), [tint]);
 
   // The Skia Group has no `visible` prop: hiding is expressed as a combined

package/src/react/sprites/SpriteBatch.tsx

@@ -5,8 +5,9 @@
  * `Atlas` with fixed-capacity, UI-owned buffers. The normal path owns all
  * derived-value plumbing: `select` maps the committed snapshot to the item
  * array and `write` is a UI-runtime setter that writes transforms in place —
- * no per-frame allocation, no per-frame React, no author-written
- * `useDerivedValue` side effects.
+ * no per-frame React and no author-written `useDerivedValue` side effects.
+ * Per commit the select array, one policy object, and one RSXform result
+ * per written item are allocated; buffers themselves are never reallocated.
  *
  * Contract:
  * - `capacity` is fixed for the mounted batch; active count is explicit.
@@ -20,11 +21,17 @@ import { Atlas, type SkImage } from '@shopify/react-native-skia';
 import { useDerivedValue, type SharedValue } from 'react-native-reanimated';
 import { useRectBuffer, useRSXformBuffer } from '@shopify/react-native-skia';
 
+import type { CameraCut2D } from '../../camera2d';
+import type { Aabb2D } from '../../geometry/types';
 import type { CommitFrame } from '../../core/session/types';
+import { batchVisibleBounds2D, intersectsBounds2D } from './batchVisibility';
+import type { ResolvedViewport2D } from '../../viewport2d/types';
+export { batchVisibleBounds2D, intersectsBounds2D };
 import type { SceneSnapshot } from '../../scene/types';
 import type { SceneMap } from '../../definition/types';
 import type { LoadedImage, LoadedSpriteSheet } from '../../assets/types';
 import { computeSpriteRsxform } from './spriteTransform';
+import { selectSpriteFrameRect } from './spriteSelection';
 import { batchUpdatePolicy } from './spriteBatchPolicy';
 
 /** The per-item write surface handed to the author's `write` mapper. */
@@ -70,6 +77,22 @@ export interface SpriteBatchProps<
   readonly write: (write: SpriteBatchWrite, item: TItem, index: number) => void;
   /** Uniform anchor in [0, 1] relative to the selected frame. */
   readonly anchor?: { readonly x: number; readonly y: number };
+  /**
+   * Optional camera culling (T12.6): items whose authored world bounds fall
+   * outside the conservative visible region are hidden (zero-size slots)
+   * instead of drawn. Slot identity and capacity are unchanged; the
+   * simulation never knows culling happened. `bounds` maps an item to its
+   * world AABB and runs as a worklet on the UI runtime. A bounds record
+   * with non-finite values hides the item (fail-safe: invalid geometry is
+   * never drawn); padding must be finite and nonnegative (T12-F5).
+   */
+  readonly cull?: {
+    readonly camera: SharedValue<CameraCut2D | undefined>;
+    readonly viewport: SharedValue<ResolvedViewport2D | undefined>;
+    readonly bounds: (item: TItem) => Aabb2D;
+    /** Optional world-space padding around the visible region. */
+    readonly padding?: number;
+  };
 }
 
 function frameRectOf(
@@ -77,11 +100,13 @@ function frameRectOf(
   frame: string,
 ): { x: number; y: number; width: number; height: number } | undefined {
   'worklet';
-  if (source.descriptor.kind === 'image') {
-    const image = source as LoadedImage;
-    return { x: 0, y: 0, width: image.width, height: image.height };
+  // GS-SPRITE-04: the shared selection contract resolves the rectangle, so
+  // unknown frames fail with the same actionable error as retained sprites.
+  const resolved = selectSpriteFrameRect(source, { frame });
+  if (resolved === undefined) {
+    throw new Error(`frame ${JSON.stringify(frame)} does not belong to this sprite sheet`);
   }
-  return (source as LoadedSpriteSheet).frames[frame];
+  return resolved;
 }
 
 export function SpriteBatch<
@@ -97,6 +122,7 @@ export function SpriteBatch<
   select,
   write,
   anchor = { x: 0, y: 0 },
+  cull,
 }: SpriteBatchProps<TScenes, TSceneName, TItem>) {
   const image = source.image as SkImage;
   if (!Number.isInteger(capacity) || capacity <= 0) {
@@ -104,6 +130,14 @@ export function SpriteBatch<
       `SpriteBatch capacity must be a positive integer, got ${String(capacity)}`,
     );
   }
+  // T12-F5: culling padding is validated ONCE at the React boundary; the UI
+  // worklet consumes a trusted finite nonnegative scalar.
+  const cullPadding = cull?.padding ?? 0;
+  if (!Number.isFinite(cullPadding) || cullPadding < 0) {
+    throw new RangeError(
+      `SpriteBatch cull.padding must be a finite nonnegative number, got ${String(cullPadding)}`,
+    );
+  }
   const rects = useRectBuffer(capacity, (rect) => {
     'worklet';
     rect.setXYWH(0, 0, 0, 0);
@@ -119,9 +153,11 @@ export function SpriteBatch<
     () => ({
       set: (index, frame, x, y, rotation, scale, visible = true) => {
         'worklet';
-        if (index < 0 || index >= capacity) {
+        // GS-SPRITE-04: the author-exposed index is validated as an integer
+        // slot — a fractional index would silently miss every buffer slot.
+        if (!Number.isInteger(index) || index < 0 || index >= capacity) {
           throw new Error(
-            `SpriteBatch write index ${index} is outside the capacity ${capacity}`,
+            `SpriteBatch write index ${String(index)} is outside the capacity ${capacity}`,
           );
         }
         const rectSlot = rects.value[index];
@@ -161,8 +197,10 @@ export function SpriteBatch<
 
   // The batch's own UI mapper: one derived value reads the committed
   // snapshot, runs the author's select + write per item, and reports the
-  // active count. Buffers are mutated in place; no objects are allocated
-  // per item per frame beyond the item array the select returns.
+  // active count. Buffers are mutated in place with no per-frame React;
+  // per commit the select array, one policy object, and one RSXform result
+  // per written item are allocated (GS-SPRITE-04: scalar writers stay
+  // unjustified without a benchmark showing this matters).
   const activeCount = useDerivedValue(() => {
     'worklet';
     const envelope = commit.value;
@@ -182,22 +220,36 @@ export function SpriteBatch<
       alpha: alpha.value,
     });
     const policy = batchUpdatePolicy(items.length, capacity, __DEV__);
-    if (policy.overflow) {
-      // RF8: production never crashes the UI runtime for ordinary data
-      // growth: hide the overflowing items.
-      for (let index = capacity; index < items.length; index += 1) {
+    // GS-SPRITE-04: no overflow loop — `policy.activeCount` already clamps
+    // production writes to capacity, and every buffer slot past capacity is
+    // absent by construction, so iterating [capacity, items.length) could
+    // only add unbounded dead work.
+    const count = policy.activeCount;
+    // T12.6 + T12-F5: culling hides off-screen slots in place, and
+    // authored writes run ONLY through `policy.activeCount`. In production
+    // an overflowing item (index >= capacity) is never written and never
+    // indexes a buffer — the [count, capacity) hide loop below clears the
+    // unused tail. The visible bounds are computed once per commit from the
+    // PRESENTED camera; hidden slots are cleared directly (zero size)
+    // without touching the author's write or reallocating buffers, so slot
+    // identity is stable across camera moves.
+    const visible =
+      cull === undefined
+        ? undefined
+        : batchVisibleBounds2D(cull.camera.value, cull.viewport.value, cullPadding);
+    for (let index = 0; index < count; index += 1) {
+      const item = items[index];
+      if (item === undefined) {
+        continue;
+      }
+      if (visible !== undefined && !intersectsBounds2D(cull!.bounds(item), visible)) {
         const slot = rects.value[index];
         if (slot !== undefined) {
           slot.setXYWH(0, 0, 0, 0);
         }
+        continue;
       }
-    }
-    const count = policy.activeCount;
-    for (let index = 0; index < items.length; index += 1) {
-      const item = items[index];
-      if (item !== undefined) {
-        write(writeApi, item, index);
-      }
+      write(writeApi, item, index);
     }
     // Hide every inactive slot.
     for (let index = count; index < capacity; index += 1) {
@@ -207,7 +259,7 @@ export function SpriteBatch<
       }
     }
     return count;
-  }, [commit, alpha, scene, select, write, writeApi]);
+  }, [commit, alpha, scene, select, write, writeApi, cull, cullPadding]);
 
   void activeCount;
 

package/src/react/sprites/batchVisibility.ts

@@ -0,0 +1,76 @@
+/**
+ * Batch culling math (T12.6, T12-F5) — pure and worklet-safe, with no React
+ * imports, so the benchmark and headless tests can import them directly.
+ */
+import type { CameraCut2D } from '../../camera2d';
+import { rotatedHalfExtents2D } from '../../camera2d/extents';
+import type { Aabb2D } from '../../geometry/types';
+import type { ResolvedViewport2D } from '../../viewport2d/types';
+
+/**
+ * Conservative visible bounds for batch culling (T12.6).
+ *
+ * Worklet-safe inline version of the headless `paddedCameraBounds2D` —
+ * the presented camera is already validated at the public boundary, so the
+ * per-frame path allocates nothing and validates nothing.
+ */
+export function batchVisibleBounds2D(
+  camera: CameraCut2D | undefined,
+  viewport: ResolvedViewport2D | undefined,
+  padding: number,
+): Aabb2D | undefined {
+  'worklet';
+  if (camera === undefined || viewport === undefined) {
+    return undefined;
+  }
+  const view = viewport.visibleLogicalBounds;
+  const extent = rotatedHalfExtents2D(
+    view.width / 2 / camera.camera.zoom,
+    view.height / 2 / camera.camera.zoom,
+    camera.camera.rotationRadians,
+  );
+  const extentX = extent.x + padding;
+  const extentY = extent.y + padding;
+  return {
+    x: camera.camera.center.x - extentX,
+    y: camera.camera.center.y - extentY,
+    width: extentX * 2,
+    height: extentY * 2,
+  };
+}
+
+function isFiniteBounds(bounds: Aabb2D): boolean {
+  'worklet';
+  return (
+    Number.isFinite(bounds.x) &&
+    Number.isFinite(bounds.y) &&
+    Number.isFinite(bounds.width) &&
+    Number.isFinite(bounds.height) &&
+    bounds.width >= 0 &&
+    bounds.height >= 0
+  );
+}
+
+/** Axis-aligned intersection test, worklet-safe (no validation).
+ *
+ * Inclusive comparisons, matching the public `intersectsAabbAabb2D`
+ * contract (T12-F5): exact boundary contact IS an intersection, so a
+ * sprite touching the camera edge is never culled.
+ *
+ * T12-RF6 malformed-bounds fail-safe: any non-finite field or negative
+ * size in EITHER rect hides the item (returns false) before the
+ * intersection test — invalid geometry is never drawn. Scalar and
+ * allocation-free; no structured error construction on the UI path.
+ */
+export function intersectsBounds2D(first: Aabb2D, second: Aabb2D): boolean {
+  'worklet';
+  if (!isFiniteBounds(first) || !isFiniteBounds(second)) {
+    return false;
+  }
+  return (
+    first.x <= second.x + second.width &&
+    first.x + first.width >= second.x &&
+    first.y <= second.y + second.height &&
+    first.y + first.height >= second.y
+  );
+}