rn-gamekit 0.1.0 → 0.2.1

package/src/haptics/createGameHaptics.ts

@@ -0,0 +1,214 @@
+import { createHapticsInstallationError, GameHapticsError } from './errors';
+import { loadPulsar } from './resolver';
+import type { CreateGameHapticsOptions, GameHaptics, HapticPreset, HapticsResult } from './types';
+import type { GameLifecycleSource } from '../core/session/types';
+
+const PRESETS: readonly HapticPreset[] = [
+  'impact',
+  'selection',
+  'success',
+  'warning',
+  'error',
+  'light',
+  'medium',
+  'heavy',
+] as const;
+
+function isValidPreset(preset: HapticPreset): boolean {
+  return (PRESETS as readonly string[]).includes(preset);
+}
+
+function mapToSystemPreset(preset: HapticPreset): string {
+  switch (preset) {
+    case 'impact':
+      return 'impactMedium';
+    case 'light':
+      return 'impactLight';
+    case 'medium':
+      return 'impactMedium';
+    case 'heavy':
+      return 'impactHeavy';
+    case 'selection':
+      return 'selection';
+    case 'success':
+      return 'notificationSuccess';
+    case 'warning':
+      return 'notificationWarning';
+    case 'error':
+      return 'notificationError';
+    default:
+      return preset;
+  }
+}
+
+export function createGameHaptics(options?: CreateGameHapticsOptions): GameHaptics {
+  let pulsar: ReturnType<typeof loadPulsar>;
+  try {
+    pulsar = loadPulsar();
+  } catch {
+    throw createHapticsInstallationError();
+  }
+  if (!pulsar || !pulsar.Presets) {
+    throw createHapticsInstallationError();
+  }
+  const { Presets } = pulsar;
+
+  // Capability through the single public Settings adapter (GS-HAPTICS-02,
+  // verified against installed Pulsar 1.7.0): HapticSupport 0 is
+  // NO_SUPPORT, 1-3 are supported tiers; anything else fails closed.
+  function getSupportLevel(): number | null {
+    try {
+      const level = pulsar.Settings?.getHapticsSupportLevel?.();
+      if (typeof level === 'number' && Number.isFinite(level)) return level;
+    } catch {}
+    return null;
+  }
+
+  function isCapabilitySupported(_preset: HapticPreset): boolean {
+    const level = getSupportLevel();
+    if (level === null) return false;
+    const support = pulsar.HapticSupport;
+    if (support !== undefined) {
+      return (
+        level === support['LIMITED_SUPPORT'] ||
+        level === support['STANDARD_SUPPORT'] ||
+        level === support['ADVANCED_SUPPORT']
+      );
+    }
+    return level === 1 || level === 2 || level === 3;
+  }
+
+  let muted = Boolean(options?.muted);
+  let disposed = false;
+  // GS-HAPTICS-01: manual and lifecycle pauses are independent gates —
+  // either alone suppresses, and neither overwrites the other. Detaching
+  // a lifecycle source clears only its own gate.
+  let manualPaused = false;
+  let lifecyclePaused = false;
+  let backgrounded = false;
+  // GS-HAPTICS-03: monotonic clock at the adapter seam (injectable for
+  // deterministic tests; defaults to wall time). The throttle is one
+  // GLOBAL 100ms budget shared by every preset: a selection pulse
+  // consumes the interval for a following success effect. Only successful
+  // dispatches consume budget — failures and rollbacks never suppress.
+  const now = options?.now ?? Date.now;
+  let lastPlayAt = Number.NEGATIVE_INFINITY;
+  // T20L-R3: exactly one active lifecycle source per haptics instance. The
+  // active detach is retained so replacement swaps sources, repeated detach
+  // is idempotent, and disposal detaches before everything else.
+  let lifecycleDetach: (() => void) | null = null;
+  const MIN_INTERVAL_MS = 100;
+
+  // AppState integration (best-effort)
+  let appStateSub: { remove(): void } | null = null;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const RN = require('react-native') as { AppState?: { currentState?: string; addEventListener: (t:string, cb:(s:string)=>void)=>{ remove:()=>void } } };
+    const AppState = RN?.AppState;
+    if (AppState?.addEventListener) {
+      const isInactive = (s: string | null | undefined) => s === 'inactive' || s === 'background';
+      if (isInactive(AppState.currentState)) backgrounded = true;
+      appStateSub = AppState.addEventListener('change', (next: string) => {
+        if (isInactive(next)) backgrounded = true;
+        else if (next === 'active') backgrounded = false;
+      });
+    }
+  } catch {}
+
+  const haptics: GameHaptics & {
+    /** Test-only backdoor for the AppState path; never part of the public type. */
+    _setBackgrounded?: (b:boolean)=>void;
+  } = {
+    play(preset: HapticPreset): HapticsResult {
+      if (disposed) return { played: false, reason: 'disposed' };
+      if (manualPaused || lifecyclePaused) return { played: false, reason: 'paused' };
+      if (backgrounded) return { played: false, reason: 'paused' };
+      if (!isValidPreset(preset)) throw new GameHapticsError(`Unknown haptic preset "${String(preset)}"`);
+      if (muted) return { played: false, reason: 'muted' };
+      if (!isCapabilitySupported(preset)) return { played: false, reason: 'unsupported' };
+      const systemName = mapToSystemPreset(preset);
+      const fn =
+        (Presets.System as Record<string, unknown>)[systemName] ??
+        (Presets as Record<string, unknown>)[preset];
+      if (typeof fn !== 'function') return { played: false, reason: 'unsupported' };
+      const at = now();
+      const elapsed = at - lastPlayAt;
+      if (elapsed >= 0 && elapsed < MIN_INTERVAL_MS) return { played: false, reason: 'throttled' };
+      try {
+        (fn as () => void)();
+        lastPlayAt = at;
+        // played means request dispatched, not confirmed physical playback — system may suppress
+        return { played: true };
+      } catch {
+        return { played: false, reason: 'error' };
+      }
+    },
+
+    isSupported(_preset: HapticPreset): boolean {
+      if (disposed) return false;
+      if (!isValidPreset(_preset)) throw new GameHapticsError(`Unknown haptic preset "${String(_preset)}"`);
+      if (!isCapabilitySupported(_preset)) return false;
+      const systemName = mapToSystemPreset(_preset);
+      const fn =
+        (Presets.System as Record<string, unknown>)[systemName] ??
+        (Presets as Record<string, unknown>)[_preset];
+      return typeof fn === 'function';
+    },
+
+    setMuted(next: boolean): void {
+      if (disposed) throw new GameHapticsError('GameHaptics is disposed');
+      muted = Boolean(next);
+    },
+
+    isMuted(): boolean {
+      if (disposed) throw new GameHapticsError('GameHaptics is disposed');
+      return muted;
+    },
+
+    setPaused(next: boolean): void {
+      if (disposed) throw new GameHapticsError('GameHaptics is disposed');
+      manualPaused = Boolean(next);
+    },
+
+    bindLifecycle(source: GameLifecycleSource): () => void {
+      if (disposed) throw new GameHapticsError('GameHaptics is disposed');
+      // One active source: a replacement detaches the previous one first.
+      lifecycleDetach?.();
+      lifecycleDetach = null;
+      // Apply the current status immediately, then follow transitions.
+      // AppState backgrounding stays independent (separate flag).
+      lifecyclePaused = source.getStatus() !== 'running';
+      // GameLifecycleSource.subscribe returns a bare detach function (T20.3).
+      const sourceDetach = source.subscribe((status) => {
+        lifecyclePaused = status !== 'running';
+      });
+      let detached = false;
+      const detach = (): void => {
+        if (detached) return;
+        detached = true;
+        sourceDetach();
+        // GS-HAPTICS-01: detach removes this source's ownership — its last
+        // status must not linger as a permanent gate. Manual pause is
+        // untouched.
+        lifecyclePaused = false;
+        if (lifecycleDetach === detach) lifecycleDetach = null;
+      };
+      lifecycleDetach = detach;
+      return detach;
+    },
+
+    dispose(): void {
+      if (disposed) return;
+      disposed = true;
+      // T20L-R3: detach the active lifecycle source BEFORE removing the
+      // AppState listener so the session retains no closure.
+      lifecycleDetach?.();
+      lifecycleDetach = null;
+      if (appStateSub) { try { appStateSub.remove(); } catch {} appStateSub=null; }
+    },
+  };
+
+  (haptics as unknown as { _setBackgrounded: (b:boolean)=>void })._setBackgrounded = (b:boolean)=>{ backgrounded = b; };
+
+  return haptics;
+}

package/src/haptics/errors.ts

@@ -0,0 +1,12 @@
+export class GameHapticsError extends Error {
+  override name = 'GameHapticsError';
+  constructor(message: string) {
+    super(message);
+  }
+}
+
+export function createHapticsInstallationError(): GameHapticsError {
+  return new GameHapticsError(
+    'react-native-pulsar is not installed. Run `npx expo install react-native-pulsar react-native-worklets` and rebuild with `npx expo prebuild` (or `expo run:ios` / `expo run:android`). See https://github.com/software-mansion/pulsar',
+  );
+}

package/src/haptics/index.ts

@@ -0,0 +1,3 @@
+export { createGameHaptics } from './createGameHaptics';
+export { GameHapticsError } from './errors';
+export type { CreateGameHapticsOptions, GameHaptics, HapticPreset, HapticsResult } from './types';

package/src/haptics/resolver.ts

@@ -0,0 +1,58 @@
+/**
+ * Injectable resolver for the optional `react-native-pulsar` peer
+ * (GS-HAPTICS-02).
+ *
+ * The adapter surface is the package's PUBLIC entry — `Presets`,
+ * `Settings.getHapticsSupportLevel()`, and the `HapticSupport` enum —
+ * verified against installed react-native-pulsar 1.7.0. No TurboModule
+ * digging, no private root functions: capability queries go through the
+ * single Settings adapter, and a missing method fails closed downstream.
+ */
+export type LoadedPulsar = {
+  Presets: {
+    System: Record<string, () => void>;
+  };
+  Settings: {
+    getHapticsSupportLevel(): number;
+  };
+  HapticSupport?: Record<string, number>;
+};
+
+let loader: (() => LoadedPulsar) | null = null;
+
+export function __setPulsarLoader(fn: (() => LoadedPulsar) | null): void {
+  loader = fn;
+}
+
+export function loadPulsar(): LoadedPulsar {
+  if (loader) {
+    return loader();
+  }
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const mod = require('react-native-pulsar') as unknown as LoadedPulsar & {
+    default?: LoadedPulsar;
+    Presets?: LoadedPulsar['Presets'];
+    Settings?: LoadedPulsar['Settings'];
+    HapticSupport?: Record<string, number>;
+  };
+  const Presets =
+    (mod as unknown as { Presets?: LoadedPulsar['Presets'] }).Presets ??
+    (mod as unknown as LoadedPulsar).Presets;
+  if (!Presets) {
+    throw new Error('Presets not found in react-native-pulsar — linking may have failed');
+  }
+  // Resolve public Settings + HapticSupport from the package root (not deep imports).
+  const Settings =
+    (mod as unknown as { Settings?: LoadedPulsar['Settings'] }).Settings ??
+    (mod as unknown as { default?: { Settings?: LoadedPulsar['Settings'] } }).default?.Settings ??
+    (mod as unknown as LoadedPulsar).Settings;
+  const HapticSupport =
+    (mod as unknown as { HapticSupport?: Record<string, number> }).HapticSupport ??
+    (mod as unknown as { default?: { HapticSupport?: Record<string, number> } }).default?.HapticSupport ??
+    (mod as unknown as LoadedPulsar).HapticSupport;
+  return {
+    Presets,
+    Settings: Settings as LoadedPulsar['Settings'],
+    HapticSupport,
+  } as LoadedPulsar;
+}

package/src/haptics/types.ts

@@ -0,0 +1,48 @@
+import type { GameLifecycleSource } from '../core/session/types';
+
+export type HapticPreset =
+  | 'impact'
+  | 'selection'
+  | 'success'
+  | 'warning'
+  | 'error'
+  | 'light'
+  | 'medium'
+  | 'heavy';
+
+export interface HapticsResult {
+  readonly played: boolean;
+  readonly reason?: 'unsupported' | 'muted' | 'throttled' | 'disposed' | 'paused' | 'error';
+}
+
+export interface GameHaptics {
+  play(preset: HapticPreset): HapticsResult;
+  isSupported(preset: HapticPreset): boolean;
+  setMuted(muted: boolean): void;
+  isMuted(): boolean;
+  /**
+   * Public pause gate (T20.7, GS-HAPTICS-01): while paused, `play` drops
+   * transient requests with reason `'paused'`. Independent from the
+   * lifecycle gate, AppState backgrounding, and mute — any one alone
+   * suppresses feedback, and clearing one never clears another.
+   */
+  setPaused(paused: boolean): void;
+  /**
+   * Follow a session lifecycle source (T20.3/T20.7, GS-HAPTICS-01): applies
+   * the source's current status immediately, then pauses on every
+   * non-running transition and resumes on `'running'`. Returns a detach
+   * function. Detaching removes only this source's gate (manual pause is
+   * untouched). AppState backgrounding stays independent.
+   */
+  bindLifecycle(source: GameLifecycleSource): () => void;
+  dispose(): void;
+}
+
+export interface CreateGameHapticsOptions {
+  readonly muted?: boolean;
+  /**
+   * Monotonic clock for the throttle budget (GS-HAPTICS-03). Defaults to
+   * `Date.now`; inject a controlled clock for deterministic tests.
+   */
+  readonly now?: () => number;
+}

package/src/haptics.ts

@@ -0,0 +1,7 @@
+/**
+ * Subpath entry for `rn-gamekit/haptics`.
+ * Importing `rn-gamekit` or `rn-gamekit/react` must not load this module.
+ */
+export { createGameHaptics } from './haptics/createGameHaptics';
+export { GameHapticsError } from './haptics/errors';
+export type { CreateGameHapticsOptions, GameHaptics, HapticPreset, HapticsResult } from './haptics/types';

package/src/index.ts

@@ -1,4 +1,37 @@
+export {
+  clampCameraBounds2D,
+  createCamera2D,
+  filterCameraVisible2D,
+  followCamera2D,
+  getCameraVisibleBounds2D,
+  interpolateCamera2D,
+  intersectsCameraView2D,
+  logicalToWorld2D,
+  sampleCameraShake2D,
+  surfaceToWorld2D,
+  worldToLogical2D,
+  worldToSurface2D,
+} from './camera2d';
+export type {
+  Camera2D,
+  CameraCut2D,
+  CameraShakeOptions2D,
+  CameraViewShape2D,
+  FollowCamera2DOptions2D,
+} from './camera2d';
 export { createGameSession } from './core/session/createGameSession';
+export { GameEventError } from './events/errors';
+export { defineGameEvents, gameEvent } from './events/defineGameEvents';
+export { seedGameEvent } from './events/seed';
+export type {
+  AnyGameEventEnvelope,
+  GameEventDefinitions,
+  GameEventDescriptor,
+  GameEventEmitter,
+  GameEventEnvelope,
+  GameEventMap,
+  InferGameEventMap,
+} from './events/types';
 export { GameSessionDisposedError, GameSessionLifecycleError } from './core/session/types';
 export type {
   ButtonState,
@@ -27,6 +60,7 @@ export {
   sampleSpriteClipFrame,
   sampleSpriteClipFrameName,
   spriteClipDurationMs,
+  spriteFrameNameForClip,
 } from './sprites/sampleSpriteClip';
 export type { SpriteAnimationState, SpriteClipNames } from './sprites/spriteAnimationState';
 export { defineAssets, image, spriteSheet } from './assets/defineAssets';
@@ -59,7 +93,9 @@ export type {
   SceneDefinitionMarker,
   SceneMap,
 } from './definition/types';
-export type { Point2D } from './geometry/types';
+export { PAYLOAD_LIMITS } from './events/payload';
+export * from './geometry';
+export * from './collision2d';
 export { defineScene } from './scene/defineScene';
 export type {
   SceneDefinition,