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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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.esscenenew file mode 100644index 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.jsonnew file mode 100644index 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.mdindex 71ff70d13..e99985cc9 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1534,6 +1534,7 @@ pixelPerfect: booleanpriority: numberprojection: numberrotation: number+tilt: { x: number; y: number; z: number; w: number; } | undefinedviewport: { x: number; y: number; z: number; w: number; }x: numbery: numberdiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex ca1fef750..919eac4aa 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1534,6 +1534,7 @@ pixelPerfect: booleanpriority: numberprojection: numberrotation: number+tilt: { x: number; y: number; z: number; w: number; } | undefinedviewport: { x: number; y: number; z: number; w: number; }x: numbery: numberdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 716326b18..bbeec89d6 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1529,6 +1529,7 @@ pixelPerfect: booleanpriority: numberprojection: numberrotation: number+tilt: { x: number; y: number; z: number; w: number; } | undefinedviewport: { x: number; y: number; z: number; w: number; }x: numbery: numberdiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex de6c4229c..6b457cbf5 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1529,6 +1529,7 @@ pixelPerfect: booleanpriority: numberprojection: numberrotation: number+tilt: { x: number; y: number; z: number; w: number; } | undefinedviewport: { x: number; y: number; z: number; w: number; }x: numbery: numberdiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 599a1364f..ea4dd293b 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1529,6 +1529,7 @@ pixelPerfect: booleanpriority: numberprojection: numberrotation: number+tilt: { x: number; y: number; z: number; w: number; } | undefinedviewport: { x: number; y: number; z: number; w: number; }x: numbery: numberdiff --git a/sdk/src/camera/CameraPlugin.ts b/sdk/src/camera/CameraPlugin.tsindex 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.tsindex 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.tsindex 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.mjsindex 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