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): hide inert inspector fields by component state

yhhde04d05b2f6f
diff --git a/desktop/src/engine/schema.ts b/desktop/src/engine/schema.ts
index 9602acb58..3f0c33f1d 100644
--- a/desktop/src/engine/schema.ts
+++ b/desktop/src/engine/schema.ts
@@ -567,15 +567,57 @@ function fieldFor(
* overrides; an entity with no prefab base just compares against the default.
*/
// Fields that only apply to some states of the SAME component — hidden from the
-// inspector when inert so the panel shows just the controls that matter. Currently
-// the tilemap stagger/hex fields, gated on the layer's orientation (an orthogonal or
-// isometric map has no stagger; only hexagonal reads the side length).
+// inspector when inert so the panel shows just the controls that matter, gated on a
+// sibling discriminator field's live value. Each rule hides ONLY a field that is
+// definitively meaningless in the current state (never one that merely defaults),
+// so switching the discriminator back brings the field (and its stored value) right
+// back. `data` here is the effective view (stored values over registered defaults),
+// so a discriminator omitted from the stored data still resolves.
function isConditionallyHidden(compType: string, key: string, data: Record<string, unknown>): boolean {
- if (compType !== 'TilemapLayer') return false;
- const orientation = Number(data.orientation) || 0;
- if (key === 'hexSideLength') return !isHexOrientation(orientation);
- if (key === 'staggerAxis' || key === 'staggerIndex') return !usesStagger(orientation);
- return false;
+ switch (compType) {
+ case 'TilemapLayer': {
+ const orientation = Number(data.orientation) || 0;
+ if (key === 'hexSideLength') return !isHexOrientation(orientation);
+ if (key === 'staggerAxis' || key === 'staggerIndex') return !usesStagger(orientation);
+ return false;
+ }
+ case 'Camera': {
+ // projectionType: Perspective = 0, Orthographic = 1.
+ const ortho = Number(data.projectionType) === 1;
+ if (key === 'fov') return ortho; // an ortho projection has no field of view
+ if (key === 'orthoSize') return !ortho; // ortho-only half-height
+ if (key === 'pixelPerfect') return !ortho; // pixel snap is an ortho pixel-art concern
+ return false;
+ }
+ case 'Light2D': {
+ // type: Point = 0, Directional = 1, Ambient = 2, Spot = 3.
+ const type = Number(data.type) || 0;
+ if (key === 'radius') return type === 1 || type === 2; // Point / Spot reach only
+ if (key === 'direction') return type === 0 || type === 2; // Directional / Spot aim only
+ if (key === 'innerAngle' || key === 'outerAngle') return type !== 3; // Spot cone only
+ if (key === 'shadowDistance') return type !== 1; // Directional shadow only
+ if (key === 'shadowSoftness') return type === 2; // Ambient casts no shadow
+ return false;
+ }
+ case 'ParticleEmitter': {
+ // shape: Point = 0, Circle = 1, Rectangle = 2, Cone = 3 (Circle & Cone use the
+ // radius; Rectangle the size; Cone the angle — see the emitter shape gizmo).
+ const shape = Number(data.shape) || 0;
+ if (key === 'shapeRadius') return shape === 0 || shape === 2;
+ if (key === 'shapeSize') return shape !== 2;
+ if (key === 'shapeAngle') return shape !== 3;
+ // A disabled trail / floor collision hides its whole tuning block.
+ if (key === 'trailWidth' || key === 'trailPoints' || key === 'trailMinDistance') {
+ return data.trailEnabled === false;
+ }
+ if (key === 'collisionFloor' || key === 'collisionBounce' || key === 'collisionFriction' || key === 'collisionLifetimeLoss') {
+ return data.collisionEnabled === false;
+ }
+ return false;
+ }
+ default:
+ return false;
+ }
}
export function inspectorFields(
@@ -589,10 +631,14 @@ export function inspectorFields(
const defaults = def ? componentDefaults(def) : schema?.default;
// Field order: the registered / schema defaults; else the stored data's keys.
const keys = defaults ? Object.keys(defaults) : Object.keys(data);
+ // Effective values (stored data over registered defaults) — a conditional-visibility
+ // discriminator (projection / light type / emitter shape) may be omitted from the
+ // stored `data` when it equals its default, so resolve against defaults here.
+ const eff = defaults ? { ...defaults, ...data } : data;
const fields: InspectorField[] = [];
for (const key of keys) {
if (DERIVED_FIELDS.has(key)) continue;
- if (isConditionallyHidden(compType, key, data)) continue;
+ if (isConditionallyHidden(compType, key, eff)) continue;
const value = key in data ? data[key] : defaults?.[key];
const f = fieldFor(compType, key, value, colorKeys.has(key));
if (!f) continue;
diff --git a/desktop/tests/inspector-conditional-fields.test.ts b/desktop/tests/inspector-conditional-fields.test.ts
new file mode 100644
index 000000000..04c5eb299
--- /dev/null
+++ b/desktop/tests/inspector-conditional-fields.test.ts
@@ -0,0 +1,112 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Conditional field visibility — the Details panel hides fields that are
+ * inert in a component's current state (Camera projection, Light2D type,
+ * ParticleEmitter shape/trail/collision), gated on a sibling discriminator.
+ * Exercised through the builtin registry (no WASM). A rule must hide a field
+ * ONLY when it is meaningless, and bring it back when the discriminator flips.
+ */
+import { describe, it, expect } from 'vitest';
+import { inspectorFields } from '@/engine/schema';
+
+/** The visible field keys the inspector would render for `data`. */
+const keys = (comp: string, data: Record<string, unknown>): Set<string> =>
+ new Set(inspectorFields(comp, data).map((f) => f.key));
+
+describe('conditional inspector fields', () => {
+ describe('Camera projection', () => {
+ it('an Orthographic camera shows orthoSize/pixelPerfect and hides fov', () => {
+ const k = keys('Camera', { projectionType: 1 });
+ expect(k.size).toBeGreaterThan(0); // registry loaded
+ expect(k.has('orthoSize')).toBe(true);
+ expect(k.has('pixelPerfect')).toBe(true);
+ expect(k.has('fov')).toBe(false);
+ });
+ it('a Perspective camera shows fov and hides orthoSize/pixelPerfect', () => {
+ const k = keys('Camera', { projectionType: 0 });
+ expect(k.has('fov')).toBe(true);
+ expect(k.has('orthoSize')).toBe(false);
+ expect(k.has('pixelPerfect')).toBe(false);
+ });
+ });
+
+ describe('Light2D type', () => {
+ it('Point: radius only, no direction / cone angles / directional shadow', () => {
+ const k = keys('Light2D', { type: 0 });
+ expect(k.has('radius')).toBe(true);
+ expect(k.has('direction')).toBe(false);
+ expect(k.has('innerAngle')).toBe(false);
+ expect(k.has('shadowDistance')).toBe(false);
+ });
+ it('Directional: direction + directional shadow, no radius / cone angles', () => {
+ const k = keys('Light2D', { type: 1 });
+ expect(k.has('direction')).toBe(true);
+ expect(k.has('shadowDistance')).toBe(true);
+ expect(k.has('radius')).toBe(false);
+ expect(k.has('outerAngle')).toBe(false);
+ });
+ it('Ambient: neither reach, aim, cone, nor shadows', () => {
+ const k = keys('Light2D', { type: 2 });
+ expect(k.has('radius')).toBe(false);
+ expect(k.has('direction')).toBe(false);
+ expect(k.has('innerAngle')).toBe(false);
+ expect(k.has('shadowSoftness')).toBe(false);
+ expect(k.has('intensity')).toBe(true); // still tunable
+ });
+ it('Spot: reach + aim + cone angles, no directional shadow', () => {
+ const k = keys('Light2D', { type: 3 });
+ expect(k.has('radius')).toBe(true);
+ expect(k.has('direction')).toBe(true);
+ expect(k.has('innerAngle')).toBe(true);
+ expect(k.has('outerAngle')).toBe(true);
+ expect(k.has('shadowDistance')).toBe(false);
+ });
+ });
+
+ describe('ParticleEmitter shape', () => {
+ it('Point: no shape geometry fields', () => {
+ const k = keys('ParticleEmitter', { shape: 0 });
+ expect(k.has('shapeRadius')).toBe(false);
+ expect(k.has('shapeSize')).toBe(false);
+ expect(k.has('shapeAngle')).toBe(false);
+ });
+ it('Circle: radius only', () => {
+ const k = keys('ParticleEmitter', { shape: 1 });
+ expect(k.has('shapeRadius')).toBe(true);
+ expect(k.has('shapeSize')).toBe(false);
+ expect(k.has('shapeAngle')).toBe(false);
+ });
+ it('Rectangle: size only', () => {
+ const k = keys('ParticleEmitter', { shape: 2 });
+ expect(k.has('shapeSize')).toBe(true);
+ expect(k.has('shapeRadius')).toBe(false);
+ expect(k.has('shapeAngle')).toBe(false);
+ });
+ it('Cone: radius (reach) + angle, no rectangle size', () => {
+ const k = keys('ParticleEmitter', { shape: 3 });
+ expect(k.has('shapeRadius')).toBe(true);
+ expect(k.has('shapeAngle')).toBe(true);
+ expect(k.has('shapeSize')).toBe(false);
+ });
+ });
+
+ describe('ParticleEmitter trail / collision toggles', () => {
+ it('a disabled trail hides its tuning block', () => {
+ expect(keys('ParticleEmitter', { trailEnabled: false }).has('trailWidth')).toBe(false);
+ expect(keys('ParticleEmitter', { trailEnabled: true }).has('trailWidth')).toBe(true);
+ });
+ it('disabled floor collision hides its tuning block', () => {
+ expect(keys('ParticleEmitter', { collisionEnabled: false }).has('collisionBounce')).toBe(false);
+ expect(keys('ParticleEmitter', { collisionEnabled: true }).has('collisionBounce')).toBe(true);
+ });
+ });
+
+ describe('TilemapLayer orientation (regression)', () => {
+ it('an orthogonal layer hides stagger + hex fields', () => {
+ const k = keys('TilemapLayer', { orientation: 0 });
+ expect(k.has('hexSideLength')).toBe(false);
+ expect(k.has('staggerAxis')).toBe(false);
+ });
+ });
+});
diff --git a/desktop/tests/inspector-model.test.ts b/desktop/tests/inspector-model.test.ts
index 6de716a42..4227e509b 100644
--- a/desktop/tests/inspector-model.test.ts
+++ b/desktop/tests/inspector-model.test.ts
@@ -192,7 +192,8 @@ describe('Unknown-component inspector (schemas.json consumer)', () => {
name: 'Cam',
parent: null,
children: [],
- components: [{ type: 'Camera', data: { fov: 60 } }],
+ // Perspective, so fov is a live field (an ortho camera hides it).
+ components: [{ type: 'Camera', data: { projectionType: 0, fov: 60 } }],
},
],
} as unknown as SceneData,
@@ -485,7 +486,8 @@ describe('Multi-selection inspector (D6)', () => {
describe('Advanced fields (D5)', () => {
it('flags rarely-edited builtin fields as advanced, leaving primaries plain', () => {
const S = EditorSession.create();
- S.model.adopt(sceneWithCamera({ fov: 60, nearPlane: 0.1 }), new Map([[1, 1]]));
+ // Perspective, so fov is a live (primary, non-advanced) field to probe.
+ S.model.adopt(sceneWithCamera({ projectionType: 0, fov: 60, nearPlane: 0.1 }), new Map([[1, 1]]));
const cam = S.query.readInspector(1).find((c) => c.name === 'Camera')!;
expect(cam.fields.find((f) => f.key === 'fov')!.advanced).toBeFalsy();
expect(cam.fields.find((f) => f.key === 'nearPlane')!.advanced).toBe(true);
@@ -719,9 +721,10 @@ describe('Reset-to-default + override base (D3)', () => {
const orthoSize = cam.fields.find((f) => f.key === 'orthoSize')!;
expect(orthoSize.value).toBe(800);
expect(orthoSize.defaultValue).toBe(540); // an override: value ≠ default
- // A field left untouched reads value === default (not modified).
- const fov = cam.fields.find((f) => f.key === 'fov')!;
- expect(fov.value).toBe(fov.defaultValue);
+ // A field left untouched reads value === default (not modified). (clearFlags,
+ // not fov — an ortho camera hides fov, so it isn't in the field list here.)
+ const clearFlags = cam.fields.find((f) => f.key === 'clearFlags')!;
+ expect(clearFlags.value).toBe(clearFlags.defaultValue);
});
it('resetting a field to its defaultValue restores the default', () => {
@@ -745,9 +748,10 @@ describe('Reset-to-default + override base (D3)', () => {
const orthoSize = cam.fields.find((f) => f.key === 'orthoSize')!;
expect(orthoSize.value).toBe(800);
expect(orthoSize.defaultValue).toBe(300); // prefab base wins over the 540 class default
- // A field the prefab base omits falls back to the class default.
- const fov = cam.fields.find((f) => f.key === 'fov')!;
- expect(fov.defaultValue).toBe(60);
+ // A field the prefab base omits falls back to the class default. (clearFlags,
+ // not fov — an ortho camera hides fov, so it isn't in the field list here.)
+ const clearFlags = cam.fields.find((f) => f.key === 'clearFlags')!;
+ expect(clearFlags.defaultValue).toBe(3);
});
it('without a registered resolver, a tagged instance just uses the class default', () => {