Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

test(world): the cut takes a document, and a handed scene is not fetched again

esenginec7f0b0f0c51a
diff --git a/desktop b/desktop
index 9b2033f84..d509e08e9 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 9b2033f841830ced931473bf765e35d1301f9c32
+Subproject commit d509e08e9be9add3a5234972685f925dc1c140ca
diff --git a/pipeline/tests/world-partition-purity.test.ts b/pipeline/tests/world-partition-purity.test.ts
new file mode 100644
index 000000000..a9cb41be1
--- /dev/null
+++ b/pipeline/tests/world-partition-purity.test.ts
@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file partitionWorld takes a document, not a file, and gives back documents
+ * that are not the one it took.
+ *
+ * cookWorlds is the filesystem around it — read the staged scene, write the
+ * cells, overwrite the persistent one. What the cut itself needs is the
+ * document, the entity-ref fields and where a prefab's root sits. Anything that
+ * wanted to partition something never written to disk depends on that staying
+ * true, and on the input surviving the call unchanged.
+ */
+import { describe, it, expect } from 'vitest';
+import { partitionWorld } from '../src/world/partitionWorld';
+import { engineEntityFields } from '../src/world/componentRefs';
+import type { SceneData } from 'esengine';
+
+const CELL = 100;
+
+/** A world authored in memory — never written, never read back. */
+function world(sentinelX: number): SceneData {
+ return {
+ version: '1.0', name: 'purity',
+ entities: [
+ { id: 1, name: 'World', parent: null, children: [],
+ components: [{ type: 'StreamedWorld', data: { cellSize: CELL } }] },
+ { id: 2, name: 'Anchor', parent: null, children: [],
+ components: [{ type: 'Transform', data: { position: { x: 50, y: 0, z: 50 } } }] },
+ { id: 3, name: 'Sentinel', parent: null, children: [],
+ components: [{ type: 'Transform', data: { position: { x: sentinelX, y: 0, z: 50 } } }] },
+ ],
+ } as unknown as SceneData;
+}
+
+const opts = { entityFieldsOf: engineEntityFields };
+const cellOf = (p: ReturnType<typeof partitionWorld>, name: string): string | null =>
+ p!.cells.find((c) =>
+ (c.data.entities as unknown as Array<{ name?: string }>).some((e) => e.name === name))?.name ?? null;
+
+describe('partitionWorld over a document that was never staged', () => {
+ it('places an entity by the position the document holds', () => {
+ const near = partitionWorld(world(50), 'purity', opts);
+ const far = partitionWorld(world(250), 'purity', opts);
+ expect(near!.errors).toEqual([]);
+ expect(far!.errors).toEqual([]);
+ expect(cellOf(near, 'Sentinel')).toBe(cellOf(near, 'Anchor'));
+ expect(cellOf(far, 'Sentinel')).not.toBe(cellOf(far, 'Anchor'));
+ });
+
+ it('leaves the document it was given byte-identical', () => {
+ const doc = world(250);
+ const snapshot = JSON.stringify(doc);
+ expect(partitionWorld(doc, 'purity', opts)!.errors).toEqual([]);
+ expect(JSON.stringify(doc)).toBe(snapshot);
+ });
+
+ it('gives back cell entities that do not alias the input', () => {
+ // A cell that shared entity objects with its source would let a runtime
+ // mutation reach back into whatever authored the world.
+ const doc = world(250);
+ const authored = doc.entities as unknown as unknown[];
+ for (const cell of partitionWorld(doc, 'purity', opts)!.cells) {
+ for (const e of cell.data.entities as unknown as unknown[]) {
+ expect(authored.includes(e)).toBe(false);
+ }
+ }
+ });
+});
diff --git a/sdk/tests/cell-document-delivery.test.ts b/sdk/tests/cell-document-delivery.test.ts
new file mode 100644
index 000000000..4ee5fc9c9
--- /dev/null
+++ b/sdk/tests/cell-document-delivery.test.ts
@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file A scene the loader was handed is not fetched again.
+ *
+ * `createRuntimeSceneConfig` takes a document OR a path, and the streamed cells
+ * a package boots are registered with the path. That the document wins is what
+ * lets a cell be delivered from somewhere other than a file — so it is pinned
+ * from both sides, or the branch could be removed and only a build would notice.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { createRuntimeSceneConfig } from '../src/runtime/runtimeLoader';
+import type { SceneData } from '../src/scene/scene';
+
+const FETCHED = 'the loader reached for the path';
+
+const doc = { version: '1.0', name: 'cell_0_0', entities: [] } as unknown as SceneData;
+
+/** An app whose only observable behaviour is whether a fetch was attempted. */
+function appThatRefusesToFetch() {
+ const fetchJson = vi.fn(() => { throw new Error(FETCHED); });
+ return { fetchJson, app: { getResource: () => ({ fetchJson }) } as never };
+}
+
+const opts = (app: unknown) => ({ app, module: null, source: {} } as never);
+
+describe('a registered scene with a document', () => {
+ it('never asks the backend for its path', async () => {
+ const { app, fetchJson } = appThatRefusesToFetch();
+ const config = createRuntimeSceneConfig('cell_0_0', doc, opts(app), 'world/cell_0_0.json');
+ // prepare goes on to need a real app; which step it fails at is the point.
+ await config.prepare!().catch((e: Error) => expect(e.message).not.toContain(FETCHED));
+ expect(fetchJson).not.toHaveBeenCalled();
+ });
+
+ it('does ask when it was given only a path, so the case above is a choice', async () => {
+ const { app, fetchJson } = appThatRefusesToFetch();
+ const config = createRuntimeSceneConfig('cell_0_0', undefined, opts(app), 'world/cell_0_0.json');
+ await expect(config.prepare!()).rejects.toThrow(FETCHED);
+ expect(fetchJson).toHaveBeenCalledWith('world/cell_0_0.json');
+ });
+
+ it('says so when it was given neither, rather than bringing up an empty scene', async () => {
+ const { app } = appThatRefusesToFetch();
+ await expect(createRuntimeSceneConfig('cell_0_0', undefined, opts(app)).prepare!())
+ .rejects.toThrow(/neither data nor path/);
+ });
+});