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(editor): project component-schema extractor → schemas.json (editor-realm P2)

esengine63df696d5756
diff --git a/desktop/electron/extractSchemas.ts b/desktop/electron/extractSchemas.ts
new file mode 100644
index 000000000..a2058c310
--- /dev/null
+++ b/desktop/electron/extractSchemas.ts
@@ -0,0 +1,184 @@
+/**
+ * @file Project component-schema extractor (REARCH_EDITOR_REALM.md Phase P2).
+ *
+ * Builds `.esengine/cache/schemas.json` — the field schema of a project's own
+ * components — so the editor's MAIN realm can give unknown/project components a
+ * real inspector WITHOUT executing any project code (schema-as-artifact).
+ *
+ * How: esbuild-bundle the project's DECLARATION entry (`src/components.ts`) with
+ * the SDK (`esengine`) inlined, run it in a FRESH `AppContext`, read
+ * `getUserComponents()`, and serialize each component's `{name,isTag,default,
+ * colorKeys,assetFields,spineFields,entityFields}`.
+ *
+ * Zero wasm: `defineComponent`/`AppContext`/`createComponentDef` are pure JS and
+ * systems are only queued (never run). The fresh context isolates the project's
+ * components from the SDK's own `defineComponent` ones (Name/SceneOwner/…), so
+ * those — and the C++ builtins — never leak into schemas.json.
+ *
+ * Pure Node (esbuild + fs/path/url), no Electron imports → unit-testable and
+ * reusable; the IPC wiring lives in main.ts.
+ */
+import { build, type Plugin } from 'esbuild';
+import { existsSync, mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const DEFAULT_SRC_DIR = 'src';
+/** The pure declaration module (only defineComponent/defineTag, no app startup). */
+const DEFAULT_DECL_ENTRY = 'components.ts';
+/** Local, gitignored cache inside the project (next to workspace.json). */
+const CACHE_DIR = '.esengine/cache';
+const OUTPUT = 'schemas.json';
+
+/**
+ * Anchor for resolving the bare `esengine` specifier. This file lives inside the
+ * desktop package (which depends on `esengine`), so esbuild walks up from here to
+ * `desktop/node_modules/esengine` no matter where the project itself lives — a
+ * project under /tmp has no esengine in its own node_modules (cf. build-scripts).
+ */
+const ANCHOR_DIR = path.dirname(fileURLToPath(import.meta.url));
+
+/** The serialized field schema of one project component. */
+export interface ComponentSchema {
+ name: string;
+ /** True for `defineTag` components (no data fields). */
+ isTag: boolean;
+ /** Default field values — the inspector infers controls from these. */
+ default: Record<string, unknown>;
+ /** Field keys whose value is an {r,g,b,a} color (render as a color picker). */
+ colorKeys: string[];
+ /** Asset-reference field metadata (e.g. textures). */
+ assetFields: unknown[];
+ /** Spine field metadata, when present. */
+ spineFields?: unknown;
+ /** Field keys that hold an Entity handle. */
+ entityFields: string[];
+}
+
+export interface ExtractSchemasResult {
+ ok: boolean;
+ /** Absolute path to the written schemas.json, or null on failure. */
+ outputPath: string | null;
+ /** The extracted schemas (also written to outputPath). */
+ schemas: ComponentSchema[];
+ errors: string[];
+ warnings: string[];
+}
+
+/**
+ * Force every `esengine` (and `esengine/*`) import — from the generated entry
+ * AND from the project's own modules — to resolve from {@link ANCHOR_DIR} and be
+ * inlined, instead of from the importer's location (which, for a /tmp project,
+ * has no esengine). Anchoring all of them at one path also guarantees a SINGLE
+ * SDK instance, so the registry the entry reads is the one the project wrote.
+ */
+function esengineAnchor(): Plugin {
+ return {
+ name: 'esengine-anchor',
+ setup(b) {
+ b.onResolve({ filter: /^esengine($|\/)/ }, async (args) => {
+ if (args.pluginData === 'anchored') return undefined; // fall through to default resolver
+ const r = await b.resolve(args.path, {
+ kind: 'import-statement',
+ resolveDir: ANCHOR_DIR,
+ pluginData: 'anchored',
+ });
+ if (r.errors.length) return { errors: r.errors };
+ return { path: r.path, external: r.external };
+ });
+ },
+ };
+}
+
+/**
+ * Extract `<root>/<srcDir>/<entry>` → `<root>/.esengine/cache/schemas.json`.
+ * Never throws — failures come back as `{ ok:false, errors }`.
+ */
+export async function extractProjectSchemas(
+ root: string,
+ opts?: { srcDir?: string; entry?: string },
+): Promise<ExtractSchemasResult> {
+ const declPath = path.join(root, opts?.srcDir ?? DEFAULT_SRC_DIR, opts?.entry ?? DEFAULT_DECL_ENTRY);
+ if (!existsSync(declPath)) {
+ return { ok: false, outputPath: null, schemas: [], errors: [`declaration entry not found: ${declPath}`], warnings: [] };
+ }
+
+ // Generated entry: install a fresh context FIRST (top-level, so it runs before
+ // any project code), then defer the declaration's `defineComponent` side
+ // effects to a dynamic import inside __extract() and hand back the registry.
+ const entry =
+ `import { AppContext, setDefaultContext, getUserComponents } from 'esengine';\n` +
+ `setDefaultContext(new AppContext());\n` +
+ `export async function __extract() {\n` +
+ ` await import(${JSON.stringify(declPath)});\n` +
+ ` return getUserComponents();\n` +
+ `}\n`;
+
+ const tmp = mkdtempSync(path.join(tmpdir(), 'estella-schema-'));
+ const bundlePath = path.join(tmp, 'extract.mjs');
+ const warnings: string[] = [];
+ try {
+ const result = await build({
+ stdin: { contents: entry, resolveDir: ANCHOR_DIR, loader: 'ts', sourcefile: 'extract-entry.ts' },
+ bundle: true,
+ format: 'esm',
+ platform: 'node',
+ target: 'node18',
+ outfile: bundlePath,
+ write: true,
+ sourcemap: false,
+ logLevel: 'silent',
+ plugins: [esengineAnchor()],
+ });
+ warnings.push(...result.warnings.map((w) => w.text));
+
+ const mod: { __extract(): Promise<Map<string, unknown>> } = await import(pathToFileURL(bundlePath).href);
+ const registry = await mod.__extract();
+ const schemas = [...registry.values()]
+ .map(toSchema)
+ .sort((a, b) => a.name.localeCompare(b.name)); // deterministic output
+
+ const outputPath = path.join(root, CACHE_DIR, OUTPUT);
+ mkdirSync(path.dirname(outputPath), { recursive: true });
+ writeFileSync(outputPath, JSON.stringify(schemas, null, 2) + '\n');
+
+ return { ok: true, outputPath, schemas, errors: [], warnings };
+ } catch (err) {
+ const e = err as { errors?: { text: string }[]; warnings?: { text: string }[]; message?: string };
+ return {
+ ok: false,
+ outputPath: null,
+ schemas: [],
+ errors: e.errors?.map((x) => x.text) ?? [String(e.message ?? err)],
+ warnings: e.warnings?.map((x) => x.text) ?? warnings,
+ };
+ } finally {
+ rmSync(tmp, { recursive: true, force: true });
+ }
+}
+
+/** A user ComponentDef carries the field metadata; see sdk component.ts. */
+interface UserComponentDef {
+ _name: string;
+ _default?: Record<string, unknown>;
+ colorKeys?: readonly string[];
+ assetFields?: readonly unknown[];
+ spineFields?: unknown;
+ entityFields?: readonly string[];
+}
+
+function toSchema(def: unknown): ComponentSchema {
+ const d = def as UserComponentDef;
+ const defaults = d._default ?? {};
+ const schema: ComponentSchema = {
+ name: d._name,
+ isTag: Object.keys(defaults).length === 0,
+ default: defaults,
+ colorKeys: [...(d.colorKeys ?? [])],
+ assetFields: [...(d.assetFields ?? [])],
+ entityFields: [...(d.entityFields ?? [])],
+ };
+ if (d.spineFields) schema.spineFields = d.spineFields;
+ return schema;
+}
diff --git a/desktop/electron/main.ts b/desktop/electron/main.ts
index e9bbfa9e1..daebdc595 100644
--- a/desktop/electron/main.ts
+++ b/desktop/electron/main.ts
@@ -12,6 +12,7 @@ import {
} from './projectFs';
import { listRecents, addRecent, listTemplates, createFromTemplate } from './launcher';
import { buildProjectScripts } from './buildScripts';
+import { extractProjectSchemas } from './extractSchemas';
import type { WorkspaceState } from '../src/project/format';
// Custom scheme that serves files from the open project root (sandboxed). Lets
@@ -136,6 +137,11 @@ ipcMain.handle('workspace:save', (_e, ws: WorkspaceState) => saveWorkspace(requi
// external) for the isolated play realm (REARCH_EDITOR_REALM P1 / RC12 §E8-1).
ipcMain.handle('project:buildScripts', () => buildProjectScripts(requireRoot()));
+// Extract the open project's component field schemas (src/components.ts →
+// .esengine/cache/schemas.json) so the editor main realm can inspect unknown
+// components without executing project code (REARCH_EDITOR_REALM P2).
+ipcMain.handle('project:extractSchemas', () => extractProjectSchemas(requireRoot()));
+
ipcMain.handle('recents:list', () => listRecents());
ipcMain.handle('recents:add', (_e, root: string, name: string) => addRecent(root, name));
diff --git a/desktop/electron/preload.ts b/desktop/electron/preload.ts
index 7ba094ba7..4decf9461 100644
--- a/desktop/electron/preload.ts
+++ b/desktop/electron/preload.ts
@@ -1,6 +1,7 @@
import { contextBridge, ipcRenderer } from 'electron';
import type { OpenedProject, WorkspaceState, DirEntry, RecentEntry, TemplateEntry } from '../src/project/format';
import type { BuildScriptsResult } from './buildScripts';
+import type { ExtractSchemasResult } from './extractSchemas';
// The privileged bridge the renderer is allowed to touch. Keep this surface small
// and explicit — anything the editor needs from the OS or Node goes through here.
@@ -27,6 +28,8 @@ const api = {
chooseDirectory: (): Promise<string | null> => ipcRenderer.invoke('project:chooseDirectory'),
/** Bundle the open project's scripts (src/main.ts) for the isolated play realm. */
buildScripts: (): Promise<BuildScriptsResult> => ipcRenderer.invoke('project:buildScripts'),
+ /** Extract the project's component field schemas → .esengine/cache/schemas.json. */
+ extractSchemas: (): Promise<ExtractSchemasResult> => ipcRenderer.invoke('project:extractSchemas'),
},
// New-project templates (launcher New tab).
templates: {
diff --git a/desktop/tests/extract-schemas.test.ts b/desktop/tests/extract-schemas.test.ts
new file mode 100644
index 000000000..82dc02d18
--- /dev/null
+++ b/desktop/tests/extract-schemas.test.ts
@@ -0,0 +1,88 @@
+/**
+ * @file Project schema extractor (REARCH_EDITOR_REALM Phase P2).
+ * A pure-node, zero-wasm step: bundle a project's declaration module,
+ * run its defineComponent side effects in a fresh AppContext, and
+ * serialize the field schema of ONLY the project's own components —
+ * excluding C++ builtins (Sprite/…) and the SDK's own defineComponent
+ * ones (Name/SceneOwner/…).
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { extractProjectSchemas, type ComponentSchema } from '../electron/extractSchemas';
+
+let root: string;
+
+beforeAll(() => {
+ root = mkdtempSync(path.join(tmpdir(), 'estella-schema-proj-'));
+ mkdirSync(path.join(root, 'src'), { recursive: true });
+ // A project's DECLARATION module: only defineComponent/defineTag, no startup.
+ writeFileSync(
+ path.join(root, 'src', 'components.ts'),
+ `import { defineComponent, defineTag } from 'esengine';\n` +
+ `export const Wave = defineComponent('Wave', {\n` +
+ ` amplitude: 1,\n` +
+ ` speed: 2.5,\n` +
+ ` tint: { r: 1, g: 0, b: 0, a: 1 },\n` +
+ `});\n` +
+ `export const Marker = defineTag('Marker');\n`,
+ );
+});
+
+afterAll(() => {
+ if (root) rmSync(root, { recursive: true, force: true });
+});
+
+const byName = (schemas: ComponentSchema[], name: string) => schemas.find((s) => s.name === name);
+
+describe('extractProjectSchemas (P2)', () => {
+ it('extracts the project component field schemas to .esengine/cache/schemas.json', async () => {
+ const res = await extractProjectSchemas(root);
+ expect(res.errors).toEqual([]);
+ expect(res.ok).toBe(true);
+ expect(res.outputPath).toBe(path.join(root, '.esengine/cache/schemas.json'));
+ expect(existsSync(res.outputPath!)).toBe(true);
+
+ const wave = byName(res.schemas, 'Wave');
+ expect(wave).toBeDefined();
+ expect(wave!.isTag).toBe(false);
+ expect(wave!.default).toEqual({ amplitude: 1, speed: 2.5, tint: { r: 1, g: 0, b: 0, a: 1 } });
+ // {r,g,b,a} default is detected as a color field:
+ expect(wave!.colorKeys).toContain('tint');
+
+ const marker = byName(res.schemas, 'Marker');
+ expect(marker).toBeDefined();
+ expect(marker!.isTag).toBe(true);
+ expect(marker!.default).toEqual({});
+ });
+
+ it('excludes C++ builtins and the SDK\'s own defineComponent components', async () => {
+ const res = await extractProjectSchemas(root);
+ const names = res.schemas.map((s) => s.name).sort();
+ expect(names).toEqual(['Marker', 'Wave']); // ONLY the project's, nothing else
+ // sanity: none of the engine-provided ones leaked in
+ for (const builtin of ['Sprite', 'Transform', 'Name', 'SceneOwner', 'PostProcessVolume', 'Disabled']) {
+ expect(names).not.toContain(builtin);
+ }
+ });
+
+ it('the written JSON matches the returned schemas (the artifact is the source of truth)', async () => {
+ const res = await extractProjectSchemas(root);
+ const onDisk = JSON.parse(readFileSync(res.outputPath!, 'utf8')) as ComponentSchema[];
+ expect(onDisk).toEqual(res.schemas);
+ });
+
+ it('reports a clean failure when the declaration entry is missing', async () => {
+ const empty = mkdtempSync(path.join(tmpdir(), 'estella-schema-empty-'));
+ try {
+ const res = await extractProjectSchemas(empty);
+ expect(res.ok).toBe(false);
+ expect(res.outputPath).toBeNull();
+ expect(res.schemas).toEqual([]);
+ expect(res.errors.join(' ')).toMatch(/declaration entry not found/);
+ } finally {
+ rmSync(empty, { recursive: true, force: true });
+ }
+ });
+});