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): 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.mjs
index 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.mjs
index 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.ts
index 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.ts
index 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.tsx
index 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[]; comp
end();
};
- // 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 (
<div
diff --git a/desktop/tests/editor-control-surface.test.ts b/desktop/tests/editor-control-surface.test.ts
index 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]);