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): scene validation becomes queryable - getDiagnostics + one emptiness truth
yhhfa164c8ce157
diff --git a/desktop/scripts/editor-mcp-editor-e2e.mjs b/desktop/scripts/editor-mcp-editor-e2e.mjsindex 70dceb6a4..b50363e77 100644--- a/desktop/scripts/editor-mcp-editor-e2e.mjs+++ b/desktop/scripts/editor-mcp-editor-e2e.mjs@@ -108,6 +108,13 @@ try {if (!Number.isFinite(created) || after <= before) await fail(`create_entity did not spawn (${before} -> ${after})`);console.log(`create_entity OK — id ${created} (${before} -> ${after} entities)`);+ // The fresh Sprite has no texture — the diagnostics sweep must flag it (the+ // same truth as the Details red asterisk, queryable instead of pixel-only).+ const diags = JSON.parse((await call('get_diagnostics')).text);+ if (!diags.some((d) => d.entity === created && d.problem === 'required-empty' && d.field === 'texture'))+ await fail(`get_diagnostics missed the fresh Sprite's empty texture (${JSON.stringify(diags).slice(0, 200)})`);+ console.log(`get_diagnostics OK — flagged Sprite.texture on the new entity`);+await call('set_field', { entity: created, component: 'Transform', key: 'position', type: 'vec3', value: [64, 96, 0] });const live = JSON.parse((await call('world_component', { id: created, component: 'Transform' })).text);if (!live) await fail('world_component returned null — edit did not reach the World');diff --git a/desktop/scripts/editor-mcp-tools.mjs b/desktop/scripts/editor-mcp-tools.mjsindex dbae36161..fc1f5ede9 100644--- a/desktop/scripts/editor-mcp-tools.mjs+++ b/desktop/scripts/editor-mcp-tools.mjs@@ -129,6 +129,9 @@ export const TOOLS = [{ name: 'capture_viewport',description: 'Render the current viewport and return it as a PNG image, so you can SEE what the editor drew. Step first for a settled frame.',schema: obj({}), js: () => CAPTURE_PNG_JS, image: true },+ { name: 'get_diagnostics',+ description: "Scene-wide validation issues the editor flags in the Details panel: required fields left empty (error-grade — a Sprite with no texture draws as a white box) and component inert-state notices. CHECK THIS after building or editing a scene; an empty list is the done signal.",+ schema: obj({}), method: 'getDiagnostics', args: () => [] },{ name: 'get_stats',description: 'Live counts: entity count + last frame draw calls (cheap render evidence).',schema: obj({}), method: 'getStats', args: () => [] },diff --git a/desktop/src/engine/EditorControlSurface.ts b/desktop/src/engine/EditorControlSurface.tsindex f5a646601..44c3d47dd 100644--- a/desktop/src/engine/EditorControlSurface.ts+++ b/desktop/src/engine/EditorControlSurface.ts@@ -26,6 +26,7 @@ import type {import type { SceneData, PrefabData, SubsystemStatus } from 'esengine';import { Material, Sprite, Renderer } from 'esengine';import { EngineHost } from './EngineHost';+import { isRequiredEmpty } from './schema';import { ViewportController } from './ViewportController';import { PerfMonitor, type PerfSnapshot, type FrameSample, type SessionCapture } from './PerfMonitor';import type { SceneCommandsImpl, EditorTransaction } from './SceneCommands';@@ -42,6 +43,16 @@ export interface ViewportCapture {height: number;}+/** One scene-validation finding (see {@link EditorControlSurfaceImpl.getDiagnostics}). */+export interface SceneDiagnostic {+ entity: EntityId;+ entityName: string;+ component: string;+ field?: string;+ problem: 'required-empty' | 'notice';+ detail: string;+}+/** The session parts the surface needs (the EditorSession satisfies this). */export interface SurfaceSession {model: SceneModelImpl;@@ -254,6 +265,40 @@ export class EditorControlSurfaceImpl {getFieldValue(entity: EntityId, component: string, key: string): InspectorFieldValue | null {return this.s.query.getFieldValue(entity, component, key);}+ /**+ * Scene-wide validation sweep — the SAME truths the Details panel renders+ * (required fields left empty, component inert-state notices), aggregated so+ * automation can gate on them instead of reading red asterisks off pixels.+ * `problem: 'required-empty'` is error-grade (a Sprite with no texture draws+ * a white box); `problem: 'notice'` is informational.+ */+ getDiagnostics(): SceneDiagnostic[] {+ const issues: SceneDiagnostic[] = [];+ const visit = (nodes: SceneNode[]): void => {+ for (const node of nodes) {+ for (const comp of this.s.query.readInspector(node.id)) {+ for (const f of comp.fields) {+ if (f.required && isRequiredEmpty(f.value)) {+ issues.push({+ entity: node.id, entityName: node.name, component: comp.name, field: f.key,+ problem: 'required-empty',+ detail: `${comp.name}.${f.key} is required but empty`,+ });+ }+ }+ if (comp.notice) {+ issues.push({+ entity: node.id, entityName: node.name, component: comp.name,+ problem: 'notice', detail: comp.notice,+ });+ }+ }+ if (node.children?.length) visit(node.children);+ }+ };+ visit(this.s.query.readSceneTree());+ return issues;+ }/** The lossless JSON-first scene truth (deep clone), or null if none loaded. */serializeScene(): SceneData | null {return this.s.model.serialize();diff --git a/desktop/src/engine/schema.ts b/desktop/src/engine/schema.tsindex 9f53fa45b..b694eb9c5 100644--- a/desktop/src/engine/schema.ts+++ b/desktop/src/engine/schema.ts@@ -393,6 +393,14 @@ export function isRequiredField(compType: string, key: string): boolean {return userSchema(compType)?.fields?.[key]?.required === true;}+/** The ONE emptiness predicate for required fields — an unset asset ref is the+ * numeric 0 handle sentinel, an unset string is ''. Consumed by the Details+ * panel's red flag AND the surface's getDiagnostics sweep, so what automation+ * gates on is exactly what the UI shows. */+export function isRequiredEmpty(value: unknown): boolean {+ return value === 0 || value === '' || value == null;+}+// Editor-side "Advanced" fold policy — rarely-tuned fields moved below the fold so a// component's common controls stay uncluttered. UINode's flex-item knobs (min/max,// grow/shrink/basis, cross-axis alignSelf) are set far less than its size/anchor.diff --git a/desktop/src/panels/Details.tsx b/desktop/src/panels/Details.tsxindex e83049f79..0a74e337b 100644--- a/desktop/src/panels/Details.tsx+++ b/desktop/src/panels/Details.tsx@@ -48,7 +48,7 @@ import { ENTITY_SOURCES, createFromSource } from '@/engine/entitySources';import { PlayInspect } from '@/engine/PlayInspect';import { DimensionUnit, AnchorAxis, detectAnchor, UIPositionType, parseLocaleTable } from 'esengine';import type { SceneData, InputMapAsset, ActionType, Binding, LocaleTableAsset, PluralCategory } from 'esengine';-import { modelAddableComponentEntries, subscribeSchemas, getSchemaRevision, prettyLabel, hexToRgba, dynamicEnumOptions, boxGroupsFor, type BoxGroupDef } from '@/engine/schema';+import { modelAddableComponentEntries, subscribeSchemas, getSchemaRevision, prettyLabel, hexToRgba, dynamicEnumOptions, boxGroupsFor, isRequiredEmpty, type BoxGroupDef } from '@/engine/schema';import * as imap from '@/project/inputMapDoc';import * as ldoc from '@/project/localeTableDoc';import { buildImporterComponent, applyImporterEdit } from '@/project/assetImporter';@@ -1019,8 +1019,10 @@ function FieldRow({ entities, comp, field, write }: { entities: EntityId[]; compend();};- // A required field left empty (no asset / blank string) — flagged, not blocked (soft).- const invalid = !!field.required && (field.value === 0 || field.value === '' || field.value == null);+ // A required field left empty (no asset / blank string) — flagged, not blocked+ // (soft). ONE predicate with the surface's getDiagnostics sweep, so automation+ // gates on exactly what this red flag shows.+ const invalid = !!field.required && isRequiredEmpty(field.value);return (<divdiff --git a/desktop/tests/editor-control-surface.test.ts b/desktop/tests/editor-control-surface.test.tsindex d390d1a1e..52439132f 100644--- a/desktop/tests/editor-control-surface.test.ts+++ b/desktop/tests/editor-control-surface.test.ts@@ -107,6 +107,19 @@ describe.skipIf(!HAS_WASM)('EditorControlSurface (headless World)', () => {expect(host.ticks).toBe(3);});+ it('getDiagnostics flags a required-empty field (Details parity) and clears when set', () => {+ const id = S.surface.addEntity()!;+ S.surface.addComponent(id, 'Sprite'); // Sprite.texture is required, defaults empty+ const found = S.surface.getDiagnostics();+ expect(found).toContainEqual(+ expect.objectContaining({ entity: id, component: 'Sprite', field: 'texture', problem: 'required-empty' }),+ );+ S.surface.setField(id, 'Sprite', 'texture', 'asset', 'assets/player.png');+ expect(+ S.surface.getDiagnostics().filter((d) => d.entity === id && d.problem === 'required-empty'),+ ).toHaveLength(0);+ });+it('setRunMode delegates play/pause state to the host', () => {S.surface.setRunMode(true, true);expect(host.runMode).toEqual([true, true]);