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.

feat(project): the workspace state carries a session, and a gate keeps it one

esengine02a3f82976b2
diff --git a/desktop b/desktop
index 65e2b9a6f..1e0cd56cf 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 65e2b9a6f19721f484d0d72fc4d78a04ea8aab46
+Subproject commit 1e0cd56cfeff77326b1a0495f15824308f40c8e1
diff --git a/pipeline/src/project/format.ts b/pipeline/src/project/format.ts
index 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.mjs
new file mode 100644
index 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.mjs
index 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' },