Satchel Integration guide — Cranberry Forge

Install

This package is not published on npm. Download the tarball from the workbench, or run npm pack ./dist/packages/satchel from the repository:

npm install /path/to/cranberry-forge-satchel-0.1.0.tgz

ES modules, TypeScript declarations and MIT license are included. Use native Three.js in your game; Satchel requires no renderer, DOM, storage, framework or other Cranberry Forge package.

Saves and UI integration

const unsubscribe = pack.subscribe(snapshot => updateInventoryUI(snapshot));
const save = JSON.stringify(pack.toSnapshot());
const restored = Inventory.fromSnapshot(save, { catalog });
unsubscribe();

The cranberry-forge.satchel/1 snapshot contains layout, limits, quantities and the next stack ID. The catalog is deliberately external. Restoring rejects unknown items, duplicate IDs, reused future IDs, invalid quantities, overlaps, bounds violations and excessive weight. Choose a migration when changing catalogs between game versions. Local save files are not anti-cheat proof or authentication.

The workbench's kit-ui.js demonstrates drag/drop plus select-and-place controls for touch and keyboard users. It is demo code, not a dependency of this package. A subscriber error is logged and does not roll back a committed action. Subscriber-triggered mutations are application code; avoid reentrant writes when rendering UI.