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: preserve component schema when script recompilation fails

esengine99923f1e6f76
diff --git a/editor/src/__tests__/scripting/ComponentSwapper.test.ts b/editor/src/__tests__/scripting/ComponentSwapper.test.ts
new file mode 100644
index 000000000..390ca1e99
--- /dev/null
+++ b/editor/src/__tests__/scripting/ComponentSwapper.test.ts
@@ -0,0 +1,120 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import {
+ getComponentSchema,
+ exposeRegistrationAPI,
+} from '../../schemas/ComponentSchemas';
+import { getComponentDefaults, unregisterComponent } from 'esengine';
+import { EditorContainer, setEditorContainer } from '../../container';
+import { ComponentSwapper } from '../../scripting/ComponentSwapper';
+
+let container: EditorContainer;
+const cleanup: string[] = [];
+
+beforeEach(() => {
+ container = new EditorContainer();
+ setEditorContainer(container);
+ container.lockBuiltins();
+ exposeRegistrationAPI();
+ delete (window as any).__esengine_componentSourceMap;
+});
+
+afterEach(() => {
+ for (const n of cleanup) unregisterComponent(n);
+ cleanup.length = 0;
+ delete (window as any).__esengine_componentSourceMap;
+});
+
+function trackNames(names: string[]) {
+ cleanup.push(...names);
+}
+
+const SCRIPT_A = `defineComponent('Mover', { speed: 10 });`;
+const SCRIPT_B = `defineComponent('Mover', { speed: 20, accel: 5 });`;
+
+describe('ComponentSwapper', () => {
+ it('prepare collects new registrations without affecting current state', () => {
+ const swapper = new ComponentSwapper();
+ swapper.prepare([{ path: '/src/Mover.ts', content: SCRIPT_A }]);
+ });
+
+ it('swap atomically replaces old registrations with new ones', () => {
+ const swapper = new ComponentSwapper();
+
+ swapper.prepare([{ path: '/src/Mover.ts', content: SCRIPT_A }]);
+ swapper.swap();
+ trackNames(['Mover']);
+
+ expect(getComponentSchema('Mover')).toBeDefined();
+ expect(getComponentDefaults('Mover')).toMatchObject({ speed: 10 });
+
+ swapper.prepare([{ path: '/src/Mover.ts', content: SCRIPT_B }]);
+ swapper.swap();
+
+ expect(getComponentDefaults('Mover')).toMatchObject({ speed: 20, accel: 5 });
+ const schema = getComponentSchema('Mover');
+ expect(schema!.properties.map(p => p.name)).toContain('accel');
+ });
+
+ it('discarding a preparation preserves the current state', () => {
+ const swapper = new ComponentSwapper();
+
+ swapper.prepare([{ path: '/src/Mover.ts', content: SCRIPT_A }]);
+ swapper.swap();
+ trackNames(['Mover']);
+
+ expect(getComponentDefaults('Mover')).toMatchObject({ speed: 10 });
+
+ swapper.prepare([{ path: '/src/Mover.ts', content: SCRIPT_B }]);
+ swapper.discard();
+
+ expect(getComponentSchema('Mover')).toBeDefined();
+ expect(getComponentDefaults('Mover')).toMatchObject({ speed: 10 });
+ });
+
+ it('swap updates the source map', () => {
+ const swapper = new ComponentSwapper();
+
+ swapper.prepare([{ path: '/src/Mover.ts', content: SCRIPT_A }]);
+ swapper.swap();
+ trackNames(['Mover']);
+
+ const sourceMap = window.__esengine_componentSourceMap;
+ expect(sourceMap).toBeDefined();
+ expect(sourceMap!.get('Mover')).toBe('/src/Mover.ts');
+ });
+
+ it('handles multiple components across files', () => {
+ const swapper = new ComponentSwapper();
+
+ swapper.prepare([
+ { path: '/src/Mover.ts', content: `defineComponent('Mover', { speed: 10 });` },
+ { path: '/src/Health.ts', content: `defineComponent('Health', { hp: 100 });` },
+ ]);
+ swapper.swap();
+ trackNames(['Mover', 'Health']);
+
+ expect(getComponentSchema('Mover')).toBeDefined();
+ expect(getComponentSchema('Health')).toBeDefined();
+
+ swapper.prepare([
+ { path: '/src/Mover.ts', content: `defineComponent('Mover', { speed: 20 });` },
+ ]);
+ swapper.swap();
+
+ expect(getComponentDefaults('Mover')).toMatchObject({ speed: 20 });
+ expect(getComponentSchema('Health')).toBeUndefined();
+ });
+
+ it('handles tags', () => {
+ const swapper = new ComponentSwapper();
+ swapper.prepare([
+ { path: '/src/tags.ts', content: `defineTag('Player');` },
+ ]);
+ swapper.swap();
+ trackNames(['Player']);
+
+ const schema = getComponentSchema('Player');
+ expect(schema).toBeDefined();
+ expect(schema!.category).toBe('tag');
+ });
+});
diff --git a/editor/src/__tests__/scripting/ScriptLoader.test.ts b/editor/src/__tests__/scripting/ScriptLoader.test.ts
new file mode 100644
index 000000000..0e55cf940
--- /dev/null
+++ b/editor/src/__tests__/scripting/ScriptLoader.test.ts
@@ -0,0 +1,143 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { extractAndRegisterComponents } from '../../scripting/ScriptLoader';
+import {
+ safeParseObjectLiteral,
+ extractObjectLiteral,
+} from '../../scripting/componentExtraction';
+import {
+ clearScriptComponents,
+ getComponentSchema,
+ exposeRegistrationAPI,
+} from '../../schemas/ComponentSchemas';
+import { unregisterComponent, getComponentDefaults } from 'esengine';
+import { EditorContainer, setEditorContainer } from '../../container';
+
+// ============================================================================
+// Test setup
+// ============================================================================
+
+let container: EditorContainer;
+const registeredNames: string[] = [];
+
+beforeEach(() => {
+ container = new EditorContainer();
+ setEditorContainer(container);
+ container.lockBuiltins();
+ exposeRegistrationAPI();
+});
+
+afterEach(() => {
+ for (const name of registeredNames) unregisterComponent(name);
+ registeredNames.length = 0;
+ delete (window as any).__esengine_componentSourceMap;
+});
+
+function registerAndTrack(source: string): string[] {
+ const names = extractAndRegisterComponents(source);
+ registeredNames.push(...names);
+ return names;
+}
+
+// ============================================================================
+// Unit tests — pure parsing
+// ============================================================================
+
+describe('safeParseObjectLiteral', () => {
+ it('parses simple key-value pairs', () => {
+ expect(safeParseObjectLiteral('{ speed: 10, name: "hello" }')).toEqual({
+ speed: 10, name: 'hello',
+ });
+ });
+
+ it('handles trailing commas', () => {
+ expect(safeParseObjectLiteral('{ a: 1, b: 2, }')).toEqual({ a: 1, b: 2 });
+ });
+
+ it('handles nested objects', () => {
+ expect(safeParseObjectLiteral('{ pos: { x: 0, y: 1 } }')).toEqual({
+ pos: { x: 0, y: 1 },
+ });
+ });
+
+ it('returns null for variable references', () => {
+ expect(safeParseObjectLiteral('{ speed: MAX_SPEED }')).toBeNull();
+ });
+});
+
+describe('extractObjectLiteral', () => {
+ it('extracts balanced braces', () => {
+ expect(extractObjectLiteral('{ a: 1 }, extra')).toBe('{ a: 1 }');
+ });
+
+ it('returns null when not starting with brace', () => {
+ expect(extractObjectLiteral('defaults)')).toBeNull();
+ });
+
+ it('handles strings containing braces', () => {
+ expect(extractObjectLiteral('{ a: "}" }')).toBe('{ a: "}" }');
+ });
+});
+
+// ============================================================================
+// RED — bug reproduction: clear-before-build breaks on failure
+// ============================================================================
+
+describe('compile transactional safety', () => {
+ const SOURCE_V1 = `
+ import { defineComponent } from 'esengine';
+ defineComponent('PlayerStats', { speed: 10, health: 100 });
+ `;
+ const SOURCE_V2 = `
+ import { defineComponent } from 'esengine';
+ defineComponent('PlayerStats', { speed: 20, health: 100, armor: 50 });
+ `;
+
+ it('successful recompile updates schema and defaults', () => {
+ const names = registerAndTrack(SOURCE_V1);
+ expect(getComponentSchema('PlayerStats')).toBeDefined();
+ expect(getComponentDefaults('PlayerStats')).toMatchObject({ speed: 10 });
+
+ // Simulate successful recompile: clear old, register new
+ for (const n of names) unregisterComponent(n);
+ clearScriptComponents();
+ registeredNames.length = 0;
+
+ registerAndTrack(SOURCE_V2);
+
+ expect(getComponentDefaults('PlayerStats')).toMatchObject({ speed: 20, armor: 50 });
+ const schema = getComponentSchema('PlayerStats');
+ expect(schema).toBeDefined();
+ expect(schema!.properties.map(p => p.name)).toContain('armor');
+ });
+
+ it('clear-before-build pattern loses components on build failure', () => {
+ registerAndTrack(SOURCE_V1);
+ expect(getComponentSchema('PlayerStats')).toBeDefined();
+
+ // OLD buggy pattern: clear first, then build fails
+ for (const n of registeredNames) unregisterComponent(n);
+ clearScriptComponents();
+
+ // Build fails here — no re-registration happens
+ // This is the bug: schema is gone
+ expect(getComponentSchema('PlayerStats')).toBeUndefined(); // <-- proves the bug
+ expect(getComponentDefaults('PlayerStats')).toBeNull(); // <-- proves the bug
+ });
+
+ it('clear-after-build pattern preserves components on build failure', () => {
+ registerAndTrack(SOURCE_V1);
+ expect(getComponentSchema('PlayerStats')).toBeDefined();
+
+ // NEW correct pattern: build first, don't clear on failure
+ const buildFailed = true;
+ if (!buildFailed) {
+ for (const n of registeredNames) unregisterComponent(n);
+ clearScriptComponents();
+ // would re-register here
+ }
+
+ // Components survive the failed build
+ expect(getComponentSchema('PlayerStats')).toBeDefined();
+ expect(getComponentDefaults('PlayerStats')).toMatchObject({ speed: 10, health: 100 });
+ });
+});
diff --git a/editor/src/scripting/ComponentSwapper.ts b/editor/src/scripting/ComponentSwapper.ts
new file mode 100644
index 000000000..4bb42f5bd
--- /dev/null
+++ b/editor/src/scripting/ComponentSwapper.ts
@@ -0,0 +1,54 @@
+import { unregisterComponent } from 'esengine';
+import { clearScriptComponents } from '../schemas/ComponentSchemas';
+import {
+ extractComponentDefs,
+ registerComponentEntries,
+ type ComponentDefEntry,
+ type ScriptContent,
+} from './componentExtraction';
+
+export type { ScriptContent };
+
+interface PreparedResult {
+ entries: ComponentDefEntry[];
+ sourceMap: Map<string, string>;
+}
+
+export class ComponentSwapper {
+ private pending_: PreparedResult | null = null;
+
+ prepare(scripts: ScriptContent[]): void {
+ const entries: ComponentDefEntry[] = [];
+ const sourceMap = new Map<string, string>();
+
+ for (const { path, content } of scripts) {
+ for (const entry of extractComponentDefs(content)) {
+ entries.push(entry);
+ sourceMap.set(entry.name, path);
+ }
+ }
+
+ this.pending_ = { entries, sourceMap };
+ }
+
+ swap(): void {
+ if (!this.pending_) return;
+
+ const prevSourceMap = window.__esengine_componentSourceMap;
+ if (prevSourceMap) {
+ for (const name of prevSourceMap.keys()) {
+ unregisterComponent(name);
+ }
+ }
+ clearScriptComponents();
+
+ registerComponentEntries(this.pending_.entries);
+
+ window.__esengine_componentSourceMap = this.pending_.sourceMap;
+ this.pending_ = null;
+ }
+
+ discard(): void {
+ this.pending_ = null;
+ }
+}
diff --git a/editor/src/scripting/ScriptLoader.ts b/editor/src/scripting/ScriptLoader.ts
index 47cfee4cc..9d926674a 100644
--- a/editor/src/scripting/ScriptLoader.ts
+++ b/editor/src/scripting/ScriptLoader.ts
@@ -5,10 +5,17 @@
import * as esbuild from 'esbuild-wasm/esm/browser';
import * as esengineModule from 'esengine';
-import { defineComponent, defineTag, unregisterComponent } from 'esengine';
import { virtualFsPlugin, playModeShimPlugin } from './esbuildPlugins';
import type { NativeFS, ScriptLoaderOptions, CompileError } from './types';
-import { clearScriptComponents } from '../schemas/ComponentSchemas';
+import { ComponentSwapper } from './ComponentSwapper';
+import type { ScriptContent } from './ComponentSwapper';
+import {
+ extractComponentDefs,
+ registerComponentEntries,
+ safeParseObjectLiteral,
+ extractObjectLiteral,
+ type ComponentDefEntry,
+} from './componentExtraction';
import { getEditorContext } from '../context/EditorContext';
import { initializeEsbuild } from '../builder/ArtifactBuilder';
import { normalizePath, joinPath, getProjectDir } from '../utils/path';
@@ -67,19 +74,30 @@ export class ScriptLoader {
}
async compile(): Promise<boolean> {
- const fs = getNativeFS();
- if (!fs) {
- console.warn('ScriptLoader: NativeFS not available');
+ if (this.compiling_) {
+ this.pendingCompile_ = true;
return false;
}
+ this.compiling_ = true;
+ this.pendingCompile_ = false;
- const prevSourceMap = window.__esengine_componentSourceMap;
- if (prevSourceMap) {
- for (const name of prevSourceMap.keys()) {
- unregisterComponent(name);
+ try {
+ return await this.compileInternal_();
+ } finally {
+ this.compiling_ = false;
+ if (this.pendingCompile_) {
+ this.pendingCompile_ = false;
+ void this.compile();
}
}
- clearScriptComponents();
+ }
+
+ private async compileInternal_(): Promise<boolean> {
+ const fs = getNativeFS();
+ if (!fs) {
+ console.warn('ScriptLoader: NativeFS not available');
+ return false;
+ }
const scripts = await this.discoverScripts();
@@ -94,7 +112,10 @@ export class ScriptLoader {
}
if (scripts.length === 0 && pluginImports.length === 0) {
+ this.swapper_.prepare([]);
+ this.swapper_.swap();
this.lastCompiled_ = null;
+ this.onCompileSuccess_?.();
return true;
}
@@ -140,7 +161,9 @@ export class ScriptLoader {
}
this.lastCompiled_ = result.outputFiles?.[0]?.text ?? null;
- await this.registerDiscoveredComponents(fs, scripts);
+ const scriptContents = await this.readScriptContents_(fs, scripts);
+ this.swapper_.prepare(scriptContents);
+ this.swapper_.swap();
this.onCompileSuccess_?.();
return true;
} catch (err: any) {
@@ -206,27 +229,20 @@ export class ScriptLoader {
}
// =========================================================================
- // Component Discovery
+ // Private Helpers
// =========================================================================
- private async registerDiscoveredComponents(
+ private async readScriptContents_(
fs: { readFile(path: string): Promise<string | null> },
scripts: string[]
- ): Promise<void> {
- const sourceMap = new Map<string, string>();
-
- for (const scriptPath of scripts) {
- const content = await fs.readFile(scriptPath);
- if (!content) continue;
- const names = extractAndRegisterComponents(content);
- for (const name of names) {
- sourceMap.set(name, scriptPath);
- }
- }
-
- if (typeof window !== 'undefined') {
- window.__esengine_componentSourceMap = sourceMap;
- }
+ ): Promise<ScriptContent[]> {
+ const reads = await Promise.all(
+ scripts.map(async (path) => {
+ const content = await fs.readFile(path);
+ return content ? { path, content } : null;
+ })
+ );
+ return reads.filter((r): r is ScriptContent => r !== null);
}
// =========================================================================
@@ -239,6 +255,9 @@ export class ScriptLoader {
private lastCompiled_: string | null = null;
private unwatchFn_: (() => void) | null = null;
private recompileTimer_: number | null = null;
+ private compiling_ = false;
+ private pendingCompile_ = false;
+ private swapper_ = new ComponentSwapper();
private onCompileError_?: (errors: CompileError[]) => void;
private onCompileSuccess_?: () => void;
}
@@ -275,90 +294,13 @@ async function findTsFiles(
}
export { findTsFiles, IGNORED_SCRIPT_DIRS, EDITOR_ONLY_DIRS };
-export { extractAndRegisterComponents, safeParseObjectLiteral, extractObjectLiteral };
-
-// =============================================================================
-// Component Extraction
-// =============================================================================
-
-const DEFINE_COMPONENT_RE = /defineComponent\s*(?:<[^>]*>\s*)?\(\s*['"]([^'"]+)['"]\s*,/g;
-const DEFINE_TAG_RE = /defineTag\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+// Re-export for backward compatibility (used in tests)
function extractAndRegisterComponents(source: string): string[] {
- const names: string[] = [];
- const registerSchema = typeof window !== 'undefined'
- ? window.__esengine_registerComponent as
- ((name: string, defaults: Record<string, unknown>, isTag: boolean) => void) | undefined
- : undefined;
-
- DEFINE_COMPONENT_RE.lastIndex = 0;
- let match;
- while ((match = DEFINE_COMPONENT_RE.exec(source)) !== null) {
- const name = match[1];
- const rest = source.substring(match.index + match[0].length);
- const objStr = extractObjectLiteral(rest);
- if (!objStr) continue;
- try {
- const defaults = safeParseObjectLiteral(objStr);
- if (!defaults) continue;
- defineComponent(name, defaults);
- registerSchema?.(name, defaults, false);
- names.push(name);
- } catch { /* skip complex expressions */ }
- }
-
- DEFINE_TAG_RE.lastIndex = 0;
- while ((match = DEFINE_TAG_RE.exec(source)) !== null) {
- defineTag(match[1]);
- registerSchema?.(match[1], {}, true);
- names.push(match[1]);
- }
-
- return names;
+ const entries = extractComponentDefs(source);
+ registerComponentEntries(entries);
+ return entries.map(e => e.name);
}
-function safeParseObjectLiteral(objStr: string): Record<string, unknown> | null {
- try {
- const json = objStr
- .replace(/\/\/.*$/gm, '')
- .replace(/\/\*[\s\S]*?\*\//g, '')
- .replace(/'/g, '"')
- .replace(/(\w+)\s*:/g, '"$1":')
- .replace(/,\s*([}\]])/g, '$1');
- return JSON.parse(json) as Record<string, unknown>;
- } catch {
- return null;
- }
-}
-
-function extractObjectLiteral(source: string): string | null {
- const trimmed = source.trimStart();
- if (trimmed[0] !== '{') return null;
-
- let depth = 0;
- let inString = false;
- let quote = '';
-
- for (let i = 0; i < trimmed.length; i++) {
- const ch = trimmed[i];
-
- if (inString) {
- if (ch === quote && trimmed[i - 1] !== '\\') inString = false;
- continue;
- }
-
- if (ch === '"' || ch === "'" || ch === '`') {
- inString = true;
- quote = ch;
- continue;
- }
-
- if (ch === '{') depth++;
- else if (ch === '}') {
- depth--;
- if (depth === 0) return trimmed.substring(0, i + 1);
- }
- }
-
- return null;
-}
+export { extractAndRegisterComponents, extractComponentDefs, safeParseObjectLiteral, extractObjectLiteral };
+export type { ComponentDefEntry };
diff --git a/editor/src/scripting/componentExtraction.ts b/editor/src/scripting/componentExtraction.ts
new file mode 100644
index 000000000..ae3fd841e
--- /dev/null
+++ b/editor/src/scripting/componentExtraction.ts
@@ -0,0 +1,114 @@
+import { defineComponent, defineTag } from 'esengine';
+
+export interface ComponentDefEntry {
+ name: string;
+ defaults: Record<string, unknown>;
+ isTag: boolean;
+}
+
+export interface ScriptContent {
+ path: string;
+ content: string;
+}
+
+// =============================================================================
+// Component Extraction (pure — no side effects)
+// =============================================================================
+
+const DEFINE_COMPONENT_RE = /defineComponent\s*(?:<[^>]*>\s*)?\(\s*['"]([^'"]+)['"]\s*,/g;
+const DEFINE_TAG_RE = /defineTag\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+
+export function extractComponentDefs(source: string): ComponentDefEntry[] {
+ const entries: ComponentDefEntry[] = [];
+
+ DEFINE_COMPONENT_RE.lastIndex = 0;
+ let match;
+ while ((match = DEFINE_COMPONENT_RE.exec(source)) !== null) {
+ const name = match[1];
+ const rest = source.substring(match.index + match[0].length);
+ const objStr = extractObjectLiteral(rest);
+ if (!objStr) continue;
+ try {
+ const defaults = safeParseObjectLiteral(objStr);
+ if (!defaults) continue;
+ entries.push({ name, defaults, isTag: false });
+ } catch { /* skip complex expressions */ }
+ }
+
+ DEFINE_TAG_RE.lastIndex = 0;
+ while ((match = DEFINE_TAG_RE.exec(source)) !== null) {
+ entries.push({ name: match[1], defaults: {}, isTag: true });
+ }
+
+ return entries;
+}
+
+// =============================================================================
+// Registration (side-effecting — modifies SDK + editor registries)
+// =============================================================================
+
+export function registerComponentEntries(entries: ComponentDefEntry[]): void {
+ const registerSchema = typeof window !== 'undefined'
+ ? window.__esengine_registerComponent as
+ ((name: string, defaults: Record<string, unknown>, isTag: boolean) => void) | undefined
+ : undefined;
+
+ for (const { name, defaults, isTag } of entries) {
+ if (isTag) {
+ defineTag(name);
+ } else {
+ defineComponent(name, defaults);
+ }
+ registerSchema?.(name, defaults, isTag);
+ }
+}
+
+// =============================================================================
+// Parsing Utilities
+// =============================================================================
+
+export function safeParseObjectLiteral(objStr: string): Record<string, unknown> | null {
+ try {
+ const json = objStr
+ .replace(/\/\/.*$/gm, '')
+ .replace(/\/\*[\s\S]*?\*\//g, '')
+ .replace(/'/g, '"')
+ .replace(/(\w+)\s*:/g, '"$1":')
+ .replace(/,\s*([}\]])/g, '$1');
+ return JSON.parse(json) as Record<string, unknown>;
+ } catch {
+ return null;
+ }
+}
+
+export function extractObjectLiteral(source: string): string | null {
+ const trimmed = source.trimStart();
+ if (trimmed[0] !== '{') return null;
+
+ let depth = 0;
+ let inString = false;
+ let quote = '';
+
+ for (let i = 0; i < trimmed.length; i++) {
+ const ch = trimmed[i];
+
+ if (inString) {
+ if (ch === quote && trimmed[i - 1] !== '\\') inString = false;
+ continue;
+ }
+
+ if (ch === '"' || ch === "'" || ch === '`') {
+ inString = true;
+ quote = ch;
+ continue;
+ }
+
+ if (ch === '{') depth++;
+ else if (ch === '}') {
+ depth--;
+ if (depth === 0) return trimmed.substring(0, i + 1);
+ }
+ }
+
+ return null;
+}