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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
refactor(editor): collapse the World write boundary (RC12 E2 keystone)
esenginedf609f3b7040
diff --git a/desktop/src/engine/EngineHost.ts b/desktop/src/engine/EngineHost.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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'));}