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
feat(project): the workspace state carries a session, and a gate keeps it one
esengine02a3f82976b2
diff --git a/desktop b/desktopindex 65e2b9a6f..1e0cd56cf 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 65e2b9a6f19721f484d0d72fc4d78a04ea8aab46+Subproject commit 1e0cd56cfeff77326b1a0495f15824308f40c8e1diff --git a/pipeline/src/project/format.ts b/pipeline/src/project/format.tsindex d1052d3e3..404f3eb5c 100644--- a/pipeline/src/project/format.ts+++ b/pipeline/src/project/format.ts@@ -421,7 +421,34 @@ export function isTransientProjectPath(rel: string): boolean {/** Editor-local, transient state (`.esengine/workspace.json`; gitignored). */export interface WorkspaceState {lastOpenedScene?: string;+ /** The dock arrangement, as dockview serializes it. */panelLayout?: unknown;+ /** Editor mode the session was in (`scene` / `ui` / `tilemap` / `world` / …). */+ activeWorkspace?: string;+ /** Asset editors that were open, by document id and file. The dock layout says+ * a panel existed; only this says WHICH file it was showing. */+ openDocuments?: Array<{ kind: string; path: string }>;+ activeDocument?: { kind: string; path: string };+ /** The AUTHORED id of the selected entity. Never a runtime handle: those are+ * minted per session and index-reused, so a restored one names whatever+ * happens to occupy the slot. */+ selectedEntity?: number;+ /** Editor camera centre and the world half-height it saw. */+ viewportCamera?: { x: number; y: number; z: number; orthoSize: number };+ contentBrowserPath?: string;+ timelinePlayhead?: number;+ /**+ * The World workspace's own view state — where the author was looking, never+ * what the world was doing. Residency, prefetch counters and delivery latency+ * belong to a play session and are gone with it; a restored `Resident` would+ * be a stopped game's last frame presented as the state of the world.+ */+ world?: {+ /** Expanded rows, by AUTHORED identity (`persistent`, `cell:0,0`) — an index+ * into a list would expand a different row once the list is sorted again. */+ outlinerExpanded?: string[];+ selectedCell?: { x: number; z: number };+ };}/** An opened project as returned over IPC (plain, structured-clone-safe). */@@ -450,6 +477,9 @@ export interface RecentEntry {/** engineBuildId or version from the manifest, for the build badge. */build?: string;thumbnail?: string;+ /** The document this project was last open on, from its workspace state — so+ * a card can say what continuing it means before anyone clicks. */+ lastScene?: string;}const versionNum = (v: string): number => {diff --git a/tools/check-workspace-continuity.mjs b/tools/check-workspace-continuity.mjsnew file mode 100644index 000000000..61c31abd7--- /dev/null+++ b/tools/check-workspace-continuity.mjs@@ -0,0 +1,106 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file check-workspace-continuity.mjs — a session remembers where a person+ * was, never what a game was doing.+ *+ * Restoring a runtime fact is the failure that looks most like success: the+ * cells are plausible, the counters are real, and the editor is presenting a+ * stopped game's last frame as the state of the world. Nothing about the shape+ * of `WorkspaceState` prevents a field being added for one, so it is checked.+ *+ * node tools/check-workspace-continuity.mjs+ */+import { readFileSync, existsSync } from 'node:fs';+import path from 'node:path';+import { fileURLToPath } from 'node:url';++const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');+const read = (rel) => readFileSync(path.join(ROOT, rel), 'utf8');++const FORMAT = 'pipeline/src/project/format.ts';+const CAPTURE = 'desktop/src/project/workspaceContinuity.ts';+const SCAFFOLD = 'desktop/electron/projectScaffold.ts';++/**+ * Names that belong to a play session. A field or a capture reading one of them+ * is remembering something that ended when the game stopped.+ */+const RUNTIME_WORDS = [+ 'resident', 'prepared', 'prefetch', 'loading', 'unloading', 'demandToResident',+ 'residency', 'playing', 'isPlaying', 'frameCount', 'sessionId', 'entityHandle',+];++const problems = [];+const say = (file, what) => problems.push(`${file}: ${what}`);++// 1. The declared shape carries no runtime fact.+const format = read(FORMAT);+const shape = /export interface WorkspaceState \{([\s\S]*?)\n\}/.exec(format);+if (!shape) {+ say(FORMAT, 'WorkspaceState is not declared here any more — this gate guards nothing');+} else {+ for (const word of RUNTIME_WORDS) {+ // Field NAMES only — the comments there explain why these are absent, and+ // a gate reading prose would forbid saying so. The word may sit anywhere IN+ // the name: an exact match lets `residentCells` straight through.+ const field = new RegExp(`^\\s*\\w*${word}\\w*\\??:`, 'im');+ if (field.test(shape[1].replace(/\/\*[\s\S]*?\*\/|\/\/.*$/gm, ''))) {+ say(FORMAT, `WorkspaceState declares "${word}" — that is a play session's, not an author's`);+ }+ }+}++// 2. …and neither does what the editor puts in it. A field can be spelled+// innocently and still be filled from the runtime.+if (existsSync(path.join(ROOT, CAPTURE))) {+ const capture = read(CAPTURE);+ const body = /export function captureWorkspace\([\s\S]*?\n\}/.exec(capture);+ if (!body) {+ say(CAPTURE, 'captureWorkspace is gone — the session is being assembled somewhere unchecked');+ } else if (/WorldRuntimeStore|readWorldResidency|PlayRealm|worldResidencyReport/.test(body[0])) {+ say(CAPTURE, 'the capture reads the running world — a restored residency is a stopped game');+ }+ // The selection has to be an authored id. A runtime handle is minted per+ // session and its index is reused, so a restored one names whatever took the+ // slot — an entity the author never selected.+ if (/runtimeFor|EngineHost\.world/.test(capture)) {+ say(CAPTURE, 'the capture reaches for runtime entity handles — selection is an AUTHORED id');+ }+}++// 3. Nothing is written until the session has been put BACK: a capture before+// it writes a blank editor over what it was about to restore. Checked here+// because reaching that race depends on how slowly a project opens.+const STORE = 'desktop/src/project/ProjectStore.ts';+if (existsSync(path.join(ROOT, STORE))) {+ const store = read(STORE);+ for (const fn of ['saveWorkspaceSession', 'flushWorkspaceSession']) {+ // Anchored at the DECLARATION: an unanchored name also matches the call+ // site, and the body it then reads is whatever method does the calling.+ const body = new RegExp(+ `\\n (?:async )?${fn}\\([^)]*\\)[^{]*\\{([\\s\\S]*?)\\n \\}`).exec(store);+ if (!body) say(STORE, `${fn} is gone — the session is written from somewhere unchecked`);+ else if (!/workspaceRestored/.test(body[1])) {+ say(STORE, `${fn} writes without asking whether the session was restored yet`);+ }+ }+}++// 4. A project keeps its session out of source control. Without this the+// zero-diff claim holds only for whoever wrote their own .gitignore.+if (existsSync(path.join(ROOT, SCAFFOLD))) {+ const scaffold = read(SCAFFOLD);+ const ignore = /export const PROJECT_GITIGNORE = `([\s\S]*?)`;/.exec(scaffold);+ if (!ignore) say(SCAFFOLD, 'no PROJECT_GITIGNORE — a new project would commit its workspace');+ else if (!/^\.esengine\/$/m.test(ignore[1])) {+ say(SCAFFOLD, 'PROJECT_GITIGNORE no longer ignores .esengine/ — the session would be committed');+ }+}++if (problems.length > 0) {+ for (const problem of problems) console.error(` ${problem}`);+ console.error(`check-workspace-continuity: ${problems.length} finding(s).`);+ process.exit(1);+}+console.log('check-workspace-continuity: the session remembers an author, not a play session.');diff --git a/tools/gates.mjs b/tools/gates.mjsindex 761164628..2287197b9 100644--- a/tools/gates.mjs+++ b/tools/gates.mjs@@ -79,6 +79,7 @@ export const GATES = [// is experimental, said the same way in every place someone reads it.{ id: 'plugin-api-contract', run: 'node tools/check-plugin-api-contract.mjs' },{ id: 'residency-authority', run: 'node tools/check-residency-authority.mjs' },+ { id: 'workspace-continuity', run: 'node tools/check-workspace-continuity.mjs' },// Everything below reads what this emits: the declaration snapshot, the// editor's own type-check and the examples all resolve `esengine` from dist.{ id: 'sdk-build', run: 'pnpm --filter ./sdk build' },