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): a vec4 field no longer renders as a bogus rotation angle

yhh9289925bf449
diff --git a/desktop/src/engine/EditorControlSurface.ts b/desktop/src/engine/EditorControlSurface.ts
index e415e5c27..a0c756775 100644
--- a/desktop/src/engine/EditorControlSurface.ts
+++ b/desktop/src/engine/EditorControlSurface.ts
@@ -106,18 +106,20 @@ export function coerceFieldValue(
case 'asset':
return typeof value === 'string' ? value : String(value);
case 'vec2':
- case 'vec3': {
- const n = declared === 'vec2' ? 2 : 3;
+ case 'vec3':
+ case 'vec4': {
+ const n = declared === 'vec2' ? 2 : declared === 'vec3' ? 3 : 4;
let v: unknown = value;
if (typeof v === 'string') v = parseJsonText(v);
if (v !== null && typeof v === 'object' && !Array.isArray(v)) {
const o = v as Record<string, unknown>;
- v = n === 2 ? [o.x, o.y] : [o.x, o.y, o.z];
+ v = n === 2 ? [o.x, o.y] : n === 3 ? [o.x, o.y, o.z] : [o.x, o.y, o.z, o.w];
}
if (!Array.isArray(v) || v.length < n || v.slice(0, n).some((c) => typeof c !== 'number' || !Number.isFinite(c))) {
- return fail(`${n} numbers (e.g. ${n === 2 ? '[16, 16]' : '[0, 0, 0]'})`);
+ const example = n === 2 ? '[16, 16]' : n === 3 ? '[0, 0, 0]' : '[0, 0, 1, 1]';
+ return fail(`${n} numbers (e.g. ${example})`);
}
- return (n === 2 ? [v[0], v[1]] : [v[0], v[1], v[2]]) as InspectorFieldValue;
+ return v.slice(0, n) as InspectorFieldValue;
}
case 'color': {
let v: unknown = value;
diff --git a/desktop/src/engine/SceneCommands.ts b/desktop/src/engine/SceneCommands.ts
index 178c6d548..ff9fd847a 100644
--- a/desktop/src/engine/SceneCommands.ts
+++ b/desktop/src/engine/SceneCommands.ts
@@ -114,6 +114,19 @@ export function toModelValue(
...(Number.isFinite(z) ? { z } : {}),
};
}
+ case 'vec4': {
+ // Merge onto the base (order-preserving, so a vec4 stays x-first and never
+ // reads back as a quaternion). NaN axes are left untouched, as for vec2/vec3.
+ const [x, y, z, w] = value as [number, number, number, number];
+ const base = cur[key] as { x: number; y: number; z: number; w: number };
+ return {
+ ...base,
+ ...(Number.isFinite(x) ? { x } : {}),
+ ...(Number.isFinite(y) ? { y } : {}),
+ ...(Number.isFinite(z) ? { z } : {}),
+ ...(Number.isFinite(w) ? { w } : {}),
+ };
+ }
case 'vec2list':
// A whole Vec2[] replacement (polygon vertices / chain points) — normalized to
// plain {x,y} so a dragged vertex writes clean data; coalesced to one undo step.
diff --git a/desktop/src/engine/schema.ts b/desktop/src/engine/schema.ts
index 3f0c33f1d..6721c44b2 100644
--- a/desktop/src/engine/schema.ts
+++ b/desktop/src/engine/schema.ts
@@ -13,8 +13,10 @@ type SceneEntityLike = SceneData['entities'][number];
// infers an editable control per field from its live value shape.
//
// Note: PTR_LAYOUTS (the C++ heap layout) is intentionally NOT used for fields —
-// it can diverge from the JS data shape that world.get/set operate on (e.g.
-// Camera packs a vec4 `viewport` where the JS data exposes viewportX/Y/W/H).
+// it can diverge from the JS data shape that world.get/set operate on. A field's
+// control is inferred from its live value shape; the one ambiguity is {x,y,z,w},
+// which is a rotation quaternion OR a vec4 (Camera `viewport`, a 9-slice border) —
+// see isQuaternion.
export type WorldT = App['world'];
/**
@@ -162,6 +164,17 @@ export const angleZToQuat = (deg: number) => {
return { x: 0, y: 0, z: Math.sin(h), w: Math.cos(h) };
};
+// A rotation quaternion and a vec4 (Camera viewport rect, a 9-slice border) share the
+// exact {x,y,z,w} shape, so value-shape alone can't tell them apart — the engine's only
+// quaternions are the Transform rotation and its derived world mirror. Those are surfaced
+// as a Z angle; every other 4-component field is four editable numbers. The named set is
+// authoritative; a w-first layout (the engine's quaternion order, vs. a vec4's x-first)
+// also reads as a quaternion, so a user component's rotation quat renders as an angle
+// without a genuine vec4 (which is x-first) ever mis-rendering as a bogus rotation.
+const QUAT_FIELDS = new Set(['rotation', 'worldRotation']);
+const isQuaternion = (key: string, o: Record<string, number>): boolean =>
+ QUAT_FIELDS.has(key) || Object.keys(o)[0] === 'w';
+
const chan = (n: number) =>
Math.max(0, Math.min(255, Math.round(n * 255)))
.toString(16)
@@ -190,8 +203,11 @@ export function inferField(key: string, v: unknown, isColor: boolean): Inspector
if (typeof v === 'string') return { key, label, type: 'string', value: v };
if (v && typeof v === 'object') {
const o = v as Record<string, number>;
- if ('w' in o && 'z' in o && 'x' in o)
- return { key, label, type: 'angle', value: quatToAngleZ(o as { z: number; w: number }) };
+ if ('w' in o && 'z' in o && 'x' in o) {
+ return isQuaternion(key, o)
+ ? { key, label, type: 'angle', value: quatToAngleZ(o as { z: number; w: number }) }
+ : { key, label, type: 'vec4', value: [o.x, o.y ?? 0, o.z, o.w] };
+ }
if ('z' in o && 'x' in o && 'y' in o) return { key, label, type: 'vec3', value: [o.x, o.y, o.z] };
if ('x' in o && 'y' in o) return { key, label, type: 'vec2', value: [o.x, o.y] };
// CSS-length shape ({ value, unit }) — the UINode Dimension (width/height/inset/margin).
diff --git a/desktop/src/panels/Details.tsx b/desktop/src/panels/Details.tsx
index 0f2ccf111..a3c534d52 100644
--- a/desktop/src/panels/Details.tsx
+++ b/desktop/src/panels/Details.tsx
@@ -90,7 +90,7 @@ import { Segmented, type SegmentedOption } from '@/components/Segmented';
import { AddComponentMenu } from '@/components/AddComponentMenu';
import type { InspectorComponent, InspectorField, InspectorFieldValue, EntityId, NodeKind, EnumOption, AssetType, GradientValue, GradientStop, CurveValue, CurveKey, DimensionValue, InspectSource } from '@/types';
-const AXES = ['x', 'y', 'z'];
+const AXES = ['x', 'y', 'z', 'w'];
// Field-value equality for the "modified" (override) mark. Vectors compare
// element-wise; numbers tolerate float drift so a no-op edit doesn't read as one.
@@ -1191,6 +1191,7 @@ function FieldRow({ entities, comp, field, write }: { entities: EntityId[]; comp
break;
case 'vec2':
case 'vec3':
+ case 'vec4':
control = <VecControl value={field.value as number[]} mixed={mixed} onBegin={begin} onEnd={end} onChange={apply} />;
break;
case 'dimension':
diff --git a/desktop/src/types.ts b/desktop/src/types.ts
index c15c97228..0424a36c1 100644
--- a/desktop/src/types.ts
+++ b/desktop/src/types.ts
@@ -33,6 +33,7 @@ export type InspectorFieldType =
| 'string'
| 'vec2'
| 'vec3'
+ | 'vec4' // four editable numbers (Camera viewport rect, a 9-slice border) — NOT a rotation quaternion (see 'angle')
| 'vec2list' // a whole Vec2[] written at once (polygon vertices / chain points) — viewport vertex drag
| 'angle' // 2D rotation: a quaternion shown/edited as Z degrees
| 'color'
@@ -83,6 +84,7 @@ export type InspectorFieldValue =
| string
| [number, number]
| [number, number, number]
+ | [number, number, number, number]
| GradientValue
| CurveValue
| DimensionValue;
diff --git a/desktop/tests/inspector-vec4-quat.test.ts b/desktop/tests/inspector-vec4-quat.test.ts
new file mode 100644
index 000000000..872349429
--- /dev/null
+++ b/desktop/tests/inspector-vec4-quat.test.ts
@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file A rotation quaternion and a vec4 share the {x,y,z,w} shape, so the field
+ * inference must not surface a vec4 (Camera viewport rect, a 9-slice border)
+ * as a bogus rotation angle. Regression for `viewport` rendering as "90°"
+ * (atan2(z=1, w=1)·2 = 90°).
+ */
+import { describe, it, expect } from 'vitest';
+import { inferField, inspectorFields } from '@/engine/schema';
+
+describe('quaternion vs vec4 inference', () => {
+ it('a rotation quaternion (w-first) reads as an angle', () => {
+ expect(inferField('rotation', { w: 1, x: 0, y: 0, z: 0 }, false)!.type).toBe('angle');
+ // A user component quaternion (w-first layout) is caught even without the name.
+ expect(inferField('orient', { w: 1, x: 0, y: 0, z: 0 }, false)!.type).toBe('angle');
+ });
+
+ it('a vec4 (x-first) reads as four numbers, not an angle', () => {
+ const viewport = inferField('viewport', { x: 0, y: 0, z: 1, w: 1 }, false)!;
+ expect(viewport.type).toBe('vec4');
+ expect(viewport.value).toEqual([0, 0, 1, 1]); // NOT quatToAngleZ → 90
+ const border = inferField('sliceBorder', { x: 4, y: 4, z: 4, w: 4 }, false)!;
+ expect(border.type).toBe('vec4');
+ expect(border.value).toEqual([4, 4, 4, 4]);
+ });
+
+ it("end-to-end: the Camera's viewport field is a vec4 in the inspector", () => {
+ const viewport = inspectorFields('Camera', { projectionType: 1 }).find((f) => f.key === 'viewport');
+ expect(viewport).toBeDefined();
+ expect(viewport!.type).toBe('vec4');
+ expect(viewport!.value).toEqual([0, 0, 1, 1]);
+ });
+
+ it("end-to-end: the Transform's rotation stays an angle", () => {
+ 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 rot = inspectorFields('Transform', data).find((f) => f.key === 'rotation')!;
+ expect(rot.type).toBe('angle');
+ });
+});