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): group component properties into collapsible categories

esengine4244bb8c6e21
diff --git a/desktop/electron/extractSchemas.ts b/desktop/electron/extractSchemas.ts
index 32ea276df..b0b78b440 100644
--- a/desktop/electron/extractSchemas.ts
+++ b/desktop/electron/extractSchemas.ts
@@ -68,6 +68,7 @@ export interface SerializedFieldMeta {
slider?: boolean;
unit?: string;
advanced?: boolean;
+ category?: string;
}
export interface ExtractSchemasResult {
@@ -192,7 +193,7 @@ interface UserComponentDef {
assetFields?: readonly unknown[];
spineFields?: unknown;
entityFields?: readonly string[];
- fieldMeta?: Record<string, SerializedFieldMeta & { advanced?: boolean }>;
+ fieldMeta?: Record<string, SerializedFieldMeta & { advanced?: boolean; category?: string }>;
}
// Keep only fields the inspector actually consumes (enum / numeric range / unit),
@@ -211,6 +212,7 @@ function pickFieldMeta(
if (meta.slider != null) m.slider = meta.slider;
if (meta.unit != null) m.unit = meta.unit;
if (meta.advanced != null) m.advanced = meta.advanced;
+ if (meta.category != null) m.category = meta.category;
if (Object.keys(m).length) out[key] = m;
}
return Object.keys(out).length ? out : undefined;
diff --git a/desktop/src/engine/schema.ts b/desktop/src/engine/schema.ts
index a3b5bdec1..435c42260 100644
--- a/desktop/src/engine/schema.ts
+++ b/desktop/src/engine/schema.ts
@@ -180,6 +180,7 @@ export interface UserFieldMeta {
slider?: boolean;
unit?: string;
advanced?: boolean;
+ category?: string;
}
const userSchemas = new Map<string, UserComponentSchema>();
@@ -253,6 +254,7 @@ export function fieldMetaFor(compType: string, key: string): UserFieldMeta | nul
slider: fromDef.slider,
unit: fromDef.unit,
advanced: fromDef.advanced,
+ category: fromDef.category,
};
}
return userSchema(compType)?.fields?.[key] ?? null;
@@ -291,8 +293,9 @@ function fieldFor(
if (meta.slider && meta.min != null && meta.max != null) field.slider = true;
}
}
- // Presentation policy that applies to any field type (folds rarely-edited fields).
+ // Presentation policy that applies to any field type (folds + category grouping).
if (field && meta?.advanced) field.advanced = true;
+ if (field && meta?.category) field.category = meta.category;
return field;
}
diff --git a/desktop/src/panels/Details.tsx b/desktop/src/panels/Details.tsx
index 6f5f64b25..0446a101b 100644
--- a/desktop/src/panels/Details.tsx
+++ b/desktop/src/panels/Details.tsx
@@ -612,6 +612,24 @@ function FieldRow({ entities, comp, field, write }: { entities: EntityId[]; comp
);
}
+// A collapsible sub-section inside a component (a property category, or Advanced).
+// Children stay mounted so the grid-rows height transition animates both ways.
+function Fold({ label, open, onToggle, children }: { label: string; open: boolean; onToggle: () => void; children: React.ReactNode }) {
+ return (
+ <>
+ <div className={`subfold${open ? ' open' : ''}`} onClick={onToggle}>
+ <ChevronRight size={9} strokeWidth={3} />
+ {label}
+ </div>
+ <div className="subbody">
+ <div>{children}</div>
+ </div>
+ </>
+ );
+}
+
+const ADVANCED_FOLD = '__advanced__';
+
function ComponentSection({
entities,
comp,
@@ -629,9 +647,22 @@ function ComponentSection({
}) {
const Icon = componentIcon(comp.name);
const overridden = comp.fields.some(isModified);
- const [advOpen, setAdvOpen] = useState(false);
- const primary = comp.fields.filter((f) => !f.advanced);
- const advanced = comp.fields.filter((f) => f.advanced);
+ // Categories default open, the Advanced fold defaults closed.
+ const [openFolds, setOpenFolds] = useState<Record<string, boolean>>({});
+ const isOpen = (name: string) => openFolds[name] ?? name !== ADVANCED_FOLD;
+ const toggleFold = (name: string) => setOpenFolds((s) => ({ ...s, [name]: !isOpen(name) }));
+
+ // Bucket fields: a category wins (grouped under its header); else advanced (the
+ // Advanced fold); else ungrouped at the top.
+ const ungrouped: InspectorField[] = [];
+ const advancedFields: InspectorField[] = [];
+ const groups = new Map<string, InspectorField[]>();
+ for (const f of comp.fields) {
+ if (f.category) (groups.get(f.category) ?? groups.set(f.category, []).get(f.category)!).push(f);
+ else if (f.advanced) advancedFields.push(f);
+ else ungrouped.push(f);
+ }
+ const row = (f: InspectorField) => <FieldRow key={f.key} entities={entities} comp={comp.name} field={f} write={write} />;
const enable = comp.enable;
const on = !enable || enable.value;
// The header checkbox toggles the component's enable field across the whole
@@ -685,23 +716,16 @@ function ComponentSection({
<div className="comp-body">
<div className="cinner">
<div className="comp-fields">
- {primary.map((f) => (
- <FieldRow key={f.key} entities={entities} comp={comp.name} field={f} write={write} />
+ {ungrouped.map(row)}
+ {[...groups].map(([cat, fields]) => (
+ <Fold key={cat} label={cat} open={isOpen(cat)} onToggle={() => toggleFold(cat)}>
+ {fields.map(row)}
+ </Fold>
))}
- {advanced.length > 0 && (
- <>
- <div className={`subfold${advOpen ? ' open' : ''}`} onClick={() => setAdvOpen((o) => !o)}>
- <ChevronRight size={9} strokeWidth={3} />
- Advanced
- </div>
- <div className="subbody">
- <div>
- {advanced.map((f) => (
- <FieldRow key={f.key} entities={entities} comp={comp.name} field={f} write={write} />
- ))}
- </div>
- </div>
- </>
+ {advancedFields.length > 0 && (
+ <Fold label="Advanced" open={isOpen(ADVANCED_FOLD)} onToggle={() => toggleFold(ADVANCED_FOLD)}>
+ {advancedFields.map(row)}
+ </Fold>
)}
</div>
</div>
diff --git a/desktop/src/types.ts b/desktop/src/types.ts
index f51bfc0b2..1b1fd9c32 100644
--- a/desktop/src/types.ts
+++ b/desktop/src/types.ts
@@ -79,6 +79,8 @@ export interface InspectorField {
unit?: string;
/** A rarely-edited field — tucked behind the component's "Advanced" fold. */
advanced?: boolean;
+ /** Groups the field under a collapsible category header (UE's property categories). */
+ category?: string;
/**
* Multi-selection: the selected entities disagree on this field's value. `value`
* holds the primary entity's value (shown muted); an edit fans out to all.
diff --git a/desktop/tests/inspector-model.test.ts b/desktop/tests/inspector-model.test.ts
index 348ab91a3..1af8fcde8 100644
--- a/desktop/tests/inspector-model.test.ts
+++ b/desktop/tests/inspector-model.test.ts
@@ -374,6 +374,51 @@ describe('Advanced fields (D5)', () => {
});
});
+describe('Category grouping (D7)', () => {
+ it('groups builtin fields by category (ParticleEmitter)', () => {
+ const S = EditorSession.create();
+ S.model.adopt(
+ {
+ version: '1.0',
+ name: 'p',
+ entities: [{ id: 1, name: 'P', parent: null, children: [], components: [{ type: 'ParticleEmitter', data: {} }] }],
+ } as unknown as SceneData,
+ new Map([[1, 1]]),
+ );
+ const pe = S.query.readInspector(1).find((c) => c.name === 'ParticleEmitter')!;
+ const cats = new Set(pe.fields.map((f) => f.category).filter(Boolean));
+ expect(cats).toContain('Emission');
+ expect(cats).toContain('Rendering');
+ expect(pe.fields.find((f) => f.key === 'rate')!.category).toBe('Emission');
+ // Categorized fields are not also flagged advanced (category wins).
+ expect(pe.fields.every((f) => !(f.category && f.advanced))).toBe(true);
+ });
+
+ it('lets a user component declare a field category via its schema', () => {
+ setUserSchemas([
+ {
+ name: 'Gun',
+ isTag: false,
+ default: { fireRate: 1, recoil: 0 },
+ colorKeys: [],
+ fields: { recoil: { category: 'Feel' } },
+ },
+ ]);
+ const S = EditorSession.create();
+ S.model.adopt(
+ {
+ version: '1.0',
+ name: 'g',
+ entities: [{ id: 1, name: 'G', parent: null, children: [], components: [{ type: 'Gun', data: { fireRate: 1, recoil: 0 } }] }],
+ } as unknown as SceneData,
+ new Map([[1, 1]]),
+ );
+ const gun = S.query.readInspector(1).find((c) => c.name === 'Gun')!;
+ expect(gun.fields.find((f) => f.key === 'recoil')!.category).toBe('Feel');
+ expect(gun.fields.find((f) => f.key === 'fireRate')!.category).toBeUndefined();
+ });
+});
+
describe('Per-component enable (D4)', () => {
function sceneWith(type: string, data: Record<string, unknown>): SceneData {
return {
diff --git a/sdk/src/component.ts b/sdk/src/component.ts
index c61f711a0..a08679c72 100644
--- a/sdk/src/component.ts
+++ b/sdk/src/component.ts
@@ -739,34 +739,48 @@ export interface ParticleEmitterData {
export const ParticleEmitter = defineBuiltin<ParticleEmitterData>('ParticleEmitter',
metaDefaults<ParticleEmitterData>('ParticleEmitter'),
{
+ // A large component — organized into UE-style property categories.
fields: {
- shape: { enum: enumOptions(EmitterShape) },
- simulationSpace: { enum: enumOptions(SimulationSpace), advanced: true },
- sizeEasing: { enum: enumOptions(ParticleEasing), advanced: true },
- colorEasing: { enum: enumOptions(ParticleEasing), advanced: true },
- blendMode: { enum: enumOptions(BlendMode) },
- rate: { min: 0 },
- burstCount: { min: 0, step: 1, advanced: true },
- burstInterval: { min: 0, advanced: true },
- playOnStart: { advanced: true },
- maxParticles: { min: 1, step: 1 },
- duration: { min: 0 },
- lifetimeMin: { min: 0 },
- lifetimeMax: { min: 0 },
- shapeRadius: { min: 0, advanced: true },
- shapeAngle: { unit: '°', advanced: true },
- angleSpreadMin: { unit: '°', advanced: true },
- angleSpreadMax: { unit: '°', advanced: true },
- rotationMin: { unit: '°', advanced: true },
- rotationMax: { unit: '°', advanced: true },
- angularVelocityMin: { advanced: true },
- angularVelocityMax: { advanced: true },
- spriteColumns: { min: 1, step: 1, advanced: true },
- spriteRows: { min: 1, step: 1, advanced: true },
- spriteFPS: { min: 0, advanced: true },
- spriteLoop: { advanced: true },
- damping: { min: 0, advanced: true },
- layer: { step: 1, advanced: true },
+ rate: { min: 0, category: 'Emission' },
+ maxParticles: { min: 1, step: 1, category: 'Emission' },
+ duration: { min: 0, category: 'Emission' },
+ looping: { category: 'Emission' },
+ playOnStart: { category: 'Emission' },
+ burstCount: { min: 0, step: 1, category: 'Emission' },
+ burstInterval: { min: 0, category: 'Emission' },
+ lifetimeMin: { min: 0, category: 'Lifetime' },
+ lifetimeMax: { min: 0, category: 'Lifetime' },
+ shape: { enum: enumOptions(EmitterShape), category: 'Shape' },
+ shapeRadius: { min: 0, category: 'Shape' },
+ shapeSize: { category: 'Shape' },
+ shapeAngle: { unit: '°', category: 'Shape' },
+ speedMin: { category: 'Velocity' },
+ speedMax: { category: 'Velocity' },
+ angleSpreadMin: { unit: '°', category: 'Velocity' },
+ angleSpreadMax: { unit: '°', category: 'Velocity' },
+ gravity: { category: 'Velocity' },
+ damping: { min: 0, category: 'Velocity' },
+ startSizeMin: { min: 0, category: 'Size' },
+ startSizeMax: { min: 0, category: 'Size' },
+ endSizeMin: { min: 0, category: 'Size' },
+ endSizeMax: { min: 0, category: 'Size' },
+ sizeEasing: { enum: enumOptions(ParticleEasing), category: 'Size' },
+ startColor: { category: 'Color' },
+ endColor: { category: 'Color' },
+ colorEasing: { enum: enumOptions(ParticleEasing), category: 'Color' },
+ rotationMin: { unit: '°', category: 'Rotation' },
+ rotationMax: { unit: '°', category: 'Rotation' },
+ angularVelocityMin: { category: 'Rotation' },
+ angularVelocityMax: { category: 'Rotation' },
+ texture: { category: 'Texture' },
+ spriteColumns: { min: 1, step: 1, category: 'Texture' },
+ spriteRows: { min: 1, step: 1, category: 'Texture' },
+ spriteFPS: { min: 0, category: 'Texture' },
+ spriteLoop: { category: 'Texture' },
+ blendMode: { enum: enumOptions(BlendMode), category: 'Rendering' },
+ layer: { step: 1, category: 'Rendering' },
+ material: { category: 'Rendering' },
+ simulationSpace: { enum: enumOptions(SimulationSpace), category: 'Rendering' },
},
}
);