@crowdedkingdoms/construct 0.3.3-dev.1 → 0.3.5-dev.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crowdedkingdoms/construct",
-  "version": "0.3.3-dev.1",
+  "version": "0.3.5-dev.1",
   "description": "The Construct framework: the Crowded Kingdoms game platform layer (hosted sign-in, World Stores, voice/webcam/chat, Crowdy Studio dock, app and grid mods, grid programs) and engine loop, shared by the-construct starter and the games built on it. Ships TypeScript source for Vite.",
   "license": "MIT",
   "type": "module",
@@ -45,8 +45,8 @@
     "./grid/*": "./src/grid/*.ts"
   },
   "peerDependencies": {
-    "@crowdedkingdoms/crowdyjs": ">=18.0.3-dev.0 <19",
-    "@crowdedkingdoms/crowdy-dsh": ">=0.4.0-dev.0 <1 || >=0.4.1-dev.0 <1 || >=0.4.2-dev.0 <1 || >=0.4.3-dev.0 <1"
+    "@crowdedkingdoms/crowdyjs": ">=18.0.4-dev.0 <19 || >=18.1.0-dev.0 <19",
+    "@crowdedkingdoms/crowdy-dsh": ">=0.4.0-dev.0 <1 || >=0.4.1-dev.0 <1 || >=0.4.2-dev.0 <1 || >=0.4.3-dev.0 <1 || >=0.4.4-dev.0 <1"
   },
   "peerDependenciesMeta": {
     "@crowdedkingdoms/crowdy-dsh": {

package/src/index.ts

@@ -92,4 +92,14 @@ export {
   type GridClientHalvesOptions,
 } from './platform/studio/clientHalves';
 export { gridServerCalls, type GridServerCallsOptions } from './platform/studio/gridServerCalls';
+export {
+  EXHAUSTED_MESSAGE,
+  REFUSED_MESSAGE,
+  describeWriteBackFailure,
+  guardWriteBacks,
+  reloadChunk,
+  type GuardedChunkStore,
+  type WriteBackGuardOptions,
+  type WriteBackTone,
+} from './platform/realtime/writeBackGuard';
 export { GridProgramRunner, type GridProgramRunnerOptions } from './grid/GridProgramRunner';

package/src/platform/GameSession.ts

@@ -18,6 +18,7 @@ import {
   type RemotePlayer,
   type SaveState,
 } from './realtime/WorldStores';
+import { guardWriteBacks, type WriteBackTone } from './realtime/writeBackGuard';
 import { WebcamService } from './media/WebcamService';
 import { VoiceService } from './media/VoiceService';
 import { ModelService } from './model/ModelService';
@@ -125,6 +126,22 @@ export class GameSession {
     return this.joinedFlag;
   }
 
+  /**
+   * Undo each chunk write-back the server refuses (or never accepts) and tell
+   * the player through `notify`. @returns off.
+   */
+  guardWriteBacks(notify: (text: string, tone: WriteBackTone) => void): () => void {
+    return guardWriteBacks(this.world.chunks, {
+      onServer: async (coord) =>
+        (await this.network.game.chunks.get({
+          appId: this.appId,
+          coordinates: chunkInput(coord),
+        })) != null,
+      notify,
+      log: (message) => this.network.log(message),
+    });
+  }
+
   /** The World Stores session for this app (lazily created). */
   get world(): ConstructWorldSession {
     return worldSession();

package/src/platform/realtime/writeBackGuard.test.ts

@@ -0,0 +1,145 @@
+import { describe, expect, it, vi } from 'vitest';
+import { ChunkStore } from '@crowdedkingdoms/crowdyjs/stores';
+
+import {
+  EXHAUSTED_MESSAGE,
+  REFUSED_MESSAGE,
+  describeWriteBackFailure,
+  guardWriteBacks,
+} from './writeBackGuard';
+
+const COORD = { x: 2, y: 0, z: 3 };
+
+function base64(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString('base64');
+}
+
+function forbidden(): Error {
+  return Object.assign(new Error('You cannot edit this chunk'), {
+    extensions: { code: 'FORBIDDEN' },
+  });
+}
+
+/** The real SDK store over a fake client: `serverVoxels` is the server's copy (null: never stored). */
+function storeWith(update: () => Promise<unknown>, serverVoxels: Uint8Array | null) {
+  const client = {
+    chunks: {
+      update: vi.fn(update),
+      get: vi.fn(async () =>
+        serverVoxels ? { voxels: base64(serverVoxels), voxelStates: [] } : null,
+      ),
+      byDistance: vi.fn(async () => ({ chunks: [] })),
+    },
+    udp: { sendVoxelUpdate: vi.fn(async () => true) },
+  };
+  const ctx = {
+    appId: '1',
+    client,
+    ticker: { every: () => () => undefined },
+    on: () => () => undefined,
+    trackSend: () => undefined,
+    setSendTracker: () => undefined,
+    onDispose: () => undefined,
+  };
+  const store = new ChunkStore(ctx as never, { writeBackIntervalMs: false });
+  return { store, client };
+}
+
+async function paint(store: ChunkStore, voxelType: number): Promise<void> {
+  await store.setVoxel({ chunk: COORD, x: 1, y: 0, z: 1, voxelType, state: 'AA==' });
+  store.markDirty(COORD);
+}
+
+describe('guardWriteBacks', () => {
+  it('undoes a refused paint on a chunk the server never stored, once, and says so', async () => {
+    const { store, client } = storeWith(() => Promise.reject(forbidden()), null);
+    store.seed(COORD, new Uint8Array(4096), { writeBack: false });
+    const notify = vi.fn();
+    const off = guardWriteBacks(store, {
+      onServer: async () => (await client.chunks.get()) != null,
+      notify,
+    });
+
+    await paint(store, 5);
+    expect(store.voxelTypeAt(COORD, 1, 0, 1)).toBe(5);
+
+    const dropped = await store.flush();
+    expect(dropped).toHaveLength(1);
+    expect(dropped[0]?.reason).toBe('refused');
+    // Sent once, not retried.
+    expect(client.chunks.update).toHaveBeenCalledTimes(1);
+    expect(notify).toHaveBeenCalledWith(REFUSED_MESSAGE, 'warn');
+
+    await vi.waitFor(() => expect(store.voxelTypeAt(COORD, 1, 0, 1)).toBe(0));
+    expect(store.voxelStateAt(COORD, 1, 0, 1)).toBeUndefined();
+    expect(store.get(COORD)?.dirty).toBe(false);
+    expect(store.pendingWriteBacks).toBe(0);
+    off();
+  });
+
+  it("puts a refused chunk back to the server's copy", async () => {
+    const server = new Uint8Array(4096);
+    server[1 + 256] = 3;
+    const { store, client } = storeWith(() => Promise.reject(forbidden()), server);
+    store.seed(COORD, server.slice(), { writeBack: false });
+    guardWriteBacks(store, {
+      onServer: async () => (await client.chunks.get()) != null,
+      notify: () => undefined,
+    });
+
+    await paint(store, 7);
+    await store.flush();
+
+    await vi.waitFor(() => expect(store.voxelTypeAt(COORD, 1, 0, 1)).toBe(3));
+  });
+
+  it('says it once for a stroke that drops several chunks', async () => {
+    const { store } = storeWith(() => Promise.reject(forbidden()), null);
+    let now = 1_000;
+    const notify = vi.fn();
+    guardWriteBacks(store, { onServer: async () => false, notify, now: () => now });
+
+    for (const x of [0, 1, 2]) {
+      const coord = { x, y: 0, z: 0 };
+      store.seed(coord, new Uint8Array(4096), { writeBack: false });
+      store.markDirty(coord);
+    }
+    await store.flush();
+    expect(notify).toHaveBeenCalledTimes(1);
+
+    now += 5_000;
+    store.markDirty({ x: 0, y: 0, z: 0 });
+    await store.flush();
+    expect(notify).toHaveBeenCalledTimes(2);
+  });
+
+  it('logs the refusal and survives a failed reload', async () => {
+    const { store } = storeWith(() => Promise.reject(forbidden()), null);
+    store.seed(COORD, new Uint8Array(4096), { writeBack: false });
+    const log = vi.fn();
+    guardWriteBacks(store, {
+      onServer: () => Promise.reject(new Error('offline')),
+      notify: () => undefined,
+      log,
+    });
+    await paint(store, 5);
+    await store.flush();
+    await vi.waitFor(() => expect(log).toHaveBeenCalledWith('chunk 2,0,3 reload failed: offline'));
+    expect(log).toHaveBeenCalledWith(
+      'chunk 2,0,3 write-back refused after 1 attempt(s): You cannot edit this chunk',
+    );
+  });
+});
+
+describe('describeWriteBackFailure', () => {
+  it('tells a refusal from a server that did not answer', () => {
+    expect(describeWriteBackFailure({ reason: 'refused' })).toEqual({
+      text: REFUSED_MESSAGE,
+      tone: 'warn',
+    });
+    expect(describeWriteBackFailure({ reason: 'exhausted' })).toEqual({
+      text: EXHAUSTED_MESSAGE,
+      tone: 'error',
+    });
+  });
+});

package/src/platform/realtime/writeBackGuard.ts

@@ -0,0 +1,101 @@
+/**
+ * What the game does when a chunk write-back is dropped.
+ *
+ * `ChunkStore` applies a voxel edit locally at once and saves the chunk later
+ * (`markDirty` -> `chunks.update`). The server refuses that save for a player
+ * without edit permission on the chunk (another player's claim, a safe zone, a
+ * closed wilderness); the store sends a refusal once, retries anything else a
+ * few times, then drops it and reports it through `onWriteBackFailed`. It does
+ * not undo the local edit, so without this the player keeps seeing blocks
+ * nobody else has and that are gone on the next load.
+ *
+ * The guard puts the chunk back to the server's copy and tells the player.
+ * Paint, the holodeck and CLIENT `voxel_set` all write through the one store,
+ * and `flush()` reports what it dropped through the same listener, so one guard
+ * per world session covers every path.
+ */
+import { CHUNK_VOLUME, type ChunkWriteBackFailure } from '@crowdedkingdoms/crowdyjs/stores';
+
+import type { ChunkCoord } from './space';
+
+/** One stroke across a refused plot drops several chunks; say it once. */
+const NOTIFY_QUIET_MS = 4_000;
+
+export type WriteBackTone = 'info' | 'warn' | 'error';
+
+/** The slice of `ChunkStore` the guard uses. */
+export interface GuardedChunkStore {
+  onWriteBackFailed(
+    listener: (failure: ChunkWriteBackFailure<unknown, unknown>) => void,
+  ): () => void;
+  get(coord: ChunkCoord): { voxelStates: Map<number, unknown> } | undefined;
+  hydrate(coord: ChunkCoord): Promise<void>;
+  seed(coord: ChunkCoord, voxels: Uint8Array, options?: { writeBack?: boolean }): void;
+}
+
+export interface WriteBackGuardOptions {
+  /** Whether the server stores the chunk (`client.chunks.get` is not null). */
+  onServer(coord: ChunkCoord): Promise<boolean>;
+  notify(text: string, tone: WriteBackTone): void;
+  log?(message: string): void;
+  now?(): number;
+}
+
+export const REFUSED_MESSAGE =
+  "You can't build here: this area is someone else's claim or a protected zone. Your change was undone.";
+export const EXHAUSTED_MESSAGE =
+  "Your change couldn't be saved (the server didn't answer), so it was undone. Try again in a moment.";
+
+/** The player-facing line for a dropped write-back. */
+export function describeWriteBackFailure(failure: Pick<ChunkWriteBackFailure, 'reason'>): {
+  text: string;
+  tone: WriteBackTone;
+} {
+  return failure.reason === 'refused'
+    ? { text: REFUSED_MESSAGE, tone: 'warn' }
+    : { text: EXHAUSTED_MESSAGE, tone: 'error' };
+}
+
+/**
+ * Put a chunk back to the server's copy: hydrate it when the server stores it,
+ * else back to the empty chunk The Construct seeds for a never-written one.
+ */
+export async function reloadChunk(
+  chunks: GuardedChunkStore,
+  coord: ChunkCoord,
+  onServer: (coord: ChunkCoord) => Promise<boolean>,
+): Promise<void> {
+  const stored = await onServer(coord);
+  chunks.get(coord)?.voxelStates.clear();
+  if (stored) await chunks.hydrate(coord);
+  else chunks.seed(coord, new Uint8Array(CHUNK_VOLUME), { writeBack: false });
+}
+
+/** Undo and report every write-back the store drops. @returns off. */
+export function guardWriteBacks(
+  chunks: GuardedChunkStore,
+  options: WriteBackGuardOptions,
+): () => void {
+  const now = options.now ?? (() => Date.now());
+  let lastText = '';
+  let lastAt = -Infinity;
+  return chunks.onWriteBackFailed((failure) => {
+    const { coord } = failure;
+    const where = `${coord.x},${coord.y},${coord.z}`;
+    options.log?.(
+      `chunk ${where} write-back ${failure.reason} after ${failure.attempts} attempt(s): ${errorText(failure.error)}`,
+    );
+    const { text, tone } = describeWriteBackFailure(failure);
+    const at = now();
+    if (text !== lastText || at - lastAt >= NOTIFY_QUIET_MS) options.notify(text, tone);
+    lastText = text;
+    lastAt = at;
+    void reloadChunk(chunks, coord, options.onServer).catch((error) =>
+      options.log?.(`chunk ${where} reload failed: ${errorText(error)}`),
+    );
+  });
+}
+
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}