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): one formula for the Z angle of a rotation

esengine62c9c8433868
diff --git a/desktop/src/engine/viewportMath.ts b/desktop/src/engine/viewportMath.ts
index cb638a3ad..5d724ec25 100644
--- a/desktop/src/engine/viewportMath.ts
+++ b/desktop/src/engine/viewportMath.ts
@@ -32,9 +32,18 @@ export interface ClientRect {
h: number;
}
-/** Z angle (radians) of a rotation quaternion — the only DOF a 2D transform uses. */
-export function quatAngleZ(q: { w: number; x: number; y: number; z: number }): number {
- return Math.atan2(2 * (q.w * q.z + q.x * q.y), 1 - 2 * (q.y * q.y + q.z * q.z));
+/**
+ * Z angle (radians) of a rotation quaternion — the turn a 2D transform is made of,
+ * and the one a 2D gesture edits on a posed one. From the WHOLE quaternion:
+ * `2·atan2(z, w)` is this angle only while x and y are zero. Absent components read
+ * as the identity, so a partial rotation is no rotation rather than a NaN.
+ */
+export function quatAngleZ(q: { w?: number; x?: number; y?: number; z?: number } | undefined): number {
+ const w = q?.w ?? 1;
+ const x = q?.x ?? 0;
+ const y = q?.y ?? 0;
+ const z = q?.z ?? 0;
+ return Math.atan2(2 * (w * z + x * y), 1 - 2 * (y * y + z * z));
}
/** The four world-space corners of an OBB, CCW from the (−hw,−hh) local corner. */
@@ -221,11 +230,6 @@ export function turnQuat2D(q: { x?: number; y?: number; z?: number; w?: number }
return quatMul(axisQuat('z', radians), cur);
}
-/** The Z angle of a 2D rotation quaternion; 0 for one that isn't there. */
-export function quatAngleZ2D(q: { z?: number; w?: number } | undefined): number {
- return 2 * Math.atan2(q?.z ?? 0, q?.w ?? 1);
-}
-
/** A scale vector multiplied by a per-axis factor, keeping z. */
export function scaleVecBy(
s: { x?: number; y?: number; z?: number } | undefined,
diff --git a/desktop/src/panels/PlayOverlay.tsx b/desktop/src/panels/PlayOverlay.tsx
index 93ab7883b..425c970a8 100644
--- a/desktop/src/panels/PlayOverlay.tsx
+++ b/desktop/src/panels/PlayOverlay.tsx
@@ -24,7 +24,7 @@ import { PlayRealm } from '@/engine/PlayRealm';
import { EntityOps } from '@/engine/entityOps';
import { useSelection } from '@/store/selectionStore';
import { useEditorStore } from '@/store/editorStore';
-import { snapTo, quatAngleZ2D } from '@/engine/viewportMath';
+import { snapTo, quatAngleZ } from '@/engine/viewportMath';
import type { CanvasPoint, PlayOverlayBox } from '@/engine/playProtocol';
/** Half-size of the origin handle, in CSS px. */
@@ -135,7 +135,7 @@ export function PlayOverlay({ interactive }: Props) {
from: { x: e.clientX, y: e.clientY },
startAngle: polar.angle,
startDist: polar.dist,
- startRot: quatAngleZ2D(t.rotation as { z?: number; w?: number } | undefined),
+ startRot: quatAngleZ(t.rotation as { x?: number; y?: number; z?: number; w?: number } | undefined),
startScale: (t.scale as { x?: number } | undefined)?.x ?? 1,
sentTurn: 0,
sentScale: 1,
diff --git a/desktop/tests/viewport-math.test.ts b/desktop/tests/viewport-math.test.ts
index 95698cf66..553f88a0f 100644
--- a/desktop/tests/viewport-math.test.ts
+++ b/desktop/tests/viewport-math.test.ts
@@ -30,6 +30,23 @@ describe('quatAngleZ', () => {
const q = { w: Math.cos(a / 2), x: 0, y: 0, z: Math.sin(a / 2) };
expect(quatAngleZ(q)).toBeCloseTo(a, 6);
});
+
+ // 2*atan2(z, w) agrees only while x and y are zero. Turn the pose about X and it
+ // reports a number that is none of the three turns.
+ it('is the pose\'s Z turn, not the shortcut that only holds for a flat one', () => {
+ const half = Math.PI / 8;
+ const tilt = { w: Math.cos(half), x: Math.sin(half), y: 0, z: 0 };
+ expect(quatAngleZ(tilt)).toBeCloseTo(0, 6);
+ expect(2 * Math.atan2(tilt.z, tilt.w)).toBeCloseTo(0, 6); // agrees here
+ // ...and here it does not: a pose with x and z both set.
+ const posed = { w: 0.8446, x: 0.1913, y: 0.0, z: 0.5 };
+ expect(quatAngleZ(posed)).not.toBeCloseTo(2 * Math.atan2(posed.z, posed.w), 2);
+ });
+
+ it('an absent rotation is no rotation, not a NaN', () => {
+ expect(quatAngleZ(undefined)).toBe(0);
+ expect(quatAngleZ({ z: 0 })).toBe(0);
+ });
it('identity quat is zero', () => {
expect(quatAngleZ({ w: 1, x: 0, y: 0, z: 0 })).toBeCloseTo(0, 6);
});