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 segment can be asked for the part of it that is drawable
esengine9c9db09f4443
diff --git a/desktop b/desktopindex db6e56e0f..dede3f687 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit db6e56e0f1b852f50d6ca8a3c3ed8c1009a66e7e+Subproject commit dede3f6877dbe151a4c746bf1bdada69ec8f71a5diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 19aef33d1..b699104d5 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1810,6 +1810,7 @@ ResourceDef<CameraViewAPI>## CameraViewAPI — class @experimental```+clipSegment: (a: Vec3, b: Vec3) => { a: Vec3; b: Vec3; } | nullgetWorldBounds: () => { left: number; right: number; bottom: number; top: number; } | nullgetWorldMousePosition: () => { x: number; y: number; } | nullprojectDirectionAt: (at: Vec3, dir: Vec3) => { x: number; y: number; } | nulldiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 1a5a2df08..c50dde2e7 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1810,6 +1810,7 @@ ResourceDef<CameraViewAPI>## CameraViewAPI — class @experimental```+clipSegment: (a: Vec3, b: Vec3) => { a: Vec3; b: Vec3; } | nullgetWorldBounds: () => { left: number; right: number; bottom: number; top: number; } | nullgetWorldMousePosition: () => { x: number; y: number; } | nullprojectDirectionAt: (at: Vec3, dir: Vec3) => { x: number; y: number; } | nulldiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 56ad433fd..b57e388b7 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1805,6 +1805,7 @@ ResourceDef<CameraViewAPI>## CameraViewAPI — class @experimental```+clipSegment: (a: Vec3, b: Vec3) => { a: Vec3; b: Vec3; } | nullgetWorldBounds: () => { left: number; right: number; bottom: number; top: number; } | nullgetWorldMousePosition: () => { x: number; y: number; } | nullprojectDirectionAt: (at: Vec3, dir: Vec3) => { x: number; y: number; } | nulldiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 7189c3a2f..5bb81243b 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1805,6 +1805,7 @@ ResourceDef<CameraViewAPI>## CameraViewAPI — class @experimental```+clipSegment: (a: Vec3, b: Vec3) => { a: Vec3; b: Vec3; } | nullgetWorldBounds: () => { left: number; right: number; bottom: number; top: number; } | nullgetWorldMousePosition: () => { x: number; y: number; } | nullprojectDirectionAt: (at: Vec3, dir: Vec3) => { x: number; y: number; } | nulldiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 51569cfaa..54a2d0f89 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1805,6 +1805,7 @@ ResourceDef<CameraViewAPI>## CameraViewAPI — class @experimental```+clipSegment: (a: Vec3, b: Vec3) => { a: Vec3; b: Vec3; } | nullgetWorldBounds: () => { left: number; right: number; bottom: number; top: number; } | nullgetWorldMousePosition: () => { x: number; y: number; } | nullprojectDirectionAt: (at: Vec3, dir: Vec3) => { x: number; y: number; } | nulldiff --git a/sdk/src/camera/Camera.ts b/sdk/src/camera/Camera.tsindex 997fa9b82..b51d81651 100644--- a/sdk/src/camera/Camera.ts+++ b/sdk/src/camera/Camera.ts@@ -4,7 +4,7 @@ import type { App } from '../app/app';import { defineResource } from '../ecs/resource';import { UICameraInfo, type UICameraData } from '../ui/core/ui-camera-info';import type { Vec3 } from '../types';-import { screenToWorld, projectWorldPoint, projectDirectionAt, isProjectable, createInvVPCache, screenRay, type WorldRay } from '../ui/util/math';+import { screenToWorld, projectWorldPoint, projectDirectionAt, nearPlaneSide, isProjectable, createInvVPCache, screenRay, type WorldRay } from '../ui/util/math';/*** Per-App camera-space query API: screen<->world conversions, the world-space@@ -15,6 +15,9 @@ import { screenToWorld, projectWorldPoint, projectDirectionAt, isProjectable, cr* inverse-view-projection cache, so two Apps running at once never share a* single cached `app` or clobber each other's cache.*/+/** How far inside the near plane a cut lands, as a fraction of the segment. */+const CLIP_NUDGE = 1e-4;+export class CameraViewAPI {private readonly invVPCache = createInvVPCache();@@ -75,6 +78,32 @@ export class CameraViewAPI {return isProjectable(p) ? { x: p.x, y: p.y } : null;}+ /**+ * The part of segment @p a → @p b that can be drawn, cut at the near plane.+ *+ * @details One end behind the eye still leaves a visible part, and dropping the+ * whole segment is what makes a wireframe come apart as the eye moves+ * into it. Null when none of it is in front.+ */+ clipSegment(a: Vec3, b: Vec3): { a: Vec3; b: Vec3 } | null {+ const cam = this.cam();+ if (!cam) return null;+ const at = (p: Vec3) => projectWorldPoint(p.x, p.y, p.z,+ cam.viewProjection, cam.vpX, cam.vpY, cam.vpW, cam.vpH);+ const sa = nearPlaneSide(at(a));+ const sb = nearPlaneSide(at(b));+ if (sa >= 0 && sb >= 0) return { a, b };+ if (sa < 0 && sb < 0) return null;+ const cross = sa / (sa - sb);+ const t = sa >= 0 ? cross * (1 - CLIP_NUDGE) : cross + (1 - cross) * CLIP_NUDGE;+ const cut = {+ x: a.x + (b.x - a.x) * t,+ y: a.y + (b.y - a.y) * t,+ z: a.z + (b.z - a.z) * t,+ };+ return sa >= 0 ? { a, b: cut } : { a: cut, b };+ }+/*** Where a world DIRECTION points on screen at @p at — px per world unit, y-up.*diff --git a/sdk/src/ui/index.ts b/sdk/src/ui/index.tsindex 7a4706eb4..c635cfba1 100644--- a/sdk/src/ui/index.ts+++ b/sdk/src/ui/index.ts@@ -341,6 +341,7 @@ export {quaternionToAngle2D,projectWorldPoint,projectDirectionAt,+ nearPlaneSide,isProjectable,createInvVPCache,type ScreenRect,diff --git a/sdk/src/ui/util/math.ts b/sdk/src/ui/util/math.tsindex 34e82edc3..47ffa7293 100644--- a/sdk/src/ui/util/math.ts+++ b/sdk/src/ui/util/math.ts@@ -187,6 +187,17 @@ export function projectWorldPoint(};}+/**+ * How far a projected point is in FRONT of the near plane, in clip units.+ *+ * @details Negative behind it, and affine along a world segment — so where a+ * segment crosses solves for one t, and the world point at that t is the+ * furthest the segment can be drawn to.+ */+export function nearPlaneSide(p: ProjectedPoint): number {+ return p.clipZ + p.clipW;+}+/*** How a world direction moves the projection of its own anchor, in viewport* pixels per world unit, y-up.diff --git a/sdk/tests/uiMath.test.ts b/sdk/tests/uiMath.test.tsindex 178be4fd3..732ea08e4 100644--- a/sdk/tests/uiMath.test.ts+++ b/sdk/tests/uiMath.test.ts@@ -9,6 +9,7 @@ import {quaternionToAngle2D,projectWorldPoint,projectDirectionAt,+ nearPlaneSide,isProjectable,createInvVPCache,pointInOBB,@@ -664,6 +665,44 @@ describe('projectWorldPoint says whether a point has a screen position at all',});});+describe('nearPlaneSide is what a segment is cut on', () => {+ const vp = perspective4(Math.PI / 2, 4 / 3, 10, 1000);+ const side = (x: number, y: number, z: number) =>+ nearPlaneSide(projectWorldPoint(x, y, z, vp, 0, 0, 640, 480));++ it('is zero on the near plane and signed either side of it', () => {+ expect(side(0, 0, -10)).toBeCloseTo(0, 6);+ expect(side(0, 0, -200)).toBeGreaterThan(0);+ expect(side(0, 0, -1)).toBeLessThan(0); // between the eye and the near plane+ expect(side(0, 0, 200)).toBeLessThan(0); // behind the eye+ });++ // The whole cut rests on this: one crossing, solved for one t, and the world+ // point at that t is where the drawable part ends.+ it('is affine along a world segment', () => {+ const a = { x: -300, y: 120, z: -400 };+ const b = { x: 500, y: -80, z: 300 };+ const sa = side(a.x, a.y, a.z);+ const sb = side(b.x, b.y, b.z);+ for (const t of [0.1, 0.37, 0.5, 0.9]) {+ const mid = side(a.x + (b.x - a.x) * t, a.y + (b.y - a.y) * t, a.z + (b.z - a.z) * t);+ expect(mid).toBeCloseTo(sa + (sb - sa) * t, 6);+ }+ // And it does cross, or the case above is never exercised.+ expect(sa * sb).toBeLessThan(0);+ });++ // Orthographically w does not vary and the volume the editor builds is vast, so+ // nothing a 2D scene contains is ever on the wrong side of this.+ it('keeps every depth a 2D scene uses under an orthographic projection', () => {+ const flat = ortho4(160, 120, 100000);+ for (const z of [-4000, -400, 0, 400]) {+ expect(nearPlaneSide(projectWorldPoint(80, -30, z, flat, 0, 0, 640, 480)))+ .toBeGreaterThan(0);+ }+ });+});+describe('projectDirectionAt answers for the point, not just for the camera', () => {const VP_W = 830;const VP_H = 494;