rn-gamekit 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,74 @@
 
 All notable changes to React Native GameKit will be documented in this file.
 
+## Unreleased
+
+No changes yet.
+
+## 0.2.0 - 2026-09-27
+
+### Added
+
+- Package entry points normalized: `rn-gamekit/geometry`, `rn-gamekit/collision2d`, `rn-gamekit/camera2d`, `rn-gamekit/events`, `rn-gamekit/assets`, and `rn-gamekit/sprites` are now explicit subpaths of the single `rn-gamekit` package (one version, one tarball, `exports` map). Existing `import { … } from 'rn-gamekit'` compatibility re-exports remain and reference the same symbols (`===` / `instanceof` preserved); the new subpaths are the preferred organization (additive, no breaking change). Headless subpaths import no React/Skia/native peers.
+- `useGameSession(definition)` from `rn-gamekit/react`: React-owned session
+  creation and terminal disposal, safe under Strict Mode, with exact
+  scene/input type inference from the game definition.
+- Observable pause/resume lifecycle: `GameSession.addStatusListener()` with
+  queued, snapshot-delivered notifications, and `useGameSessionStatus()`
+  from `rn-gamekit/react`.
+- Paused-input policy: gameplay input is cancelled on pause and rejected
+  while paused at the shared session/input boundary (never replayed).
+- `GameView` presentation follows core status; app backgrounding pauses and
+  foregrounding resumes only the lifecycle-owned pause, and an external
+  start while inactive is returned to paused.
+- `GameButtonPad` and `GameButton` provide multi-touch-safe button controls
+  through the same semantic input boundary as pointer input.
+- Collision2D: canonical 2D geometry (`Aabb2D`, `Circle2D`, `Segment2D`,
+  `Vector2D`), static predicates and contact manifolds, swept circle-AABB and
+  AABB-AABB queries, segment crossings, symmetric category/mask filtering,
+  local/world collider records with typed placement, a deterministic spatial
+  hash broad phase, and headless debug projections.
+- Camera2D: one presented camera owned by `GameView` that drives rendering
+  and pointer input through the same generation, headless helpers for follow
+  behavior, clamped bounds, deterministic shake, interpolation, visibility
+  culling, and parallax layers via `GameLayer2D`.
+- Typed game events: `defineGameEvents` / `gameEvent` declarations, typed
+  envelopes with payload limits, deterministic seeding, and an update-scoped
+  emitter on every scene update.
+- Particles: headless `defineParticleEffect` / `createParticleSystem`
+  simulation with presentation-only Skia rendering (`ParticleView`,
+  `useParticlePresentation`) and camera-aware culling.
+- Audio (opt-in `rn-gamekit/audio`): `createGameAudio` with one shared
+  `AudioContext`, fixed category gains, fire-and-forget SFX, and a single
+  music channel.
+- Haptics (opt-in `rn-gamekit/haptics`): `createGameHaptics` with bounded
+  presets over Pulsar, mute, capability checks, and rate limits.
+- Tilemaps: `defineTileSet2D` / `defineTileLayer2D` / `defineTileMap2D` with chunked storage, `movePlatformerBody2D` tunable platformer resolver, `TileMapLayer2D` atlas rendering with culling, and Tiled JSON adapter.
+- Versioned storage (opt-in `rn-gamekit/storage`): `defineGameSave` / `createGameSaveStore` with `createMemoryStorageAdapter` and optional `createGameStorageAdapter` (`@react-native-async-storage/async-storage@2.1.2`), envelope `rn-gamekit.save`, per-slot serialized queue, `flush()` / `dispose()`, migrations, bounded plain-data serialization (256 KiB, depth 16), and explicit `GameStorageError` codes.
+
+### Changed
+
+- Pausing a session now cancels active gameplay input and rejects new input
+  until the session resumes. Paused input is never replayed.
+- Running scene transitions now commit on the next frame-driver callback,
+  even when no fixed simulation step is due. The new scene first updates on
+  the next due fixed step.
+- Scene snapshots now accept only bounded plain records, arrays, and scalar
+  values. Unsupported mutable or executable values fail before publication
+  with a path-aware `SnapshotDomainError`.
+- Asset, sprite, session, lifecycle, particle, tilemap, audio, haptics, and
+  storage ownership paths now fail closed and clean up accepted work exactly
+  once.
+
+### Dependencies
+
+- Replaced the unused `expo-audio` and `expo-haptics` peer declarations with
+  optional `react-native-audio-api` and `react-native-pulsar` peers.
+- Added optional `@react-native-async-storage/async-storage` support for the
+  persistent storage adapter.
+- Removed `react-native-safe-area-context` from the package peer requirements;
+  applications can still install it for their own HUD and screen layouts.
+
 ## 0.1.0 - 2026-08-12
 
 First public preview.

package/README.md

@@ -3,7 +3,7 @@
 A headless-first 2D game toolkit for React Native and Expo, built for phones
 and tablets.
 
-> **0.1 preview:** React Native GameKit is usable for small 2D games and
+> **0.2 preview:** React Native GameKit is usable for small 2D games and
 > prototypes, but its API may change before 1.0.
 
 ## What is included
@@ -15,11 +15,14 @@ and tablets.
 - React Native Skia rendering with Reanimated interpolation;
 - typed local images, sprite sheets, animation clips, and asset loading;
 - retained sprites and Atlas-backed sprite batching;
+- geometry, Collision2D, Camera2D, and deterministic game events;
+- bounded particles, tilemaps, and platformer movement helpers;
+- opt-in audio, haptics, and versioned storage;
 - a native-free root entry for headless tests.
 
 ## Requirements
 
-Version 0.1 targets the Expo SDK 57 compatibility set:
+Version 0.2 targets the Expo SDK 57 compatibility set:
 
 | Package | Supported version |
 | --- | --- |
@@ -42,6 +45,19 @@ npx expo install expo-asset @shopify/react-native-skia react-native-gesture-hand
 npx expo prebuild
 ```
 
+Install optional native peers only for the systems you use:
+
+```sh
+# rn-gamekit/audio
+npx expo install react-native-audio-api@0.13.3
+
+# rn-gamekit/haptics
+npx expo install react-native-pulsar@1.7.0
+
+# Persistent rn-gamekit/storage adapter
+npx expo install @react-native-async-storage/async-storage@2.1.2
+```
+
 Wrap the application with Gesture Handler's root view:
 
 ```tsx
@@ -97,24 +113,79 @@ const session = createGameSession(game);
 session.start();
 ```
 
-Mount the session through the native entry point:
+In React, own the session with `useGameSession` and hand it to the native
+entry point:
 
 ```tsx
 import {
   GamePointerInput,
   GameView,
+  useGameSession,
 } from 'rn-gamekit/react';
 
-<GameView game={session} renderer={GameRenderer}>
-  <GamePointerInput game={session} action="move" />
-</GameView>;
+function GameScreen() {
+  const session = useGameSession(game);
+
+  if (session === undefined) {
+    return null;
+  }
+
+  return (
+    <GameView game={session} renderer={GameRenderer}>
+      <GamePointerInput game={session} action="move" />
+    </GameView>
+  );
+}
+```
+
+The hook creates the session, disposes it exactly once on replacement or
+unmount, and is safe under Strict Mode. `GameView` borrows the session: it
+starts it while mounted, pauses it on unmount and backgrounding, and never
+disposes it. For headless tests and non-React owners, keep the imperative
+`createGameSession()` / `try/finally dispose()` path shown above.
+
+Pause and resume are the same commands everywhere: `session.pause()` freezes
+the simulation and holds the last frame, `session.start()` resumes with a
+fresh clock baseline, gameplay input is cancelled and rejected while paused,
+and `useGameSessionStatus(session)` drives pause UI without a second state
+source.
+
+`rn-gamekit` is one npm package. Paths like `rn-gamekit/collision2d` are
+package export subpaths. They aren't separately versioned or published; they
+share the same version, peer policy, exports map, and tarball.
+
+### Entry points (one package, one install)
+
+| Entry point | What lives there | Must not load |
+| --- | --- | --- |
+| `rn-gamekit` | Game & scene definitions, session creation, viewport contracts, and compatibility re-exports for all headless systems | — |
+| `rn-gamekit/geometry` | Points, vectors, AABBs, circles, segments, immutable geometry helpers, `GeometryError` | React / Skia / native peers |
+| `rn-gamekit/collision2d` | Predicates, manifolds, sweeps, filters, colliders, spatial hash, debug projections | React / Skia / physics backends |
+| `rn-gamekit/camera2d` | Pure camera values, transforms, follow, clamp, shake, interpolation, visibility | React hooks / Skia / Reanimated |
+| `rn-gamekit/events` | `defineGameEvents` / `gameEvent`, envelopes, `PAYLOAD_LIMITS`, `seedGameEvent`, `GameEventError` | Effect consumers / React / native peers |
+| `rn-gamekit/assets` | `defineAssets` / `image` / `spriteSheet`, descriptor & loaded-value types, `GameAssetError` | React hooks / Skia decoding / Expo Asset |
+| `rn-gamekit/sprites` | `sampleSpriteClip*` & playback-state helpers (`start/advance/…SpriteAnimation`) | React components / Skia Atlas |
+| `rn-gamekit/storage` | Versioned settings and save projections (`defineGameSave`, `createGameSaveStore`, `createMemoryStorageAdapter` / `createGameStorageAdapter`, `GameStorageError`, `STORAGE_LIMITS`) | React / Skia / native peers except optional `async-storage` peer |
+| `rn-gamekit/react` | `GameView`, `GameWorld2D`, `Sprite`, `GameSprite`, `SpriteBatch`, `defineGameCamera2D`, asset/particle/tilemap rendering, pointer input, hooks | — |
+| `rn-gamekit/audio` · `rn-gamekit/haptics` · `rn-gamekit/particles` · `rn-gamekit/tilemap` | Audio, haptics, particle effects, tilemaps (existing ownership) | — |
+| `rn-gamekit/testing` | Deterministic frame drivers for Node tests (test-only, never production) | — |
+
+Headless entries (`geometry`, `collision2d`, `camera2d`, `events`, `assets`, `sprites`, `storage`) import no React, React Native, Skia, Reanimated, Worklets, Expo Asset, or optional native peers. `rn-gamekit/react` is the only entry that loads Skia/Reanimated/Gesture Handler.
+
+**Preferred imports (new code):**
+
+```ts
+import type { Aabb2D } from 'rn-gamekit/geometry';
+import { collideCircleAabb2D } from 'rn-gamekit/collision2d';
+import { createCamera2D } from 'rn-gamekit/camera2d';
+import { defineGameEvents, gameEvent } from 'rn-gamekit/events';
+import { defineAssets, image, spriteSheet } from 'rn-gamekit/assets';
+import { sampleSpriteClipFrame, startSpriteAnimation } from 'rn-gamekit/sprites';
+import { createGameSaveStore, defineGameSave } from 'rn-gamekit/storage';
+import { GameView, GameWorld2D, Sprite } from 'rn-gamekit/react';
 ```
 
-`rn-gamekit` contains the headless definition, session, viewport,
-asset-manifest, and animation APIs. `rn-gamekit/react` contains the
-Skia renderer, native pointer adapter, asset loader, sprites, and sprite
-batching. `rn-gamekit/testing` contains deterministic frame drivers
-for Node tests.
+**Compatibility:** `import { collideCircleAabb2D } from 'rn-gamekit'` and other existing root imports continue to work. Root and subpath exports reference the same underlying symbols (`===` and `instanceof` preserved, no duplicate state). No deprecation or removal is announced in this release — the new subpaths are the preferred organization, not a breaking change.
 
 See the [repository documentation](https://github.com/OrekuD/react-native-gamekit/tree/main/apps/docs/content/docs)
 and [Expo playground](https://github.com/OrekuD/react-native-gamekit/tree/main/apps/playground)
@@ -122,10 +193,20 @@ for complete examples.
 
 ## Current scope
 
-The 0.1 release focuses on performant 2D foundations. Physics, tilemaps,
-audio, haptics, game-level navigation, save data, and 3D rendering are not yet
-part of the public package.
+The 0.2 release focuses on performant 2D foundations and the core systems
+needed by small games. Physics simulation and 3D rendering aren't part of the
+public package. Tilemaps, audio, haptics, events, particles, and versioned
+storage are included.
 
 ## License
 
 MIT
+
+## Credits
+
+The playground demo games use third-party asset packs (not part of the `rn-gamekit` package). Follow each pack's license terms if you redistribute them:
+
+- [Mossy Cavern](https://maaot.itch.io/mossy-cavern) by maaot
+- [Pixel Adventure 1](https://pixelfrog-assets.itch.io/pixel-adventure-1) by Pixel Frog
+- [Brackeys' Platformer Bundle](https://brackeysgames.itch.io/brackeys-platformer-bundle) by Brackeys Games
+- [Mixkit Game Sound Effects](https://mixkit.co/free-sound-effects/game/) — free SFX for the audio demos (see [mixkit.co/license](https://mixkit.co/license/))

package/lib/module/assets/defineAssets.js

@@ -6,6 +6,14 @@
  * `image(...)` and `spriteSheet(...)` build immutable descriptors;
  * `defineAssets(...)` groups them into a deeply immutable typed manifest.
  * Definition performs no I/O and allocates no native handle.
+ *
+ * Ownership decision (GS-ASSET-04): declaration helpers CLONE the
+ * author-supplied structure and freeze the clone. Caller-owned spec
+ * records, frame/clip objects, and group maps are never frozen in place,
+ * so one reusable author record can back several declarations and later
+ * edits cannot reach an already-built manifest. Descriptor objects are
+ * expected from `image(...)`/`spriteSheet(...)` and are shared already
+ * immutable; the helpers never take ownership of caller input.
  */
 import { createDeepFreeze } from "../core/session/deepFreeze.js";
 import { validateImageSource, validateManifest, validateSpriteSheet } from "./validation.js";
@@ -25,12 +33,23 @@ export function image(source) {
  */
 export function spriteSheet(source, spec) {
   validateSpriteSheet(source, spec);
+  // Clone the author records before freezing: the caller's spec stays
+  // owned by the caller and reusable for further declarations.
+  const frames = Object.fromEntries(Object.entries(spec.frames).map(([name, rect]) => [name, {
+    ...rect
+  }]));
+  const animations = Object.fromEntries(Object.entries(spec.animations).map(([name, clip]) => [name, {
+    ...clip,
+    frames: [...clip.frames]
+  }])
+  // The shape was validated above; the clone preserves every value.
+  );
   const freezer = createDeepFreeze();
   return freezer({
     kind: 'sprite-sheet',
     source,
-    frames: spec.frames,
-    animations: spec.animations
+    frames,
+    animations
   });
 }
 
@@ -42,7 +61,13 @@ export function spriteSheet(source, spec) {
  */
 export function defineAssets(groups) {
   validateManifest(groups);
+  // Clone the group/asset maps before freezing: the caller's object stays
+  // owned by the caller. Descriptor values are shared — they are expected
+  // from image()/spriteSheet() and are already immutable.
+  const groupsCopy = Object.fromEntries(Object.entries(groups).map(([group, assets]) => [group, {
+    ...assets
+  }]));
   const freezer = createDeepFreeze();
-  return freezer(groups);
+  return freezer(groupsCopy);
 }
 //# sourceMappingURL=defineAssets.js.map

package/lib/module/assets/defineAssets.js.map

@@ -1 +1 @@
-{"version":3,"names":["createDeepFreeze","validateImageSource","validateManifest","validateSpriteSheet","image","source","Object","freeze","kind","spriteSheet","spec","freezer","frames","animations","defineAssets","groups"],"sourceRoot":"../../../src","sources":["assets/defineAssets.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASA,gBAAgB,QAAQ,+BAA4B;AAC7D,SAASC,mBAAmB,EAAEC,gBAAgB,EAAEC,mBAAmB,QAAQ,iBAAc;AAUzF;AACA,OAAO,SAASC,KAAKA,CAACC,MAAc,EAAmB;EACrDJ,mBAAmB,CAACI,MAAM,CAAC;EAC3B,OAAOC,MAAM,CAACC,MAAM,CAAC;IAAEC,IAAI,EAAE,OAAO;IAAEH;EAAO,CAAC,CAAC;AACjD;;AAEA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASI,WAAWA,CAIzBJ,MAAc,EACdK,IAGC,EACuC;EACxCP,mBAAmB,CAACE,MAAM,EAAEK,IAAI,CAAC;EACjC,MAAMC,OAAO,GAAGX,gBAAgB,CAAC,CAAC;EAClC,OAAOW,OAAO,CAAC;IACbH,IAAI,EAAE,cAAc;IACpBH,MAAM;IACNO,MAAM,EAAEF,IAAI,CAACE,MAAM;IACnBC,UAAU,EAAEH,IAAI,CAACG;EACnB,CAAC,CAAC;AACJ;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,YAAYA,CAC1BC,MAAe,EACa;EAC5Bb,gBAAgB,CAACa,MAAM,CAAC;EACxB,MAAMJ,OAAO,GAAGX,gBAAgB,CAAC,CAAC;EAClC,OAAOW,OAAO,CAACI,MAAM,CAAC;AACxB","ignoreList":[]}
+{"version":3,"names":["createDeepFreeze","validateImageSource","validateManifest","validateSpriteSheet","image","source","Object","freeze","kind","spriteSheet","spec","frames","fromEntries","entries","map","name","rect","animations","clip","freezer","defineAssets","groups","groupsCopy","group","assets"],"sourceRoot":"../../../src","sources":["assets/defineAssets.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASA,gBAAgB,QAAQ,+BAA4B;AAC7D,SAASC,mBAAmB,EAAEC,gBAAgB,EAAEC,mBAAmB,QAAQ,iBAAc;AAUzF;AACA,OAAO,SAASC,KAAKA,CAACC,MAAc,EAAmB;EACrDJ,mBAAmB,CAACI,MAAM,CAAC;EAC3B,OAAOC,MAAM,CAACC,MAAM,CAAC;IAAEC,IAAI,EAAE,OAAO;IAAEH;EAAO,CAAC,CAAC;AACjD;;AAEA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASI,WAAWA,CAIzBJ,MAAc,EACdK,IAGC,EACuC;EACxCP,mBAAmB,CAACE,MAAM,EAAEK,IAAI,CAAC;EACjC;EACA;EACA,MAAMC,MAAM,GAAGL,MAAM,CAACM,WAAW,CAC/BN,MAAM,CAACO,OAAO,CAACH,IAAI,CAACC,MAAM,CAAC,CAACG,GAAG,CAAC,CAAC,CAACC,IAAI,EAAEC,IAAI,CAAC,KAAK,CAACD,IAAI,EAAE;IAAE,GAAGC;EAAK,CAAC,CAAC,CACvE,CAAY;EACZ,MAAMC,UAAU,GAAGX,MAAM,CAACM,WAAW,CACnCN,MAAM,CAACO,OAAO,CAACH,IAAI,CAACO,UAAU,CAAC,CAACH,GAAG,CAAC,CAAC,CAACC,IAAI,EAAEG,IAAI,CAAC,KAAK,CACpDH,IAAI,EACJ;IAAE,GAAGG,IAAI;IAAEP,MAAM,EAAE,CAAC,GAAGO,IAAI,CAACP,MAAM;EAAE,CAAC,CACtC;EACD;EACF,CAAsB;EACtB,MAAMQ,OAAO,GAAGnB,gBAAgB,CAAC,CAAC;EAClC,OAAOmB,OAAO,CAAC;IACbX,IAAI,EAAE,cAAc;IACpBH,MAAM;IACNM,MAAM;IACNM;EACF,CAAC,CAAC;AACJ;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASG,YAAYA,CAC1BC,MAAe,EACa;EAC5BnB,gBAAgB,CAACmB,MAAM,CAAC;EACxB;EACA;EACA;EACA,MAAMC,UAAU,GAAGhB,MAAM,CAACM,WAAW,CACnCN,MAAM,CAACO,OAAO,CAACQ,MAAM,CAAC,CAACP,GAAG,CAAC,CAAC,CAACS,KAAK,EAAEC,MAAM,CAAC,KAAK,CAACD,KAAK,EAAE;IAAE,GAAGC;EAAO,CAAC,CAAC,CACxE,CAAY;EACZ,MAAML,OAAO,GAAGnB,gBAAgB,CAAC,CAAC;EAClC,OAAOmB,OAAO,CAACG,UAAU,CAAC;AAC5B","ignoreList":[]}

package/lib/module/assets.js

@@ -0,0 +1,11 @@
+"use strict";
+
+/**
+ * Subpath entry for `rn-gamekit/assets`.
+ *
+ * Asset manifest definitions and public descriptor types — no React hooks,
+ * Skia decoding, or Expo Asset acquisition.
+ */
+export { defineAssets, image, spriteSheet } from "./assets/defineAssets.js";
+export { GameAssetError } from "./assets/errors.js";
+//# sourceMappingURL=assets.js.map

package/lib/module/assets.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["defineAssets","image","spriteSheet","GameAssetError"],"sourceRoot":"../../src","sources":["assets.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA,SAASA,YAAY,EAAEC,KAAK,EAAEC,WAAW,QAAQ,0BAAuB;AACxE,SAASC,cAAc,QAAQ,oBAAiB","ignoreList":[]}