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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crowdedkingdoms/construct",
-  "version": "0.3.5-dev.1",
+  "version": "0.3.7-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.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"
+    "@crowdedkingdoms/crowdyjs": ">=18.0.4-dev.0 <19 || >=18.1.0-dev.0 <19 || >=18.2.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 || >=0.4.5-dev.0 <1"
   },
   "peerDependenciesMeta": {
     "@crowdedkingdoms/crowdy-dsh": {

package/src/platform/realtime/WorldStores.ts

@@ -9,7 +9,8 @@
  *               would get their own lane.
  *  - `chunks` — the voxel cache Paint draws in 2D and the holodeck draws as
  *               cubes. CLIENT `voxel_set` writes here so other players see
- *               the same blocks.
+ *               the same blocks. Every loaded chunk is hydrated, so blocks a
+ *               SERVER mod placed come back after a reload.
  *  - `errors` — server-reported send failures attributed to what we sent.
  *  - `events` — SERVER `emit_spatial("server_event")` catalog/pose packets
  *               for the replicated instance layer (construct.scene.v1).
@@ -32,6 +33,7 @@ import { ACTOR_SYNC_INTERVAL_MS, REPLICATION_DISTANCE, STALE_ACTOR_TIMEOUT_MS }
 import { envScopedKey } from '../envScope';
 import { NetworkManager } from '../network/NetworkManager';
 import { NEUTRAL_POSE, poseCodec, type Pose } from './actorCodec';
+import { chunkStoreConfig } from './chunkStoreConfig';
 import { InstanceStore } from '../studio/instanceStore';
 
 /** What survives between sessions. Deliberately small; add fields freely. */
@@ -62,13 +64,7 @@ function buildConfig() {
         players: () => true,
       },
     },
-    chunks: {
-      distance: REPLICATION_DISTANCE,
-      // The Construct has no terrain to generate: a chunk the server has never
-      // stored is simply empty. Seed it locally (no write-back) so the paint
-      // program and CLIENT mods always see a dense grid.
-      onMissing: () => ({ voxels: new Uint8Array(4096), writeBack: false }),
-    },
+    chunks: chunkStoreConfig(),
     errors: true as const,
     events: true as const,
     host: {

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

@@ -0,0 +1,101 @@
+import { describe, expect, it, vi } from 'vitest';
+import { ChunkStore, type ChunkStoreConfig } from '@crowdedkingdoms/crowdyjs/stores';
+
+import { chunkStoreConfig } from './chunkStoreConfig';
+
+const STORED = { x: 3, y: 0, z: 3 };
+const NEVER_STORED = { x: 4, y: 0, z: 3 };
+const at = (x: number, y: number, z: number) => x + y * 16 + z * 256;
+
+/**
+ * What ck-api v2.33.0's `getChunk` returns for a chunk whose dense grid holds one block (5) and
+ * whose edit log holds the pool cue mod's felt and white ball (`world.set_voxels`, no state), a
+ * painted cell (one byte of state), and that block mined (type 0).
+ */
+const RECORDED_EDITS = [
+  { voxelCoord: { x: 6, y: 1, z: 7 }, voxelType: 1, state: null },
+  { voxelCoord: { x: 7, y: 2, z: 8 }, voxelType: 3, state: null },
+  { voxelCoord: { x: 8, y: 0, z: 8 }, voxelType: 4, state: 'AA==' },
+  { voxelCoord: { x: 2, y: 0, z: 2 }, voxelType: 0, state: null },
+];
+
+function base64(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString('base64');
+}
+
+/** The real SDK store over a fake game API that stores only `STORED`. */
+function storeWith(config: ChunkStoreConfig) {
+  const grid = new Uint8Array(4096);
+  grid[at(2, 0, 2)] = 5;
+  const coordinates = { x: String(STORED.x), y: String(STORED.y), z: String(STORED.z) };
+  const client = {
+    chunks: {
+      byDistance: vi.fn(async () => ({
+        chunks: [{ coordinates, voxels: base64(grid), chunkState: null }],
+      })),
+      get: vi.fn(async () => ({
+        voxels: base64(grid),
+        chunkState: null,
+        voxelStates: RECORDED_EDITS,
+      })),
+      update: vi.fn(async () => ({})),
+    },
+    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, { ...config, writeBackIntervalMs: false });
+  return { store, client };
+}
+
+describe('chunkStoreConfig', () => {
+  it("brings back a SERVER mod's blocks, a painted cell and a mined block after a reload", async () => {
+    const { store, client } = storeWith(chunkStoreConfig());
+    await store.ensureAround(STORED, 1);
+
+    expect(client.chunks.get).toHaveBeenCalledTimes(1);
+    expect(client.chunks.get).toHaveBeenCalledWith({
+      appId: '1',
+      coordinates: { x: '3', y: '0', z: '3' },
+    });
+    expect(store.get(STORED)?.hydrated).toBe(true);
+    expect(store.voxelTypeAt(STORED, 6, 1, 7)).toBe(1);
+    expect(store.voxelTypeAt(STORED, 7, 2, 8)).toBe(3);
+    expect(store.voxelTypeAt(STORED, 8, 0, 8)).toBe(4);
+    expect(store.voxelStateAt(STORED, 8, 0, 8)).toBe('AA==');
+    expect(store.voxelTypeAt(STORED, 2, 0, 2)).toBe(0);
+
+    // Moving on loads the next cube, which returns this chunk again (CrowdyJS 18.2.0 keeps it).
+    await store.ensureAround({ x: 3, y: 0, z: 4 }, 1);
+    expect(client.chunks.byDistance).toHaveBeenCalledTimes(2);
+    expect(store.voxelTypeAt(STORED, 6, 1, 7)).toBe(1);
+    expect(store.voxelTypeAt(STORED, 2, 0, 2)).toBe(0);
+    expect(client.chunks.get).toHaveBeenCalledTimes(1);
+  });
+
+  it('shows only the stored grid when the store does not hydrate (the construct before 0.3.6)', async () => {
+    const { store, client } = storeWith({ ...chunkStoreConfig(), hydrateVoxelStates: false });
+    await store.ensureAround(STORED, 1);
+
+    expect(client.chunks.get).not.toHaveBeenCalled();
+    expect(store.voxelTypeAt(STORED, 6, 1, 7)).toBe(0);
+    expect(store.voxelTypeAt(STORED, 2, 0, 2)).toBe(5);
+  });
+
+  it('seeds a chunk the server never stored, empty and without a write-back', async () => {
+    const { store } = storeWith(chunkStoreConfig());
+    await store.ensureAround(STORED, 1);
+
+    const seeded = store.get(NEVER_STORED);
+    expect(seeded?.loadState).toBe('seeded');
+    expect(seeded?.voxels).toEqual(new Uint8Array(4096));
+    expect(store.pendingWriteBacks).toBe(0);
+  });
+});

package/src/platform/realtime/chunkStoreConfig.ts

@@ -0,0 +1,20 @@
+/**
+ * The World Stores chunk cache's settings, shared by the session and its test.
+ */
+import { REPLICATION_DISTANCE } from '../config';
+
+export function chunkStoreConfig() {
+  return {
+    distance: REPLICATION_DISTANCE,
+    // A SERVER mod's or hub's `world.set_voxels`, `updateVoxel` and realtime
+    // voxel updates reach a reload only as `getChunk` `voxelStates` entries
+    // (ck-api v2.33.0): the bulk load's dense `voxels` hold none of them. The
+    // store hydrates every loaded chunk only when asked, or when it has a voxel
+    // state codec, which The Construct does not.
+    hydrateVoxelStates: true,
+    // The Construct has no terrain to generate: a chunk the server has never
+    // stored is simply empty. Seed it locally (no write-back) so the paint
+    // program and CLIENT mods always see a dense grid.
+    onMissing: () => ({ voxels: new Uint8Array(4096), writeBack: false }),
+  };
+}