rn-gamekit 0.1.0 → 0.2.1

package/src/particles/sampling.ts

@@ -0,0 +1,141 @@
+import type { ParticleEffectDefinition } from './types';
+import type { Point2D } from '../geometry/types';
+
+/** Deterministic PRNG (mulberry32). Documented, schedule-independent. */
+export function createRng(seed: number): () => number {
+  let s = seed >>> 0;
+  return () => {
+    s |= 0;
+    s = (s + 0x6d2b79f5) | 0;
+    let t = Math.imul(s ^ (s >>> 15), 1 | s);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+export function hashSeed(seed: number): number {
+  let h = seed >>> 0;
+  h = Math.imul(h ^ (h >>> 16), 0x85ebca6b);
+  h = Math.imul(h ^ (h >>> 13), 0xc2b2ae35);
+  return (h ^ (h >>> 16)) >>> 0;
+}
+
+export function sampleRange(rng: () => number, range: { min: number; max: number }): number {
+  if (range.min === range.max) return range.min;
+  return range.min + rng() * (range.max - range.min);
+}
+
+/** Internal sampled seed values for one new particle slot. */
+export interface SampledInitial {
+  readonly active: boolean;
+  readonly age: number;
+  readonly lifetime: number;
+  readonly origin: Point2D;
+  readonly position: Point2D;
+  readonly velocity: Point2D;
+  readonly rotation: number;
+  readonly rotationSpeed: number;
+  readonly scaleStart: number;
+  readonly scaleEnd: number;
+  readonly scale: number;
+  readonly opacity: number;
+  readonly color: string;
+  readonly spawnSequence: number;
+  readonly effect: string;
+}
+
+/**
+ * Field consumption order is fixed and documented:
+ * lifetime -> speed -> direction -> rotation -> rotationSpeed -> scaleStart
+ * -> scaleEnd (envelope only; the legacy `scaleOverLife` range draws once).
+ */
+function toRange(endpoint: number | { min: number; max: number }): { min: number; max: number } {
+  return typeof endpoint === 'number' ? { min: endpoint, max: endpoint } : endpoint;
+}
+
+export function sampleInitialSlot(
+  rng: () => number,
+  def: ParticleEffectDefinition,
+  origin: Point2D,
+  spawnSequence: number,
+  effectName: string,
+): SampledInitial {
+  const lifetime = sampleRange(rng, def.lifetimeSeconds);
+  const speed = sampleRange(rng, def.speed);
+  const directionRange = def.direction ?? { min: 0, max: Math.PI * 2 };
+  const direction = sampleRange(rng, directionRange);
+  const rotation = def.rotation ? sampleRange(rng, def.rotation) : 0;
+  const rotationSpeed = def.rotation ? sampleRange(rng, { min: -2, max: 2 }) : 0;
+  let scaleStart: number;
+  let scaleEnd: number;
+  if (def.scale) {
+    // T20.1 explicit envelope: both endpoints are sampled, start before end.
+    scaleStart = sampleRange(rng, toRange(def.scale.start));
+    scaleEnd = sampleRange(rng, toRange(def.scale.end));
+  } else {
+    // Legacy semantics (byte-for-byte): one draw for the start, max as end.
+    const scaleRange = def.scaleOverLife ?? { min: 1, max: 1 };
+    scaleStart = sampleRange(rng, scaleRange);
+    scaleEnd = scaleRange.max;
+  }
+  const vx = Math.cos(direction) * speed;
+  const vy = Math.sin(direction) * speed;
+  return {
+    active: true,
+    age: 0,
+    lifetime,
+    origin: { x: origin.x, y: origin.y },
+    position: { x: origin.x, y: origin.y },
+    velocity: { x: vx, y: vy },
+    rotation,
+    rotationSpeed,
+    scaleStart,
+    scaleEnd,
+    scale: scaleStart,
+    opacity: 1,
+    color: def.particle.kind === 'shape' && def.particle.color ? def.particle.color : '#ffffff',
+    spawnSequence,
+    effect: effectName,
+  };
+}
+
+/** The pure sampler's input view of a particle's age-independent fields. */
+export interface AgeSource {
+  readonly lifetime: number;
+  readonly origin: Point2D;
+  readonly velocity: Point2D;
+  readonly rotation: number;
+  readonly rotationSpeed: number;
+  readonly scaleStart: number;
+  readonly scaleEnd: number;
+}
+
+export interface SampledTransform {
+  readonly x: number;
+  readonly y: number;
+  readonly rotation: number;
+  readonly scale: number;
+  readonly opacity: number;
+}
+
+/**
+ * Closed-form sampling from active age (never accumulated):
+ * position = origin + v·age + ½·a·age². Positions follow the CENTER anchor
+ * convention for every particle kind (T15-F5).
+ */
+export function sampleSlotAtAge(
+  slot: AgeSource,
+  def: ParticleEffectDefinition,
+  age: number,
+): SampledTransform {
+  const t = Math.min(age / slot.lifetime, 1);
+  const x = slot.origin.x + slot.velocity.x * age + 0.5 * def.gravity.x * age * age;
+  const y = slot.origin.y + slot.velocity.y * age + 0.5 * def.gravity.y * age * age;
+  const rotation = slot.rotation + slot.rotationSpeed * age;
+  const scale = slot.scaleStart + (slot.scaleEnd - slot.scaleStart) * t;
+  const opacity = def.fadeOut ? 1 - t : 1;
+  return { x, y, rotation, scale, opacity };
+}
+
+/** Floating-point equality tolerance for deterministic comparisons. */
+export const PARTICLE_TOLERANCE = 0.0001;

package/src/particles/types.ts

@@ -0,0 +1,327 @@
+import type { Point2D } from '../geometry/types';
+
+export type ParticleSpace = 'world' | 'screen';
+export type ParticleOverflow = 'drop-new' | 'recycle-oldest';
+export type ParticleKind = 'sprite' | 'shape';
+export type ShapeKind = 'circle' | 'rectangle';
+
+export interface Range {
+  readonly min: number;
+  readonly max: number;
+}
+
+/**
+ * One author-input endpoint of an explicit scale envelope (T20.1): a fixed
+ * scalar or a `{ min, max }` sampling range for deterministic per-particle
+ * variation. `defineParticleEffect` normalizes scalars into frozen fixed
+ * ranges (T20A-R3).
+ */
+export type ParticleScaleEndpointInput = number | Range;
+
+/**
+ * Author-input scale envelope (T20.1): scale begins at `start` and ends at
+ * `end`, interpolated linearly from active age. Mutually exclusive with the
+ * legacy `scaleOverLife` range; the runtime rejects definitions that carry
+ * both (T20A-R3 keeps that check in the type layer as well).
+ */
+export interface ParticleScaleEnvelopeInput {
+  readonly start: ParticleScaleEndpointInput;
+  readonly end: ParticleScaleEndpointInput;
+}
+
+/**
+ * Normalized envelope endpoint (T20A-R3): always a frozen `{ min, max }`
+ * range — scalar author inputs never appear on a normalized definition.
+ */
+export type ParticleScaleEndpoint = Range;
+
+/**
+ * Normalized explicit scale envelope (T20.1): scale begins at `start` and
+ * ends at `end`, interpolated linearly from active age. Both endpoints are
+ * sampled independently (start first, then end) so shrinking, growth, and
+ * fixed scales are all directly expressible. Endpoints are non-negative and
+ * finite; zero collapses the particle to a point. Negative scale has no
+ * defined rendering semantics and is rejected at definition time (T20A-R1).
+ * Mutually exclusive with the legacy `scaleOverLife` range.
+ */
+export interface ParticleScaleEnvelope {
+  readonly start: ParticleScaleEndpoint;
+  readonly end: ParticleScaleEndpoint;
+}
+
+export interface SpriteParticleConfig {
+  readonly kind: 'sprite';
+  readonly sheet: string;
+  readonly frame: string;
+  readonly size: { readonly width: number; readonly height: number };
+}
+
+export interface ShapeParticleConfig {
+  readonly kind: 'shape';
+  readonly shape: ShapeKind;
+  readonly radius?: number;
+  readonly width?: number;
+  readonly height?: number;
+  readonly color?: string;
+}
+
+export type ParticleConfig = SpriteParticleConfig | ShapeParticleConfig;
+
+export interface ParticleEffectDefinitionFields {
+  readonly capacity: number;
+  readonly space: ParticleSpace;
+  readonly overflow: ParticleOverflow;
+  readonly particle: ParticleConfig;
+  readonly burst: { readonly count: number };
+  readonly lifetimeSeconds: Range;
+  readonly speed: Range;
+  readonly direction?: Range;
+  readonly gravity: Point2D;
+  readonly fadeOut: boolean;
+  readonly rotation?: Range;
+}
+
+/**
+ * Normalized effect definition (T20A-R3): the scale fields are an exclusive
+ * union — a normalized definition carries the explicit `scale` envelope, the
+ * legacy `scaleOverLife` range, or neither, never both. Declared as a flat
+ * union (not an intersection) so normalized definitions remain assignable to
+ * the author-input type at every call site.
+ */
+interface NormalizedExplicitScale extends ParticleEffectDefinitionFields {
+  readonly scale: ParticleScaleEnvelope;
+  readonly scaleOverLife?: undefined;
+}
+
+interface NormalizedLegacyScale extends ParticleEffectDefinitionFields {
+  readonly scale?: undefined;
+  readonly scaleOverLife: Range;
+}
+
+interface NormalizedNoScale extends ParticleEffectDefinitionFields {
+  readonly scale?: undefined;
+  readonly scaleOverLife?: undefined;
+}
+
+export type ParticleEffectDefinition =
+  | NormalizedExplicitScale
+  | NormalizedLegacyScale
+  | NormalizedNoScale;
+
+/**
+ * Authoring shape for `defineParticleEffect` (T20A-R3): identical to the
+ * normalized definition except that scale envelope endpoints accept scalars,
+ * and legacy versus explicit scale authoring is an exclusive union — a
+ * definition carrying both `scale` and `scaleOverLife` fails to compile.
+ * The runtime boundary still validates every JavaScript input.
+ */
+export type ParticleEffectDefinitionInput = Omit<
+  ParticleEffectDefinition,
+  'scale' | 'scaleOverLife'
+> &
+  (
+    | {
+        readonly scale?: ParticleScaleEnvelopeInput | undefined;
+        readonly scaleOverLife?: undefined;
+      }
+    | {
+        readonly scale?: undefined;
+        readonly scaleOverLife?: Range | undefined;
+      }
+  );
+
+export interface ParticleEmitCommand {
+  /** Center position of the burst origin (the anchor convention for every kind). */
+  readonly position: Point2D;
+  readonly seed: number;
+}
+
+export interface ParticleSystemOptions {
+  /**
+   * Raw author definitions or already-normalized definitions. Every value is
+   * validated, cloned, and frozen at the system boundary (T15-F6).
+   */
+  readonly effects: Record<string, ParticleEffectDefinitionInput>;
+}
+
+/**
+ * Frozen diagnostic counters. Semantics are per particle:
+ * - `emitted`: particles actually placed into a slot this burst (fresh OR
+ *   recycled).
+ * - `dropped`: particles never placed — overflow under `drop-new`, plus every
+ *   particle of a burst rejected while paused.
+ * - `recycled`: placed particles whose slot was previously occupied.
+ */
+export interface ParticleDiagnostics {
+  readonly active: number;
+  readonly emitted: number;
+  readonly dropped: number;
+  readonly recycled: number;
+}
+
+/** A frozen, sampled view of one active particle (safe for consumers). */
+export interface ParticleSlotSnapshot {
+  readonly active: boolean;
+  readonly age: number;
+  readonly lifetime: number;
+  readonly origin: Point2D;
+  readonly position: Point2D;
+  readonly velocity: Point2D;
+  readonly rotation: number;
+  readonly scale: number;
+  readonly opacity: number;
+  readonly color: string;
+  readonly spawnSequence: number;
+  readonly effect: string;
+}
+
+export interface ParticleSystem<
+  TEffects extends Record<string, ParticleEffectDefinitionInput> = Record<string, ParticleEffectDefinition>,
+> {
+  /** Validate + place a burst. Throws for unknown effect or malformed command, even while paused. */
+  emit<K extends keyof TEffects & string>(effect: K, command: ParticleEmitCommand): void;
+  /** Advance the clock; a no-op while paused. */
+  update(deltaSeconds: number): void;
+  pause(): void;
+  resume(): void;
+  dispose(): void;
+  getDiagnostics(effect?: keyof TEffects & string): ParticleDiagnostics;
+  /**
+   * Frozen snapshots of active slots. Mutating the returned objects can never
+   * affect controller state (T15-F6).
+   */
+  getActiveParticles(effect: keyof TEffects & string): readonly ParticleSlotSnapshot[];
+  /** Session-lifecycle helpers: idempotent transitions that never throw on already-paused/running. */
+  pauseIfRunning(): void;
+  resumeIfPaused(): void;
+  /** 'running' | 'paused' | 'disposed' — read once per decision point. */
+  readonly status: 'running' | 'paused' | 'disposed';
+  /**
+   * Typed presentation binding for renderers (T15-F6): exposes frozen
+   * definitions plus fixed-capacity sample buffers without revealing pool
+   * internals. One binding per renderer generation; creating it does not
+   * start any clock.
+   */
+  bindPresentation(): ParticlePresentationBinding;
+}
+
+/**
+ * The exclusive presentation-clock lease (T15-RF3).
+ *
+ * Exactly one owner may drive the clock. While a driver is held, public
+ * `tick()` calls are rejected so ad-hoc callers can never double-advance
+ * the system. The driver exposes an idle probe and a wake listener so the
+ * scheduler can fully stop while nothing is active and resume on the next
+ * accepted emission.
+ */
+export interface ParticleDriverHandle {
+  /** Advance + resample. No-op while the owning system is paused/disposed. */
+  step(deltaSeconds: number): void;
+  /** True when every pool slot is inactive (scheduler may stop). */
+  isIdle(): boolean;
+  /** Observe emissions that may end an idle period; pass null to clear. */
+  setWakeListener(listener: (() => void) | null): void;
+  /** Release the exclusive lease; idempotent. */
+  release(): void;
+}
+
+/**
+ * The renderer-facing half of a particle system (T15-F1/F2/F6).
+ *
+ * A binding owns sampled, fixed-capacity buffers per effect. React views
+ * are readers: they never advance the system. The clock itself is held by
+ * exactly one driver acquired through `acquireDriver()`.
+ */
+export interface ParticlePresentationBinding {
+  /** Generation of the owning system at bind time. */
+  readonly systemGeneration: number;
+  /** The frozen, validated definition for one effect. Throws when unknown. */
+  definition(effect: string): ParticleEffectDefinition;
+  /** All bound effect names (stable order). */
+  readonly effects: readonly string[];
+  /**
+   * Manual advance for headless tests and custom drivers. Throws while a
+   * driver owns the clock (T15-RF3); otherwise advances the active clock and
+   * expires slots. A no-op while paused.
+   */
+  tick(deltaSeconds: number): void;
+  /** Acquire the exclusive presentation clock. Throws while another owner holds it. */
+  acquireDriver(): ParticleDriverHandle;
+  /** Whether a driver currently holds the exclusive clock. */
+  readonly driverOwned: boolean;
+  /** Monotonic revision of the EMISSION REGISTRY (bumped on membership changes). */
+  readonly registryRevision: number;
+  /** Current accumulated ACTIVE time (freezes while paused). */
+  readonly activeClock: number;
+  /** Number of active slots summed over all effects (idle probe). */
+  readonly activeCount: number;
+  /**
+   * Deeply frozen per-emission init records for one effect — the diagnostics/
+   * readback surface. Positions derive analytically from activeClock.
+   */
+  emissions(effect: string): readonly ParticleEmissionRecord[];
+  /** Build the bounded UI-runtime registry (frozen). Called on membership changes. */
+  buildUiRegistry(): ParticleUiRegistry;
+}
+
+/**
+ * Structural mirror of the React-layer frame snapshot, declared here so the
+ * particle types stay renderer-agnostic.
+ */
+export interface ParticleFrameSnapshotLike {
+  readonly revision: number;
+  readonly effects: Readonly<
+    Record<
+      string,
+      {
+        readonly x: number[];
+        readonly y: number[];
+        readonly rotation: number[];
+        readonly scale: number[];
+        readonly opacity: number[];
+        readonly visible: number[];
+        readonly capacity: number;
+      }
+    >
+  >;
+}
+
+/** Fixed-capacity presentation buffers for one effect (T15-F2). */
+export interface ParticleSlotBuffers {
+  readonly x: Float32Array;
+  readonly y: Float32Array;
+  readonly rotation: Float32Array;
+  readonly scale: Float32Array;
+  readonly opacity: Float32Array;
+  readonly visible: Uint8Array;
+  readonly capacity: number;
+}
+
+/** Initial state for one emitted particle, in ACTIVE-time coordinates. */
+export interface ParticleEmissionRecord {
+  /** ACTIVE-clock time at which this particle was born. */
+  readonly bornAt: number;
+  readonly originX: number;
+  readonly originY: number;
+  readonly vx: number;
+  readonly vy: number;
+  readonly rotation: number;
+  readonly rotationSpeed: number;
+  readonly scaleStart: number;
+  readonly scaleEnd: number;
+  readonly lifetime: number;
+  readonly spawnSequence: number;
+}
+
+/**
+ * What the presentation layer transfers across the runtime boundary
+ * (T15-SF1): bounded per-emission init records plus the scalar clock.
+ * Transforms are computed analytically on the UI runtime.
+ */
+export interface ParticleUiRegistry {
+  readonly registryRevision: number;
+  readonly activeClock: number;
+  readonly effects: Readonly<
+    Record<string, { readonly capacity: number; readonly particles: readonly ParticleEmissionRecord[] }>
+  >;
+}

package/src/particles.ts

@@ -0,0 +1 @@
+export * from './particles/index';