rn-gamekit 0.1.0 → 0.2.1

package/src/react/particles/ParticleView.tsx

@@ -0,0 +1,358 @@
+import { useContext, useMemo } from 'react';
+import { Atlas, Picture, Skia } from '@shopify/react-native-skia';
+import { useColorBuffer, useRectBuffer, useRSXformBuffer } from '@shopify/react-native-skia';
+import { useDerivedValue, type SharedValue } from 'react-native-reanimated';
+import type { SkImage, SkColor } from '@shopify/react-native-skia';
+
+import { GameWorldContext } from '../sprites/GameWorld2D';
+import type {
+  ParticleEffectDefinition,
+  ParticleEmissionRecord,
+  ParticleSystem,
+  ParticleUiRegistry,
+} from '../../particles/types';
+
+import {
+  PARTICLE_CULL_PADDING,
+  cameraVisibleWorldBounds,
+  maxParticleExtent,
+  screenVisibleBounds,
+  viewportWorldBounds,
+  visibleInBounds,
+} from './culling';
+import { assertUniformParticleSpriteRatio, particleSpriteXform } from './spriteXForm';
+
+export interface ParticleViewProps {
+  readonly system: ParticleSystem;
+  readonly effect: string;
+  /** Surface size: px for screen space, world units for world space. */
+  readonly width: number;
+  readonly height: number;
+  /**
+   * The presentation handle from `useParticlePresentation`: a scalar
+   * active-time clock plus the bounded emission registry. Views are pure
+   * readers and NEVER advance the system clock (T15-F1).
+   */
+  readonly presentation: {
+    readonly clock: SharedValue<number>;
+    readonly registry: SharedValue<ParticleUiRegistry>;
+  };
+  /**
+   * Sprite source for `kind: 'sprite'` effects — the decoded sheet resolved
+   * once at bind time by the caller. Required for sprite effects; a missing
+   * source is a structured render error (T15-F3).
+   */
+  readonly spriteSource?: {
+    readonly image: SkImage;
+    readonly frame: { x: number; y: number; width: number; height: number };
+  };
+}
+
+/**
+ * Presentation-only particle renderer.
+ *
+ * Topology is CONSTANT per effect regardless of capacity (T15-RF5): exactly
+ * one React node (`Picture` for shapes, `Atlas` for sprites) plus a single
+ * UI-runtime derived worklet that walks the effect's emission records and
+ * computes analytic transforms from the scalar active-time clock. No per-slot
+ * data crosses the runtime boundary per frame (T15-SF1).
+ *
+ * Coordinate ownership (GS-PARTICLE-02): `space: 'world'` effects sample in
+ * world units and must mount inside world space (no parent transform);
+ * `space: 'screen'` effects sample in surface pixels and must mount inside
+ * screen space. World culling uses the presented camera when one exists
+ * and the resolved viewport bounds otherwise; zoom applies through the
+ * camera, and there is no parallax factor on particles by design.
+ */
+export function ParticleView({
+  system,
+  effect,
+  width,
+  height,
+  presentation,
+  spriteSource,
+}: ParticleViewProps) {
+  const definition = useMemo<ParticleEffectDefinition>(
+    () => system.bindPresentation().definition(effect),
+    [system, effect],
+  );
+  // GS-PARTICLE-02: conservative cull extent from authored geometry and
+  // scale endpoints (bounding radius, rotation-proof); overscan stays in
+  // the bounds padding, never in this extent.
+  const cullExtent = useMemo(() => maxParticleExtent(definition), [definition]);
+  const world = useContext(GameWorldContext);
+  const camera = (world?.camera ?? null) as never;
+  const viewport = (world?.viewport ?? null) as never;
+
+  if (definition.particle.kind === 'sprite') {
+    if (spriteSource === undefined) {
+      throw new Error(
+        `[rn-gamekit/particles] effect "${effect}" declares kind "sprite" but no spriteSource was provided — resolve the sheet via the asset store before rendering`,
+      );
+    }
+    assertUniformParticleSpriteRatio(
+      definition.particle.size.width,
+      definition.particle.size.height,
+      spriteSource.frame.width,
+      spriteSource.frame.height,
+    );
+    return (
+      <SpriteSlots
+        clock={presentation.clock}
+        registry={presentation.registry}
+        effect={effect}
+        capacity={definition.capacity}
+        image={spriteSource.image}
+        frameRect={spriteSource.frame}
+        drawWidth={definition.particle.size.width}
+        drawHeight={definition.particle.size.height}
+        cullExtent={cullExtent}
+        fadeOut={definition.fadeOut}
+        gravityX={definition.gravity.x}
+        gravityY={definition.gravity.y}
+        width={width}
+        height={height}
+        space={definition.space}
+        camera={camera}
+        viewport={viewport}
+      />
+    );
+  }
+
+  return (
+    <ShapeBatch
+      clock={presentation.clock}
+      registry={presentation.registry}
+      effect={effect}
+      capacity={definition.capacity}
+      shape={definition.particle.shape === 'rectangle' ? 'rect' : 'circle'}
+      radius={definition.particle.radius ?? 3}
+      rectWidth={definition.particle.width ?? 6}
+      rectHeight={definition.particle.height ?? 6}
+      cullExtent={cullExtent}
+      color={definition.particle.color ?? '#ffffff'}
+      fadeOut={definition.fadeOut}
+      gravityX={definition.gravity.x}
+      gravityY={definition.gravity.y}
+      width={width}
+      height={height}
+      space={definition.space}
+      camera={camera}
+      viewport={viewport}
+    />
+  );
+}
+
+/**
+ * Analytic transform for one emission at the given ACTIVE time.
+ *
+ * T15-TF3: opacity honors the definition's fade policy — `fadeOut: true`
+ * ramps `1 -> t`, `fadeOut: false` stays fully opaque for the whole life.
+ */
+export function sampleEmission(
+  e: ParticleEmissionRecord,
+  now: number,
+  gravityX: number,
+  gravityY: number,
+  fadeOut: boolean,
+): { x: number; y: number; rotation: number; scale: number; opacity: number; alive: boolean } {
+  'worklet';
+  const age = now - e.bornAt;
+  if (age < 0 || age >= e.lifetime) {
+    return { x: 0, y: 0, rotation: 0, scale: 0, opacity: 0, alive: false };
+  }
+  const t = age / e.lifetime;
+  const x = e.originX + e.vx * age + 0.5 * gravityX * age * age;
+  const y = e.originY + e.vy * age + 0.5 * gravityY * age * age;
+  const rotation = e.rotation + e.rotationSpeed * age;
+  // T20A-R1: definitions guarantee non-negative scale. The clamp keeps any
+  // legacy negative `scaleOverLife` value DEFINED (collapse to a point)
+  // instead of handing Skia a signed radius or rectangle extent.
+  const scale = Math.max(0, e.scaleStart + (e.scaleEnd - e.scaleStart) * t);
+  const opacity = fadeOut ? 1 - t : 1;
+  return { x, y, rotation, scale, opacity, alive: true };
+}
+
+// ---------------------------------------------------------------------------
+// Shapes: ONE immediate Picture built in ONE worklet per effect (T15-RF5).
+// ---------------------------------------------------------------------------
+
+function ShapeBatch(props: {
+  readonly clock: SharedValue<number>;
+  readonly registry: SharedValue<ParticleUiRegistry>;
+  readonly effect: string;
+  readonly capacity: number;
+  readonly shape: 'circle' | 'rect';
+  readonly radius: number;
+  readonly rectWidth: number;
+  readonly rectHeight: number;
+  readonly color: string;
+  readonly fadeOut: boolean;
+  readonly gravityX: number;
+  readonly gravityY: number;
+  readonly width: number;
+  readonly height: number;
+  readonly space: 'world' | 'screen';
+  readonly cullExtent: number;
+  readonly camera: unknown;
+  readonly viewport: unknown;
+}) {
+  const { clock, registry, effect, capacity, shape, radius, rectWidth, rectHeight, color, fadeOut, gravityX, gravityY, width, height, space, cullExtent, camera, viewport } =
+    props;
+
+  const picture = useDerivedValue(() => {
+    'worklet';
+    const reg = registry.value;
+    const entry = reg.effects[effect];
+    const now = clock.value;
+    // Culling bounds computed ONCE per revision. World space without a
+    // presented camera falls back to the resolved viewport bounds (never
+    // fail-closed hide); the particle extent keeps crossings visible.
+    const bounds =
+      space === 'world'
+        ? (camera as { value?: { camera?: unknown } } | null)?.value?.camera === undefined
+          ? viewportWorldBounds(viewport as never, PARTICLE_CULL_PADDING)
+          : cameraVisibleWorldBounds(camera as never, viewport as never, PARTICLE_CULL_PADDING)
+        : screenVisibleBounds(width, height, PARTICLE_CULL_PADDING);
+
+    const recorder = Skia.PictureRecorder();
+    const canvas = recorder.beginRecording();
+    if (entry === undefined) return recorder.finishRecordingAsPicture();
+
+    const paint = Skia.Paint();
+    paint.setColor(Skia.Color(color));
+
+    const particles = entry.particles;
+    for (let i = 0; i < particles.length && i < capacity; i++) {
+      const e = particles[i]!;
+      const s = sampleEmission(e, now, gravityX, gravityY, fadeOut);
+      if (!s.alive || s.opacity <= 0) continue;
+      if (!visibleInBounds(s.x, s.y, cullExtent, bounds)) continue;
+      paint.setAlphaf(Math.max(0, Math.min(1, s.opacity)));
+      if (shape === 'circle') {
+        canvas.drawCircle(s.x, s.y, radius * s.scale, paint);
+      } else {
+        const w = rectWidth * s.scale;
+        const h = rectHeight * s.scale;
+        const matrix = Skia.Matrix().translate(s.x, s.y).rotate(s.rotation);
+        canvas.save();
+        canvas.concat(matrix);
+        canvas.drawRect({ x: -w / 2, y: -h / 2, width: w, height: h }, paint);
+        canvas.restore();
+      }
+    }
+    return recorder.finishRecordingAsPicture();
+  });
+
+  return <Picture picture={picture} />;
+}
+
+// ---------------------------------------------------------------------------
+// Sprites: fixed-capacity Atlas buffers filled by ONE worklet (T15-F3/R4/SF2).
+// ---------------------------------------------------------------------------
+
+function SpriteSlots(props: {
+  readonly clock: SharedValue<number>;
+  readonly registry: SharedValue<ParticleUiRegistry>;
+  readonly effect: string;
+  readonly capacity: number;
+  readonly image: SkImage;
+  readonly frameRect: { x: number; y: number; width: number; height: number };
+  readonly drawWidth: number;
+  readonly drawHeight: number;
+  readonly fadeOut: boolean;
+  readonly gravityX: number;
+  readonly gravityY: number;
+  readonly width: number;
+  readonly height: number;
+  readonly space: 'world' | 'screen';
+  readonly cullExtent: number;
+  readonly camera: unknown;
+  readonly viewport: unknown;
+}) {
+  const { clock, registry, effect, capacity, image, frameRect, drawWidth, drawHeight, fadeOut, gravityX, gravityY, width, height, space, cullExtent, camera, viewport } =
+    props;
+
+  // UI-owned buffers created once per mount (T15-SF1). Colors use the
+  // supported Skia color buffer (T15-TF3): each entry is an SkColor
+  // Float32Array [r,g,b,a] mutated on the UI runtime.
+  const rects = useRectBuffer(capacity, (rect) => {
+    'worklet';
+    rect.setXYWH(0, 0, 0, 0);
+  });
+  const xforms = useRSXformBuffer(capacity, (xform) => {
+    'worklet';
+    xform.set(1, 0, 0, 0);
+  });
+  const colors = useColorBuffer(capacity, (color: SkColor) => {
+    'worklet';
+    color[0] = 1;
+    color[1] = 1;
+    color[2] = 1;
+    color[3] = 0;
+  });
+
+  useDerivedValue(() => {
+    'worklet';
+    const reg = registry.value;
+    const entry = reg.effects[effect];
+    const now = clock.value;
+    const bounds =
+      space === 'world'
+        ? (camera as { value?: { camera?: unknown } } | null)?.value?.camera === undefined
+          ? viewportWorldBounds(viewport as never, PARTICLE_CULL_PADDING)
+          : cameraVisibleWorldBounds(camera as never, viewport as never, PARTICLE_CULL_PADDING)
+        : screenVisibleBounds(width, height, PARTICLE_CULL_PADDING);
+
+    for (let i = 0; i < capacity; i++) {
+      const rectSlot = rects.value[i];
+      const xformSlot = xforms.value[i];
+      const colorSlot: SkColor | undefined = colors.value[i];
+      if (rectSlot === undefined || xformSlot === undefined || colorSlot === undefined) continue;
+
+      let placed = false;
+      if (entry !== undefined && i < entry.particles.length) {
+        const e = entry.particles[i]!;
+        const age = now - e.bornAt;
+        if (age >= 0 && age < e.lifetime) {
+          const t = age / e.lifetime;
+          const x = e.originX + e.vx * age + 0.5 * gravityX * age * age;
+          const y = e.originY + e.vy * age + 0.5 * gravityY * age * age;
+          if (visibleInBounds(x, y, cullExtent, bounds)) {
+            const op = fadeOut ? 1 - t : 1;
+            const xf = particleSpriteXform({
+              x,
+              y,
+              rotation: e.rotation + e.rotationSpeed * age,
+              // T20A-R1: non-negative clamp — see the shape sampler note.
+              scale: Math.max(0, e.scaleStart + (e.scaleEnd - e.scaleStart) * t),
+              drawWidth,
+              drawHeight,
+              frameWidth: frameRect.width,
+              frameHeight: frameRect.height,
+            });
+            rectSlot.setXYWH(frameRect.x, frameRect.y, frameRect.width, frameRect.height);
+            xformSlot.set(xf.scos, xf.ssin, xf.tx, xf.ty);
+            // White modulates the texture; alpha carries sampled fade.
+            colorSlot[0] = 1;
+            colorSlot[1] = 1;
+            colorSlot[2] = 1;
+            colorSlot[3] = Math.max(0, Math.min(1, op));
+            placed = true;
+          }
+        }
+      }
+      if (!placed) {
+        // Hide inactive/culled slots AND clear stale alpha (T15-SF2).
+        rectSlot.setXYWH(0, 0, 0, 0);
+        colorSlot[0] = 1;
+        colorSlot[1] = 1;
+        colorSlot[2] = 1;
+        colorSlot[3] = 0;
+      }
+    }
+    return colors;
+  });
+
+  return <Atlas image={image} sprites={rects} transforms={xforms} colors={colors} />;
+}

package/src/react/particles/culling.ts

@@ -0,0 +1,145 @@
+/** Conservative world-space AABB used for presentation-only culling. */
+import { rotatedHalfExtents2D } from '../../camera2d/extents';
+import type { ParticleEffectDefinition } from '../../particles/types';
+export interface WorldAabb {
+  readonly minX: number;
+  readonly minY: number;
+  readonly maxX: number;
+  readonly maxY: number;
+}
+
+export const PARTICLE_CULL_PADDING = 16;
+
+/**
+ * The world region visible through the PRESENTED camera (T15-RF2).
+ *
+ * The logical viewport rectangle is rotated/zoomed by the camera, so its
+ * axis-aligned world bounds are the center plus the rotated half-extents:
+ *
+ *   ex = |hx·cosθ| + |hy·sinθ|, ey = |hx·sinθ| + |hy·cosθ|
+ *
+ * which is the exact AABB of the rotated view rect. Padding is applied in
+ * world units. Worklet-safe; shared by the shape Picture and Atlas paths so
+ * their culling results cannot diverge.
+ */
+export function cameraVisibleWorldBounds(
+  camera: SharedCamera | null,
+  viewport: SharedViewport | null,
+  pad: number,
+): WorldAabb | undefined {
+  'worklet';
+  if (camera === null || viewport === null) return undefined;
+  const view = viewport.value?.visibleLogicalBounds;
+  const cam = camera.value?.camera;
+  if (view === undefined || cam === undefined) return undefined;
+  const hx = view.width / (2 * cam.zoom);
+  const hy = view.height / (2 * cam.zoom);
+  const extent = rotatedHalfExtents2D(hx, hy, cam.rotationRadians);
+  const ex = extent.x + pad;
+  const ey = extent.y + pad;
+  return {
+    minX: cam.center.x - ex,
+    minY: cam.center.y - ey,
+    maxX: cam.center.x + ex,
+    maxY: cam.center.y + ey,
+  };
+}
+
+export function screenVisibleBounds(
+  width: number,
+  height: number,
+  pad: number,
+): WorldAabb {
+  'worklet';
+  return { minX: -pad, minY: -pad, maxX: width + pad, maxY: height + pad };
+}
+
+/**
+ * Viewport-only world bounds for presentation without a presented camera
+ * (GS-PARTICLE-02): the tile layer's viewport-only path — the resolved
+ * logical bounds expanded by world-unit padding. World particles inside an
+ * ordinary viewport-only GameWorld2D render instead of failing closed.
+ */
+export function viewportWorldBounds(
+  viewport: SharedViewport | null,
+  pad: number,
+): WorldAabb | undefined {
+  'worklet';
+  const view = viewport?.value?.visibleLogicalBounds;
+  if (view === undefined) return undefined;
+  return {
+    minX: view.x - pad,
+    minY: view.y - pad,
+    maxX: view.x + view.width + pad,
+    maxY: view.y + view.height + pad,
+  };
+}
+
+/**
+ * Circle-vs-bounds visibility (GS-PARTICLE-02): the particle's
+ * conservative extent (bounding radius from geometry and scale endpoints)
+ * expands the bounds, so partially crossing shapes stay visible while
+ * fully outside shapes cull. Extra overscan stays in the bounds padding —
+ * never folded into the shape extent. A missing bounds still hides.
+ */
+export function visibleInBounds(
+  x: number,
+  y: number,
+  extent: number,
+  b: WorldAabb | undefined,
+): boolean {
+  'worklet';
+  if (b === undefined) return false;
+  return x >= b.minX - extent && x <= b.maxX + extent && y >= b.minY - extent && y <= b.maxY + extent;
+}
+
+/**
+ * Conservative per-effect cull extent (GS-PARTICLE-02): the bounding
+ * radius of the authored geometry times the largest scale endpoint, so
+ * rotation can never push drawn pixels past the culled region. Circles
+ * use radius; rectangles and sprites use half the diagonal; absent
+ * dimensions fall back to the render defaults. The legacy scale range
+ * contributes its maximum; definitions without scale use 1.
+ */
+export function maxParticleExtent(definition: ParticleEffectDefinition): number {
+  'worklet';
+  let maxScale = 1;
+  const scale = (definition as { scale?: { start: { max: number }; end: { max: number } } }).scale;
+  if (scale !== undefined) {
+    if (scale.start.max > maxScale) maxScale = scale.start.max;
+    if (scale.end.max > maxScale) maxScale = scale.end.max;
+  }
+  const legacy = (
+    definition as { scaleOverLife?: { max: number } }
+  ).scaleOverLife;
+  if (legacy !== undefined && legacy.max > maxScale) maxScale = legacy.max;
+  const particle = definition.particle;
+  if (particle.kind === 'sprite') {
+    return (Math.hypot(particle.size.width, particle.size.height) / 2) * maxScale;
+  }
+  if (particle.shape === 'circle') {
+    return (particle.radius ?? 3) * maxScale;
+  }
+  return (Math.hypot(particle.width ?? 6, particle.height ?? 6) / 2) * maxScale;
+}
+// keeping this pure module free of Reanimated/RN imports while accepting
+// real SharedValue<CameraCut2D|ResolvedViewport2D> instances.
+// Minimal structural mirrors of the shared refs the view layer passes in,
+// keeping this pure module free of Reanimated/RN imports while accepting
+// real SharedValue<CameraCut2D|ResolvedViewport2D> instances.
+interface SharedCamera {
+  readonly value?:
+    | {
+        readonly camera?: {
+          readonly center: { readonly x: number; readonly y: number };
+          readonly zoom: number;
+          readonly rotationRadians: number;
+        };
+      }
+    | undefined;
+}
+interface SharedViewport {
+  readonly value?:
+    | { readonly visibleLogicalBounds?: { readonly x: number; readonly y: number; readonly width: number; readonly height: number } }
+    | undefined;
+}

package/src/react/particles/index.ts

@@ -0,0 +1,6 @@
+export { ParticleView } from './ParticleView';
+export type { ParticleViewProps } from './ParticleView';
+export { useParticlePresentation } from './useParticlePresentation';
+export type { ParticlePresentation, SessionStatus } from './useParticlePresentation';
+export { particleSpriteXform, assertUniformParticleSpriteRatio } from './spriteXForm';
+export { cameraVisibleWorldBounds, screenVisibleBounds, visibleInBounds, PARTICLE_CULL_PADDING } from './culling';

package/src/react/particles/spriteXForm.ts

@@ -0,0 +1,72 @@
+/**
+ * Particle sprite transform (T15-RF4).
+ *
+ * Atlas RSXform carries rotation AND uniform scale in its 2×2 part:
+ * \`scos = s·cosθ\`, \`ssin = s·sinθ\`. The pivot compensation uses the
+ * AUTHORED draw size (the definition's \`size\`), and the source rect stays
+ * the sheet frame — so the authored-to-source ratio scales the drawn sprite.
+ *
+ * v1 requires the authored size ratio to match the source frame ratio; a
+ * mismatch is a structured error (RSXform cannot express nonuniform scale).
+ */
+import { ParticleError } from '../../particles/errors';
+
+export interface ParticleSpriteXformInput {
+  /** Sampled CENTER position (surface or world units). */
+  readonly x: number;
+  readonly y: number;
+  /** Sampled rotation in radians. */
+  readonly rotation: number;
+  /** Sampled uniform scale (scaleOverLife domain). */
+  readonly scale: number;
+  /** Authored draw size (definition particle.size). */
+  readonly drawWidth: number;
+  readonly drawHeight: number;
+  /** Source frame size in sheet pixels. */
+  readonly frameWidth: number;
+  readonly frameHeight: number;
+}
+
+export interface ParticleSpriteXform {
+  readonly scos: number;
+  readonly ssin: number;
+  readonly tx: number;
+  readonly ty: number;
+}
+
+export function particleSpriteXform(input: ParticleSpriteXformInput): ParticleSpriteXform {
+  'worklet';
+  // T15-SF2: Atlas draws the SOURCE rect, so the authored-to-source ratio
+  // must ride in scos/ssin or the drawn size ignores particle.size entirely.
+  const effScale = input.scale * (input.drawWidth / input.frameWidth);
+  const cos = Math.cos(input.rotation);
+  const sin = Math.sin(input.rotation);
+  // Center anchor pivot against the DRAWN (scaled source) extent.
+  const px = (input.frameWidth / 2) * effScale;
+  const py = (input.frameHeight / 2) * effScale;
+  return {
+    scos: effScale * cos,
+    ssin: effScale * sin,
+    tx: input.x - px * cos + py * sin,
+    ty: input.y - px * sin - py * cos,
+  };
+}
+
+/**
+ * Validate that the authored size ratio matches the source frame ratio so
+ * uniform-scale Atlas drawing preserves the intended aspect.
+ */
+export function assertUniformParticleSpriteRatio(
+  drawWidth: number,
+  drawHeight: number,
+  frameWidth: number,
+  frameHeight: number,
+): void {
+  const drawRatio = drawWidth / drawHeight;
+  const frameRatio = frameWidth / frameHeight;
+  if (!Number.isFinite(drawRatio) || !Number.isFinite(frameRatio) || Math.abs(drawRatio - frameRatio) > 1e-3) {
+    throw new ParticleError(
+      `[rn-gamekit/particles] sprite effect size ${drawWidth}x${drawHeight} does not match source frame ${frameWidth}x${frameHeight} aspect — nonuniform sprite scaling is not supported in v1`,
+    );
+  }
+}