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(editor): whether a component may be authored is one answer, not the list's

yhh5894bf4e4084
diff --git a/desktop/src/engine/EditorControlSurface.ts b/desktop/src/engine/EditorControlSurface.ts
index 9e715d2c3..f4dab1ef5 100644
--- a/desktop/src/engine/EditorControlSurface.ts
+++ b/desktop/src/engine/EditorControlSurface.ts
@@ -26,7 +26,7 @@ import type {
import type { SceneData, PrefabData, SubsystemStatus, EventBindingRow } from 'esengine';
import { Material, Sprite, Renderer } from 'esengine';
import { EngineHost } from './EngineHost';
-import { isRequiredEmpty, componentByName, userSchema, coerceEnumInput } from './schema';
+import { isRequiredEmpty, componentByName, userSchema, coerceEnumInput, componentAuthorability } from './schema';
import { ViewportController } from './ViewportController';
import { PerfMonitor, type PerfSnapshot, type FrameSample, type SessionCapture } from './PerfMonitor';
import type { SceneCommandsImpl, EditorTransaction } from './SceneCommands';
@@ -451,9 +451,20 @@ export class EditorControlSurfaceImpl {
*/
addComponent(entity: EntityId, component: string): void {
if (!componentByName(component) && !userSchema(component)) {
+ throw new Error(`no component schema named "${component}" — the editor cannot add it.`);
+ }
+ // The Add Component list hides these; the command that performs the add drops
+ // them too. Said out loud here because a driver that is refused deserves the
+ // reason — this door used to name EventBinding's own door only in the message
+ // for an UNKNOWN component, which is the one case EventBinding never hits.
+ const authorable = componentAuthorability(component);
+ if (!authorable.ok) {
throw new Error(
- `no component schema named "${component}" — the editor cannot add it. `
- + 'Authored-wire components (EventBinding) have their own doors: setEventBindings.',
+ authorable.reason === 'transient'
+ ? `"${component}" is runtime-only state, not something a scene authors.`
+ : `"${component}" is not authored as a component — it has its own door `
+ + '(EventBinding: setEventBindings; UIController/UIGear: the Controllers panel; '
+ + 'Parent/Children: setParent; Name: renameEntity).',
);
}
this.s.commands.addComponent(entity, component);
diff --git a/desktop/src/engine/SceneCommands.ts b/desktop/src/engine/SceneCommands.ts
index 5955e3d0e..114b51644 100644
--- a/desktop/src/engine/SceneCommands.ts
+++ b/desktop/src/engine/SceneCommands.ts
@@ -19,6 +19,7 @@ import {
hexToRgba,
prettyLabel,
clampFieldValue,
+ componentAuthorability,
} from './schema';
import { normalizeFolder, folderParent, isFolderUnder, rebaseFolder } from '@/outliner/folders';
import { convertColliderData, COLLIDER_SHAPE_COMP, COMP_COLLIDER_SHAPE, type ColliderShapeKind } from './colliderConvert';
@@ -1268,6 +1269,10 @@ export class SceneCommandsImpl {
private addComponentOp(sourceId: EntityId, compName: string): UndoOp | null {
const entity = this.model.entityBySource(sourceId);
if (!entity || entity.components.some((c) => c.type === compName)) return null;
+ // Not authorable at all (runtime-only state, or a component whose own panel
+ // owns it) — the mirror of removeComponentOp's protected list, so no caller
+ // can author one by reaching past the Add Component list that hides it.
+ if (!componentAuthorability(compName).ok) return null;
const data = this.defaultDataFor(compName);
this.model.setComponent(sourceId, compName, data);
return {
diff --git a/desktop/src/engine/schema.ts b/desktop/src/engine/schema.ts
index 0ebbf16f4..1ce7735af 100644
--- a/desktop/src/engine/schema.ts
+++ b/desktop/src/engine/schema.ts
@@ -866,15 +866,36 @@ export function modelInspectableComponents(
* it, plus user (schemas.json) components absent from both the entity and the
* engine registry. Transform / structural components are excluded.
*/
+/**
+ * Whether a component is something a person (or an agent) may ADD to an entity at
+ * all — a property of the component itself, as against `addComponentOp`'s "does
+ * this entity already have one".
+ *
+ * Lives here, beside the sets it reads, because three places need the same answer:
+ * the Add Component list, the command that performs the add, and the automation
+ * door that has to say WHY it refused. It used to be enforced only while building
+ * the list, so the other two doors would happily author a runtime-only component
+ * into the scene file, or a second EventBinding beside the one its own panel owns.
+ */
+export type ComponentAuthorability = { ok: true } | { ok: false; reason: 'hidden' | 'transient' };
+
+export function componentAuthorability(name: string): ComponentAuthorability {
+ // Structural/relationship components and those with their own authoring panel.
+ if (HIDDEN_COMPONENTS.has(name)) return { ok: false, reason: 'hidden' };
+ // Runtime-only state is never authorable — it is the engine's, not the scene's.
+ if (getComponentRegistry().get(name)?.transient) return { ok: false, reason: 'transient' };
+ return { ok: true };
+}
+
export function modelAddableComponentEntries(
entity: SceneEntityLike,
): Array<{ name: string; label: string; category: string }> {
const present = new Set(entity.components.map((c) => c.type));
const userNames = new Set(getUserComponents().keys());
const out: Array<{ name: string; label: string; category: string }> = [];
- for (const [name, def] of getComponentRegistry()) {
- if (HIDDEN_COMPONENTS.has(name) || name === 'Transform' || present.has(name)) continue;
- if (def.transient) continue; // runtime-only state is never authorable
+ for (const name of getComponentRegistry().keys()) {
+ if (name === 'Transform' || present.has(name)) continue;
+ if (!componentAuthorability(name).ok) continue;
out.push({ name, label: prettyLabel(name), category: componentCategory(name, userNames.has(name)) });
}
for (const name of userSchemas.keys()) {
diff --git a/desktop/tests/field-constraints.test.ts b/desktop/tests/field-constraints.test.ts
index 75846bfcb..6aa527aa3 100644
--- a/desktop/tests/field-constraints.test.ts
+++ b/desktop/tests/field-constraints.test.ts
@@ -7,7 +7,7 @@
* UI; assetTypeAllowed is the drag-drop type guard. Pure TS.
*/
import { describe, it, expect } from 'vitest';
-import { clampFieldValue, isRequiredField, setUserSchemas } from '@/engine/schema';
+import { clampFieldValue, isRequiredField, setUserSchemas, componentAuthorability } from '@/engine/schema';
import { ProjectStore } from '@/project/ProjectStore';
describe('field constraints (C1: write-gate clamp + asset-type guard)', () => {
@@ -27,6 +27,23 @@ describe('field constraints (C1: write-gate clamp + asset-type guard)', () => {
expect(ProjectStore.assetTypeAllowed(undefined, 'assets/anything.xyz')).toBe(true); // unconstrained slot
});
+ // Whether a component may be authored at all was enforced only while building
+ // the Add Component list, so the two doors that don't build that list — the
+ // command, and the automation surface — would author one anyway.
+ it('componentAuthorability refuses what has its own door, and runtime-only state', () => {
+ // Structural / owns-its-own-panel: authored through setEventBindings, the
+ // Controllers panel, setParent, renameEntity — not as a component.
+ for (const name of ['EventBinding', 'UIController', 'UIGear', 'Parent', 'Children', 'Name']) {
+ const v = componentAuthorability(name);
+ expect(v.ok).toBe(false);
+ expect(v.ok === false && v.reason).toBe('hidden');
+ }
+ // An ordinary component stays addable, and so does a project script component
+ // the engine registry has never heard of.
+ expect(componentAuthorability('Sprite').ok).toBe(true);
+ expect(componentAuthorability('SomeProjectScript').ok).toBe(true);
+ });
+
it('isRequiredField flags builtin required asset fields + user-schema required (C2)', () => {
expect(isRequiredField('Sprite', 'texture')).toBe(true);
expect(isRequiredField('Sprite', 'material')).toBe(false); // optional override