@crowdedkingdoms/crowdyjs 8.3.0 → 8.4.0

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/index.d.ts

@@ -45,7 +45,7 @@
  * or internal tooling, never an untrusted browser.
  */
 /** The published package version. Mirrors `package.json`. */
-export declare const VERSION = "8.3.0";
+export declare const VERSION = "8.4.0";
 export { LbCookieStore } from './lb-cookie-store.js';
 export { CrowdyClient, createCrowdyClient, type CrowdyClientConfig, } from './crowdy-client.js';
 export { BrowserLocalStorageTokenStore, SessionStore, type SessionListener, type TokenStore, } from './session.js';
@@ -53,6 +53,7 @@ export { GraphQLClient, GraphQLTransport, type GraphQLClientConfig, } from './cl
 export { RealtimeClient, type RealtimeConfig, type RealtimeStatus, type SpatialNotification, type UdpNotification, type UdpNotificationHandlers, } from './realtime.js';
 export { WorldClient, ActorClient, type ActorOptions } from './world.js';
 export { CombatKit, DecksKit, EconomyKit, FeaturesKit, GameKitClient, InventoryKit, LeaderboardsKit, LootKit, MatchesKit, NpcsKit, ObjectsKit, PlotsKit, ProgressionKit, QuestsKit, SocialKit, WorldsimKit, andPolicies, combatBlueprint, combatNames, composeBlueprints, decksBlueprint, decksNames, economyBlueprint, economyCurrencyFn, economyNames, featureGate, guildBlueprint, guildNames, inventoryBlueprint, inventoryNames, kitInvoke, kitPolicyJson, leaderboardsBlueprint, leaderboardsNames, lockBlueprint, lockNames, lootBlueprint, lootNames, lootRollFn, matchesBlueprint, matchesNames, mergeBlueprints, npcBehaviorFunctionName, npcBlueprint, ownerEqualsCaller, ownerMirrorProperty, ownerEquals, plotBlueprint, plotNames, progressionBlueprint, progressionNames, questsBlueprint, questsNames, toKitInvokeResult, trustedAuthorityFields, worldsimBlueprint, worldsimNames, type CombatBlueprintOptions, type CombatKitOptions, type CombatNames, type DecksBlueprintOptions, type DecksKitOptions, type DecksNames, type EconomyBlueprintOptions, type EconomyKitOptions, type EconomyNames, type GameKitDomains, type GameKitOptions, type GuildBlueprintOptions, type GuildNames, type InventoryBlueprintOptions, type InventoryKitOptions, type InventoryNames, type KitAchievementDef, type KitAchievementUnlock, type KitAutomationSpec, type KitAutomationTriggerSpec, type KitBlueprint, type KitCard, type KitChatMessage, type KitCombatant, type KitCrop, type KitGroupWithChannel, type KitDeployResult, type KitInvokePolicy, type KitInvokeResult, type KitItemStack, type KitLeaderboardEntry, type KitLootRoll, type KitMarketListing, type KitMatch, type KitMatchScore, type KitNpc, type KitOwnerIdKind, type KitPlot, type KitProgress, type KitQuestDef, type KitQuestProgress, type KitResourceNode, type KitSelectorSpec, type KitShopListing, type KitSkillDef, type KitSkillRank, type KitStatusEffect, type KitTradeOffer, type KitTrustedAuthority, type KitWallet, type KitWaveSpawner, type LeaderboardsBlueprintOptions, type LeaderboardsKitOptions, type LeaderboardsNames, type KitWorldState, type LockAuthority, type LockBlueprintOptions, type LockNames, type LootBlueprintOptions, type LootDropSpec, type LootEntrySpec, type LootKitOptions, type LootNames, type LootTableSpec, type MatchesBlueprintOptions, type MatchesKitOptions, type MatchesNames, type MergedBlueprints, type NpcBehaviorSpec, type NpcBehaviorTrigger, type NpcBlueprintOptions, type NpcsKitOptions, type ObjectsKitOptions, type PlotBlueprintOptions, type PlotNames, type PlotsKitOptions, type ProgressionBlueprintOptions, type ProgressionKitOptions, type ProgressionNames, type QuestAdvanceSpec, type QuestsBlueprintOptions, type QuestsKitOptions, type QuestsNames, type SelectorPermissionPredicate, type SocialKitOptions, type WorldsimBlueprintOptions, type WorldsimKitOptions, type WorldsimNames, } from './kit/index.js';
+export type { StateCodec, Ticker, WorldSession, WorldSessionConfig, WorldStoresClient, } from './stores/index.js';
 export { CrowdyError, CrowdyGraphQLError, CrowdyHttpError, CrowdyNetworkError, CrowdyProtocolError, CrowdyRealtimeError, CrowdyTimeoutError, } from './errors.js';
 export { SequenceAllocator, decodeBase64, encodeBase64, generateCrowdyUuid, validateChunkCoordinates, validateCrowdyUuid, } from './utils.js';
 export type { BigInt, ChunkCoordinates, VoxelCoordinates, ActorUpdateNotification, ActorUpdateResponse, VoxelUpdateNotification, VoxelUpdateResponse, ClientAudioNotification, ClientTextNotification, ClientEventNotification, ServerEventNotification, GenericErrorResponse, ActorUpdateHandler, ActorUpdateResponseHandler, VoxelUpdateHandler, VoxelUpdateResponseHandler, ClientAudioHandler, ClientTextHandler, ClientEventHandler, ServerEventHandler, GenericErrorHandler, UnsubscribeFn, } from './types.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -45,7 +45,7 @@
  * or internal tooling, never an untrusted browser.
  */
 /** The published package version. Mirrors `package.json`. */
-export const VERSION = '8.3.0';
+export const VERSION = '8.4.0';
 export { LbCookieStore } from './lb-cookie-store.js';
 export { CrowdyClient, createCrowdyClient, } from './crowdy-client.js';
 export { BrowserLocalStorageTokenStore, SessionStore, } from './session.js';

package/dist/stores/actors.d.ts

@@ -0,0 +1,316 @@
+/**
+ * Actor stores — the SDK-managed bookkeeping every multiplayer game
+ * otherwise hand-writes: your own actor's identity, typed state, and send
+ * loop ({@link LocalActorStore}), created via {@link attachLocalActor} on a
+ * world session.
+ */
+import type { ChunkCoordinatesInput } from '../generated/graphql.js';
+import type { UdpNotificationHandlers } from '../realtime.js';
+import type { StateCodec } from './codec.js';
+import type { WorldSessionContext } from './session.js';
+/** The notification type delivered for actor updates (incl. your own echo). */
+export type ActorUpdateEcho = Parameters<NonNullable<UdpNotificationHandlers['actorUpdate']>>[0];
+/** The error notification type. */
+export type GenericErrorEcho = Parameters<NonNullable<UdpNotificationHandlers['genericError']>>[0];
+/** Where the local actor's 32-char uuid lives across page loads. */
+export interface UuidStore {
+    load(): string | null;
+    save(uuid: string): void;
+}
+/** Keep the uuid for this tab session only (a fresh actor per reload). */
+export declare function memoryUuidStore(): UuidStore;
+/**
+ * Persist the uuid in `localStorage` so the player keeps a stable actor
+ * identity across reloads (the convention games converge on). Falls back to
+ * {@link memoryUuidStore} behavior outside the browser.
+ */
+export declare function localStorageUuidStore(key?: string): UuidStore;
+/** Why a send happened — recorded on {@link SentActorUpdate}. */
+export type SendReason = 'join' | 'move' | 'interval' | 'keyframe' | 'manual' | 'visibility' | 'refresh';
+/** The record of the most recent outbound actor update. */
+export interface SentActorUpdate<T> {
+    /** The typed state that was sent. */
+    state: T;
+    /** The encoded (base64) wire form. */
+    encoded: string;
+    chunk: ChunkCoordinatesInput;
+    sequenceNumber: number;
+    sentAt: number;
+    reason: SendReason;
+}
+/** The record of the most recent server-applied echo of our own update. */
+export interface AckedActorUpdate<T> {
+    /** The typed state decoded from the echo. */
+    state: T;
+    /** The raw self-echo notification. */
+    notification: ActorUpdateEcho;
+    receivedAt: number;
+}
+/** The record of the most recent send error attributed to this actor. */
+export interface ActorSendError {
+    errorCode: string;
+    sequenceNumber: number;
+    receivedAt: number;
+}
+/** Lifecycle of the local actor's replication. */
+export type LocalActorStatus = 'idle' | 'pending' | 'acked' | 'error';
+/** Options for {@link attachLocalActor}. */
+export interface LocalActorConfig<T> {
+    /** Codec between your typed replication state and the base64 wire form. */
+    codec: StateCodec<T>;
+    /** The state sent until {@link LocalActorStore.setState} changes it. */
+    initialState: T;
+    /** Explicit 32-char uuid (wins over `uuidStore`). */
+    uuid?: string;
+    /**
+     * Where the minted uuid persists. Defaults to {@link memoryUuidStore};
+     * pass {@link localStorageUuidStore} for a stable identity across reloads.
+     */
+    uuidStore?: UuidStore;
+    /**
+     * Send-loop cadence in ms. Defaults to **200 (5 Hz)** — the proven
+     * cadence for player presence. Set `0` or `false` to disable the loop and
+     * drive {@link LocalActorStore.sendNow} yourself. Runs on the session
+     * {@link Ticker}: pass `workerTicker()` to `createWorldSession` to hold
+     * the rate in backgrounded tabs.
+     */
+    sendIntervalMs?: number | false;
+    /**
+     * Skip loop sends whose encoded state is byte-identical to the last send.
+     * Defaults to true. Explicit sends (`sendNow`, `join`, `moveTo`) always go
+     * out.
+     */
+    sendOnChange?: boolean;
+    /**
+     * With `sendOnChange`, still force a keyframe send after this many ms of
+     * dedup silence so presence never starves. Defaults to 3000.
+     */
+    keyframeEveryMs?: number;
+    /** Default replication radius in chunk units (0-8). */
+    distance?: number;
+    /** Default replication decay algorithm (0-5). */
+    decayRate?: number;
+    /**
+     * Re-send presence when the browser tab becomes visible again (timers may
+     * have been throttled while hidden). Defaults to true in browsers.
+     */
+    refreshOnVisibility?: boolean;
+    /** Clock override for tests. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * The SDK-managed **local actor**: identity (minted + persisted uuid), typed
+ * replication state, current chunk, an automatic 5 Hz send loop with
+ * send-on-change dedup, and queryable send bookkeeping — {@link lastSent},
+ * {@link lastAck} (the server-applied self-echo), {@link lastError}, and
+ * {@link status}. Replaces the hand-written codec + sender + uuid plumbing
+ * every game rebuilds.
+ *
+ * Reads are synchronous; all record updates happen on WebSocket events, so
+ * the render loop can query freely regardless of tab visibility.
+ */
+export declare class LocalActorStore<T> {
+    private readonly ctx;
+    private readonly config;
+    /** This actor's 32-char wire id. */
+    readonly uuid: string;
+    private currentState;
+    private currentChunk;
+    private lastSentRecord;
+    private lastAckRecord;
+    private lastErrorRecord;
+    private readonly inFlight;
+    private readonly sequences;
+    private readonly now;
+    constructor(ctx: WorldSessionContext, config: LocalActorConfig<T>);
+    /** The current typed replication state (what the loop sends). */
+    get state(): T;
+    /** The actor's current chunk (null before {@link join}). */
+    get chunk(): ChunkCoordinatesInput | null;
+    /** The most recent outbound update (typed + encoded + seq + timestamp). */
+    get lastSent(): SentActorUpdate<T> | null;
+    /** The most recent server-applied self-echo. */
+    get lastAck(): AckedActorUpdate<T> | null;
+    /** The most recent send error attributed to this actor. */
+    get lastError(): ActorSendError | null;
+    /**
+     * Replication lifecycle: `idle` (nothing sent), `pending` (sent, no echo
+     * yet), `acked` (echo at or after the last send), `error` (an error
+     * arrived after the last send).
+     */
+    get status(): LocalActorStatus;
+    /** Update the typed state; the next loop tick (or `sendNow`) sends it. */
+    setState(state: T): void;
+    /** Merge a partial update into the typed state (object states only). */
+    patchState(patch: Partial<T>): void;
+    /**
+     * Enter a chunk: records it as the actor's current chunk and immediately
+     * sends presence there. (The first message to a brand-new chunk may be
+     * dropped server-side while grid permissions load — if {@link status}
+     * stays `pending`, call {@link refresh}.)
+     */
+    join(chunk: ChunkCoordinatesInput, state?: T): Promise<void>;
+    /** Move to another chunk and immediately send presence there. */
+    moveTo(chunk: ChunkCoordinatesInput): Promise<void>;
+    /** Send the current state now, bypassing dedup. */
+    sendNow(): Promise<void>;
+    /** Re-register presence (reconnects, tab return, dropped first join). */
+    refresh(reason?: SendReason): Promise<void>;
+    /** One send-loop tick: dedup unchanged state, keyframe when quiet. */
+    private tick;
+    private send;
+}
+/**
+ * Attach a {@link LocalActorStore} to a world session context. Prefer the
+ * `self` key of `createWorldSession`'s config; use this directly for custom
+ * compositions.
+ */
+export declare function attachLocalActor<T>(ctx: WorldSessionContext, config: LocalActorConfig<T>): LocalActorStore<T>;
+/** One timestamped state sample of a remote actor (newest first in history). */
+export interface RemoteActorSample<T> {
+    state: T;
+    chunk: ChunkCoordinatesInput;
+    /** Server-stamped epoch ms of the update. */
+    epochMillis: number;
+    /** Local receive time (ms). */
+    receivedAt: number;
+}
+/**
+ * A tracked remote actor. The object identity is **stable** across updates
+ * (fields mutate in place), so render code can hold references; check the
+ * lane's `revision` for cheap change detection.
+ */
+export interface RemoteActor<T> {
+    readonly uuid: string;
+    /** The latest decoded state. */
+    state: T;
+    /** The chunk of the latest update. */
+    chunk: ChunkCoordinatesInput;
+    /** Replication radius of the latest update. */
+    distance: number;
+    /** Server-stamped epoch ms of the latest update. */
+    epochMillis: number;
+    /** Local receive time of the latest update (ms). */
+    receivedAt: number;
+    /**
+     * Recent samples, newest first (length ≤ `historySize`) — the data an
+     * interpolating renderer needs without keeping its own buffers.
+     */
+    samples: Array<RemoteActorSample<T>>;
+}
+/** Options for {@link attachRemoteActors}. */
+export interface RemoteActorsConfig<T> {
+    /** Codec between the base64 wire state and the typed actor state. */
+    codec: StateCodec<T>;
+    /**
+     * The local actor's uuid (or a getter), filtered out as the self-echo.
+     * `createWorldSession` wires this automatically from `config.self`.
+     */
+    selfUuid?: string | (() => string | null);
+    /**
+     * Actors quieter than this are considered gone: excluded from reads and
+     * physically reaped (with `onLeave`) by the reap timer. Defaults to
+     * 12 000 ms. `false` disables staleness entirely.
+     */
+    staleAfterMs?: number | false;
+    /**
+     * Reap-timer cadence (physically deletes stale records and fires
+     * `onLeave`). Defaults to 1000 ms; `false` relies on read-time filtering +
+     * manual {@link RemoteActorStore.reap} only. Reads are always correct
+     * regardless — staleness is ALSO computed at read time, so a throttled
+     * timer can never serve stale actors.
+     */
+    reapIntervalMs?: number | false;
+    /** Samples kept per actor for interpolation. Defaults to 2. */
+    historySize?: number;
+    /**
+     * Named lanes routing one decoded notification to the first matching
+     * sub-registry — e.g. `{ players: (s) => !(s.flags & 2), mobs: (s) => !!(s.flags & 2) }`
+     * lets a player renderer and a mob system share the stream without
+     * double-decoding. Omit for a single implicit lane.
+     */
+    lanes?: Record<string, (state: T, notification: ActorUpdateEcho) => boolean>;
+    /** Clock override for tests. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/** One lane's registry of remote actors. */
+export declare class RemoteActorLane<T> {
+    private readonly historySize;
+    private readonly staleAfterMs;
+    private readonly now;
+    private readonly actors;
+    private readonly joinListeners;
+    private readonly updateListeners;
+    private readonly leaveListeners;
+    private revisionValue;
+    constructor(historySize: number, staleAfterMs: number | false, now: () => number);
+    /** Bumped on every change — poll it cheaply from a render loop. */
+    get revision(): number;
+    /** Live actors (stale ones filtered at read time), unordered. */
+    list(): Array<RemoteActor<T>>;
+    /** One live actor, or undefined when unknown/stale. */
+    get(uuid: string): RemoteActor<T> | undefined;
+    /** Live actor count. */
+    get count(): number;
+    /** A new actor appeared. @returns off. */
+    onJoin(listener: (actor: RemoteActor<T>) => void): () => void;
+    /** An actor's state updated (fires after `onJoin` for the first update). @returns off. */
+    onUpdate(listener: (actor: RemoteActor<T>) => void): () => void;
+    /** An actor went stale and was reaped (or the store was cleared). @returns off. */
+    onLeave(listener: (actor: RemoteActor<T>) => void): () => void;
+    /** Apply one decoded update (internal). */
+    apply(uuid: string, state: T, chunk: ChunkCoordinatesInput, distance: number, epochMillis: number): void;
+    /** Physically delete stale records, firing `onLeave` for each. */
+    reap(): void;
+    /** Drop every record (fires `onLeave` for each live one). */
+    clear(): void;
+    private isStale;
+}
+/**
+ * The SDK-managed **remote actor registry**: subscribes to `actorUpdate`,
+ * decodes each notification ONCE, filters the local self-echo, and maintains
+ * per-actor records with timestamped sample history, staleness, and
+ * join/update/leave events. With `lanes`, one decoded stream feeds several
+ * consumers (players vs mobs) without double-decoding.
+ *
+ * Reads are synchronous and always live-filtered (staleness is computed at
+ * read time), so render loops can query at any cadence — including after a
+ * backgrounded tab resumes.
+ */
+export declare class RemoteActorStore<T> {
+    private readonly config;
+    private readonly lanes;
+    private readonly laneFilters;
+    private readonly defaultLane;
+    private decodeFailureCount;
+    constructor(ctx: WorldSessionContext, config: RemoteActorsConfig<T>);
+    /** A named lane's registry (throws for unknown names). */
+    lane(name: string): RemoteActorLane<T>;
+    /** Live actors across every lane (the default lane when none configured). */
+    list(): Array<RemoteActor<T>>;
+    /** One live actor, searched across lanes. */
+    get(uuid: string): RemoteActor<T> | undefined;
+    /** Live actor count across lanes. */
+    get count(): number;
+    /** Sum of lane revisions — poll it cheaply from a render loop. */
+    get revision(): number;
+    /** Notifications whose state failed to decode (foreign layouts). */
+    get decodeFailures(): number;
+    /** A new actor appeared (default/single-lane sugar; use `lane()` with lanes). */
+    onJoin(listener: (actor: RemoteActor<T>) => void): () => void;
+    /** An actor updated. */
+    onUpdate(listener: (actor: RemoteActor<T>) => void): () => void;
+    /** An actor was reaped. */
+    onLeave(listener: (actor: RemoteActor<T>) => void): () => void;
+    /** Physically delete stale records in every lane. */
+    reap(): void;
+    /** Drop every record in every lane. */
+    clear(): void;
+    private everyLane;
+}
+/**
+ * Attach a {@link RemoteActorStore} to a world session context. Prefer the
+ * `actors` key of `createWorldSession`'s config.
+ */
+export declare function attachRemoteActors<T>(ctx: WorldSessionContext, config: RemoteActorsConfig<T>): RemoteActorStore<T>;
+//# sourceMappingURL=actors.d.ts.map

package/dist/stores/actors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actors.d.ts","sourceRoot":"","sources":["../../src/stores/actors.ts"],"names":[],"mappings":"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"}