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(camera): a game camera that can look from somewhere else

esengine290f3c456e2b
diff --git a/desktop/public/scenes/camera-tilt.esscene b/desktop/public/scenes/camera-tilt.esscene
new file mode 100644
index 000000000..721f93921
--- /dev/null
+++ b/desktop/public/scenes/camera-tilt.esscene
@@ -0,0 +1,109 @@
+{
+ "version": 1,
+ "name": "CameraTilt",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 300
+ },
+ "rotation": {
+ "x": -0.17364817766693033,
+ "y": 0,
+ "z": 0,
+ "w": 0.984807753012208
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 1,
+ "orthoSize": 300,
+ "isActive": true,
+ "priority": 0,
+ "farPlane": 2000
+ }
+ }
+ ]
+ },
+ {
+ "id": 1,
+ "name": "Near",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 80,
+ "y": 80
+ },
+ "color": {
+ "r": 1,
+ "g": 0,
+ "b": 0,
+ "a": 1
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 2,
+ "name": "Far",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": -300
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 80,
+ "y": 80
+ },
+ "color": {
+ "r": 0,
+ "g": 1,
+ "b": 0,
+ "a": 1
+ }
+ }
+ }
+ ]
+ }
+ ]
+}
diff --git a/desktop/public/scenes/camera-tilt.textures.json b/desktop/public/scenes/camera-tilt.textures.json
new file mode 100644
index 000000000..0967ef424
--- /dev/null
+++ b/desktop/public/scenes/camera-tilt.textures.json
@@ -0,0 +1 @@
+{}
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 71ff70d13..e99985cc9 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1534,6 +1534,7 @@ pixelPerfect: boolean
priority: number
projection: number
rotation: number
+tilt: { x: number; y: number; z: number; w: number; } | undefined
viewport: { x: number; y: number; z: number; w: number; }
x: number
y: number
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index ca1fef750..919eac4aa 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -1534,6 +1534,7 @@ pixelPerfect: boolean
priority: number
projection: number
rotation: number
+tilt: { x: number; y: number; z: number; w: number; } | undefined
viewport: { x: number; y: number; z: number; w: number; }
x: number
y: number
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 716326b18..bbeec89d6 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1529,6 +1529,7 @@ pixelPerfect: boolean
priority: number
projection: number
rotation: number
+tilt: { x: number; y: number; z: number; w: number; } | undefined
viewport: { x: number; y: number; z: number; w: number; }
x: number
y: number
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index de6c4229c..6b457cbf5 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1529,6 +1529,7 @@ pixelPerfect: boolean
priority: number
projection: number
rotation: number
+tilt: { x: number; y: number; z: number; w: number; } | undefined
viewport: { x: number; y: number; z: number; w: number; }
x: number
y: number
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 599a1364f..ea4dd293b 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1529,6 +1529,7 @@ pixelPerfect: boolean
priority: number
projection: number
rotation: number
+tilt: { x: number; y: number; z: number; w: number; } | undefined
viewport: { x: number; y: number; z: number; w: number; }
x: number
y: number
diff --git a/sdk/src/camera/CameraPlugin.ts b/sdk/src/camera/CameraPlugin.ts
index 38a2953f1..2fbfb2d83 100644
--- a/sdk/src/camera/CameraPlugin.ts
+++ b/sdk/src/camera/CameraPlugin.ts
@@ -25,7 +25,7 @@ import { RenderPipeline } from '../render/renderPipeline';
import { Renderer } from '../render/renderer';
import { platformNow, platformDevicePixelRatio } from '../platform';
import { SceneManager } from '../scene/sceneManager';
-import { ortho, perspective, invertViewZ, invertViewOrbit, multiply, IDENTITY } from '../math/mat4';
+import { ortho, perspective, invertViewZ, invertViewOrbit, invertViewQuat, multiply, IDENTITY } from '../math/mat4';
// =============================================================================
// Camera Info
@@ -150,6 +150,12 @@ export interface CameraPOV {
y: number;
z: number;
rotation: number; // Z rotation, radians
+ /**
+ * The camera's full orientation, when it is turned off the 2D plane. Absent
+ * for a rotation purely about Z — which every 2D camera is, and which the
+ * scalar above already says — so turning this on cannot move a 2D scene.
+ */
+ tilt?: { x: number; y: number; z: number; w: number };
/** Orbit about (x, y, z) in radians — an eye that stands off the -Z axis.
* Absent (the 2D case) keeps the rotation-about-Z view exactly as it was. */
orbit?: { yaw: number; pitch: number };
@@ -189,6 +195,9 @@ function readCameraPOV(
y: transform.position.y,
z: transform.position.z,
rotation: 2 * Math.atan2(q.z, q.w), // quaternion → Z angle (2D convention)
+ // Kept whole only when it says something the Z angle cannot: a camera
+ // that looks at 3D content from anywhere but straight down -Z.
+ tilt: (q.x !== 0 || q.y !== 0) ? { x: q.x, y: q.y, z: q.z, w: q.w } : undefined,
projection: camera.projectionType,
orthoSize: camera.orthoSize,
fov: camera.fov,
@@ -251,11 +260,14 @@ export function buildCameraInfo(
camY = snapToPixelGrid(pov.y, worldPerPixel);
}
- // An orbited camera stands off the axis, so its view comes from the focus it
- // turns around; without one the 2D path is untouched.
+ // Three ways to say where the eye is, one view: an orbit turns around a focus
+ // (editor navigation), a tilt is the camera's own transform inverted (a scene
+ // camera on 3D content), and 2D is the rotation-about-Z, untouched.
const view = pov.orbit
? invertViewOrbit(camX, camY, 0, pov.orbit.yaw, pov.orbit.pitch, pov.z)
- : invertViewZ(camX, camY, pov.z, Math.cos(pov.rotation), Math.sin(pov.rotation));
+ : pov.tilt
+ ? invertViewQuat(camX, camY, pov.z, pov.tilt.x, pov.tilt.y, pov.tilt.z, pov.tilt.w)
+ : invertViewZ(camX, camY, pov.z, Math.cos(pov.rotation), Math.sin(pov.rotation));
const cam = acquireCameraInfo(pool, index);
cam.entity = pov.entity;
cam.viewProjection.set(multiply(projection, view));
diff --git a/sdk/src/math/mat4.ts b/sdk/src/math/mat4.ts
index 9492315c1..09338da9d 100644
--- a/sdk/src/math/mat4.ts
+++ b/sdk/src/math/mat4.ts
@@ -79,6 +79,38 @@ export function invertViewZ(
return m;
}
+const _viewQM = new Float32Array(16);
+
+/**
+ * The view matrix of a camera at (x, y, z) turned by a quaternion — the inverse
+ * of its own transform, which is what a camera's view IS.
+ *
+ * A rotation purely about Z reproduces {@link invertViewZ} cell for cell, so the
+ * 2D camera is this one's special case rather than a different path.
+ */
+export function invertViewQuat(
+ x: number, y: number, z: number,
+ qx: number, qy: number, qz: number, qw: number,
+): Float32Array {
+ const xx = qx * qx, yy = qy * qy, zz = qz * qz;
+ const xy = qx * qy, xz = qx * qz, yz = qy * qz;
+ const wx = qw * qx, wy = qw * qy, wz = qw * qz;
+ // The rotation's own basis; the view takes its transpose (an inverse rotation).
+ const r00 = 1 - 2 * (yy + zz), r01 = 2 * (xy - wz), r02 = 2 * (xz + wy);
+ const r10 = 2 * (xy + wz), r11 = 1 - 2 * (xx + zz), r12 = 2 * (yz - wx);
+ const r20 = 2 * (xz - wy), r21 = 2 * (yz + wx), r22 = 1 - 2 * (xx + yy);
+
+ const m = _viewQM;
+ m[0] = r00; m[1] = r01; m[2] = r02; m[3] = 0;
+ m[4] = r10; m[5] = r11; m[6] = r12; m[7] = 0;
+ m[8] = r20; m[9] = r21; m[10] = r22; m[11] = 0;
+ m[12] = -(r00 * x + r10 * y + r20 * z);
+ m[13] = -(r01 * x + r11 * y + r21 * z);
+ m[14] = -(r02 * x + r12 * y + r22 * z);
+ m[15] = 1;
+ return m;
+}
+
const _orbitM = new Float32Array(16);
/**
diff --git a/sdk/tests/editor-view-orbit.test.ts b/sdk/tests/editor-view-orbit.test.ts
index b131cbfc1..aa77bcf70 100644
--- a/sdk/tests/editor-view-orbit.test.ts
+++ b/sdk/tests/editor-view-orbit.test.ts
@@ -8,8 +8,8 @@
* turned one against where a point lands.
*/
import { describe, expect, it } from 'vitest';
-import { invertViewZ, invertViewOrbit, multiply, perspective, ortho } from '../src/math/mat4';
-import { editorCameraInfo } from '../src/camera/CameraPlugin';
+import { invertViewZ, invertViewOrbit, invertViewQuat, multiply, perspective, ortho } from '../src/math/mat4';
+import { editorCameraInfo, buildCameraInfo } from '../src/camera/CameraPlugin';
import {
DEFAULT_EDITOR_VIEW, editorViewIsOrbited, editorViewAxes, editorViewAxisAngles, editorViewHalfHeight,
} from '../src/camera/EditorView';
@@ -136,3 +136,46 @@ describe('where the world axes point on screen', () => {
}
});
});
+
+describe('a scene camera that looks from somewhere else', () => {
+ const cells = (m: Float32Array) => Array.from(m, v => v + 0);
+
+ it.each([0, 0.7, -2.1])('is the 2D view exactly, for a Z rotation of %s rad', (angle) => {
+ // A camera's view IS its own transform inverted; the 2D path builds that
+ // from an angle. If the two ever differ, giving cameras a full orientation
+ // moves every 2D scene — so this is asserted cell for cell.
+ const q = { x: 0, y: 0, z: Math.sin(angle / 2), w: Math.cos(angle / 2) };
+ expect(cells(invertViewQuat(30, -40, 500, q.x, q.y, q.z, q.w)))
+ .toEqual(cells(invertViewZ(30, -40, 500, Math.cos(angle), Math.sin(angle))));
+ });
+
+ it('sees depth once it is tilted, where the 2D camera cannot', () => {
+ // Pitched down 30°: content further along +Y is nearer the horizon, which
+ // is the whole reason a game camera needs an orientation at all.
+ const half = (15 * Math.PI) / 180;
+ const view = invertViewQuat(0, 0, 500, -Math.sin(half), 0, 0, Math.cos(half));
+ const vp = multiply(ortho(-400, 400, -400, 400, -2000, 2000), view);
+ const near = project(vp, 0, -200, 0);
+ const far = project(vp, 0, 200, 0);
+ expect(far.y).toBeGreaterThan(near.y);
+ // ...and the same points are FLAT under the 2D camera, which is the contrast.
+ const flat = multiply(ortho(-400, 400, -400, 400, -2000, 2000), invertViewZ(0, 0, 500, 1, 0));
+ expect(project(flat, 0, 200, 0).y - project(flat, 0, -200, 0).y)
+ .toBeGreaterThan(far.y - near.y);
+ });
+
+ it('carries a tilted camera through the POV the renderer reads', () => {
+ const half = (20 * Math.PI) / 180;
+ const pov = {
+ entity: 1, isActive: true, x: 0, y: 0, z: 500, rotation: 0,
+ tilt: { x: -Math.sin(half), y: 0, z: 0, w: Math.cos(half) },
+ projection: 1, orthoSize: 400, fov: 60, near: 0.1, far: 2000,
+ viewport: { x: 0, y: 0, z: 1, w: 1 }, clearFlags: 0, priority: 0,
+ pixelPerfect: false, cullingMask: 0xFFFFFFFF,
+ };
+ const cam = buildCameraInfo(pov, 256, 256, null, [], 0);
+ // Ground that is further away rides UP the screen, exactly as the matrix says.
+ expect(project(cam.viewProjection, 0, 200, 0).y)
+ .toBeGreaterThan(project(cam.viewProjection, 0, -200, 0).y);
+ });
+});
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index aca5419ac..86efba6b1 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -148,6 +148,10 @@ export const SCENES = [
// path. What it adds over a material ball is the FRAMING: the gate asks for a
// clear border (nothing escaped) and an outer eighth reached (nothing shrank).
{ id: "mesh-preview", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_MESH_PREVIEW: "{\"w\":128,\"h\":128}", ESTELLA_VERIFY_MESH_ASSET: "/scenes/lit-triangles.esmesh", ESTELLA_VERIFY_SCENE: "/scenes/mesh-lit.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mesh-lit.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4" } },
+ // A SCENE camera that looks from somewhere else. Two sprites on the camera's
+ // own axis project to ONE point for a 2D camera; pitched 20 deg they land at
+ // 0.329 and 0.158 down the frame — arithmetic — and the centre is empty.
+ { id: "camera-tilt", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/camera-tilt.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/camera-tilt.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.329,\"rgb\":[255,0,0],\"tol\":40},{\"x\":0.5,\"y\":0.158,\"rgb\":[0,255,0],\"tol\":40},{\"x\":0.5,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":30}]" } },
// A mesh assigned IN THE EDITOR: a cold ref reaches the World only through the
// live loader + re-projection. The quad covers the gap between the scene's own
// two triangles, so the frame says which geometry is drawn — and the hit test