@crowdedkingdoms/crowdyjs 8.3.0 → 8.4.0

package/dist/stores/actors.js

@@ -0,0 +1,506 @@
+/**
+ * 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 { SequenceAllocator, generateCrowdyUuid, validateCrowdyUuid } from '../utils.js';
+/** Keep the uuid for this tab session only (a fresh actor per reload). */
+export function memoryUuidStore() {
+    let value = null;
+    return {
+        load: () => value,
+        save: (uuid) => {
+            value = uuid;
+        },
+    };
+}
+/**
+ * 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 function localStorageUuidStore(key = 'crowdyjs:actor-uuid') {
+    const storage = globalThis.localStorage;
+    if (!storage)
+        return memoryUuidStore();
+    return {
+        load: () => {
+            try {
+                return storage.getItem(key);
+            }
+            catch {
+                return null;
+            }
+        },
+        save: (uuid) => {
+            try {
+                storage.setItem(key, uuid);
+            }
+            catch {
+                // Quota/permission failures degrade to per-session identity.
+            }
+        },
+    };
+}
+/**
+ * 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 class LocalActorStore {
+    constructor(ctx, config) {
+        this.ctx = ctx;
+        this.config = config;
+        this.currentChunk = null;
+        this.lastSentRecord = null;
+        this.lastAckRecord = null;
+        this.lastErrorRecord = null;
+        this.inFlight = new Map(); // seq → sentAt
+        this.sequences = new SequenceAllocator();
+        this.now = config.now ?? Date.now;
+        this.currentState = config.initialState;
+        // Identity: explicit uuid > persisted uuid > freshly minted (persisted).
+        const uuidStore = config.uuidStore ?? memoryUuidStore();
+        let uuid = config.uuid ?? uuidStore.load();
+        if (!uuid) {
+            uuid = generateCrowdyUuid();
+        }
+        validateCrowdyUuid(uuid);
+        uuidStore.save(uuid);
+        this.uuid = uuid;
+        // Self-echo: the server includes the sender in the chunk fan-out, so our
+        // own applied update arrives as an actorUpdate with our uuid.
+        ctx.onDispose(ctx.on('actorUpdate', (notification) => {
+            if (notification.uuid !== this.uuid)
+                return;
+            let state;
+            try {
+                state = this.config.codec.decode(notification.state);
+            }
+            catch {
+                return; // Not our layout (shouldn't happen for our own echo).
+            }
+            this.lastAckRecord = { state, notification, receivedAt: this.now() };
+            this.inFlight.delete(notification.sequenceNumber);
+        }));
+        // Attribute send errors to our in-flight sequence numbers.
+        ctx.onDispose(ctx.on('genericError', (notification) => {
+            if (!this.inFlight.has(notification.sequenceNumber))
+                return;
+            this.inFlight.delete(notification.sequenceNumber);
+            this.lastErrorRecord = {
+                errorCode: String(notification.errorCode),
+                sequenceNumber: notification.sequenceNumber,
+                receivedAt: this.now(),
+            };
+        }));
+        // The send loop (5 Hz default) on the shared session ticker.
+        const interval = config.sendIntervalMs ?? 200;
+        if (interval !== false && interval > 0) {
+            ctx.onDispose(ctx.ticker.every(interval, () => this.tick()));
+        }
+        // Tab-return re-registration.
+        const doc = globalThis.document;
+        if ((config.refreshOnVisibility ?? true) && doc?.addEventListener) {
+            const onVisibility = () => {
+                if (doc.visibilityState === 'visible')
+                    void this.refresh('visibility');
+            };
+            doc.addEventListener('visibilitychange', onVisibility);
+            ctx.onDispose(() => doc.removeEventListener('visibilitychange', onVisibility));
+        }
+    }
+    /** The current typed replication state (what the loop sends). */
+    get state() {
+        return this.currentState;
+    }
+    /** The actor's current chunk (null before {@link join}). */
+    get chunk() {
+        return this.currentChunk;
+    }
+    /** The most recent outbound update (typed + encoded + seq + timestamp). */
+    get lastSent() {
+        return this.lastSentRecord;
+    }
+    /** The most recent server-applied self-echo. */
+    get lastAck() {
+        return this.lastAckRecord;
+    }
+    /** The most recent send error attributed to this actor. */
+    get lastError() {
+        return this.lastErrorRecord;
+    }
+    /**
+     * 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() {
+        if (!this.lastSentRecord)
+            return 'idle';
+        if (this.lastErrorRecord &&
+            this.lastErrorRecord.receivedAt >= this.lastSentRecord.sentAt) {
+            return 'error';
+        }
+        if (this.lastAckRecord &&
+            this.lastAckRecord.receivedAt >= this.lastSentRecord.sentAt) {
+            return 'acked';
+        }
+        return 'pending';
+    }
+    /** Update the typed state; the next loop tick (or `sendNow`) sends it. */
+    setState(state) {
+        this.currentState = state;
+    }
+    /** Merge a partial update into the typed state (object states only). */
+    patchState(patch) {
+        this.currentState = { ...this.currentState, ...patch };
+    }
+    /**
+     * 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}.)
+     */
+    async join(chunk, state) {
+        this.currentChunk = chunk;
+        if (state !== undefined)
+            this.currentState = state;
+        await this.send('join');
+    }
+    /** Move to another chunk and immediately send presence there. */
+    async moveTo(chunk) {
+        this.currentChunk = chunk;
+        await this.send('move');
+    }
+    /** Send the current state now, bypassing dedup. */
+    async sendNow() {
+        await this.send('manual');
+    }
+    /** Re-register presence (reconnects, tab return, dropped first join). */
+    async refresh(reason = 'refresh') {
+        if (!this.currentChunk)
+            return;
+        await this.send(reason);
+    }
+    /** One send-loop tick: dedup unchanged state, keyframe when quiet. */
+    tick() {
+        if (!this.currentChunk)
+            return;
+        const encoded = this.config.codec.encode(this.currentState);
+        if ((this.config.sendOnChange ?? true) && this.lastSentRecord) {
+            const quietFor = this.now() - this.lastSentRecord.sentAt;
+            const keyframeEvery = this.config.keyframeEveryMs ?? 3000;
+            if (encoded === this.lastSentRecord.encoded && quietFor < keyframeEvery) {
+                return;
+            }
+            if (encoded === this.lastSentRecord.encoded) {
+                void this.send('keyframe', encoded);
+                return;
+            }
+        }
+        void this.send('interval', encoded);
+    }
+    async send(reason, preEncoded) {
+        const chunk = this.currentChunk;
+        if (!chunk) {
+            throw new Error('Local actor must join a chunk before sending');
+        }
+        const state = this.currentState;
+        const encoded = preEncoded ?? this.config.codec.encode(state);
+        const sequenceNumber = this.sequences.next();
+        const sentAt = this.now();
+        this.lastSentRecord = { state, encoded, chunk, sequenceNumber, sentAt, reason };
+        this.inFlight.set(sequenceNumber, sentAt);
+        if (this.inFlight.size > 256) {
+            const oldest = this.inFlight.keys().next().value;
+            if (oldest !== undefined)
+                this.inFlight.delete(oldest);
+        }
+        this.ctx.trackSend({
+            kind: 'actorUpdate',
+            sequenceNumber,
+            sentAt,
+            uuid: this.uuid,
+            detail: { reason },
+        });
+        await this.ctx.client.udp.sendActorUpdate({
+            appId: this.ctx.appId,
+            chunk,
+            uuid: this.uuid,
+            state: encoded,
+            sequenceNumber,
+            ...(this.config.distance !== undefined ? { distance: this.config.distance } : {}),
+            ...(this.config.decayRate !== undefined
+                ? { decayRate: this.config.decayRate }
+                : {}),
+        });
+    }
+}
+/**
+ * Attach a {@link LocalActorStore} to a world session context. Prefer the
+ * `self` key of `createWorldSession`'s config; use this directly for custom
+ * compositions.
+ */
+export function attachLocalActor(ctx, config) {
+    return new LocalActorStore(ctx, config);
+}
+/** One lane's registry of remote actors. */
+export class RemoteActorLane {
+    constructor(historySize, staleAfterMs, now) {
+        this.historySize = historySize;
+        this.staleAfterMs = staleAfterMs;
+        this.now = now;
+        this.actors = new Map();
+        this.joinListeners = new Set();
+        this.updateListeners = new Set();
+        this.leaveListeners = new Set();
+        this.revisionValue = 0;
+    }
+    /** Bumped on every change — poll it cheaply from a render loop. */
+    get revision() {
+        return this.revisionValue;
+    }
+    /** Live actors (stale ones filtered at read time), unordered. */
+    list() {
+        const out = [];
+        for (const actor of this.actors.values()) {
+            if (!this.isStale(actor))
+                out.push(actor);
+        }
+        return out;
+    }
+    /** One live actor, or undefined when unknown/stale. */
+    get(uuid) {
+        const actor = this.actors.get(uuid);
+        return actor && !this.isStale(actor) ? actor : undefined;
+    }
+    /** Live actor count. */
+    get count() {
+        return this.list().length;
+    }
+    /** A new actor appeared. @returns off. */
+    onJoin(listener) {
+        this.joinListeners.add(listener);
+        return () => this.joinListeners.delete(listener);
+    }
+    /** An actor's state updated (fires after `onJoin` for the first update). @returns off. */
+    onUpdate(listener) {
+        this.updateListeners.add(listener);
+        return () => this.updateListeners.delete(listener);
+    }
+    /** An actor went stale and was reaped (or the store was cleared). @returns off. */
+    onLeave(listener) {
+        this.leaveListeners.add(listener);
+        return () => this.leaveListeners.delete(listener);
+    }
+    /** Apply one decoded update (internal). */
+    apply(uuid, state, chunk, distance, epochMillis) {
+        const receivedAt = this.now();
+        let actor = this.actors.get(uuid);
+        const isNew = !actor;
+        if (!actor) {
+            actor = {
+                uuid,
+                state,
+                chunk,
+                distance,
+                epochMillis,
+                receivedAt,
+                samples: [],
+            };
+            this.actors.set(uuid, actor);
+        }
+        actor.state = state;
+        actor.chunk = chunk;
+        actor.distance = distance;
+        actor.epochMillis = epochMillis;
+        actor.receivedAt = receivedAt;
+        actor.samples.unshift({ state, chunk, epochMillis, receivedAt });
+        if (actor.samples.length > this.historySize) {
+            actor.samples.length = this.historySize;
+        }
+        this.revisionValue += 1;
+        if (isNew) {
+            for (const listener of [...this.joinListeners])
+                listener(actor);
+        }
+        for (const listener of [...this.updateListeners])
+            listener(actor);
+    }
+    /** Physically delete stale records, firing `onLeave` for each. */
+    reap() {
+        for (const [uuid, actor] of this.actors) {
+            if (this.isStale(actor)) {
+                this.actors.delete(uuid);
+                this.revisionValue += 1;
+                for (const listener of [...this.leaveListeners])
+                    listener(actor);
+            }
+        }
+    }
+    /** Drop every record (fires `onLeave` for each live one). */
+    clear() {
+        for (const [uuid, actor] of this.actors) {
+            this.actors.delete(uuid);
+            this.revisionValue += 1;
+            for (const listener of [...this.leaveListeners])
+                listener(actor);
+        }
+    }
+    isStale(actor) {
+        return (this.staleAfterMs !== false && this.now() - actor.receivedAt > this.staleAfterMs);
+    }
+}
+/**
+ * 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 class RemoteActorStore {
+    constructor(ctx, config) {
+        this.config = config;
+        this.lanes = new Map();
+        this.decodeFailureCount = 0;
+        const now = config.now ?? Date.now;
+        const historySize = Math.max(1, config.historySize ?? 2);
+        const staleAfterMs = config.staleAfterMs ?? 12000;
+        const laneNames = config.lanes ? Object.keys(config.lanes) : ['default'];
+        for (const name of laneNames) {
+            this.lanes.set(name, new RemoteActorLane(historySize, staleAfterMs, now));
+        }
+        this.laneFilters = config.lanes
+            ? Object.entries(config.lanes)
+            : [['default', () => true]];
+        this.defaultLane = config.lanes ? null : this.lanes.get('default');
+        ctx.onDispose(ctx.on('actorUpdate', (notification) => {
+            const selfUuid = typeof this.config.selfUuid === 'function'
+                ? this.config.selfUuid()
+                : this.config.selfUuid;
+            if (selfUuid && notification.uuid === selfUuid)
+                return;
+            let state;
+            try {
+                state = this.config.codec.decode(notification.state);
+            }
+            catch {
+                this.decodeFailureCount += 1;
+                return;
+            }
+            for (const [name, filter] of this.laneFilters) {
+                let matches;
+                try {
+                    matches = filter(state, notification);
+                }
+                catch {
+                    continue;
+                }
+                if (!matches)
+                    continue;
+                this.lanes.get(name).apply(notification.uuid, state, {
+                    x: notification.chunkX,
+                    y: notification.chunkY,
+                    z: notification.chunkZ,
+                }, notification.distance, Number(notification.epochMillis));
+                break; // first matching lane wins
+            }
+        }));
+        const reapInterval = config.reapIntervalMs ?? 1000;
+        if (reapInterval !== false && reapInterval > 0 && staleAfterMs !== false) {
+            ctx.onDispose(ctx.ticker.every(reapInterval, () => this.reap()));
+        }
+    }
+    /** A named lane's registry (throws for unknown names). */
+    lane(name) {
+        const lane = this.lanes.get(name);
+        if (!lane) {
+            throw new Error(`Unknown actor lane '${name}' (configured: ${[...this.lanes.keys()].join(', ')})`);
+        }
+        return lane;
+    }
+    /** Live actors across every lane (the default lane when none configured). */
+    list() {
+        if (this.defaultLane)
+            return this.defaultLane.list();
+        const out = [];
+        for (const lane of this.lanes.values())
+            out.push(...lane.list());
+        return out;
+    }
+    /** One live actor, searched across lanes. */
+    get(uuid) {
+        for (const lane of this.lanes.values()) {
+            const actor = lane.get(uuid);
+            if (actor)
+                return actor;
+        }
+        return undefined;
+    }
+    /** Live actor count across lanes. */
+    get count() {
+        let total = 0;
+        for (const lane of this.lanes.values())
+            total += lane.count;
+        return total;
+    }
+    /** Sum of lane revisions — poll it cheaply from a render loop. */
+    get revision() {
+        let total = 0;
+        for (const lane of this.lanes.values())
+            total += lane.revision;
+        return total;
+    }
+    /** Notifications whose state failed to decode (foreign layouts). */
+    get decodeFailures() {
+        return this.decodeFailureCount;
+    }
+    /** A new actor appeared (default/single-lane sugar; use `lane()` with lanes). */
+    onJoin(listener) {
+        return this.everyLane((lane) => lane.onJoin(listener));
+    }
+    /** An actor updated. */
+    onUpdate(listener) {
+        return this.everyLane((lane) => lane.onUpdate(listener));
+    }
+    /** An actor was reaped. */
+    onLeave(listener) {
+        return this.everyLane((lane) => lane.onLeave(listener));
+    }
+    /** Physically delete stale records in every lane. */
+    reap() {
+        for (const lane of this.lanes.values())
+            lane.reap();
+    }
+    /** Drop every record in every lane. */
+    clear() {
+        for (const lane of this.lanes.values())
+            lane.clear();
+    }
+    everyLane(register) {
+        const offs = [...this.lanes.values()].map(register);
+        return () => {
+            for (const off of offs)
+                off();
+        };
+    }
+}
+/**
+ * Attach a {@link RemoteActorStore} to a world session context. Prefer the
+ * `actors` key of `createWorldSession`'s config.
+ */
+export function attachRemoteActors(ctx, config) {
+    return new RemoteActorStore(ctx, config);
+}

package/dist/stores/chunks.d.ts

@@ -0,0 +1,180 @@
+/**
+ * ChunkStore — the SDK-managed chunk/voxel cache: bulk loading, typed
+ * per-voxel and per-chunk state, realtime merge of voxel notifications,
+ * optimistic local edits, and the deterministic-worldgen write-back pattern.
+ * Replaces the WorldStreamer + WorldState + codec plumbing every voxel game
+ * hand-writes (~860 LOC in Blocks with Friends).
+ */
+import { type StateCodec } from './codec.js';
+import { type ChunkCoord } from './keys.js';
+import type { WorldSessionContext } from './session.js';
+/** Load lifecycle of a cached chunk. */
+export type ChunkLoadState = 'loading' | 'loaded' | 'missing' | 'seeded' | 'failed';
+/**
+ * One cached chunk. Object identity is stable; check `revision` for cheap
+ * change detection from a render loop.
+ */
+export interface CachedChunk<TVoxelState = string, TChunkState = string> {
+    readonly key: string;
+    readonly coord: ChunkCoord;
+    /** Dense voxel-type grid (4096 bytes, `x + y*16 + z*256`), null when unknown. */
+    voxels: Uint8Array | null;
+    /** Sparse typed per-voxel state by voxel index. */
+    voxelStates: Map<number, TVoxelState>;
+    /** Typed chunk-level state (null when absent/undecoded). */
+    chunkState: TChunkState | null;
+    loadState: ChunkLoadState;
+    /** Bumped on every change to this chunk. */
+    revision: number;
+    /** Local time of the last change. */
+    updatedAt: number;
+    /** Whether sparse voxel states were hydrated (bulk loads omit them). */
+    hydrated: boolean;
+    /** Whether local edits are queued for write-back. */
+    dirty: boolean;
+}
+/** Options for {@link attachChunkStore}. */
+export interface ChunkStoreConfig<TVoxelState = string, TChunkState = string> {
+    /** Codec for per-voxel state blobs. Defaults to raw base64 strings. */
+    voxelStateCodec?: StateCodec<TVoxelState>;
+    /** Codec for the chunk-level state blob. Defaults to raw base64 strings. */
+    chunkStateCodec?: StateCodec<TChunkState>;
+    /**
+     * After a bulk load, fetch each chunk individually to hydrate its sparse
+     * `voxelStates` (`getChunksByDistance` does NOT return them — a platform
+     * trap this store encapsulates). Defaults to true when a
+     * `voxelStateCodec` is configured, else false.
+     */
+    hydrateVoxelStates?: boolean;
+    /**
+     * Called for chunks the server has never stored. Return a 4096-byte dense
+     * grid to seed it locally (deterministic client-side worldgen) — seeded
+     * chunks are queued for write-back so the world persists and stays
+     * identical for everyone.
+     */
+    onMissing?: (coord: ChunkCoord) => Uint8Array | undefined | void;
+    /**
+     * Write-back cadence: one dirty chunk persists per tick (throttled, like
+     * the proven BWF pattern). Defaults to 700 ms; `false` disables the timer
+     * (call {@link ChunkStore.flush} yourself). Runs on the session ticker.
+     */
+    writeBackIntervalMs?: number | false;
+    /** Replication radius for outbound voxel updates (0-8). */
+    distance?: number;
+    /** Decay algorithm for outbound voxel updates (0-5). */
+    decayRate?: number;
+    /**
+     * The actor uuid stamped on outbound voxel updates. Wired from the
+     * session's local actor automatically; a random uuid otherwise.
+     */
+    actorUuid?: string | (() => string | null);
+    /** Clock override for tests. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/** A voxel edit for {@link ChunkStore.setVoxel}. */
+export interface SetVoxelInput<TVoxelState> {
+    chunk: ChunkCoord;
+    /** Within-chunk voxel coordinates (0-15 each). */
+    x: number;
+    y: number;
+    z: number;
+    voxelType: number;
+    /** Typed per-voxel state (encoded with the store's codec). */
+    state?: TVoxelState;
+    /** Apply locally before the send resolves. Defaults to true. */
+    optimistic?: boolean;
+}
+/**
+ * The SDK-managed **chunk/voxel cache** — the client-side source of truth
+ * for terrain:
+ *
+ * - `ensureAround(center, radius)` bulk-loads via `chunks.byDistance`
+ *   (in-flight deduped), hydrates sparse voxel states, marks chunks the
+ *   server never stored as `missing`, and hands them to your `onMissing`
+ *   worldgen hook.
+ * - Realtime `voxelUpdate` notifications merge into the cache automatically
+ *   (dense grid write + typed state decode + revision bump + change event).
+ * - `setVoxel` applies locally (optimistic) and replicates via the UDP path.
+ * - `seed`/`flush` implement deterministic-worldgen write-back through
+ *   `chunks.update`, one throttled chunk at a time.
+ *
+ * All reads are synchronous; writes land on WebSocket events, so render
+ * loops and background tabs behave (see the module docs).
+ */
+export declare class ChunkStore<TVoxelState = string, TChunkState = string> {
+    private readonly ctx;
+    private readonly config;
+    private readonly chunks;
+    private readonly inFlight;
+    private readonly writeBackQueue;
+    private readonly changeListeners;
+    private readonly voxelStateCodec;
+    private readonly chunkStateCodec;
+    private readonly hydrateStates;
+    private readonly now;
+    private readonly fallbackUuid;
+    private revisionValue;
+    private sequence;
+    constructor(ctx: WorldSessionContext, config?: ChunkStoreConfig<TVoxelState, TChunkState>);
+    /** Bumped on every cache change — poll it cheaply from a render loop. */
+    get revision(): number;
+    /** The cached chunk at a coordinate (any load state), if tracked. */
+    get(coord: ChunkCoord): CachedChunk<TVoxelState, TChunkState> | undefined;
+    /** Every tracked chunk (any load state). */
+    list(): Array<CachedChunk<TVoxelState, TChunkState>>;
+    /** The dense voxel type at a within-chunk coordinate (0 when unknown). */
+    voxelTypeAt(coord: ChunkCoord, x: number, y: number, z: number): number;
+    /** The typed per-voxel state at a within-chunk coordinate, if any. */
+    voxelStateAt(coord: ChunkCoord, x: number, y: number, z: number): TVoxelState | undefined;
+    /** Subscribe to per-chunk changes (loads, merges, edits). @returns off. */
+    onChunkChanged(listener: (chunk: CachedChunk<TVoxelState, TChunkState>) => void): () => void;
+    /**
+     * Ensure every chunk within `radius` (Chebyshev, 1-8) of `center` is
+     * tracked: bulk-loads untracked ones, hydrates sparse voxel states when
+     * configured, marks server-unknown chunks `missing`, and seeds them via
+     * `onMissing`. In-flight requests are deduped; safe to call every time the
+     * player crosses a chunk boundary.
+     */
+    ensureAround(center: ChunkCoord, radius: number): Promise<void>;
+    /**
+     * Hydrate one chunk's sparse voxel states (and chunk state) via a
+     * single-chunk fetch — bulk loads omit them.
+     */
+    hydrate(coord: ChunkCoord): Promise<void>;
+    /**
+     * Edit one voxel: applies to the cache immediately (optimistic) and
+     * replicates via the realtime voxel path. Resolves with the send
+     * acceptance.
+     */
+    setVoxel(input: SetVoxelInput<TVoxelState>): Promise<boolean>;
+    /**
+     * Seed a locally generated chunk (deterministic worldgen) and queue it for
+     * write-back so the server copy exists for everyone.
+     */
+    seed(coord: ChunkCoord, voxels: Uint8Array, options?: {
+        writeBack?: boolean;
+    }): void;
+    /** Queue a tracked chunk's dense grid for (throttled) write-back. */
+    markDirty(coord: ChunkCoord): void;
+    /** Chunks currently queued for write-back. */
+    get pendingWriteBacks(): number;
+    /** Persist every queued chunk now (awaits all writes). */
+    flush(): Promise<void>;
+    /** Drop tracked chunks farther than `radius` from `center` (dirty ones kept). */
+    pruneBeyond(center: ChunkCoord, radius: number): void;
+    private persistNext;
+    private applyServerChunk;
+    private markMissing;
+    private applyVoxel;
+    private ensureEntry;
+    private decodeChunkState;
+    private touch;
+    private senderUuid;
+    private nextSequence;
+}
+/**
+ * Attach a {@link ChunkStore} to a world session context. Prefer the
+ * `chunks` key of `createWorldSession`'s config.
+ */
+export declare function attachChunkStore<TVoxelState = string, TChunkState = string>(ctx: WorldSessionContext, config?: ChunkStoreConfig<TVoxelState, TChunkState>): ChunkStore<TVoxelState, TChunkState>;
+//# sourceMappingURL=chunks.d.ts.map

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

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