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): the projection can be asked its slope at a point
esengine139aba172d31
diff --git a/desktop b/desktopindex 199adce1b..4c2de5d60 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 199adce1bfa0323d8757134ea7e27bc9aee48a98+Subproject commit 4c2de5d6034e33e9376cd47e2e2ae735608fa69cdiff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 76cf3a63f..19aef33d1 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1812,6 +1812,7 @@ ResourceDef<CameraViewAPI>```getWorldBounds: () => { left: number; right: number; bottom: number; top: number; } | nullgetWorldMousePosition: () => { x: number; y: number; } | null+projectDirectionAt: (at: Vec3, dir: Vec3) => { x: number; y: number; } | nullscreenRay: (screenX: number, screenY: number) => WorldRay | nullscreenToWorld: (screenX: number, screenY: number, planeZ?: number) => { x: number; y: number; } | nullworldToScreen: (worldX: number, worldY: number, worldZ?: number) => { x: number; y: number; } | nulldiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex c35e28b24..1a5a2df08 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1812,6 +1812,7 @@ ResourceDef<CameraViewAPI>```getWorldBounds: () => { left: number; right: number; bottom: number; top: number; } | nullgetWorldMousePosition: () => { x: number; y: number; } | null+projectDirectionAt: (at: Vec3, dir: Vec3) => { x: number; y: number; } | nullscreenRay: (screenX: number, screenY: number) => WorldRay | nullscreenToWorld: (screenX: number, screenY: number, planeZ?: number) => { x: number; y: number; } | nullworldToScreen: (worldX: number, worldY: number, worldZ?: number) => { x: number; y: number; } | nulldiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 0f94f7719..56ad433fd 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1807,6 +1807,7 @@ ResourceDef<CameraViewAPI>```getWorldBounds: () => { left: number; right: number; bottom: number; top: number; } | nullgetWorldMousePosition: () => { x: number; y: number; } | null+projectDirectionAt: (at: Vec3, dir: Vec3) => { x: number; y: number; } | nullscreenRay: (screenX: number, screenY: number) => WorldRay | nullscreenToWorld: (screenX: number, screenY: number, planeZ?: number) => { x: number; y: number; } | nullworldToScreen: (worldX: number, worldY: number, worldZ?: number) => { x: number; y: number; } | nulldiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 0f5fe65c9..7189c3a2f 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1807,6 +1807,7 @@ ResourceDef<CameraViewAPI>```getWorldBounds: () => { left: number; right: number; bottom: number; top: number; } | nullgetWorldMousePosition: () => { x: number; y: number; } | null+projectDirectionAt: (at: Vec3, dir: Vec3) => { x: number; y: number; } | nullscreenRay: (screenX: number, screenY: number) => WorldRay | nullscreenToWorld: (screenX: number, screenY: number, planeZ?: number) => { x: number; y: number; } | nullworldToScreen: (worldX: number, worldY: number, worldZ?: number) => { x: number; y: number; } | nulldiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex b01f89f71..51569cfaa 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1807,6 +1807,7 @@ ResourceDef<CameraViewAPI>```getWorldBounds: () => { left: number; right: number; bottom: number; top: number; } | nullgetWorldMousePosition: () => { x: number; y: number; } | null+projectDirectionAt: (at: Vec3, dir: Vec3) => { x: number; y: number; } | nullscreenRay: (screenX: number, screenY: number) => WorldRay | nullscreenToWorld: (screenX: number, screenY: number, planeZ?: number) => { x: number; y: number; } | nullworldToScreen: (worldX: number, worldY: number, worldZ?: number) => { x: number; y: number; } | nulldiff --git a/sdk/src/camera/Camera.ts b/sdk/src/camera/Camera.tsindex 5201a476f..997fa9b82 100644--- a/sdk/src/camera/Camera.ts+++ b/sdk/src/camera/Camera.ts@@ -3,7 +3,8 @@import type { App } from '../app/app';import { defineResource } from '../ecs/resource';import { UICameraInfo, type UICameraData } from '../ui/core/ui-camera-info';-import { screenToWorld, projectWorldPoint, isProjectable, createInvVPCache, screenRay, type WorldRay } from '../ui/util/math';+import type { Vec3 } from '../types';+import { screenToWorld, projectWorldPoint, projectDirectionAt, isProjectable, createInvVPCache, screenRay, type WorldRay } from '../ui/util/math';/*** Per-App camera-space query API: screen<->world conversions, the world-space@@ -74,6 +75,23 @@ export class CameraViewAPI {return isProjectable(p) ? { x: p.x, y: p.y } : null;}+ /**+ * Where a world DIRECTION points on screen at @p at — px per world unit, y-up.+ *+ * @details Null when @p at has no projection. Perspective makes this a fact+ * about the POINT: an arm drawn on something asks here, where a basis+ * read off the camera answers only for the centre of the view.+ */+ projectDirectionAt(at: Vec3, dir: Vec3): { x: number; y: number } | null {+ const cam = this.cam();+ if (!cam) return null;+ const p = projectWorldPoint(at.x, at.y, at.z,+ cam.viewProjection, cam.vpX, cam.vpY, cam.vpW, cam.vpH);+ if (!isProjectable(p)) return null;+ return projectDirectionAt(p, dir.x, dir.y, dir.z,+ cam.viewProjection, cam.vpX, cam.vpY, cam.vpW, cam.vpH);+ }+getWorldMousePosition(): { x: number; y: number } | null {const cam = this.cam();if (!cam) return null;diff --git a/sdk/src/ui/index.ts b/sdk/src/ui/index.tsindex d7494e0d2..7a4706eb4 100644--- a/sdk/src/ui/index.ts+++ b/sdk/src/ui/index.ts@@ -340,6 +340,7 @@ export {pointInOBB,quaternionToAngle2D,projectWorldPoint,+ projectDirectionAt,isProjectable,createInvVPCache,type ScreenRect,diff --git a/sdk/src/ui/util/math.ts b/sdk/src/ui/util/math.tsindex b933c4cab..34e82edc3 100644--- a/sdk/src/ui/util/math.ts+++ b/sdk/src/ui/util/math.ts@@ -187,6 +187,29 @@ export function projectWorldPoint(};}+/**+ * How a world direction moves the projection of its own anchor, in viewport+ * pixels per world unit, y-up.+ *+ * @details Under perspective the answer depends on the POINT: the divide by w+ * swings an axis's screen direction with where it stands.+ */+export function projectDirectionAt(+ at: ProjectedPoint,+ dx: number, dy: number, dz: number,+ vp: Float32Array, vpX: number, vpY: number, vpW: number, vpH: number,+): { x: number; y: number } {+ const ndcX = ((at.x - vpX) / vpW) * 2 - 1;+ const ndcY = ((at.y - vpY) / vpH) * 2 - 1;+ const cx = vp[0] * dx + vp[4] * dy + vp[8] * dz;+ const cy = vp[1] * dx + vp[5] * dy + vp[9] * dz;+ const cw = vp[3] * dx + vp[7] * dy + vp[11] * dz;+ return {+ x: ((cx - ndcX * cw) / at.clipW) * 0.5 * vpW,+ y: ((cy - ndcY * cw) / at.clipW) * 0.5 * vpH,+ };+}+export function createInvVPCache() {const invVP = new Float32Array(16);const cachedVP = new Float32Array(16);diff --git a/sdk/tests/uiMath.test.ts b/sdk/tests/uiMath.test.tsindex c250a6d1c..178be4fd3 100644--- a/sdk/tests/uiMath.test.ts+++ b/sdk/tests/uiMath.test.ts@@ -8,13 +8,14 @@ import {pointInWorldRect,quaternionToAngle2D,projectWorldPoint,+ projectDirectionAt,isProjectable,createInvVPCache,pointInOBB,screenRay,rayPlaneHit,} from '../src/ui/util/math';-import type { ScreenRect } from '../src/ui/util/math';+import type { ScreenRect, ProjectedPoint } from '../src/ui/util/math';// =============================================================================// Helpers@@ -663,6 +664,59 @@ describe('projectWorldPoint says whether a point has a screen position at all',});});+describe('projectDirectionAt answers for the point, not just for the camera', () => {+ const VP_W = 830;+ const VP_H = 494;+ const ASPECT = VP_W / VP_H;+ const project = (vp: Float32Array, x: number, y: number, z: number): ProjectedPoint =>+ projectWorldPoint(x, y, z, vp, 0, 0, VP_W, VP_H);+ const direction = (vp: Float32Array, at: ProjectedPoint, d: readonly number[]) =>+ projectDirectionAt(at, d[0], d[1], d[2], vp, 0, 0, VP_W, VP_H);++ // The derivative and the projector have to be the same function, or an arm is+ // drawn along one and dragged along the other.+ it('is the projection own slope, to the digit a difference can measure', () => {+ const vp = perspective4(Math.PI / 3, ASPECT, 1, 5000);+ const h = 1e-4;+ for (const [x, y, z] of [[0, 0, -600], [500, 200, -600], [-320, -90, -1800]]) {+ for (const d of [[1, 0, 0], [0, 1, 0], [0, 0, 1]]) {+ const here = project(vp, x, y, z);+ const step = project(vp, x + d[0] * h, y + d[1] * h, z + d[2] * h);+ const slope = direction(vp, here, d);+ expect(slope.x).toBeCloseTo((step.x - here.x) / h, 4);+ expect(slope.y).toBeCloseTo((step.y - here.y) / h, 4);+ }+ }+ });++ // Orthographically there is no divide to vary, so the camera alone DOES answer+ // — which is why a basis read off it was right until the eye gained a fov.+ it('is the same everywhere under an orthographic projection', () => {+ const vp = ortho4(160 * ASPECT, 160, 4000);+ for (const d of [[1, 0, 0], [0, 1, 0], [0, 0, 1]]) {+ const centre = direction(vp, project(vp, 0, 0, 0), d);+ const corner = direction(vp, project(vp, 150 * ASPECT, 140, -900), d);+ expect(corner.x).toBeCloseTo(centre.x, 9);+ expect(corner.y).toBeCloseTo(centre.y, 9);+ }+ });++ // Head-on, world Z runs straight at the eye and projects to nothing — AT THE+ // CENTRE. Off to the side the same axis leans outward, and by a length worth+ // grabbing: the arm a camera-only basis draws as zero everywhere.+ it('turns the axis that runs at the eye into a real arm off-centre', () => {+ const vp = perspective4(Math.PI / 3, ASPECT, 1, 5000);+ const centre = direction(vp, project(vp, 0, 0, -600), [0, 0, 1]);+ expect(Math.hypot(centre.x, centre.y)).toBeLessThan(1e-9);++ const at = project(vp, 500, 0, -600);+ const alongZ = direction(vp, at, [0, 0, 1]);+ const alongX = direction(vp, at, [1, 0, 0]);+ expect(alongZ.x).toBeGreaterThan(0); // outward, toward the edge it sits near+ expect(Math.hypot(alongZ.x, alongZ.y)).toBeGreaterThan(Math.hypot(alongX.x, alongX.y) * 0.5);+ });+});+/*** The property a game reads a click through, spelled out.*