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.

refactor(editor): collapse the World write boundary (RC12 E2 keystone)

esenginedf609f3b7040
diff --git a/desktop/src/engine/EngineHost.ts b/desktop/src/engine/EngineHost.ts
index 02036d3e2..c57d9ebba 100644
--- a/desktop/src/engine/EngineHost.ts
+++ b/desktop/src/engine/EngineHost.ts
@@ -11,10 +11,11 @@ import {
serializeScene,
resetWorldTo,
} from 'esengine';
-import type { App, ESEngineModule, SceneData } from 'esengine';
+import type { App, ESEngineModule, SceneData, ResourceDef } from 'esengine';
import { SceneStore } from './SceneStore';
import { SceneLoader } from './SceneLoader';
import { checkEngineBuild } from './EngineGuard';
+import type { ReadonlyWorldT, WorldT } from './schema';
// Scene the editor opens on boot (placeholder until a project/open-scene flow exists).
const DEFAULT_SCENE_URL = '/scenes/sprite-rendering.esscene';
@@ -58,9 +59,26 @@ class EngineHostImpl {
this.sceneBootstrap = fn;
}
- // Live handles read by the layered modules.
- get app(): App | null {
- return this.app_;
+ // — World access behind two doors (RC12 §E2) —
+ // The App is private: no module can reach `app.world` and write straight to
+ // the World, bypassing the command/undo layer. Reads get a read-only view;
+ // the single mutable door (mutableWorld) is used only by SceneCommands
+ // (undoable edits) and bulk scene load (ProjectStore / SceneLoader).
+
+ /** Read-only view of the live World — for reflection, picking, stats. */
+ get world(): ReadonlyWorldT | null {
+ return this.app_?.world ?? null;
+ }
+ /**
+ * The mutable World — the editor's single write door. Only SceneCommands and
+ * bulk scene load/reset should call this; everything else reads via `world`.
+ */
+ mutableWorld(): WorldT | null {
+ return this.app_?.world ?? null;
+ }
+ /** Read an app-scoped resource (e.g. Assets, CameraView). */
+ getResource<T>(resource: ResourceDef<T>): T | undefined {
+ return this.app_?.getResource(resource);
}
get module(): ESEngineModule | null {
return this.module_;
diff --git a/desktop/src/engine/SceneCommands.ts b/desktop/src/engine/SceneCommands.ts
index a62e18738..5ec38f6d4 100644
--- a/desktop/src/engine/SceneCommands.ts
+++ b/desktop/src/engine/SceneCommands.ts
@@ -83,7 +83,7 @@ function applyFieldWrite(
type: InspectorFieldType,
value: InspectorFieldValue,
): void {
- const world = EngineHost.app?.world;
+ const world = EngineHost.mutableWorld();
if (!world || !world.valid(entity)) return;
const def = componentByName(compName);
if (!def) return;
@@ -165,7 +165,7 @@ export const SceneCommands = {
type: InspectorFieldType,
value: InspectorFieldValue,
): void {
- const world = EngineHost.app?.world;
+ const world = EngineHost.mutableWorld();
if (!world || !world.valid(entity) || !componentByName(compName)) return;
const k = editKey(entity, compName, key);
@@ -193,7 +193,7 @@ export const SceneCommands = {
/** Move an entity to a world position (keeps Z). Undoable like any field edit. */
setEntityXY(id: EntityId, x: number, y: number): void {
- const world = EngineHost.app?.world;
+ const world = EngineHost.mutableWorld();
if (!world || !world.valid(id) || !world.has(id, Transform)) return;
const z = world.get(id, Transform).position.z;
this.setField(id, 'Transform', 'position', 'vec3', [x, y, z]);
@@ -204,7 +204,7 @@ export const SceneCommands = {
/** Spawn a new empty entity (with a Transform). Returns its id. */
addEntity(): EntityId | null {
- const world = EngineHost.app?.world;
+ const world = EngineHost.mutableWorld();
if (!world) return null;
const e = world.spawn('Entity');
world.insert(e, Transform, DEFAULT_TRANSFORM);
@@ -222,7 +222,7 @@ export const SceneCommands = {
/** Delete an entity (undo re-creates it under the same stable handle). */
deleteEntity(id: EntityId): void {
- const world = EngineHost.app?.world;
+ const world = EngineHost.mutableWorld();
if (!world || !world.valid(id)) return;
const cap = captureEntity(world, id);
if (!cap) return;
@@ -238,7 +238,7 @@ export const SceneCommands = {
/** Duplicate an entity (offset slightly). Returns the new id. */
duplicateEntity(id: EntityId): EntityId | null {
- const world = EngineHost.app?.world;
+ const world = EngineHost.mutableWorld();
if (!world || !world.valid(id)) return null;
const cap = captureEntity(world, id);
if (!cap) return null;
@@ -260,7 +260,7 @@ export const SceneCommands = {
/** Rename an entity via its Name component (undoable). */
renameEntity(id: EntityId, name: string): void {
- const world = EngineHost.app?.world;
+ const world = EngineHost.mutableWorld();
if (!world || !world.valid(id)) return;
const before = world.has(id, Name) ? world.get(id, Name).value : '';
if (before === name) return;
diff --git a/desktop/src/engine/SceneQuery.ts b/desktop/src/engine/SceneQuery.ts
index 6365a8456..0e0573493 100644
--- a/desktop/src/engine/SceneQuery.ts
+++ b/desktop/src/engine/SceneQuery.ts
@@ -14,12 +14,12 @@ import {
export const SceneQuery = {
/** Monotonic counter; bump means the entity set / structure changed. */
worldVersion(): number {
- return EngineHost.app?.world.getWorldVersion() ?? -1;
+ return EngineHost.world?.getWorldVersion() ?? -1;
},
/** Build the outliner tree from the live World, nesting via the Parent component. */
readSceneTree(): SceneNode[] {
- const world = EngineHost.app?.world;
+ const world = EngineHost.world;
if (!world) return [];
const ids = world.getAllEntities();
@@ -60,7 +60,7 @@ export const SceneQuery = {
/** Inspect a single live entity (name, kind, which components it carries). */
readEntity(id: EntityId): { name: string; kind: NodeKind; components: string[] } | null {
- const world = EngineHost.app?.world;
+ const world = EngineHost.world;
if (!world || !world.valid(id)) return null;
const kind = kindOf(world, id);
const components = inspectableComponents(world, id).map((c) => c.label);
@@ -69,7 +69,7 @@ export const SceneQuery = {
/** Full editable inspector model for an entity — components from the engine registry. */
readInspector(entity: EntityId): InspectorComponent[] {
- const world = EngineHost.app?.world;
+ const world = EngineHost.world;
if (!world || !world.valid(entity)) return [];
const out: InspectorComponent[] = [];
@@ -82,7 +82,7 @@ export const SceneQuery = {
/** Read one inspector field's current value (for undo before/after capture). */
getFieldValue(entity: EntityId, compName: string, key: string): InspectorFieldValue | null {
- const world = EngineHost.app?.world;
+ const world = EngineHost.world;
if (!world || !world.valid(entity)) return null;
const def = componentByName(compName);
if (!def || !world.has(entity, def)) return null;
diff --git a/desktop/src/engine/StatsStore.ts b/desktop/src/engine/StatsStore.ts
index 1030a0966..7217714bc 100644
--- a/desktop/src/engine/StatsStore.ts
+++ b/desktop/src/engine/StatsStore.ts
@@ -29,7 +29,7 @@ class StatsStoreImpl {
const elapsed = t - this.windowStart;
if (elapsed >= 333) {
const fps = Math.round((this.frames * 1000) / elapsed);
- const entities = EngineHost.app?.world.getAllEntities().length ?? 0;
+ const entities = EngineHost.world?.getAllEntities().length ?? 0;
this.frames = 0;
this.windowStart = t;
if (fps !== this.snapshot.fps || entities !== this.snapshot.entities) {
diff --git a/desktop/src/engine/ViewportController.ts b/desktop/src/engine/ViewportController.ts
index 45d1f7b46..5420b8804 100644
--- a/desktop/src/engine/ViewportController.ts
+++ b/desktop/src/engine/ViewportController.ts
@@ -9,7 +9,7 @@ interface CameraViewLike {
}
function cameraView(): CameraViewLike | null {
- const cv = EngineHost.app?.getResource(CameraView) as unknown as CameraViewLike | undefined;
+ const cv = EngineHost.getResource(CameraView) as unknown as CameraViewLike | undefined;
return cv ?? null;
}
@@ -49,7 +49,7 @@ export const ViewportController = {
/** Topmost sprite under a pointer (AABB test in world space), or null. */
pickEntity(clientX: number, clientY: number): EntityId | null {
- const world = EngineHost.app?.world;
+ const world = EngineHost.world;
const wp = this.canvasToWorld(clientX, clientY);
if (!world || !wp) return null;
@@ -78,7 +78,7 @@ export const ViewportController = {
},
getEntityXY(id: EntityId): { x: number; y: number } | null {
- const world = EngineHost.app?.world;
+ const world = EngineHost.world;
if (!world || !world.valid(id) || !world.has(id, Transform)) return null;
const t = world.get(id, Transform);
return { x: t.position.x, y: t.position.y };
@@ -86,7 +86,7 @@ export const ViewportController = {
/** Screen-space bounding rect (CSS px rel. canvas) of an entity, for the selection outline. */
getEntityScreenRect(id: EntityId): { x: number; y: number; w: number; h: number } | null {
- const world = EngineHost.app?.world;
+ const world = EngineHost.world;
if (!world || !world.valid(id) || !world.has(id, Transform)) return null;
const t = world.get(id, Transform);
diff --git a/desktop/src/engine/schema.ts b/desktop/src/engine/schema.ts
index 3c8d086eb..805f7ab0e 100644
--- a/desktop/src/engine/schema.ts
+++ b/desktop/src/engine/schema.ts
@@ -26,6 +26,17 @@ import type { NodeKind, EntityId, InspectorField } from '@/types';
// Camera packs a vec4 `viewport` where the JS data exposes viewportX/Y/W/H).
export type WorldT = App['world'];
+/**
+ * Read-only projection of the engine World: the query surface, with no mutators.
+ * EngineHost hands this out by default so reflection / picking / stats can read
+ * the live world but cannot write it — a write must go through the one mutable
+ * door (EngineHost.mutableWorld, used only by SceneCommands and bulk scene load).
+ * Adding a method here is the deliberate way to widen the read surface.
+ */
+export type ReadonlyWorldT = Pick<
+ WorldT,
+ 'valid' | 'has' | 'get' | 'getAllEntities' | 'getWorldVersion'
+>;
export type AnyComp = Parameters<WorldT['has']>[1];
// — Presentation policy (editor-side, not engine schema) —
@@ -46,7 +57,7 @@ export function componentByName(name: string): AnyComp | undefined {
/** Every editable component the entity currently carries, in display order. */
export function inspectableComponents(
- world: WorldT,
+ world: ReadonlyWorldT,
entity: EntityId,
): Array<{ name: string; def: AnyComp; label: string }> {
const out: Array<{ name: string; def: AnyComp; label: string }> = [];
@@ -130,7 +141,7 @@ export function inferField(key: string, v: unknown, isColor: boolean): Inspector
// — Outliner kind/name (presentation; uses specific defs for icon mapping) —
-export function kindOf(world: WorldT, e: EntityId): NodeKind {
+export function kindOf(world: ReadonlyWorldT, e: EntityId): NodeKind {
if (world.has(e, Camera)) return 'camera';
if (world.has(e, SpineAnimation)) return 'spine';
if (world.has(e, Canvas) || world.has(e, BitmapText)) return 'ui';
@@ -141,7 +152,7 @@ export function kindOf(world: WorldT, e: EntityId): NodeKind {
return 'empty';
}
-export function nameOf(world: WorldT, e: EntityId, kind: NodeKind): string {
+export function nameOf(world: ReadonlyWorldT, e: EntityId, kind: NodeKind): string {
if (world.has(e, Name)) {
const v = world.get(e, Name).value;
if (v) return v;
diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.ts
index b9aeb9394..2274ab9f2 100644
--- a/desktop/src/project/ProjectStore.ts
+++ b/desktop/src/project/ProjectStore.ts
@@ -135,7 +135,7 @@ class ProjectStoreImpl {
this.adopt(opened);
await window.estella.recents.add(opened.root, opened.manifest.name);
EngineHost.setSceneBootstrap(() => this.loadCurrentScene());
- if (EngineHost.app?.world) await this.loadCurrentScene();
+ if (EngineHost.world) await this.loadCurrentScene();
}
private adopt(opened: OpenedProject) {
@@ -172,7 +172,7 @@ class ProjectStoreImpl {
);
}
const data = await this.resolveTextures(raw);
- const world = EngineHost.app?.world;
+ const world = EngineHost.mutableWorld();
if (world) resetWorldTo(world, data);
this.state = { ...st, currentScene: rel, lossy: dropped.length > 0 };
this.emit();
@@ -214,7 +214,7 @@ class ProjectStoreImpl {
// no textures dir — every ref blanks to 0
}
- const assets = EngineHost.app?.getResource(Assets) as unknown as AssetsLike | undefined;
+ const assets = EngineHost.getResource(Assets) as unknown as AssetsLike | undefined;
const uuidToHandle = new Map<string, number>();
if (assets) {
for (const [uuid, rel] of uuidToPath) {
@@ -232,7 +232,7 @@ class ProjectStoreImpl {
/** Serialize the live world; map texture handles back to `@uuid:` (portable). */
private serializeCurrent(): SceneData {
- const world = EngineHost.app?.world;
+ const world = EngineHost.mutableWorld();
if (!world) throw new Error('engine not ready');
return this.restoreAssetRefs(serializeScene(world, this.state?.name ?? 'scene'));
}