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(editor): project component-schema extractor → schemas.json (editor-realm P2)
esengine63df696d5756
diff --git a/desktop/electron/extractSchemas.ts b/desktop/electron/extractSchemas.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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 });+ }+ });+});