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): live user-component schema reflection
esengine64dc75ffb7e8
diff --git a/desktop/src/engine/schema.ts b/desktop/src/engine/schema.tsindex 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.tsxindex 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.tsxindex 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.tsindex 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.tsnew file mode 100644index 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();+ });+});