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.

fix(editor): packaged builds never extracted a project's component schemas

yhh59c467ef96a6
diff --git a/desktop/electron/extractSchemas.ts b/desktop/electron/extractSchemas.ts
index eb06b08d5..6e808a5ea 100644
--- a/desktop/electron/extractSchemas.ts
+++ b/desktop/electron/extractSchemas.ts
@@ -22,6 +22,7 @@
*/
import type { Plugin } from 'esbuild';
import { loadEsbuild } from './esbuildRuntime';
+import { esengineAlias } from './esengineResolve';
import { existsSync, mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import path from 'node:path';
@@ -34,10 +35,17 @@ 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).
+ * Anchor for resolving the bare `esengine` specifier when no `sdkDir` is given.
+ * 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).
+ *
+ * Walking up only works when this file sits on the REAL filesystem. Once packaged
+ * it does not: it lives inside app.asar, which Node reads through a patched fs but
+ * esbuild — a native subprocess — cannot see into at all. That is why callers in
+ * the app pass `sdkDir` (main.ts SDK_DIST, retargeted to the app.asar.unpacked
+ * twin); the walk-up stays for tests and any consumer running from source.
*/
const ANCHOR_DIR = path.dirname(fileURLToPath(import.meta.url));
@@ -158,10 +166,15 @@ const EMPTY: SchemasArtifact = { components: [], actions: [], conditions: [] };
* A missing entry: if `required` (the manifest explicitly named it) it's an
* error; otherwise the project simply has no custom components → an empty
* artifact is written and `ok:true` returned.
+ *
+ * `sdkDir` is the SDK dist esbuild inlines `esengine` from — the same alias every
+ * inlined export pipeline uses (esengineResolve.ts). Pass it whenever the caller
+ * knows a real-filesystem dist: without it resolution walks up from
+ * {@link ANCHOR_DIR}, which a packaged app cannot do.
*/
export async function extractProjectSchemas(
root: string,
- opts?: { entry?: string; required?: boolean },
+ opts?: { entry?: string; required?: boolean; sdkDir?: string },
): Promise<ExtractSchemasResult> {
const declPath = path.join(root, opts?.entry ?? DEFAULT_DECL_ENTRY);
if (!existsSync(declPath)) {
@@ -215,7 +228,12 @@ export async function extractProjectSchemas(
write: true,
sourcemap: false,
logLevel: 'silent',
- plugins: [esengineAnchor()],
+ // One strategy or the other, never both: an alias names the SDK's files
+ // outright (and so still yields the SINGLE instance the anchor plugin was
+ // there to guarantee — every importer lands on the same absolute path).
+ ...(opts?.sdkDir
+ ? { alias: esengineAlias(opts.sdkDir) }
+ : { plugins: [esengineAnchor()] }),
});
warnings.push(...result.warnings.map((w) => w.text));
diff --git a/desktop/electron/main.ts b/desktop/electron/main.ts
index c1ad226fb..fca168636 100644
--- a/desktop/electron/main.ts
+++ b/desktop/electron/main.ts
@@ -866,11 +866,22 @@ ipcMain.handle('project:buildScripts', async () => {
// realm can inspect unknown components without executing project code. An
// explicitly-declared register that's missing is an error; the default merely
// being absent means the project has no custom components (REARCH_EDITOR_REALM P2/P3).
+//
+// SDK_DIST, like every other esbuild consumer here: the extractor INLINES the SDK,
+// and a packaged app's node_modules is inside app.asar, which the esbuild
+// subprocess cannot read. Left to walk up from its own location the bundle failed
+// to resolve `esengine` in every shipped build — silently, since a failed extract
+// writes nothing and the last artifact stands, so a project's own components
+// simply never reached Add Component.
ipcMain.handle('project:extractSchemas', async () => {
const root = requireRoot();
const manifest = await readManifest(root);
const { register } = resolveScripts(manifest);
- return extractProjectSchemas(root, { entry: register, required: manifest.scripts?.register !== undefined });
+ return extractProjectSchemas(root, {
+ entry: register,
+ required: manifest.scripts?.register !== undefined,
+ sdkDir: SDK_DIST,
+ });
});
// Write a new project script and wire it into the entry its kind belongs to —
diff --git a/desktop/src/commands/editorCommands.ts b/desktop/src/commands/editorCommands.ts
index 629e0c3c5..ecc8ec7d9 100644
--- a/desktop/src/commands/editorCommands.ts
+++ b/desktop/src/commands/editorCommands.ts
@@ -563,9 +563,14 @@ commands.register({
label: t('menu.extractSchemas'),
category: t('cat.file'),
isEnabled: () => !!ProjectStore.getSnapshot(),
- // Extracts user component schemas AND reloads them into the editor.
+ // Extracts user component schemas AND reloads them into the editor. A refused
+ // extract resolves like any other — report ITS verdict, not merely whether the
+ // call threw (the console carries the reason).
run: () => void ProjectStore.refreshUserSchemas()
- .then(() => Toasts.push(t('toast.extractedSchemas'), 'success'))
+ .then((ok) => Toasts.push(
+ ok ? t('toast.extractedSchemas') : t('toast.extractFailed'),
+ ok ? 'success' : 'error',
+ ))
.catch(() => Toasts.push(t('toast.extractFailed'), 'error')),
});
diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.ts
index 626694fa0..9e6790190 100644
--- a/desktop/src/project/ProjectStore.ts
+++ b/desktop/src/project/ProjectStore.ts
@@ -388,14 +388,30 @@ class ProjectStoreImpl {
* round-trips it losslessly) WITHOUT the editor realm ever running project code.
* Call on open + whenever the declaration entry changes. Best-effort — a failure
* leaves the previous schemas (or builtins-only) and never blocks opening.
+ *
+ * Returns whether the extract itself succeeded. A failed one used to be
+ * indistinguishable from "this project declares no components": the result was
+ * discarded, nothing is written on failure, so the stale (usually empty)
+ * artifact was simply reloaded and Add Component came up short with not one
+ * word anywhere about why. Report it — the caller decides how loudly.
*/
- async refreshUserSchemas(): Promise<void> {
+ async refreshUserSchemas(): Promise<boolean> {
+ let ok = false;
try {
- await window.estella.project.extractSchemas();
+ const res = await window.estella.project.extractSchemas();
+ ok = res.ok;
+ if (!res.ok) {
+ console.error(
+ '[project] component schema extract FAILED — the project\'s own components ' +
+ 'cannot appear in Add Component (their scene data still round-trips ' +
+ `losslessly): ${res.errors.join('; ')}`,
+ );
+ }
} catch (err) {
console.warn('[project] schema extract failed (custom components fall back to lossless-only)', err);
}
await this.loadUserSchemas();
+ return ok;
}
/**
diff --git a/desktop/tests/extract-schemas.test.ts b/desktop/tests/extract-schemas.test.ts
index 0bbe38d68..7929b9909 100644
--- a/desktop/tests/extract-schemas.test.ts
+++ b/desktop/tests/extract-schemas.test.ts
@@ -12,6 +12,7 @@ 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 { fileURLToPath } from 'node:url';
import { extractProjectSchemas, type ComponentSchema, type SchemasArtifact } from '../electron/extractSchemas';
let root: string;
@@ -147,6 +148,33 @@ describe('extractProjectSchemas (P2)', () => {
}
});
+ // The extractor INLINES the SDK, so esbuild — a NATIVE subprocess — has to
+ // READ esengine's dist. Packaged, extractSchemas.ts lives inside app.asar,
+ // which Node reads through a patched fs but that subprocess cannot see into
+ // at all: walking up from there resolved nothing, so EVERY shipped build
+ // failed to resolve `esengine` and silently wrote no artifact — a project's
+ // own components never reached Add Component. main.ts passes SDK_DIST (the
+ // app.asar.unpacked twin) instead, the same alias the export pipelines use.
+ describe('the SDK dist it inlines from', () => {
+ const SDK_DIST = fileURLToPath(new URL('../node_modules/esengine/dist', import.meta.url));
+
+ it('inlines esengine from an explicitly-given dist', async () => {
+ const res = await extractProjectSchemas(root, { sdkDir: SDK_DIST });
+ expect(res.errors).toEqual([]);
+ expect(res.ok).toBe(true);
+ expect(res.schemas.map((s) => s.name)).toEqual(['Marker', 'Wave']);
+ });
+
+ // The teeth: if the alias stops being wired in, resolution silently falls
+ // back to walking up from this package — which works HERE and nowhere a
+ // user runs the editor, which is exactly how the packaged break hid.
+ it('resolves through that dist rather than walking up, so a bogus one fails', async () => {
+ const res = await extractProjectSchemas(root, { sdkDir: path.join(root, 'no-such-sdk') });
+ expect(res.ok).toBe(false);
+ expect(res.errors.join(' ')).toMatch(/esengine|no-such-sdk/);
+ });
+ });
+
// The palettes can only offer a game's own action names if they reach the
// editor as data — the main realm never runs project code.
describe('the project\'s registered actions', () => {