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(inspector): property tooltips + DisplayName overrides (RC9-1 editor slice)

esengineb6b941ff9487
diff --git a/desktop/src/engine/schema.ts b/desktop/src/engine/schema.ts
index eb48ae421..1b3a71f03 100644
--- a/desktop/src/engine/schema.ts
+++ b/desktop/src/engine/schema.ts
@@ -200,6 +200,10 @@ export interface UserFieldMeta {
unit?: string;
advanced?: boolean;
category?: string;
+ /** Hover help (UE ToolTip). */
+ tooltip?: string;
+ /** A display name overriding the key-derived label (UE DisplayName). */
+ label?: string;
}
const userSchemas = new Map<string, UserComponentSchema>();
@@ -279,6 +283,8 @@ export function fieldMetaFor(compType: string, key: string): UserFieldMeta | nul
unit: fromDef.unit,
advanced: fromDef.advanced,
category: fromDef.category,
+ tooltip: fromDef.tooltip,
+ label: fromDef.label,
};
}
return userSchema(compType)?.fields?.[key] ?? null;
@@ -359,9 +365,12 @@ function fieldFor(
if (meta.slider && meta.min != null && meta.max != null) field.slider = true;
}
}
- // Presentation policy that applies to any field type (folds + category grouping).
+ // Presentation policy that applies to any field type (folds, category, help text,
+ // and a DisplayName override of the key-derived label).
if (field && meta?.advanced) field.advanced = true;
if (field && meta?.category) field.category = meta.category;
+ if (field && meta?.tooltip) field.tooltip = meta.tooltip;
+ if (field && meta?.label) field.label = meta.label;
return field;
}
diff --git a/desktop/src/panels/Details.tsx b/desktop/src/panels/Details.tsx
index 97c80a71f..7432e60c7 100644
--- a/desktop/src/panels/Details.tsx
+++ b/desktop/src/panels/Details.tsx
@@ -1160,7 +1160,11 @@ function FieldRow({ entities, comp, field, write }: { entities: EntityId[]; comp
}
}
>
- <span className={`prop-label${isScalar ? ' scrub' : ''}`} {...(isScalar ? labelScrub : {})}>
+ <span
+ className={`prop-label${isScalar ? ' scrub' : ''}`}
+ title={field.tooltip}
+ {...(isScalar ? labelScrub : {})}
+ >
{field.label}
</span>
<div className="prop-value">{control}</div>
diff --git a/desktop/src/types.ts b/desktop/src/types.ts
index 0dcb7efa1..7490ef2c4 100644
--- a/desktop/src/types.ts
+++ b/desktop/src/types.ts
@@ -106,6 +106,8 @@ export interface InspectorField {
advanced?: boolean;
/** Groups the field under a collapsible category header (UE's property categories). */
category?: string;
+ /** Hover help for the property (UE's UPROPERTY ToolTip). */
+ tooltip?: 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/field-tooltip.test.ts b/desktop/tests/field-tooltip.test.ts
new file mode 100644
index 000000000..2e5b569f0
--- /dev/null
+++ b/desktop/tests/field-tooltip.test.ts
@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Inspector field metadata wiring — tooltip (UE ToolTip) and a DisplayName
+ * label override flow from a component's field metadata to the InspectorField
+ * the Details panel renders. Exercised through the user-schema path (no WASM).
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { setUserSchemas, inspectorFields } from '@/engine/schema';
+
+beforeEach(() => {
+ setUserSchemas([
+ {
+ name: 'Mover',
+ default: { speed: 5, hp: 100 },
+ colorKeys: [],
+ fields: {
+ speed: { tooltip: 'Units travelled per second', label: 'Move Speed', min: 0, max: 10 },
+ },
+ },
+ ]);
+});
+afterEach(() => setUserSchemas([]));
+
+describe('inspector field tooltip + DisplayName', () => {
+ it('carries the tooltip and overrides the label', () => {
+ const speed = inspectorFields('Mover', { speed: 5, hp: 100 }).find((f) => f.key === 'speed')!;
+ expect(speed.tooltip).toBe('Units travelled per second');
+ expect(speed.label).toBe('Move Speed'); // DisplayName override, not the key-derived 'Speed'
+ expect(speed.min).toBe(0); // existing numeric metadata still flows
+ expect(speed.max).toBe(10);
+ });
+
+ it('leaves fields without metadata on the key-derived label and no tooltip', () => {
+ const hp = inspectorFields('Mover', { speed: 5, hp: 100 }).find((f) => f.key === 'hp')!;
+ expect(hp.tooltip).toBeUndefined();
+ expect(hp.label).not.toBe('Move Speed'); // default prettyLabel, not the override
+ });
+
+ it('flows an authored builtin tooltip end-to-end (Transform.position)', () => {
+ const data = { position: { x: 0, y: 0, z: 0 }, rotation: { w: 1, x: 0, y: 0, z: 0 }, scale: { x: 1, y: 1, z: 1 } };
+ const pos = inspectorFields('Transform', data).find((f) => f.key === 'position')!;
+ expect(typeof pos.tooltip).toBe('string');
+ expect(pos.tooltip!.length).toBeGreaterThan(0);
+ });
+});
diff --git a/sdk/src/component.ts b/sdk/src/component.ts
index ca5006070..d791ecd4f 100644
--- a/sdk/src/component.ts
+++ b/sdk/src/component.ts
@@ -583,7 +583,14 @@ function metaDefaults<T>(name: string, overrides?: Partial<T>): T {
}
export const Transform = defineBuiltin<TransformData>('Transform',
- metaDefaults<TransformData>('Transform')
+ metaDefaults<TransformData>('Transform'),
+ {
+ fields: {
+ position: { tooltip: 'Local position in world units, relative to the parent.' },
+ rotation: { tooltip: 'Rotation about the Z axis, in degrees.' },
+ scale: { tooltip: 'Local scale per axis (1 = original size; negative flips).' },
+ },
+ }
);
export const LocalTransform = Transform;
export const WorldTransform = Transform;
@@ -594,8 +601,9 @@ export const Sprite = defineBuiltin<SpriteData>('Sprite',
}),
{
fields: {
- layer: { step: 1, enumSource: 'sortingLayers' },
- pivot: { advanced: true },
+ layer: { step: 1, enumSource: 'sortingLayers', tooltip: 'Sorting layer — controls draw order across sprites.' },
+ color: { tooltip: 'Tint multiplied into the texture (white = unchanged).' },
+ pivot: { advanced: true, tooltip: 'Anchor point (0–1) the sprite rotates and scales about.' },
uvOffset: { advanced: true },
uvScale: { advanced: true },
tileSize: { advanced: true },
@@ -620,10 +628,10 @@ export const Light2D = defineBuiltin<Light2DData>('Light2D',
metaDefaults<Light2DData>('Light2D'),
{
fields: {
- type: { enum: enumOptions(Light2DType) },
- intensity: { min: 0 },
- radius: { min: 0 },
- direction: { advanced: true },
+ type: { enum: enumOptions(Light2DType), tooltip: 'Point, Directional, Ambient, or Spot.' },
+ intensity: { min: 0, tooltip: 'Brightness multiplier of the light.' },
+ radius: { min: 0, tooltip: 'Falloff reach in world units (Point / Spot).' },
+ direction: { advanced: true, tooltip: 'Aim direction (Directional / Spot).' },
innerAngle: { min: 0, max: 180, unit: '°', advanced: true },
outerAngle: { min: 0, max: 180, unit: '°', advanced: true },
},
@@ -640,11 +648,11 @@ export const Camera = defineBuiltin<CameraData>('Camera',
}),
{
fields: {
- projectionType: { enum: enumOptions(ProjectionType) },
+ projectionType: { enum: enumOptions(ProjectionType), tooltip: 'Orthographic (2D) or Perspective projection.' },
// A bitmask (ColorAndDepth = Color | Depth), so a multi-select, not a dropdown.
- clearFlags: { flags: [{ label: 'Color', value: 1 }, { label: 'Depth', value: 2 }] },
+ clearFlags: { flags: [{ label: 'Color', value: 1 }, { label: 'Depth', value: 2 }], tooltip: 'Which buffers to clear before rendering this camera.' },
fov: { min: 1, max: 179, unit: '°' },
- orthoSize: { min: 0 },
+ orthoSize: { min: 0, tooltip: 'Half the visible height in world units (Orthographic).' },
nearPlane: { min: 0, advanced: true },
farPlane: { min: 0, advanced: true },
aspectRatio: { advanced: true },
@@ -664,10 +672,11 @@ export const Canvas = defineBuiltin<CanvasData>('Canvas',
fields: {
scaleMode: {
enum: enumOptions(ScaleMode, ['FixedWidth', 'FixedHeight', 'Expand', 'Shrink', 'Match']),
+ tooltip: 'How the canvas adapts the design resolution to the screen.',
},
// 0 = match width, 1 = match height (only meaningful in the Match mode).
- matchWidthOrHeight: { min: 0, max: 1, slider: true },
- pixelsPerUnit: { min: 1 },
+ matchWidthOrHeight: { min: 0, max: 1, slider: true, tooltip: '0 matches width, 1 matches height (Match mode only).' },
+ pixelsPerUnit: { min: 1, tooltip: 'Texture pixels mapped to one world unit.' },
},
}
);
@@ -704,7 +713,7 @@ export const TilemapLayer = defineBuiltin<TilemapLayerData>('TilemapLayer',
metaDefaults<TilemapLayerData>('TilemapLayer'),
{
fields: {
- opacity: { min: 0, max: 1, slider: true },
+ opacity: { min: 0, max: 1, slider: true, tooltip: 'Layer transparency (0 = invisible, 1 = opaque).' },
tilesetColumns: { min: 1, step: 1 },
tilesetRows: { min: 1, step: 1 },
renderLayer: { step: 1, enumSource: 'sortingLayers' },
diff --git a/sdk/tests/component.test.ts b/sdk/tests/component.test.ts
index 809a7610f..0630845e8 100644
--- a/sdk/tests/component.test.ts
+++ b/sdk/tests/component.test.ts
@@ -314,7 +314,9 @@ describe('Field metadata (editor presentation policy)', () => {
expect(Camera.fieldMeta.projectionType?.enum).toBe(meta.projectionType?.enum);
// Numeric range/unit policy rides the same channel.
expect(meta.fov).toMatchObject({ min: 1, max: 179, unit: '°' });
- expect(meta.orthoSize).toEqual({ min: 0 });
+ expect(meta.orthoSize).toMatchObject({ min: 0 });
+ // Tooltips (UE ToolTip) ride the same metadata channel as range/unit.
+ expect(typeof meta.orthoSize?.tooltip).toBe('string');
// An unannotated field carries no metadata at all.
expect(meta.isActive).toBeUndefined();
});