@crowdedkingdoms/crowdyjs 8.3.0 → 8.4.1

package/README.md

@@ -106,6 +106,7 @@ If `managementUrl` is omitted, the SDK falls back to `httpUrl` for backwards-com
 | `client.udp` | UDP proxy subscriptions + spatial mutations (`sendActorUpdate`, `sendVoxelUpdate`, `sendAudioPacket`, `sendTextPacket`, `sendClientEvent`). |
 | `client.realtime` | Connection status, manual `connect()` / `disconnect()`, `onStatus()` listener. |
 | `client.world(appId)` | Higher-level helpers for browser games (`actor.join`, `actor.sendState`, `actor.sendText`). |
+| `createWorldSession(client, appId, config)` (from `@crowdedkingdoms/crowdyjs/stores`) | World Stores: opt-in, SDK-managed game state — typed codecs (`structCodec` binary DSL), your own actor with a 5 Hz send loop (`session.self`), a remote-actor registry with lanes/history/staleness (`session.actors`), attributed send errors (`session.errors`), a chunk/voxel cache with realtime merge + worldgen write-back (`session.chunks`), channel/direct-message inboxes + a typed event router, host tracking, typed save/avatar state, and a game-model container mirror. Only configured stores exist (compile-time + runtime); unimported stores tree-shake away. |
 | `client.kit(appId)` | Game Kit: ready-made mappings of game concepts onto the game model — `kit.inventory`, `kit.objects` (lockable doors/chests with custom permissions), `kit.npcs`, `kit.plots` (buy/rent land with transactional, replication-enforced grid grants), and the genre layers `kit.economy` (wallets/shops/trades/market), `kit.progression` (xp/skills/achievements/rating), `kit.loot`, `kit.quests`, `kit.combat`, `kit.matches` (session lobbies/turns/scores with notify-to-pull channels), `kit.decks` (hidden hands), `kit.worldsim` (clock/nodes/crops/waves), `kit.social` (parties/guilds/chat over teams+channels), `kit.leaderboards`, `kit.features` (tier gates) — plus blueprint builders + `kit.deploy(...)` for the admin "load the rules" step. |
 
 **Studio-admin surface** (privileged; drive with a server-side / studio token, grouped under `client.admin`):
@@ -269,6 +270,65 @@ await actor.sendToActor(
 
 The world helpers are thin wrappers over `client.udp.*` with the appId pre-bound — convenient for browser games. Advanced callers can always use `client.udp.*` with the generated GraphQL input types directly.
 
+## World Stores
+
+The core client is a thin transport; the **World Stores** layer
+(`@crowdedkingdoms/crowdyjs/stores`, 8.4+) adds the source-of-truth data
+structures every game otherwise hand-writes: actor registries, chunk/voxel
+caches, error attribution, message inboxes, host tracking, and typed
+durable-state wrappers — all driven by ONE shared `udpNotifications`
+subscription and ONE scheduler.
+
+```ts
+import {
+  createWorldSession, structCodec, f32, u8, jsonCodec, workerTicker,
+} from '@crowdedkingdoms/crowdyjs/stores';
+
+// Describe your replication state ONCE (48-byte binary layouts, declaratively):
+const poseCodec = structCodec({
+  x: f32(), y: f32(), z: f32(), yaw: f32(),
+  flags: u8(), held: u8(),
+});
+
+const session = createWorldSession(game, appId, {
+  ticker: workerTicker(), // keep 5 Hz sends even in backgrounded tabs
+  self:   { codec: poseCodec, initialState: { x: 0, y: 0, z: 0, yaw: 0, flags: 0, held: 0 } },
+  actors: { codec: poseCodec, staleAfterMs: 12_000, historySize: 2 },
+  errors: true,
+  chunks: { voxelStateCodec: jsonCodec<MyVoxelMeta>() },
+});
+
+// Your actor: uuid minted + persisted, presence sent at 5 Hz with
+// send-on-change dedup; just update the typed state from your game loop.
+await session.self.join({ x: '0', y: '0', z: '0' });
+session.self.patchState({ x: 12.5, yaw: 1.57 });
+console.log(session.self.status, session.self.lastAck?.state);
+
+// Everyone else: typed, self-filtered, staleness-managed — render from it.
+for (const actor of session.actors.list()) {
+  render(actor.uuid, actor.state, actor.samples); // samples → interpolation
+}
+
+// Terrain: cached, hydrated, realtime-merged, optimistically editable.
+await session.chunks.ensureAround({ x: 0, y: 0, z: 0 }, 3);
+await session.chunks.setVoxel({ chunk: { x: 0, y: 0, z: 0 }, x: 1, y: 2, z: 3, voxelType: 7 });
+
+// Server-reported send errors, attributed to what you sent:
+session.errors.onError((e) => console.warn(e.errorCode, e.send?.kind));
+
+session.dispose();
+```
+
+Every store is **opt-in twice over**: only configured stores are constructed
+(and only they exist on the session's TYPE — `session.host` without
+`host: ...` in the config is a compile error), and the layer lives behind the
+`./stores` subpath with `"sideEffects": false`, so unimported stores never
+reach your bundle. Reads are synchronous snapshots and writes happen on
+WebSocket events (not `requestAnimationFrame`), so render loops read freely
+and a backgrounded tab keeps ingesting updates; pass `workerTicker()` to also
+keep timer-driven sends at full rate while hidden. See the
+[World Stores guide](https://docs.crowdedkingdoms.com/crowdyjs/stores).
+
 ## Game Kit
 
 `client.kit(appId)` maps traditional game concepts onto the abstract game

package/dist/generated/graphql.d.ts

@@ -133,7 +133,7 @@ export type ActorUpdateRequestInput = {
     /** A unique identifier for the actor. Must be exactly 32 bytes when encoded as UTF-8. This is typically a client-generated UUID. */
     uuid: Scalars['String']['input'];
 };
-/** Response from the UDP game server for an actor update request. Received via the udpNotifications subscription. */
+/** LEGACY — never emitted. The game server retired the dedicated actor-update response opcode (129); an applied update now arrives as your own ActorUpdateNotification (the sender is included in the chunk fan-out) and failures arrive as GenericErrorResponse. This type remains in the UdpNotification union for backward compatibility only — do not select it in new code; it will be removed in a future major version. */
 export type ActorUpdateResponse = {
     __typename?: 'ActorUpdateResponse';
     /** The ID of the app where the actor update was processed. */
@@ -5782,7 +5782,7 @@ export declare enum UdpErrorCode {
     /** This client has no authenticated session on the server. Complete the UDP token handshake (or open the UDP proxy) before sending spatial messages. */
     UserNotAuthenticated = "USER_NOT_AUTHENTICATED"
 }
-/** All game-server messages delivered over the UDP proxy as GraphQL payloads. Subscribe to udpNotifications before or with sending mutations so responses and GenericErrorResponse (correlate via sequenceNumber) are not missed. */
+/** All game-server messages delivered over the UDP proxy as GraphQL payloads. Subscribe to udpNotifications before or with sending mutations so responses and GenericErrorResponse (correlate via sequenceNumber) are not missed. NOTE: the ActorUpdateResponse and VoxelUpdateResponse members are LEGACY and never emitted (applied updates arrive as your own *Notification self-echo; failures as GenericErrorResponse) — they remain in the union for backward compatibility and will be removed in a future major version. */
 export type UdpNotification = ActorUpdateNotification | ActorUpdateResponse | ChannelMessageNotification | ClientAudioNotification | ClientEventNotification | ClientTextNotification | GenericErrorResponse | RealtimeConnectionEvent | ServerEventNotification | SingleActorMessageNotification | VoxelUpdateNotification | VoxelUpdateResponse;
 /** UDP proxy session for the game token on the request. Returned by udpProxyConnectionStatus and connectUdpProxy. Binary UDP layouts are documented in database/client-wire-formats.md. */
 export type UdpProxyConnectionStatus = {
@@ -6417,7 +6417,7 @@ export type VoxelUpdateRequestInput = {
     /** The new voxel type ID. This determines the appearance and properties of the voxel. */
     voxelType: Scalars['Int']['input'];
 };
-/** Response from the UDP game server for a voxel update request. Received via the udpNotifications subscription. */
+/** LEGACY — never emitted. The game server retired the dedicated voxel-update response opcode (132); an applied update now arrives as your own VoxelUpdateNotification (the sender is included in the chunk fan-out) and failures arrive as GenericErrorResponse. This type remains in the UdpNotification union for backward compatibility only — do not select it in new code; it will be removed in a future major version. */
 export type VoxelUpdateResponse = {
     __typename?: 'VoxelUpdateResponse';
     /** The ID of the app where the voxel update was processed. */