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 segment can be asked for the part of it that is drawable

esengine9c9db09f4443
diff --git a/desktop b/desktop
index db6e56e0f..dede3f687 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit db6e56e0f1b852f50d6ca8a3c3ed8c1009a66e7e
+Subproject commit dede3f6877dbe151a4c746bf1bdada69ec8f71a5
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 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; } | null
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
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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; } | null
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
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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; } | null
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
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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; } | null
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
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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; } | null
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
diff --git a/sdk/src/camera/Camera.ts b/sdk/src/camera/Camera.ts
index 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.ts
index 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.ts
index 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.ts
index 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;