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): live user-component schema reflection

esengine64dc75ffb7e8
diff --git a/desktop/src/engine/schema.ts b/desktop/src/engine/schema.ts
index 3fa23f1bf..24d1cdfc0 100644
--- a/desktop/src/engine/schema.ts
+++ b/desktop/src/engine/schema.ts
@@ -171,10 +171,24 @@ export interface UserComponentSchema {
const userSchemas = new Map<string, UserComponentSchema>();
-/** Replace the user-component schema source (called on project open). */
+// Revision bumped whenever the user-component schemas change, so the inspector
+// re-renders when a project component is edited live (not only on scene change).
+const schemaListeners = new Set<() => void>();
+let schemaRevision = 0;
+/** Subscribe to user-schema changes (for useSyncExternalStore). */
+export const subscribeSchemas = (fn: () => void): (() => void) => {
+ schemaListeners.add(fn);
+ return () => { schemaListeners.delete(fn); };
+};
+export const getSchemaRevision = (): number => schemaRevision;
+
+/** Replace the user-component schema source (project open, manual extract, or a
+ * live edit of the project's component sources). Notifies subscribers. */
export function setUserSchemas(schemas: UserComponentSchema[]): void {
userSchemas.clear();
for (const s of schemas) userSchemas.set(s.name, s);
+ schemaRevision++;
+ for (const l of schemaListeners) l();
}
/** The user schema for a component name, if any. */
diff --git a/desktop/src/layout/MenuBar.tsx b/desktop/src/layout/MenuBar.tsx
index 91100e77b..a6aadb12e 100644
--- a/desktop/src/layout/MenuBar.tsx
+++ b/desktop/src/layout/MenuBar.tsx
@@ -116,7 +116,9 @@ export function MenuBar() {
cmdItem('build.scripts'),
{
label: 'Extract Component Schemas',
- onClick: () => void window.estella?.project?.extractSchemas?.()
+ // refreshUserSchemas extracts AND reloads into the editor (so the
+ // inspector updates), unlike a bare extract that only writes the file.
+ onClick: () => void ProjectStore.refreshUserSchemas()
.then(() => Toasts.push('Extracted component schemas', 'success'))
.catch(() => Toasts.push('Extract failed', 'error')),
disabled: !project,
diff --git a/desktop/src/panels/Details.tsx b/desktop/src/panels/Details.tsx
index c37aeeb6a..23709d7e4 100644
--- a/desktop/src/panels/Details.tsx
+++ b/desktop/src/panels/Details.tsx
@@ -35,7 +35,7 @@ import { SceneModel } from '@/engine/SceneModel';
import { SceneCommands, toModelValue } from '@/engine/SceneCommands';
import { PlayInspect } from '@/engine/PlayInspect';
import type { SceneData } from 'esengine';
-import { modelAddableComponentEntries } from '@/engine/schema';
+import { modelAddableComponentEntries, subscribeSchemas, getSchemaRevision } from '@/engine/schema';
import { ProjectStore } from '@/project/ProjectStore';
import { ContextMenu } from '@/components/Menu';
import { AddComponentMenu } from '@/components/AddComponentMenu';
@@ -595,6 +595,8 @@ export function Details() {
function EditorDetails() {
const engine = useSyncExternalStore(EngineHost.subscribe, EngineHost.getSnapshot);
const revision = useSyncExternalStore(SceneStore.subscribe, SceneStore.getRevision);
+ // Re-render when a project component's schema changes (live edit of its source).
+ useSyncExternalStore(subscribeSchemas, getSchemaRevision);
const selectedId = useSelection((s) => s.selectedId);
const selectedAsset = useSelection((s) => s.selectedAsset);
const ready = engine.status === 'ready' && selectedId != null;
diff --git a/desktop/src/project/fsWatch.ts b/desktop/src/project/fsWatch.ts
index 60e128bcf..3adb158eb 100644
--- a/desktop/src/project/fsWatch.ts
+++ b/desktop/src/project/fsWatch.ts
@@ -30,17 +30,29 @@ export const fsRefresh = {
let inited = false;
let debounce: ReturnType<typeof setTimeout> | null = null;
+let schemaDebounce: ReturnType<typeof setTimeout> | null = null;
+
+// A project source module under src/ — a change here can alter a project
+// component's field schema, so the inspector must re-extract (esbuild, ~100ms).
+const isSourceModule = (p: string): boolean => /(^|[\\/])src[\\/].*\.(t|j)sx?$/.test(p);
/** Subscribe to the main-process project watcher (call once at startup). */
export function initFsWatch(): void {
if (inited || !window.estella?.fs?.onChange) return;
inited = true;
- window.estella.fs.onChange(() => {
+ window.estella.fs.onChange((paths) => {
// Coalesce back-to-back bursts; one scan + one bump per quiet window.
if (debounce) clearTimeout(debounce);
debounce = setTimeout(() => {
void ProjectStore.refreshAssets();
fsRefresh.bump();
}, 60);
+
+ // A component-source edit → re-extract schemas so the inspector reflects the
+ // new fields live (separate, longer window: extraction bundles with esbuild).
+ if (paths.some(isSourceModule)) {
+ if (schemaDebounce) clearTimeout(schemaDebounce);
+ schemaDebounce = setTimeout(() => void ProjectStore.refreshUserSchemas(), 250);
+ }
});
}
diff --git a/desktop/tests/user-schemas.test.ts b/desktop/tests/user-schemas.test.ts
new file mode 100644
index 000000000..e7fb4943a
--- /dev/null
+++ b/desktop/tests/user-schemas.test.ts
@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file User-component schema reflection — setUserSchemas stores the project's
+ * component field schemas and bumps a revision so the inspector re-renders
+ * on a live edit (the T4 reflection loop). Pure TS (no WASM).
+ */
+import { describe, it, expect } from 'vitest';
+import {
+ setUserSchemas,
+ userSchema,
+ assetFieldType,
+ subscribeSchemas,
+ getSchemaRevision,
+ type UserComponentSchema,
+} from '@/engine/schema';
+
+const marker = (count: number): UserComponentSchema => ({
+ name: 'SpawnMarker',
+ isTag: false,
+ default: { count },
+ colorKeys: [],
+ assetFields: [{ field: 'icon', type: 'texture' }],
+});
+
+describe('user-component schemas', () => {
+ it('stores schemas, bumps the revision, and notifies subscribers', () => {
+ const r0 = getSchemaRevision();
+ let notified = 0;
+ const unsub = subscribeSchemas(() => notified++);
+
+ setUserSchemas([marker(3)]);
+ expect(getSchemaRevision()).toBe(r0 + 1);
+ expect(notified).toBe(1);
+ expect((userSchema('SpawnMarker')?.default as { count: number }).count).toBe(3);
+
+ // A user component's asset field resolves as an asset control (inspector).
+ expect(assetFieldType('SpawnMarker', 'icon')).toBe('texture');
+ expect(assetFieldType('SpawnMarker', 'count')).toBeNull();
+
+ // A live re-extract replaces the set and bumps again.
+ setUserSchemas([marker(9)]);
+ expect((userSchema('SpawnMarker')?.default as { count: number }).count).toBe(9);
+ expect(notified).toBe(2);
+
+ unsub();
+ setUserSchemas([]);
+ expect(notified).toBe(2); // unsubscribed → not notified
+ expect(userSchema('SpawnMarker')).toBeUndefined();
+ });
+});