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): the projection can be asked its slope at a point

esengine139aba172d31
diff --git a/desktop b/desktop
index 199adce1b..4c2de5d60 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 199adce1bfa0323d8757134ea7e27bc9aee48a98
+Subproject commit 4c2de5d6034e33e9376cd47e2e2ae735608fa69c
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 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; } | null
getWorldMousePosition: () => { x: number; y: number; } | null
+projectDirectionAt: (at: Vec3, dir: Vec3) => { x: number; y: number; } | null
screenRay: (screenX: number, screenY: number) => WorldRay | null
screenToWorld: (screenX: number, screenY: number, planeZ?: number) => { x: number; y: number; } | null
worldToScreen: (worldX: number, worldY: number, worldZ?: number) => { x: number; y: number; } | null
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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; } | null
getWorldMousePosition: () => { x: number; y: number; } | null
+projectDirectionAt: (at: Vec3, dir: Vec3) => { x: number; y: number; } | null
screenRay: (screenX: number, screenY: number) => WorldRay | null
screenToWorld: (screenX: number, screenY: number, planeZ?: number) => { x: number; y: number; } | null
worldToScreen: (worldX: number, worldY: number, worldZ?: number) => { x: number; y: number; } | null
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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; } | null
getWorldMousePosition: () => { x: number; y: number; } | null
+projectDirectionAt: (at: Vec3, dir: Vec3) => { x: number; y: number; } | null
screenRay: (screenX: number, screenY: number) => WorldRay | null
screenToWorld: (screenX: number, screenY: number, planeZ?: number) => { x: number; y: number; } | null
worldToScreen: (worldX: number, worldY: number, worldZ?: number) => { x: number; y: number; } | null
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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; } | null
getWorldMousePosition: () => { x: number; y: number; } | null
+projectDirectionAt: (at: Vec3, dir: Vec3) => { x: number; y: number; } | null
screenRay: (screenX: number, screenY: number) => WorldRay | null
screenToWorld: (screenX: number, screenY: number, planeZ?: number) => { x: number; y: number; } | null
worldToScreen: (worldX: number, worldY: number, worldZ?: number) => { x: number; y: number; } | null
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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; } | null
getWorldMousePosition: () => { x: number; y: number; } | null
+projectDirectionAt: (at: Vec3, dir: Vec3) => { x: number; y: number; } | null
screenRay: (screenX: number, screenY: number) => WorldRay | null
screenToWorld: (screenX: number, screenY: number, planeZ?: number) => { x: number; y: number; } | null
worldToScreen: (worldX: number, worldY: number, worldZ?: number) => { x: number; y: number; } | null
diff --git a/sdk/src/camera/Camera.ts b/sdk/src/camera/Camera.ts
index 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.ts
index 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.ts
index 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.ts
index 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.
*