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(editor): an entity's box has a third dimension, and one hit test uses it

yhh36947edb0566
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f171e5ed1..620898f2e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,35 @@ published separately; it ships inside the editor.
### Added
+- **An entity's box has a third dimension, and one hit test uses it.** `EntityBox`
+ was `{cx, cy, hw, hh, rot}` with `rot` the Z angle of a quaternion, and the
+ engine answered a mesh's extent with its XY bounds. So a model turned about X or
+ Y had a box that did not turn with it, and a click was the cursor unprojected
+ onto that entity's own z plane and tested against a rect — an answer that is
+ right only while the eye is head-on.
+
+ The box is an oriented box now: a centre, half-extents on its own three axes,
+ and the rotation the renderer draws it with. A sprite and a UI node are flat
+ (`hd` zero), which is what they are; an icon is a cube, so a camera or a light
+ reads and clicks the same from wherever the view has been turned to. A click is
+ a ray, and `entityBoxRayHit` is the slab test against it — where a flat box is
+ not a degenerate case but a quad, met by a ray in its own plane, which is what a
+ 2D editor asking "is the cursor on this sprite" has always meant.
+
+ The editor and a running game asked that question twice, and the two had
+ drifted: the play realm boxed a model by its transform alone, so a click
+ anywhere on an imported mesh landed on whatever was behind it. There is one
+ `pickEntitiesByRay` now; each realm passes its own camera, its own refusals, and
+ whether it draws gizmos to aim at. The ray decides what is hit and the layer
+ rules still decide which hit is on top, because that is what the renderer
+ stacked them by.
+
+ Outlines follow: every corner projects through its own depth rather than one
+ shared plane, and a box's screen outline is the convex hull of those corners —
+ four points while it is flat, more once it has depth to turn. `q.rotate` and
+ `q.conjugate` join the math module, where the one copy of turning a vector by a
+ rotation now lives.
+
- **The editor's view has a focus in space, and a plane it works on.** The editor
eye could turn, and everything else about it was still pinned to z = 0: it
orbited a point on that plane, panned across it, framed on it, and drew its grid
diff --git a/desktop/src/engine/ViewportController.ts b/desktop/src/engine/ViewportController.ts
index c664af3e3..c19c6b650 100644
--- a/desktop/src/engine/ViewportController.ts
+++ b/desktop/src/engine/ViewportController.ts
@@ -14,9 +14,9 @@ import {
BoxCollider3D, SphereCollider3D, CapsuleCollider3D, MeshCollider3D, CharacterController3D,
readCollider3DShapes, collider3DWireframe, placeCollider3DWireframe,
readJoint3D, rotateVec3ByQuat,
- layerOrderOf,
editorViewHalfHeight, editorViewHalfExtent, setEditorViewHalfHeight, EDITOR_UI_ANCHOR,
- entityWorldBox, uiNodeWorldBox, meshWorldBox, editorViewIsOrbited,
+ entityWorldBox, uiNodeWorldBox, meshWorldBox, entityBoxCorners, type EntityBox,
+ pickEntitiesByRay, editorViewIsOrbited,
moveEditorViewFocus, editorViewBoxExtent,
editorViewAxes, editorViewAxisAngles, cameraFrustumCorners, type ScreenAxis,
rayPlaneHit, type WorldRay, type Vec3,
@@ -27,17 +27,13 @@ import { EngineHost } from './EngineHost';
import { projectDesignSeed, projectCameraFit, projectSortingLayerModes } from './projectSeams';
import { SceneModel } from './SceneModel';
import {
- type OBB,
type ClientRect,
frustumPlaneCrossings,
quatAngleZ,
obbCorners,
- pointInOBB,
rectsIntersect,
screenAABB,
worldToLocal2D,
- rankPickCandidates,
- type PickCandidate,
} from './viewportMath';
// Half-length of a 3D joint's axis marker, in world units — long enough to read
@@ -48,9 +44,6 @@ const JOINT3D_AXIS_WORLD_HALF = 60;
const ICON_WORLD_HALF = 24;
// Degrees of turn per pixel dragged — the rate a DCC's orbit uses.
const ORBIT_DEG_PER_PX = 0.4;
-// Pick priority for icon-only entities: above any real sprite layer, so a small
-// foreground gizmo (camera/light) wins a tie against a big sprite beneath it.
-const ICON_PICK_LAYER = 1e6;
// The scene-authored joint components, each drawn as an anchor-to-anchor link gizmo.
// (The mouse/drag joint is imperative runtime API only — no component, nothing to draw.)
@@ -283,7 +276,7 @@ export const ViewportController = {
* (= transform position). Reads the parent-composed world transform — the same
* fields the renderer draws from — so parented entities pick where they render.
*/
- entityBounds(id: EntityId): OBB | null {
+ entityBounds(id: EntityId): EntityBox | null {
const world = EngineHost.world;
if (!world) return null;
// A mesh's extent is in its vertices, so it is asked for before the icon
@@ -362,41 +355,33 @@ export const ViewportController = {
const out: EntityId[] = [...this.pickUIEntities(clientX, clientY)];
const world = EngineHost.world;
- if (world) {
+ const ray = this.canvasRay(clientX, clientY);
+ if (world && ray) {
const masks = projectSortingLayerModes();
- const hits: PickCandidate<EntityId>[] = [];
- // The cursor is tested against each candidate ON ITS OWN PLANE. One shared
- // world point would be the 2D projection of the cursor, which under a
- // perspective view is where a sprite's shadow falls rather than where the
- // sprite is — so anything off the z = 0 plane would be unclickable at the
- // place it is drawn. Orthographically every plane gives the same point, so
- // this costs an unproject per candidate and changes no answer.
- for (const e of world.getAllEntities()) {
- if (!world.has(e, Transform)) continue;
+ for (const e of pickEntitiesByRay(world, ray, {
+ iconHalf: ICON_WORLD_HALF,
// Locked / editor-hidden / environment entities aren't click-selectable.
- const src = SceneModel.sourceFor(e);
- if (src != null && !SceneModel.isPickable(src)) continue;
- const wp = this.canvasToWorld(clientX, clientY, this.entityPlaneZ(e));
- const b = this.entityBounds(e);
- if (!wp || !b || !pointInOBB(wp.x, wp.y, b)) continue;
- const layer = world.has(e, Sprite) ? world.get(e, Sprite).layer : ICON_PICK_LAYER;
- const t = world.get(e, Transform);
- hits.push({
- entity: e,
- index: hits.length,
- rank: {
- layer,
- order: layerOrderOf(layer, masks.ySort, masks.depth),
- worldY: t.worldPosition.y,
- worldZ: t.worldPosition.z,
- },
- });
+ pickable: (e) => {
+ const src = SceneModel.sourceFor(e as EntityId);
+ return src == null || SceneModel.isPickable(src);
+ },
+ ySortLayers: masks.ySort,
+ depthLayers: masks.depth,
+ })) {
+ out.push(e as EntityId);
}
- for (const e of rankPickCandidates(hits)) out.push(e);
}
return out;
},
+ /** The world ray a canvas point names — what a click actually is. */
+ canvasRay(clientX: number, clientY: number): WorldRay | null {
+ const cv = cameraView();
+ const s = clientToScreen(clientX, clientY);
+ if (!cv || !s) return null;
+ return cv.screenRay(s.sx, s.sy);
+ },
+
/** Topmost entity under the pointer — UI (screen-space) first, then a world OBB. */
pickEntity(clientX: number, clientY: number): EntityId | null {
return this.pickEntitiesAt(clientX, clientY)[0] ?? null;
@@ -478,7 +463,7 @@ export const ViewportController = {
/** World OBB of a UI node's resolved layout box (Yoga size × worldScale,
* pivot-centered on the world transform). */
- uiEntityWorldOBB(id: EntityId): OBB | null {
+ uiEntityWorldOBB(id: EntityId): EntityBox | null {
const world = EngineHost.world;
return world ? uiNodeWorldBox(world, id) : null;
},
@@ -491,7 +476,7 @@ export const ViewportController = {
const cam = EngineHost.getResource(UICameraInfo) as UICameraData | undefined;
const obb = this.uiEntityWorldOBB(id);
if (!cam?.valid || !obb) return null;
- return screenAABB(obbCorners(obb).map(([wx, wy]) => this.uiWorldToClient(cam, wx, wy)));
+ return screenAABB(entityBoxCorners(obb).map((c) => this.uiWorldToClient(cam, c.x, c.y)));
},
/** Screen-space bounding rect (CSS px rel. canvas) of an entity, for the selection outline. */
@@ -499,8 +484,9 @@ export const ViewportController = {
if (EngineHost.world?.has(id, UINode)) return this.uiEntityScreenRect(id);
const b = this.entityBounds(id);
if (!b) return null;
- const toClient = this.projectorFor(id);
- return screenAABB(obbCorners(b).map(([wx, wy]) => toClient(wx, wy)));
+ // Every corner through its OWN depth: a box with any thickness has corners on
+ // different planes, and one shared plane would draw the outline of its shadow.
+ return screenAABB(entityBoxCorners(b).map((c) => this.worldToClient(c.x, c.y, c.z)));
},
/**
@@ -623,7 +609,6 @@ export const ViewportController = {
frameSelection(ids: readonly EntityId[]): void {
const view = editorView();
const canvas = EngineHost.canvas;
- const world = EngineHost.world;
if (!view || ids.length === 0) return;
let minX = Infinity;
@@ -635,17 +620,14 @@ export const ViewportController = {
for (const id of ids) {
const b = this.entityBounds(id) ?? this.uiEntityWorldOBB(id);
if (!b) continue;
- for (const [wx, wy] of obbCorners(b)) {
- minX = Math.min(minX, wx);
- minY = Math.min(minY, wy);
- maxX = Math.max(maxX, wx);
- maxY = Math.max(maxY, wy);
+ for (const c of entityBoxCorners(b)) {
+ minX = Math.min(minX, c.x);
+ minY = Math.min(minY, c.y);
+ minZ = Math.min(minZ, c.z);
+ maxX = Math.max(maxX, c.x);
+ maxY = Math.max(maxY, c.y);
+ maxZ = Math.max(maxZ, c.z);
}
- // Depth comes from the entity until a box carries one of its own; without
- // it Frame centres on the 2D plane whatever it was asked to look at.
- const z = world?.has(id, Transform) ? world.get(id, Transform).worldPosition.z : 0;
- minZ = Math.min(minZ, z);
- maxZ = Math.max(maxZ, z);
}
if (!Number.isFinite(minX)) return;
view.x = (minX + maxX) / 2;
@@ -765,9 +747,9 @@ export const ViewportController = {
const b = this.entityBounds(e);
if (!b) continue;
let x0 = Infinity, y0 = Infinity, x1 = -Infinity, y1 = -Infinity;
- for (const [wx, wy] of obbCorners(b)) {
- x0 = Math.min(x0, wx); y0 = Math.min(y0, wy);
- x1 = Math.max(x1, wx); y1 = Math.max(y1, wy);
+ for (const c of entityBoxCorners(b)) {
+ x0 = Math.min(x0, c.x); y0 = Math.min(y0, c.y);
+ x1 = Math.max(x1, c.x); y1 = Math.max(y1, c.y);
}
add(e, x0, y0, x1, y1, world.has(e, Sprite) ? 'sprite' : 'icon');
}
diff --git a/desktop/src/engine/playProtocol.ts b/desktop/src/engine/playProtocol.ts
index a0e1c9d72..1a3db2f54 100644
--- a/desktop/src/engine/playProtocol.ts
+++ b/desktop/src/engine/playProtocol.ts
@@ -129,7 +129,8 @@ export interface CanvasPoint {
/** An entity's drawn box, as the realm's own camera projects it. */
export interface PlayOverlayBox {
- /** The four corners, counter-clockwise from the box's local -x,-y. */
+ /** The outline the box draws on screen, counter-clockwise: four points while
+ * it is flat, more once it has depth to turn. */
corners: CanvasPoint[];
/** The transform origin — where a move gizmo is anchored. Absent for a box a
* drag cannot move: a UI node is placed by layout, not by a position field. */
diff --git a/desktop/src/engine/viewportMath.ts b/desktop/src/engine/viewportMath.ts
index f783b741d..32d4b9d25 100644
--- a/desktop/src/engine/viewportMath.ts
+++ b/desktop/src/engine/viewportMath.ts
@@ -8,9 +8,11 @@
* The one import is the SDK's pure mirror of the renderer's layer rules,
* which picking has to rank by rather than restate.
*/
-import { compareDrawRank, type DrawRank, type ScreenAxis } from 'esengine';
+import type { ScreenAxis } from 'esengine';
-/** Oriented bounding box in world space: center, half-extents, Z rotation (radians). */
+/** A flat rect in the XY plane: center, half-extents, Z rotation (radians). What a
+ * 2D authoring shape is — a particle emitter's spawn box, a tile cell. An entity's
+ * extent is not one of these; it is an `EntityBox`, which has a third dimension. */
export interface OBB {
cx: number;
cy: number;
@@ -41,15 +43,28 @@ export function obbCorners(b: OBB): Array<[number, number]> {
);
}
-/** Whether a world point lies inside an OBB (transform the point into the box's local frame). */
-export function pointInOBB(px: number, py: number, b: OBB): boolean {
- const dx = px - b.cx;
- const dy = py - b.cy;
- const c = Math.cos(-b.rot);
- const s = Math.sin(-b.rot);
- const lx = dx * c - dy * s;
- const ly = dx * s + dy * c;
- return Math.abs(lx) <= b.hw && Math.abs(ly) <= b.hh;
+/**
+ * The outline of a set of projected points: their convex hull, counter-clockwise
+ * (Andrew's monotone chain). A box's eight corners are a quadrilateral on screen
+ * while it is flat and a hexagon once it has depth, and an outline drawn through
+ * them in any fixed order crosses itself.
+ */
+export function screenHull(points: ReadonlyArray<{ x: number; y: number }>): Array<{ x: number; y: number }> {
+ const pts = [...points].sort((a, b) => a.x - b.x || a.y - b.y)
+ .filter((p, i, all) => i === 0 || p.x !== all[i - 1].x || p.y !== all[i - 1].y);
+ if (pts.length < 3) return pts;
+ const cross = (o: { x: number; y: number }, a: { x: number; y: number }, b: { x: number; y: number }): number =>
+ (a.x - o.x) * (b.y - o.y) - (a.y - o.y) * (b.x - o.x);
+ const half = (source: typeof pts): typeof pts => {
+ const out: typeof pts = [];
+ for (const p of source) {
+ while (out.length >= 2 && cross(out[out.length - 2], out[out.length - 1], p) <= 0) out.pop();
+ out.push(p);
+ }
+ out.pop();
+ return out;
+ };
+ return [...half(pts), ...half([...pts].reverse())];
}
/** A 2D world frame: translation, Z rotation (radians), per-axis scale. */
@@ -97,30 +112,6 @@ export const clamp = (v: number, lo: number, hi: number): number => Math.max(lo,
/** Round to the nearest multiple of `step` (snap). `step <= 0` returns `v` unchanged. */
export const snapTo = (v: number, step: number): number => (step > 0 ? Math.round(v / step) * step : v);
-/** One entity under the pointer, with everything its rank depends on. */
-export interface PickCandidate<T> {
- entity: T;
- /** Where the frame put it: layer, that layer's rule, and the world coords it uses. */
- rank: DrawRank;
- /** Position in the World's iteration order: the paint order for equal depth. */
- index: number;
-}
-
-/**
- * Candidates ranked topmost-first, the way the RENDERER stacked them — the layer
- * rules via {@link compareDrawRank}, then later-drawn winning ties.
- *
- * Split out as a pure function because it is the part that can be wrong while
- * every hit test is right — and it ranks what a person SEES, so getting it
- * backwards means the click selects the thing hidden behind the thing they
- * aimed at.
- */
-export function rankPickCandidates<T>(candidates: ReadonlyArray<PickCandidate<T>>): T[] {
- return [...candidates]
- .sort((a, b) => compareDrawRank(b.rank, a.rank) || b.index - a.index)
- .map((c) => c.entity);
-}
-
export interface Quat { x: number; y: number; z: number; w: number }
/** Quaternion for a turn of `rad` about a world axis. */
diff --git a/desktop/src/panels/PlayOverlay.tsx b/desktop/src/panels/PlayOverlay.tsx
index e44220786..93ab7883b 100644
--- a/desktop/src/panels/PlayOverlay.tsx
+++ b/desktop/src/panels/PlayOverlay.tsx
@@ -48,7 +48,7 @@ function grabbed(box: PlayOverlayBox, origin: CanvasPoint, p: CanvasPoint, size:
const [ox, oy] = toPx(origin, size.w, size.h);
const [px, py] = toPx(p, size.w, size.h);
if (Math.hypot(px - ox, py - oy) <= HANDLE * 2) return true;
- if (box.corners.length !== 4) return false;
+ if (box.corners.length < 3) return false;
const poly = box.corners.map((c) => toPx(c, size.w, size.h));
let inside = false;
for (let i = 0, j = poly.length - 1; i < poly.length; j = i++) {
@@ -197,7 +197,7 @@ export function PlayOverlay({ interactive }: Props) {
const box = overlay && size.w > 0 ? overlay : null;
const origin = box?.origin ? toPx(box.origin, size.w, size.h) : null;
- const outline = box && box.corners.length === 4
+ const outline = box && box.corners.length >= 3
? box.corners.map((c) => toPx(c, size.w, size.h).join(',')).join(' ')
: null;
diff --git a/desktop/src/playHost.ts b/desktop/src/playHost.ts
index 5e457f2c5..2bf041a0d 100644
--- a/desktop/src/playHost.ts
+++ b/desktop/src/playHost.ts
@@ -14,7 +14,7 @@
* Everything is same-origin estella:// (host, sdk, bundle, wasm, assets),
* sidestepping the custom-scheme cross-fetch ban.
*/
-import { uiPickWorld, uiWorldToScreen, screenToUiWorld, uiNodeWorldBox, createWebApp, setEditorMode, setPlayMode, enableSceneOrigins, sceneOriginOf, entityWorldBox, entityBoxCorners, CameraView, layerOrderOf, quaternionToAngle2D, initPlayRealmRuntime, getComponent, clearUserComponents, getUserComponentFingerprint, probeRegistrations, Net, MessagePortTransport, Assets, Ads, createMockAdProvider, registerPackagedSideModules, Input, inputEventCallbacks, isEntityVisible, setEntityVisible, hasVisibility, takeCensus } from 'esengine';
+import { uiPickWorld, uiWorldToScreen, screenToUiWorld, uiNodeWorldBox, createWebApp, setEditorMode, setPlayMode, enableSceneOrigins, sceneOriginOf, entityWorldBox, entityBoxCorners, meshWorldBox, pickEntitiesByRay, CameraView, quaternionToAngle2D, initPlayRealmRuntime, getComponent, clearUserComponents, getUserComponentFingerprint, probeRegistrations, Net, MessagePortTransport, Assets, Ads, createMockAdProvider, registerPackagedSideModules, Input, inputEventCallbacks, isEntityVisible, setEntityVisible, hasVisibility, takeCensus } from 'esengine';
import type { App, SceneData, InputState, UICameraData } from 'esengine';
import type { ESEngineModule } from 'esengine/wasm';
import { extendPlatform } from 'esengine';
@@ -22,7 +22,7 @@ import { rehearseOpenData, type OpenDataRehearsal } from './engine/openDataRehea
import { PLAY_PROTOCOL_VERSION } from './engine/playProtocol';
import type { PlayOutbound, PlayInbound, LiveVisibility, CanvasPoint, PlayOverlayBox } from './engine/playProtocol';
import { translateAssetHandles, projectRelative } from './engine/liveAssetRefs';
-import { pointInOBB, rankPickCandidates, worldToLocal2D, turnQuat2D, scaleVecBy, snapTo, type PickCandidate } from '@/engine/viewportMath';
+import { screenHull, worldToLocal2D, turnQuat2D, scaleVecBy, snapTo } from '@/engine/viewportMath';
import {
inspectEntity, findEntities, readResources, readSystems,
type Realm, type EntityFilter,
@@ -223,10 +223,8 @@ function uiOverlayBoxOf(world: App['world'], entity: number): PlayOverlayBox | n
const cam = uiCamera();
const box = cam ? uiNodeWorldBox(world, entity as never) : null;
if (!cam || !box) return null;
- const corners = entityBoxCorners(box).map((c) => {
- const s = uiWorldToScreen(cam, c.x, c.y);
- return normalizePoint(s.x, s.y);
- });
+ const corners = screenHull(entityBoxCorners(box).map((c) => uiWorldToScreen(cam, c.x, c.y)))
+ .map((p) => normalizePoint(p.x, p.y));
return { corners };
}
@@ -246,14 +244,17 @@ function overlayBoxOf(world: App['world'], entity: number): PlayOverlayBox | nul
if (!originScreen) return null;
// No box is not no overlay: an empty or a camera still has an origin to put a
// move gizmo on, it just has no outline to draw.
- const box = entityWorldBox(world, entity as never);
- const corners = box
+ // A mesh's extent is in its vertices; anything else is boxed by what it draws.
+ const box = meshWorldBox(world, entity as never) ?? entityWorldBox(world, entity as never);
+ const projected = box
? entityBoxCorners(box)
- .map((c) => view.worldToScreen(c.x, c.y, z))
+ .map((c) => view.worldToScreen(c.x, c.y, c.z))
.filter((p): p is { x: number; y: number } => p !== null)
- .map((p) => normalizePoint(p.x, p.y))
: [];
- return { corners: corners.length === 4 ? corners : [], origin: normalizePoint(originScreen.x, originScreen.y) };
+ const corners = projected.length === 8
+ ? screenHull(projected).map((p) => normalizePoint(p.x, p.y))
+ : [];
+ return { corners, origin: normalizePoint(originScreen.x, originScreen.y) };
}
/** The topmost entity at a canvas point, ranked the way the frame stacked it.
@@ -267,33 +268,16 @@ function pickAt(world: App['world'], nx: number, ny: number): number | null {
if (hit !== null) return hit as never as number;
}
const view = app?.getResource(CameraView);
- const transformDef = getComponent('Transform');
- const spriteDef = getComponent('Sprite');
- if (!view || !transformDef) return null;
- const hits: PickCandidate<number>[] = [];
- for (const e of world.getAllEntities()) {
- const id = e as never as number;
- const t = world.tryGet(e, transformDef) as { worldPosition?: { x: number; y: number; z?: number } } | null;
- if (!t?.worldPosition) continue;
- // Each candidate is tested on ITS OWN plane: under a perspective camera one
- // shared world point is where a sprite's shadow falls, not where it is drawn.
- const wp = view.screenToWorld(gl.x, gl.y, t.worldPosition.z ?? 0);
- const box = entityWorldBox(world, e);
- if (!wp || !box || !pointInOBB(wp.x, wp.y, box)) continue;
- const sprite = spriteDef ? (world.tryGet(e, spriteDef) as { layer?: number } | null) : null;
- const layer = sprite?.layer ?? 0;
- hits.push({
- entity: id,
- index: hits.length,
- rank: {
- layer,
- order: layerOrderOf(layer, lastInit?.ySortLayers ?? 0, lastInit?.depthLayers ?? 0),
- worldY: t.worldPosition.y,
- worldZ: t.worldPosition.z ?? 0,
- },
- });
- }
- return rankPickCandidates(hits)[0] ?? null;
+ const ray = view?.screenRay(gl.x, gl.y);
+ if (!ray) return null;
+ // The same door the editor's viewport picks through, so a running game and the
+ // scene it came from cannot answer the same click differently. No icons here:
+ // a camera or a light draws nothing to aim at.
+ const hit = pickEntitiesByRay(world, ray, {
+ ySortLayers: lastInit?.ySortLayers ?? 0,
+ depthLayers: lastInit?.depthLayers ?? 0,
+ })[0];
+ return hit === undefined ? null : (hit as never as number);
}
/** Turn / resize a running entity by a relative amount, composed onto what it
diff --git a/desktop/src/tools/alignTools.ts b/desktop/src/tools/alignTools.ts
index f5e06867a..f738bb9ec 100644
--- a/desktop/src/tools/alignTools.ts
+++ b/desktop/src/tools/alignTools.ts
@@ -14,7 +14,7 @@ import { ViewportController } from '@/engine/ViewportController';
import { SceneCommands } from '@/engine/SceneCommands';
import { SceneModel } from '@/engine/SceneModel';
import { useSelection } from '@/store/selectionStore';
-import { obbCorners } from '@/engine/viewportMath';
+import { entityBoxCorners } from 'esengine';
import { pruneDescendants, isFlowUINode, isOrphanUINode } from './transformTools';
import { alignTargets, distributeTargets, type AlignBox, type AlignOp, type DistributeAxis } from './alignMath';
import type { EntityId } from '@/types';
@@ -32,9 +32,9 @@ function collectBoxes(): Array<{ sid: EntityId; box: AlignBox }> {
if (rt == null) continue;
const obb = ViewportController.entityBounds(rt) ?? ViewportController.uiEntityWorldOBB(rt);
if (!obb) continue;
- const corners = obbCorners(obb);
- const xs = corners.map((c) => c[0]);
- const ys = corners.map((c) => c[1]);
+ const corners = entityBoxCorners(obb);
+ const xs = corners.map((c) => c.x);
+ const ys = corners.map((c) => c.y);
out.push({
sid,
box: { minX: Math.min(...xs), maxX: Math.max(...xs), minY: Math.min(...ys), maxY: Math.max(...ys), cx: obb.cx, cy: obb.cy },
diff --git a/desktop/tests/viewport-math.test.ts b/desktop/tests/viewport-math.test.ts
index c9303d14d..e032439b8 100644
--- a/desktop/tests/viewport-math.test.ts
+++ b/desktop/tests/viewport-math.test.ts
@@ -10,18 +10,15 @@ import {
type OBB,
quatAngleZ,
obbCorners,
- pointInOBB,
rectsIntersect,
screenAABB,
snapTo,
clamp,
worldToLocal2D,
- rankPickCandidates,
axisIndicatorEnds,
frustumPlaneCrossings,
- type PickCandidate,
} from '@/engine/viewportMath';
-import { LayerOrder, layerOrderOf } from 'esengine';
+import { LayerOrder, layerOrderOf, rankPickCandidates, type PickCandidate } from 'esengine';
const box = (cx: number, cy: number, hw: number, hh: number, rot = 0): OBB => ({ cx, cy, hw, hh, rot });
@@ -36,25 +33,6 @@ describe('quatAngleZ', () => {
});
});
-describe('pointInOBB', () => {
- it('hits inside an axis-aligned box and misses outside', () => {
- const b = box(0, 0, 10, 5);
- expect(pointInOBB(0, 0, b)).toBe(true);
- expect(pointInOBB(9, 4, b)).toBe(true);
- expect(pointInOBB(11, 0, b)).toBe(false);
- expect(pointInOBB(0, 6, b)).toBe(false);
- });
-
- it('respects rotation — a 45° box rejects a point the AABB would accept', () => {
- const b = box(0, 0, 10, 10, Math.PI / 4);
- // The unrotated corner (10,10) is outside the rotated box (its corners reach ±14.1 on the axes).
- expect(pointInOBB(10, 10, b)).toBe(false);
- // A point along the rotated local-x axis at distance 10 is on the edge → inside.
- const c = Math.cos(Math.PI / 4);
- expect(pointInOBB(10 * c, 10 * c, b)).toBe(true);
- });
-});
-
describe('obbCorners', () => {
it('gives the four corners of an axis-aligned box', () => {
const cs = obbCorners(box(5, 5, 2, 1));
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index 11badf512..62b316be6 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -3,10 +3,10 @@
"counts": {
"public": 113,
"beta": 73,
- "experimental": 1582,
+ "experimental": 1588,
"deprecated": 3
},
- "total": 1768,
+ "total": 1774,
"subsystems": [
{
"id": "ecs",
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 84ac8fb1e..b1390c5b7 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 66 beta · 1468 experimental · 3 deprecated
+Symbols: 113 public · 66 beta · 1474 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -2891,9 +2891,11 @@ number
```
cx: number
cy: number
+cz: number
+hd: number
hh: number
hw: number
-rot: number
+rot: Quat
```
## EntityBoxOptions — interface @experimental
@@ -2948,6 +2950,14 @@ static prototype: EntityEventQueue
ResourceDef<EntityEventQueue>
```
+## EntityPickOptions — interface @experimental
+```
+depthLayers: number | undefined
+iconHalf: number | undefined
+pickable: ((entity: Entity) => boolean) | undefined
+ySortLayers: number | undefined
+```
+
## EventBinding — const @experimental
```
ComponentDef<EventBindingData>
@@ -5227,6 +5237,18 @@ _physics_step: (dt: number) => void
_physics_updateBodyProperties: (entityId: number, bodyType: number, gravityScale: number, linearDamping: number, angularDamping: number, fixedRotation: number, bullet: number) => void
```
+## PickCandidate — interface @experimental
+```
+entity: T
+index: number
+rank: DrawRank
+```
+
+## PickWorld — type @experimental
+```
+LayoutWorld & Pick<World, 'getAllEntities'>
+```
+
## PickableWorld — type @experimental
```
Pick<World, 'getCppRegistry' | 'getWasmModule'>
@@ -9997,7 +10019,12 @@ DragPlugin
## entityBoxCorners — function @experimental
```
-(b: EntityBox): Array<{ x: number; y: number; }>
+(b: EntityBox): Vec3[]
+```
+
+## entityBoxRayHit — function @experimental
+```
+(b: EntityBox, origin: Vec3, dir: Vec3): number | null
```
## entityWorldBox — function @experimental
@@ -10950,6 +10977,11 @@ ParticlePlugin
PerceptionPlugin
```
+## pickEntitiesByRay — function @experimental
+```
+(world: PickWorld, ray: WorldRay, opts?: EntityPickOptions): Entity[]
+```
+
## placeCollider3DWireframe — function @experimental
```
(lines: Vec3[][], position: Vec3, rotation: Quat): Vec3[][]
@@ -11097,7 +11129,7 @@ PrefabsPlugin
## q — const @experimental
```
-{ create(w?: number, x?: number, y?: number, z?: number): Quat; clone(a: Quat): Quat; mul(a: Quat, b: Quat): Quat; axis(axis: "x" | "y" | "z", rad: number): Quat; normalize(a: Quat): Quat; dot(a: Quat, b: Quat): number; neg(a: Quat): Quat; toEuler(a: Quat): [number, number, number]; fromEuler(deg: readonly number[]): Quat; setAngleZ(a: Quat | undefined, deg: number): Quat; angleZ(a: Pick<Quat, "z" | "w">): number; }
+{ create(w?: number, x?: number, y?: number, z?: number): Quat; clone(a: Quat): Quat; mul(a: Quat, b: Quat): Quat; axis(axis: "x" | "y" | "z", rad: number): Quat; normalize(a: Quat): Quat; dot(a: Quat, b: Quat): number; neg(a: Quat): Quat; conjugate(a: Quat): Quat; rotate(a: Quat, v: Vec3): Vec3; toEuler(a: Quat): [number, number, number]; fromEuler(deg: readonly number[]): Quat; setAngleZ(a: Quat | undefined, deg: number): Quat; angleZ(a: Pick<Quat, "z" | "w">): number; }
```
## quat — const @experimental
@@ -11115,6 +11147,11 @@ PrefabsPlugin
(radius: number, options?: RadiusInterestOptions): InterestPolicy
```
+## rankPickCandidates — function @experimental
+```
+<T>(candidates: ReadonlyArray<PickCandidate<T>>): T[]
+```
+
## rayPlaneHit — function @experimental
```
(ray: WorldRay, point: Vec3, normal: Vec3): Vec3 | null
@@ -11392,7 +11429,7 @@ ReplicationPlugin
## rotateVec3ByQuat — function @experimental
```
-(q: Quat, v: Vec3): Vec3
+(rot: Quat, v: Vec3): Vec3
```
## runHeadless — function @beta
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index d50850621..2947e1598 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.native
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 71 beta · 1487 experimental · 3 deprecated
+Symbols: 113 public · 71 beta · 1493 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -2899,9 +2899,11 @@ number
```
cx: number
cy: number
+cz: number
+hd: number
hh: number
hw: number
-rot: number
+rot: Quat
```
## EntityBoxOptions — interface @experimental
@@ -2956,6 +2958,14 @@ static prototype: EntityEventQueue
ResourceDef<EntityEventQueue>
```
+## EntityPickOptions — interface @experimental
+```
+depthLayers: number | undefined
+iconHalf: number | undefined
+pickable: ((entity: Entity) => boolean) | undefined
+ySortLayers: number | undefined
+```
+
## EventBinding — const @experimental
```
ComponentDef<EventBindingData>
@@ -5410,6 +5420,18 @@ _physics_step: (dt: number) => void
_physics_updateBodyProperties: (entityId: number, bodyType: number, gravityScale: number, linearDamping: number, angularDamping: number, fixedRotation: number, bullet: number) => void
```
+## PickCandidate — interface @experimental
+```
+entity: T
+index: number
+rank: DrawRank
+```
+
+## PickWorld — type @experimental
+```
+LayoutWorld & Pick<World, 'getAllEntities'>
+```
+
## PickableWorld — type @experimental
```
Pick<World, 'getCppRegistry' | 'getWasmModule'>
@@ -10230,7 +10252,12 @@ DragPlugin
## entityBoxCorners — function @experimental
```
-(b: EntityBox): Array<{ x: number; y: number; }>
+(b: EntityBox): Vec3[]
+```
+
+## entityBoxRayHit — function @experimental
+```
+(b: EntityBox, origin: Vec3, dir: Vec3): number | null
```
## entityWorldBox — function @experimental
@@ -11193,6 +11220,11 @@ ParticlePlugin
PerceptionPlugin
```
+## pickEntitiesByRay — function @experimental
+```
+(world: PickWorld, ray: WorldRay, opts?: EntityPickOptions): Entity[]
+```
+
## placeCollider3DWireframe — function @experimental
```
(lines: Vec3[][], position: Vec3, rotation: Quat): Vec3[][]
@@ -11340,7 +11372,7 @@ PrefabsPlugin
## q — const @experimental
```
-{ create(w?: number, x?: number, y?: number, z?: number): Quat; clone(a: Quat): Quat; mul(a: Quat, b: Quat): Quat; axis(axis: "x" | "y" | "z", rad: number): Quat; normalize(a: Quat): Quat; dot(a: Quat, b: Quat): number; neg(a: Quat): Quat; toEuler(a: Quat): [number, number, number]; fromEuler(deg: readonly number[]): Quat; setAngleZ(a: Quat | undefined, deg: number): Quat; angleZ(a: Pick<Quat, "z" | "w">): number; }
+{ create(w?: number, x?: number, y?: number, z?: number): Quat; clone(a: Quat): Quat; mul(a: Quat, b: Quat): Quat; axis(axis: "x" | "y" | "z", rad: number): Quat; normalize(a: Quat): Quat; dot(a: Quat, b: Quat): number; neg(a: Quat): Quat; conjugate(a: Quat): Quat; rotate(a: Quat, v: Vec3): Vec3; toEuler(a: Quat): [number, number, number]; fromEuler(deg: readonly number[]): Quat; setAngleZ(a: Quat | undefined, deg: number): Quat; angleZ(a: Pick<Quat, "z" | "w">): number; }
```
## quat — const @experimental
@@ -11358,6 +11390,11 @@ PrefabsPlugin
(radius: number, options?: RadiusInterestOptions): InterestPolicy
```
+## rankPickCandidates — function @experimental
+```
+<T>(candidates: ReadonlyArray<PickCandidate<T>>): T[]
+```
+
## rayPlaneHit — function @experimental
```
(ray: WorldRay, point: Vec3, normal: Vec3): Vec3 | null
@@ -11635,7 +11672,7 @@ ReplicationPlugin
## rotateVec3ByQuat — function @experimental
```
-(q: Quat, v: Vec3): Vec3
+(rot: Quat, v: Vec3): Vec3
```
## runHeadless — function @beta
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 3df0a5ed6..d1c572550 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.node
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 68 beta · 1467 experimental · 3 deprecated
+Symbols: 113 public · 68 beta · 1473 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -2886,9 +2886,11 @@ number
```
cx: number
cy: number
+cz: number
+hd: number
hh: number
hw: number
-rot: number
+rot: Quat
```
## EntityBoxOptions — interface @experimental
@@ -2943,6 +2945,14 @@ static prototype: EntityEventQueue
ResourceDef<EntityEventQueue>
```
+## EntityPickOptions — interface @experimental
+```
+depthLayers: number | undefined
+iconHalf: number | undefined
+pickable: ((entity: Entity) => boolean) | undefined
+ySortLayers: number | undefined
+```
+
## EventBinding — const @experimental
```
ComponentDef<EventBindingData>
@@ -5222,6 +5232,18 @@ _physics_step: (dt: number) => void
_physics_updateBodyProperties: (entityId: number, bodyType: number, gravityScale: number, linearDamping: number, angularDamping: number, fixedRotation: number, bullet: number) => void
```
+## PickCandidate — interface @experimental
+```
+entity: T
+index: number
+rank: DrawRank
+```
+
+## PickWorld — type @experimental
+```
+LayoutWorld & Pick<World, 'getAllEntities'>
+```
+
## PickableWorld — type @experimental
```
Pick<World, 'getCppRegistry' | 'getWasmModule'>
@@ -9992,7 +10014,12 @@ DragPlugin
## entityBoxCorners — function @experimental
```
-(b: EntityBox): Array<{ x: number; y: number; }>
+(b: EntityBox): Vec3[]
+```
+
+## entityBoxRayHit — function @experimental
+```
+(b: EntityBox, origin: Vec3, dir: Vec3): number | null
```
## entityWorldBox — function @experimental
@@ -10955,6 +10982,11 @@ ParticlePlugin
PerceptionPlugin
```
+## pickEntitiesByRay — function @experimental
+```
+(world: PickWorld, ray: WorldRay, opts?: EntityPickOptions): Entity[]
+```
+
## placeCollider3DWireframe — function @experimental
```
(lines: Vec3[][], position: Vec3, rotation: Quat): Vec3[][]
@@ -11102,7 +11134,7 @@ PrefabsPlugin
## q — const @experimental
```
-{ create(w?: number, x?: number, y?: number, z?: number): Quat; clone(a: Quat): Quat; mul(a: Quat, b: Quat): Quat; axis(axis: "x" | "y" | "z", rad: number): Quat; normalize(a: Quat): Quat; dot(a: Quat, b: Quat): number; neg(a: Quat): Quat; toEuler(a: Quat): [number, number, number]; fromEuler(deg: readonly number[]): Quat; setAngleZ(a: Quat | undefined, deg: number): Quat; angleZ(a: Pick<Quat, "z" | "w">): number; }
+{ create(w?: number, x?: number, y?: number, z?: number): Quat; clone(a: Quat): Quat; mul(a: Quat, b: Quat): Quat; axis(axis: "x" | "y" | "z", rad: number): Quat; normalize(a: Quat): Quat; dot(a: Quat, b: Quat): number; neg(a: Quat): Quat; conjugate(a: Quat): Quat; rotate(a: Quat, v: Vec3): Vec3; toEuler(a: Quat): [number, number, number]; fromEuler(deg: readonly number[]): Quat; setAngleZ(a: Quat | undefined, deg: number): Quat; angleZ(a: Pick<Quat, "z" | "w">): number; }
```
## quat — const @experimental
@@ -11120,6 +11152,11 @@ PrefabsPlugin
(radius: number, options?: RadiusInterestOptions): InterestPolicy
```
+## rankPickCandidates — function @experimental
+```
+<T>(candidates: ReadonlyArray<PickCandidate<T>>): T[]
+```
+
## rayPlaneHit — function @experimental
```
(ray: WorldRay, point: Vec3, normal: Vec3): Vec3 | null
@@ -11397,7 +11434,7 @@ ReplicationPlugin
## rotateVec3ByQuat — function @experimental
```
-(q: Quat, v: Vec3): Vec3
+(rot: Quat, v: Vec3): Vec3
```
## runHeadless — function @beta
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 2b57e678b..f5c2cfe88 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/minigame
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 66 beta · 1488 experimental · 3 deprecated
+Symbols: 113 public · 66 beta · 1494 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -2886,9 +2886,11 @@ number
```
cx: number
cy: number
+cz: number
+hd: number
hh: number
hw: number
-rot: number
+rot: Quat
```
## EntityBoxOptions — interface @experimental
@@ -2943,6 +2945,14 @@ static prototype: EntityEventQueue
ResourceDef<EntityEventQueue>
```
+## EntityPickOptions — interface @experimental
+```
+depthLayers: number | undefined
+iconHalf: number | undefined
+pickable: ((entity: Entity) => boolean) | undefined
+ySortLayers: number | undefined
+```
+
## EventBinding — const @experimental
```
ComponentDef<EventBindingData>
@@ -5467,6 +5477,18 @@ _physics_step: (dt: number) => void
_physics_updateBodyProperties: (entityId: number, bodyType: number, gravityScale: number, linearDamping: number, angularDamping: number, fixedRotation: number, bullet: number) => void
```
+## PickCandidate — interface @experimental
+```
+entity: T
+index: number
+rank: DrawRank
+```
+
+## PickWorld — type @experimental
+```
+LayoutWorld & Pick<World, 'getAllEntities'>
+```
+
## PickableWorld — type @experimental
```
Pick<World, 'getCppRegistry' | 'getWasmModule'>
@@ -10242,7 +10264,12 @@ DragPlugin
## entityBoxCorners — function @experimental
```
-(b: EntityBox): Array<{ x: number; y: number; }>
+(b: EntityBox): Vec3[]
+```
+
+## entityBoxRayHit — function @experimental
+```
+(b: EntityBox, origin: Vec3, dir: Vec3): number | null
```
## entityWorldBox — function @experimental
@@ -11205,6 +11232,11 @@ ParticlePlugin
PerceptionPlugin
```
+## pickEntitiesByRay — function @experimental
+```
+(world: PickWorld, ray: WorldRay, opts?: EntityPickOptions): Entity[]
+```
+
## placeCollider3DWireframe — function @experimental
```
(lines: Vec3[][], position: Vec3, rotation: Quat): Vec3[][]
@@ -11352,7 +11384,7 @@ PrefabsPlugin
## q — const @experimental
```
-{ create(w?: number, x?: number, y?: number, z?: number): Quat; clone(a: Quat): Quat; mul(a: Quat, b: Quat): Quat; axis(axis: "x" | "y" | "z", rad: number): Quat; normalize(a: Quat): Quat; dot(a: Quat, b: Quat): number; neg(a: Quat): Quat; toEuler(a: Quat): [number, number, number]; fromEuler(deg: readonly number[]): Quat; setAngleZ(a: Quat | undefined, deg: number): Quat; angleZ(a: Pick<Quat, "z" | "w">): number; }
+{ create(w?: number, x?: number, y?: number, z?: number): Quat; clone(a: Quat): Quat; mul(a: Quat, b: Quat): Quat; axis(axis: "x" | "y" | "z", rad: number): Quat; normalize(a: Quat): Quat; dot(a: Quat, b: Quat): number; neg(a: Quat): Quat; conjugate(a: Quat): Quat; rotate(a: Quat, v: Vec3): Vec3; toEuler(a: Quat): [number, number, number]; fromEuler(deg: readonly number[]): Quat; setAngleZ(a: Quat | undefined, deg: number): Quat; angleZ(a: Pick<Quat, "z" | "w">): number; }
```
## quat — const @experimental
@@ -11370,6 +11402,11 @@ PrefabsPlugin
(radius: number, options?: RadiusInterestOptions): InterestPolicy
```
+## rankPickCandidates — function @experimental
+```
+<T>(candidates: ReadonlyArray<PickCandidate<T>>): T[]
+```
+
## rayPlaneHit — function @experimental
```
(ray: WorldRay, point: Vec3, normal: Vec3): Vec3 | null
@@ -11647,7 +11684,7 @@ ReplicationPlugin
## rotateVec3ByQuat — function @experimental
```
-(q: Quat, v: Vec3): Vec3
+(rot: Quat, v: Vec3): Vec3
```
## runHeadless — function @beta
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 8af81aa0c..f61ffd2c4 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/wechat
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 66 beta · 1478 experimental · 3 deprecated
+Symbols: 113 public · 66 beta · 1484 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -2886,9 +2886,11 @@ number
```
cx: number
cy: number
+cz: number
+hd: number
hh: number
hw: number
-rot: number
+rot: Quat
```
## EntityBoxOptions — interface @experimental
@@ -2943,6 +2945,14 @@ static prototype: EntityEventQueue
ResourceDef<EntityEventQueue>
```
+## EntityPickOptions — interface @experimental
+```
+depthLayers: number | undefined
+iconHalf: number | undefined
+pickable: ((entity: Entity) => boolean) | undefined
+ySortLayers: number | undefined
+```
+
## EventBinding — const @experimental
```
ComponentDef<EventBindingData>
@@ -5229,6 +5239,18 @@ _physics_step: (dt: number) => void
_physics_updateBodyProperties: (entityId: number, bodyType: number, gravityScale: number, linearDamping: number, angularDamping: number, fixedRotation: number, bullet: number) => void
```
+## PickCandidate — interface @experimental
+```
+entity: T
+index: number
+rank: DrawRank
+```
+
+## PickWorld — type @experimental
+```
+LayoutWorld & Pick<World, 'getAllEntities'>
+```
+
## PickableWorld — type @experimental
```
Pick<World, 'getCppRegistry' | 'getWasmModule'>
@@ -10019,7 +10041,12 @@ DragPlugin
## entityBoxCorners — function @experimental
```
-(b: EntityBox): Array<{ x: number; y: number; }>
+(b: EntityBox): Vec3[]
+```
+
+## entityBoxRayHit — function @experimental
+```
+(b: EntityBox, origin: Vec3, dir: Vec3): number | null
```
## entityWorldBox — function @experimental
@@ -10977,6 +11004,11 @@ ParticlePlugin
PerceptionPlugin
```
+## pickEntitiesByRay — function @experimental
+```
+(world: PickWorld, ray: WorldRay, opts?: EntityPickOptions): Entity[]
+```
+
## placeCollider3DWireframe — function @experimental
```
(lines: Vec3[][], position: Vec3, rotation: Quat): Vec3[][]
@@ -11124,7 +11156,7 @@ PrefabsPlugin
## q — const @experimental
```
-{ create(w?: number, x?: number, y?: number, z?: number): Quat; clone(a: Quat): Quat; mul(a: Quat, b: Quat): Quat; axis(axis: "x" | "y" | "z", rad: number): Quat; normalize(a: Quat): Quat; dot(a: Quat, b: Quat): number; neg(a: Quat): Quat; toEuler(a: Quat): [number, number, number]; fromEuler(deg: readonly number[]): Quat; setAngleZ(a: Quat | undefined, deg: number): Quat; angleZ(a: Pick<Quat, "z" | "w">): number; }
+{ create(w?: number, x?: number, y?: number, z?: number): Quat; clone(a: Quat): Quat; mul(a: Quat, b: Quat): Quat; axis(axis: "x" | "y" | "z", rad: number): Quat; normalize(a: Quat): Quat; dot(a: Quat, b: Quat): number; neg(a: Quat): Quat; conjugate(a: Quat): Quat; rotate(a: Quat, v: Vec3): Vec3; toEuler(a: Quat): [number, number, number]; fromEuler(deg: readonly number[]): Quat; setAngleZ(a: Quat | undefined, deg: number): Quat; angleZ(a: Pick<Quat, "z" | "w">): number; }
```
## quat — const @experimental
@@ -11142,6 +11174,11 @@ PrefabsPlugin
(radius: number, options?: RadiusInterestOptions): InterestPolicy
```
+## rankPickCandidates — function @experimental
+```
+<T>(candidates: ReadonlyArray<PickCandidate<T>>): T[]
+```
+
## rayPlaneHit — function @experimental
```
(ray: WorldRay, point: Vec3, normal: Vec3): Vec3 | null
@@ -11419,7 +11456,7 @@ ReplicationPlugin
## rotateVec3ByQuat — function @experimental
```
-(q: Quat, v: Vec3): Vec3
+(rot: Quat, v: Vec3): Vec3
```
## runHeadless — function @beta
diff --git a/sdk/src/core-render.ts b/sdk/src/core-render.ts
index 21d45bcbd..120a694c2 100644
--- a/sdk/src/core-render.ts
+++ b/sdk/src/core-render.ts
@@ -225,7 +225,9 @@ export {
layerOrderOf,
layerFrontness,
compareDrawRank,
+ rankPickCandidates,
type DrawRank,
+ type PickCandidate,
} from './render/layerOrder';
export {
diff --git a/sdk/src/core-sys.ts b/sdk/src/core-sys.ts
index beacfd4d1..b3ae759e7 100644
--- a/sdk/src/core-sys.ts
+++ b/sdk/src/core-sys.ts
@@ -61,7 +61,8 @@ export {
export { setEntityVisible, isEntityVisible, hasVisibility, setEntityActive, isEntityActive } from './ecs/entityUtils';
-export { entityWorldBox, uiNodeWorldBox, meshWorldBox, entityBoxCorners, type EntityBox, type EntityBoxOptions, type ReadableWorld, type LayoutWorld } from './ecs/entityBox';
+export { entityWorldBox, uiNodeWorldBox, meshWorldBox, entityBoxCorners, entityBoxRayHit, type EntityBox, type EntityBoxOptions, type ReadableWorld, type LayoutWorld } from './ecs/entityBox';
+export { pickEntitiesByRay, type EntityPickOptions, type PickWorld } from './ecs/entityPick';
export { CacheBitmap, type BitmapCache } from './render/cacheBitmap';
export {
CacheAsBitmap,
diff --git a/sdk/src/ecs/entityBox.ts b/sdk/src/ecs/entityBox.ts
index 5ca5e26db..6f2fe81ff 100644
--- a/sdk/src/ecs/entityBox.ts
+++ b/sdk/src/ecs/entityBox.ts
@@ -9,11 +9,11 @@
* agree until a pivot or a parent scale is involved, and then a selection
* outline sits beside the sprite it claims to be around.
*/
-import type { Entity } from '../types';
+import type { Entity, Quat, Vec3 } from '../types';
import type { World } from './world';
import { Transform, Sprite, Mesh2D } from './component';
import { UINode } from '../ui/core/ui-node';
-import { quaternionToAngle2D } from '../ui/util/math';
+import { q } from '../math/quat';
import { worldEngineApi } from './bridge/engineApi';
/**
@@ -25,16 +25,22 @@ import { worldEngineApi } from './bridge/engineApi';
export type ReadableWorld = Pick<World, 'valid' | 'has' | 'get'>;
/**
- * An oriented box in world units: centre, half-extents, and rotation in radians.
+ * An oriented box in world units: a centre, half-extents along its own three
+ * axes, and the rotation that turns those axes into the world's.
+ *
+ * A sprite, a UI node and any other quad have `hd` zero — they are flat, and a
+ * box given thickness they do not have is hit by a ray that passes in front.
*
* @experimental
*/
export interface EntityBox {
cx: number;
cy: number;
+ cz: number;
hw: number;
hh: number;
- rot: number;
+ hd: number;
+ rot: Quat;
}
/** @experimental */
@@ -47,6 +53,12 @@ export interface EntityBoxOptions {
iconHalf?: number;
}
+/** The rotation an entity is drawn with, defaulted for a partial write. */
+function worldRot(t: { worldRotation: unknown }): Quat {
+ const r = t.worldRotation as Partial<Quat> | undefined;
+ return { x: r?.x ?? 0, y: r?.y ?? 0, z: r?.z ?? 0, w: r?.w ?? 1 };
+}
+
/**
* The world box of `entity`, or null when it has none.
*
@@ -61,18 +73,21 @@ export function entityWorldBox(world: ReadableWorld, entity: Entity, opts?: Enti
if (world.has(entity, UINode)) return null;
const t = world.get(entity, Transform);
- const r = t.worldRotation as { z: number; w: number };
- const rot = quaternionToAngle2D(r.z, r.w);
+ const rot = worldRot(t);
const iconHalf = opts?.iconHalf ?? 0;
+ // An icon is a marker in space rather than a card, so it is a cube: it reads
+ // and clicks the same from wherever the view has been turned to.
let w = iconHalf * 2;
let h = iconHalf * 2;
+ let d = iconHalf * 2;
let px = 0.5;
let py = 0.5;
if (world.has(entity, Sprite)) {
const sp = world.get(entity, Sprite);
w = sp.size.x * t.worldScale.x;
h = sp.size.y * t.worldScale.y;
+ d = 0;
px = sp.pivot?.x ?? 0.5;
py = sp.pivot?.y ?? 0.5;
} else if (iconHalf === 0) {
@@ -81,15 +96,14 @@ export function entityWorldBox(world: ReadableWorld, entity: Entity, opts?: Enti
// The centre orbits the transform position when the pivot is off-centre —
// the position is what rotation turns around, not the middle of the sprite.
- const ox = w * (0.5 - px);
- const oy = h * (0.5 - py);
- const c = Math.cos(rot);
- const s = Math.sin(rot);
+ const offset = q.rotate(rot, { x: w * (0.5 - px), y: h * (0.5 - py), z: 0 });
return {
- cx: t.worldPosition.x + ox * c - oy * s,
- cy: t.worldPosition.y + ox * s + oy * c,
+ cx: t.worldPosition.x + offset.x,
+ cy: t.worldPosition.y + offset.y,
+ cz: (t.worldPosition.z ?? 0) + offset.z,
hw: Math.abs(w) / 2,
hh: Math.abs(h) / 2,
+ hd: Math.abs(d) / 2,
rot,
};
}
@@ -118,17 +132,23 @@ export function uiNodeWorldBox(world: LayoutWorld, entity: Entity): EntityBox |
const w = engine.uiNode_computedWidth(registry, entity) * t.worldScale.x;
const h = engine.uiNode_computedHeight(registry, entity) * t.worldScale.y;
if (!(w > 0) || !(h > 0)) return null;
- const r = t.worldRotation as { z: number; w: number };
return {
cx: t.worldPosition.x,
cy: t.worldPosition.y,
+ cz: t.worldPosition.z ?? 0,
hw: Math.abs(w) / 2,
hh: Math.abs(h) / 2,
- rot: quaternionToAngle2D(r.z, r.w),
+ hd: 0,
+ rot: worldRot(t),
};
}
-interface LocalBounds { minX: number; minY: number; maxX: number; maxY: number }
+/** What the engine answers about a mesh's extent. The z pair is optional: a core
+ * without it is reporting geometry with no thickness. */
+interface LocalBounds {
+ minX: number; minY: number; minZ?: number;
+ maxX: number; maxY: number; maxZ?: number;
+}
/**
* The world box of a Mesh2D's geometry — {@link entityWorldBox} for a mesh,
@@ -152,34 +172,79 @@ export function meshWorldBox(world: LayoutWorld, entity: Entity): EntityBox | nu
if (!b) return null;
const t = world.get(entity, Transform);
- const rot = quaternionToAngle2D((t.worldRotation as { z: number }).z,
- (t.worldRotation as { w: number }).w);
+ const rot = worldRot(t);
+ const minZ = b.minZ ?? 0;
+ const maxZ = b.maxZ ?? 0;
+ const scaleZ = t.worldScale.z ?? 1;
// The geometry's centre is its own, not the transform's: a mesh authored
// off-origin is drawn off-origin, and its box has to follow.
- const ox = (b.minX + b.maxX) / 2 * t.worldScale.x;
- const oy = (b.minY + b.maxY) / 2 * t.worldScale.y;
- const c = Math.cos(rot);
- const s = Math.sin(rot);
+ const offset = q.rotate(rot, {
+ x: ((b.minX + b.maxX) / 2) * t.worldScale.x,
+ y: ((b.minY + b.maxY) / 2) * t.worldScale.y,
+ z: ((minZ + maxZ) / 2) * scaleZ,
+ });
return {
- cx: t.worldPosition.x + ox * c - oy * s,
- cy: t.worldPosition.y + ox * s + oy * c,
+ cx: t.worldPosition.x + offset.x,
+ cy: t.worldPosition.y + offset.y,
+ cz: (t.worldPosition.z ?? 0) + offset.z,
hw: Math.abs((b.maxX - b.minX) * t.worldScale.x) / 2,
hh: Math.abs((b.maxY - b.minY) * t.worldScale.y) / 2,
+ hd: Math.abs((maxZ - minZ) * scaleZ) / 2,
rot,
};
}
/**
- * The box's four corners in world units, counter-clockwise from its local
- * -x,-y — what an outline is drawn through.
+ * The box's eight corners in world units — what an outline is drawn through and
+ * what a union is taken over. A flat box reports four of them twice, which is
+ * what a quad's eight corners are.
+ *
+ * @experimental
+ */
+export function entityBoxCorners(b: EntityBox): Vec3[] {
+ const out: Vec3[] = [];
+ for (const sz of [-1, 1]) {
+ for (const sy of [-1, 1]) {
+ for (const sx of [-1, 1]) {
+ const r = q.rotate(b.rot, { x: sx * b.hw, y: sy * b.hh, z: sz * b.hd });
+ out.push({ x: b.cx + r.x, y: b.cy + r.y, z: b.cz + r.z });
+ }
+ }
+ }
+ return out;
+}
+
+/**
+ * How far along @p dir a ray from @p origin travels to meet the box, or null
+ * when it misses.
+ *
+ * The slab test in the box's own frame. Zero half-extent is a flat box rather
+ * than a degenerate one: a ray parallel to it hits only from within its plane.
*
* @experimental
*/
-export function entityBoxCorners(b: EntityBox): Array<{ x: number; y: number }> {
- const c = Math.cos(b.rot);
- const s = Math.sin(b.rot);
- return ([[-b.hw, -b.hh], [b.hw, -b.hh], [b.hw, b.hh], [-b.hw, b.hh]] as const).map(([lx, ly]) => ({
- x: b.cx + lx * c - ly * s,
- y: b.cy + lx * s + ly * c,
- }));
+export function entityBoxRayHit(b: EntityBox, origin: Vec3, dir: Vec3): number | null {
+ const inv = q.conjugate(b.rot);
+ const o = q.rotate(inv, { x: origin.x - b.cx, y: origin.y - b.cy, z: origin.z - b.cz });
+ const d = q.rotate(inv, dir);
+ const at = [o.x, o.y, o.z];
+ const along = [d.x, d.y, d.z];
+ const half = [b.hw, b.hh, b.hd];
+
+ let enter = -Infinity;
+ let exit = Infinity;
+ for (let i = 0; i < 3; i++) {
+ if (Math.abs(along[i]!) < 1e-9) {
+ if (Math.abs(at[i]!) > half[i]! + 1e-6) return null;
+ continue;
+ }
+ const t1 = (-half[i]! - at[i]!) / along[i]!;
+ const t2 = (half[i]! - at[i]!) / along[i]!;
+ enter = Math.max(enter, Math.min(t1, t2));
+ exit = Math.min(exit, Math.max(t1, t2));
+ }
+ // A screen ray starts on the near plane, so everything drawn is ahead of it;
+ // a box the ray starts inside is entered at zero rather than behind.
+ if (exit < enter || exit < 0) return null;
+ return Math.max(enter, 0);
}
diff --git a/sdk/src/ecs/entityPick.ts b/sdk/src/ecs/entityPick.ts
new file mode 100644
index 000000000..f2de6fe21
--- /dev/null
+++ b/sdk/src/ecs/entityPick.ts
@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file entityPick.ts
+ * @brief Which entities a click lands on, for whoever is holding a camera.
+ *
+ * The editor's viewport and a running game ask the same question of the same
+ * boxes. They asked it twice, and the two answers had drifted: one knew a mesh's
+ * extent and the other boxed a model as a point.
+ */
+import type { Entity } from '../types';
+import type { World } from './world';
+import type { WorldRay } from '../ui/util/math';
+import { Transform, Sprite } from './component';
+import { layerOrderOf, rankPickCandidates, type PickCandidate } from '../render/layerOrder';
+import {
+ entityWorldBox, meshWorldBox, entityBoxRayHit, type LayoutWorld,
+} from './entityBox';
+
+/** Sorting layer for an entity that has none of its own, where a realm draws a
+ * gizmo for it: above every real layer, so a small marker wins against the
+ * sprite it sits on. A realm that draws no gizmos has nothing up there. */
+const GIZMO_PICK_LAYER = 1e6;
+
+/**
+ * The reads a pick needs: a box's, plus the World's own list of entities.
+ *
+ * @experimental
+ */
+export type PickWorld = LayoutWorld & Pick<World, 'getAllEntities'>;
+
+/** @experimental */
+export interface EntityPickOptions {
+ /**
+ * World half-size of the box given to entities that draw nothing — a camera,
+ * a light, an empty. Zero (the default) leaves them unpickable, which is what
+ * a realm that draws no gizmo for them wants.
+ */
+ iconHalf?: number;
+ /** Entities this realm refuses to select. Everything is selectable by default. */
+ pickable?(entity: Entity): boolean;
+ /** The project's sorting-layer masks, so hits rank the way the frame stacked them. */
+ ySortLayers?: number;
+ depthLayers?: number;
+}
+
+/**
+ * Entities the ray meets, topmost first.
+ *
+ * The ray decides what is hit; the layer rules decide which of the hits is on
+ * top, because that is what the renderer stacked them by and a click that ranked
+ * them any other way selects something the person cannot see.
+ *
+ * @experimental
+ */
+export function pickEntitiesByRay(
+ world: PickWorld, ray: WorldRay, opts: EntityPickOptions = {},
+): Entity[] {
+ const iconHalf = opts.iconHalf ?? 0;
+ const unlayered = iconHalf > 0 ? GIZMO_PICK_LAYER : 0;
+ const hits: PickCandidate<Entity>[] = [];
+ for (const entity of world.getAllEntities()) {
+ if (!world.valid(entity) || !world.has(entity, Transform)) continue;
+ if (opts.pickable && !opts.pickable(entity)) continue;
+ // A mesh's extent is in its vertices, so it is asked for before the icon
+ // fallback would answer with the size of a gizmo.
+ const box = meshWorldBox(world, entity) ?? entityWorldBox(world, entity, { iconHalf });
+ if (!box || entityBoxRayHit(box, ray.origin, ray.dir) === null) continue;
+
+ const layer = world.has(entity, Sprite) ? world.get(entity, Sprite).layer : unlayered;
+ const t = world.get(entity, Transform);
+ hits.push({
+ entity,
+ index: hits.length,
+ rank: {
+ layer,
+ order: layerOrderOf(layer, opts.ySortLayers ?? 0, opts.depthLayers ?? 0),
+ worldY: t.worldPosition.y,
+ worldZ: t.worldPosition.z ?? 0,
+ },
+ });
+ }
+ return rankPickCandidates(hits);
+}
diff --git a/sdk/src/math/quat.ts b/sdk/src/math/quat.ts
index 4fb28c0cc..fa33206f5 100644
--- a/sdk/src/math/quat.ts
+++ b/sdk/src/math/quat.ts
@@ -13,7 +13,7 @@
* here is what lets those entries compose instead of overwrite.
*/
-import type { Quat } from '../types';
+import type { Quat, Vec3 } from '../types';
const DEG2RAD = Math.PI / 180;
const RAD2DEG = 180 / Math.PI;
@@ -60,6 +60,22 @@ export const q = {
* whether a component-wise interpolation takes the short arc or the long one. */
neg(a: Quat): Quat { return { w: -a.w, x: -a.x, y: -a.y, z: -a.z }; },
+ /** The opposite turn. For a unit quaternion — which every stored rotation is
+ * — this is the inverse, and a world direction taken into a local frame by it. */
+ conjugate(a: Quat): Quat { return { w: a.w, x: -a.x, y: -a.y, z: -a.z }; },
+
+ /** A vector turned by this rotation (q·v·q⁻¹, expanded). */
+ rotate(a: Quat, v: Vec3): Vec3 {
+ const tx = 2 * (a.y * v.z - a.z * v.y);
+ const ty = 2 * (a.z * v.x - a.x * v.z);
+ const tz = 2 * (a.x * v.y - a.y * v.x);
+ return {
+ x: v.x + a.w * tx + a.y * tz - a.z * ty,
+ y: v.y + a.w * ty + a.z * tx - a.x * tz,
+ z: v.z + a.w * tz + a.x * ty - a.y * tx,
+ };
+ },
+
/**
* A rotation as three degrees, applied X then Y then Z about fixed axes —
* the order every DCC's inspector shows. A rotation purely about Z reads
diff --git a/sdk/src/physics3d/ColliderShape3D.ts b/sdk/src/physics3d/ColliderShape3D.ts
index 3fbb20d7f..179d951be 100644
--- a/sdk/src/physics3d/ColliderShape3D.ts
+++ b/sdk/src/physics3d/ColliderShape3D.ts
@@ -20,6 +20,7 @@
* pixels-per-unit on its way into the solver), so nothing here scales.
*/
import type { Vec3, Quat } from '../types';
+import { q } from '../math/quat';
import type { World } from '../ecs/world';
import {
RigidBody3D, BoxCollider3D, SphereCollider3D, CapsuleCollider3D,
@@ -59,17 +60,9 @@ export interface Collider3DInstance {
const ZERO: Vec3 = { x: 0, y: 0, z: 0 };
/** Turn a vector by a rotation — what places an anchor, an axis or a wireframe
- * vertex in the world, and the one piece of 3D maths every visualizer needs. */
-export function rotateVec3ByQuat(q: Quat, v: Vec3): Vec3 {
- // t = 2 * (q.xyz × v); v' = v + q.w * t + q.xyz × t
- const tx = 2 * (q.y * v.z - q.z * v.y);
- const ty = 2 * (q.z * v.x - q.x * v.z);
- const tz = 2 * (q.x * v.y - q.y * v.x);
- return {
- x: v.x + q.w * tx + q.y * tz - q.z * ty,
- y: v.y + q.w * ty + q.z * tx - q.x * tz,
- z: v.z + q.w * tz + q.x * ty - q.y * tx,
- };
+ * vertex in the world. The maths is the math module's; this is its name here. */
+export function rotateVec3ByQuat(rot: Quat, v: Vec3): Vec3 {
+ return q.rotate(rot, v);
}
/** Local AABB of a loaded mesh's collision triangles, or null when nothing loaded them. */
diff --git a/sdk/src/render/layerOrder.ts b/sdk/src/render/layerOrder.ts
index ef7417be4..7a954aceb 100644
--- a/sdk/src/render/layerOrder.ts
+++ b/sdk/src/render/layerOrder.ts
@@ -77,3 +77,23 @@ export function compareDrawRank(a: DrawRank, b: DrawRank): number {
if (a.layer !== b.layer) return a.layer - b.layer;
return layerFrontness(a.order, a.worldY, a.worldZ) - layerFrontness(b.order, b.worldY, b.worldZ);
}
+
+/** One entity under the pointer, with everything its rank depends on. */
+export interface PickCandidate<T> {
+ entity: T;
+ /** Where the frame put it: layer, that layer's rule, and the world coords it uses. */
+ rank: DrawRank;
+ /** Position in the World's iteration order: the paint order for equal depth. */
+ index: number;
+}
+
+/**
+ * Candidates ranked topmost-first, the way the RENDERER stacked them — the layer
+ * rules via {@link compareDrawRank}, then later-drawn winning ties. Backwards
+ * means a click selects what is hidden behind what the person aimed at.
+ */
+export function rankPickCandidates<T>(candidates: ReadonlyArray<PickCandidate<T>>): T[] {
+ return [...candidates]
+ .sort((a, b) => compareDrawRank(b.rank, a.rank) || b.index - a.index)
+ .map((c) => c.entity);
+}
diff --git a/sdk/tests/entity-box.test.ts b/sdk/tests/entity-box.test.ts
index 9ad4c224e..685733207 100644
--- a/sdk/tests/entity-box.test.ts
+++ b/sdk/tests/entity-box.test.ts
@@ -8,7 +8,7 @@
* sitting beside its sprite is made of. One definition, these claims.
*/
import { describe, expect, it } from 'vitest';
-import { entityWorldBox, entityBoxCorners, uiNodeWorldBox, meshWorldBox } from '../src/ecs/entityBox';
+import { entityWorldBox, entityBoxCorners, entityBoxRayHit, uiNodeWorldBox, meshWorldBox } from '../src/ecs/entityBox';
import { Transform, Sprite, Mesh2D } from '../src/ecs/component';
import { UINode } from '../src/ui/core/ui-node';
import type { Entity } from '../src/types';
@@ -32,7 +32,7 @@ const T = (x: number, y: number, sx = 1, sy = 1, angle = 0) => ({
});
/** The engine side of a mesh box: the bounds of whichever geometry is live. */
-const meshBounds = (b: { minX: number; minY: number; maxX: number; maxY: number } | null) => ({
+const meshBounds = (b: { minX: number; minY: number; maxX: number; maxY: number; minZ?: number; maxZ?: number } | null) => ({
getCppRegistry: () => ({}),
getWasmModule: () => ({ mesh2d_localBounds: () => b }),
});
@@ -45,6 +45,15 @@ const layout = (w: number, h: number) => ({
const name = (c: unknown): string => (c as { _name?: string })._name ?? (c as { name: string }).name;
const ent = (n: number) => n as unknown as Entity;
+const IDENTITY = { x: 0, y: 0, z: 0, w: 1 };
+
+/** A turn of `rad` about one world axis, as a rotation. */
+const turn = (axis: 'x' | 'y' | 'z', rad: number) => ({
+ x: axis === 'x' ? Math.sin(rad / 2) : 0,
+ y: axis === 'y' ? Math.sin(rad / 2) : 0,
+ z: axis === 'z' ? Math.sin(rad / 2) : 0,
+ w: Math.cos(rad / 2),
+});
describe('an entity world box', () => {
it('is the sprite size taken through the WORLD scale', () => {
@@ -54,7 +63,7 @@ describe('an entity world box', () => {
1: { [name(Transform)]: T(10, 20, 2, 3), [name(Sprite)]: { size: { x: 100, y: 50 }, pivot: { x: 0.5, y: 0.5 } } },
});
const box = entityWorldBox(world, ent(1));
- expect(box).toEqual({ cx: 10, cy: 20, hw: 100, hh: 75, rot: 0 });
+ expect(box).toEqual({ cx: 10, cy: 20, cz: 0, hw: 100, hh: 75, hd: 0, rot: { x: 0, y: 0, z: 0, w: 1 } });
});
it('puts the centre off the transform when the pivot is off-centre', () => {
@@ -86,7 +95,10 @@ describe('an entity world box', () => {
it('reports nothing for an entity that draws nothing, unless given an icon size', () => {
const world = fakeWorld({ 1: { [name(Transform)]: T(5, 5) } });
expect(entityWorldBox(world, ent(1))).toBeNull();
- expect(entityWorldBox(world, ent(1), { iconHalf: 24 })).toEqual({ cx: 5, cy: 5, hw: 24, hh: 24, rot: 0 });
+ // A cube, not a card: an icon is a marker in space and reads the same from
+ // wherever the view has been turned to.
+ expect(entityWorldBox(world, ent(1), { iconHalf: 24 }))
+ .toEqual({ cx: 5, cy: 5, cz: 0, hw: 24, hh: 24, hd: 24, rot: { x: 0, y: 0, z: 0, w: 1 } });
});
it('has no box for an entity that is not there', () => {
@@ -99,7 +111,7 @@ describe('an entity world box', () => {
expect(entityWorldBox(world, ent(1))).toBeNull();
// Scaled like any other box, centred on the transform: layout gives size,
// the transform gives place.
- expect(uiNodeWorldBox(world, ent(1))).toEqual({ cx: 0, cy: 0, hw: 120, hh: 20, rot: 0 });
+ expect(uiNodeWorldBox(world, ent(1))).toEqual({ cx: 0, cy: 0, cz: 0, hw: 120, hh: 20, hd: 0, rot: { x: 0, y: 0, z: 0, w: 1 } });
});
it('has no UI box for something that is not a laid-out UI node', () => {
@@ -110,14 +122,14 @@ describe('an entity world box', () => {
expect(uiNodeWorldBox({ ...fakeWorld(node) as object, ...layout(0, 0) } as never, ent(1))).toBeNull();
});
- it('walks its corners counter-clockwise from the local -x,-y', () => {
- const corners = entityBoxCorners({ cx: 0, cy: 0, hw: 2, hh: 1, rot: 0 });
- expect(corners).toEqual([
- { x: -2, y: -1 },
- { x: 2, y: -1 },
- { x: 2, y: 1 },
- { x: -2, y: 1 },
- ]);
+ it('has eight corners, which for a flat box are its four twice over', () => {
+ const flat = entityBoxCorners({ cx: 0, cy: 0, cz: 0, hw: 2, hh: 1, hd: 0, rot: IDENTITY });
+ expect(flat).toHaveLength(8);
+ expect(new Set(flat.map((c) => `${c.x},${c.y},${c.z}`)).size).toBe(4);
+
+ const solid = entityBoxCorners({ cx: 0, cy: 0, cz: 0, hw: 2, hh: 1, hd: 3, rot: IDENTITY });
+ expect(new Set(solid.map((c) => `${c.x},${c.y},${c.z}`)).size).toBe(8);
+ expect(Math.min(...solid.map((c) => c.z))).toBe(-3);
});
});
@@ -129,7 +141,7 @@ describe('a mesh world box', () => {
...fakeWorld({ 1: { [name(Transform)]: T(10, 20, 2, 3), [name(Mesh2D)]: {} } }),
...meshBounds({ minX: -50, minY: -10, maxX: 50, maxY: 10 }),
} as never;
- expect(meshWorldBox(world, ent(1))).toEqual({ cx: 10, cy: 20, hw: 100, hh: 30, rot: 0 });
+ expect(meshWorldBox(world, ent(1))).toEqual({ cx: 10, cy: 20, cz: 0, hw: 100, hh: 30, hd: 0, rot: { x: 0, y: 0, z: 0, w: 1 } });
});
it('follows geometry authored off the origin', () => {
@@ -137,7 +149,7 @@ describe('a mesh world box', () => {
...fakeWorld({ 1: { [name(Transform)]: T(0, 0), [name(Mesh2D)]: {} } }),
...meshBounds({ minX: 100, minY: 0, maxX: 300, maxY: 40 }),
} as never;
- expect(meshWorldBox(world, ent(1))).toEqual({ cx: 200, cy: 20, hw: 100, hh: 20, rot: 0 });
+ expect(meshWorldBox(world, ent(1))).toEqual({ cx: 200, cy: 20, cz: 0, hw: 100, hh: 20, hd: 0, rot: { x: 0, y: 0, z: 0, w: 1 } });
});
it('has none when the mesh draws nothing, and none for a non-mesh', () => {
@@ -153,3 +165,66 @@ describe('a mesh world box', () => {
expect(meshWorldBox(sprite, ent(1))).toBeNull();
});
});
+
+// =============================================================================
+// Hit testing. A box was a rect with a Z angle, and a click was a point on the
+// entity's own z plane — which answers correctly only while the eye is head-on
+// and the entity is turned about nothing but z.
+// =============================================================================
+
+const ray = (origin: { x: number; y: number; z: number }, dir: { x: number; y: number; z: number }) => {
+ const len = Math.hypot(dir.x, dir.y, dir.z);
+ return { origin, dir: { x: dir.x / len, y: dir.y / len, z: dir.z / len } };
+};
+
+const FLAT = { cx: 0, cy: 0, cz: 0, hw: 50, hh: 20, hd: 0, rot: IDENTITY };
+const DOWN_Z = { x: 0, y: 0, z: -1 };
+
+describe('a ray against an entity box', () => {
+ it('hits a flat box through its face and misses beside it', () => {
+ expect(entityBoxRayHit(FLAT, { x: 0, y: 0, z: 100 }, DOWN_Z)).toBeCloseTo(100, 6);
+ expect(entityBoxRayHit(FLAT, { x: 49, y: 19, z: 100 }, DOWN_Z)).toBeCloseTo(100, 6);
+ expect(entityBoxRayHit(FLAT, { x: 51, y: 0, z: 100 }, DOWN_Z)).toBeNull();
+ expect(entityBoxRayHit(FLAT, { x: 0, y: 21, z: 100 }, DOWN_Z)).toBeNull();
+ });
+
+ // The whole reason the box carries a rotation rather than an angle: turned
+ // about y, a wide sprite is edge-on, and a hit test that only knew its z turn
+ // would still report the width it no longer covers.
+ it('turns with a rotation about x or y, which an angle could not express', () => {
+ const edgeOn = { ...FLAT, rot: turn('y', Math.PI / 2) };
+ expect(entityBoxRayHit(edgeOn, { x: 40, y: 0, z: 100 }, DOWN_Z)).toBeNull();
+ // Straight down the middle it is met at z = +50, where its width went.
+ expect(entityBoxRayHit(edgeOn, { x: 0, y: 0, z: 100 }, DOWN_Z)).toBeCloseTo(50, 6);
+ // ...and it is now 100 units deep where it was 100 units wide.
+ expect(entityBoxRayHit(edgeOn, { x: -400, y: 0, z: 40 }, { x: 1, y: 0, z: 0 })).toBeCloseTo(400, 6);
+ });
+
+ it('is the distance to the near face, and zero from inside', () => {
+ const solid = { ...FLAT, hd: 10 };
+ expect(entityBoxRayHit(solid, { x: 0, y: 0, z: 60 }, DOWN_Z)).toBeCloseTo(50, 6);
+ expect(entityBoxRayHit(solid, { x: 0, y: 0, z: 0 }, DOWN_Z)).toBe(0);
+ });
+
+ it('misses what is entirely behind the ray', () => {
+ expect(entityBoxRayHit(FLAT, { x: 0, y: 0, z: 100 }, { x: 0, y: 0, z: 1 })).toBeNull();
+ });
+
+ // A quad has no thickness, so a ray in its plane is in it — which is what a
+ // 2D editor asking "is the cursor on this sprite" has always meant.
+ it('meets a flat box from within its own plane', () => {
+ expect(entityBoxRayHit(FLAT, { x: -100, y: 0, z: 0 }, { x: 1, y: 0, z: 0 })).toBeCloseTo(50, 6);
+ expect(entityBoxRayHit(FLAT, { x: -100, y: 0, z: 1 }, { x: 1, y: 0, z: 0 })).toBeNull();
+ });
+
+ it('takes the depth a mesh reports, so a model is not a card', () => {
+ const world = {
+ ...fakeWorld({ 1: { [name(Transform)]: T(0, 0), [name(Mesh2D)]: {} } }),
+ ...meshBounds({ minX: -50, minY: -50, maxX: 50, maxY: 50, minZ: -50, maxZ: 50 }),
+ } as never;
+ const box = meshWorldBox(world, ent(1))!;
+ expect(box.hd).toBe(50);
+ // Side-on: nothing a box built from x and y alone could be hit by.
+ expect(entityBoxRayHit(box, { x: 500, y: 0, z: 0 }, { x: -1, y: 0, z: 0 })).toBeCloseTo(450, 6);
+ });
+});
diff --git a/sdk/tests/entity-pick.test.ts b/sdk/tests/entity-pick.test.ts
new file mode 100644
index 000000000..3147bac1f
--- /dev/null
+++ b/sdk/tests/entity-pick.test.ts
@@ -0,0 +1,107 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file One hit test for both realms.
+ *
+ * The editor's viewport and a running game ask the same question of the same
+ * boxes, and asked it twice: the answers had drifted to where a model was
+ * clickable in one and a point in the other.
+ */
+import { describe, expect, it } from 'vitest';
+import { pickEntitiesByRay } from '../src/ecs/entityPick';
+import { Transform, Sprite, Mesh2D } from '../src/ecs/component';
+import type { Entity } from '../src/types';
+
+const name = (c: unknown): string => (c as { _name?: string })._name ?? (c as { name: string }).name;
+const ent = (n: number) => n as unknown as Entity;
+
+/** A world of hand-written component values, plus the list a pick walks. */
+function fakeWorld(
+ rows: Record<number, Record<string, unknown>>,
+ meshBounds: Record<number, { minX: number; minY: number; minZ: number; maxX: number; maxY: number; maxZ: number }> = {},
+) {
+ return {
+ valid: (e: Entity) => rows[e as unknown as number] !== undefined,
+ has: (e: Entity, c: unknown) => rows[e as unknown as number]?.[name(c)] !== undefined,
+ get: (e: Entity, c: unknown) => rows[e as unknown as number]?.[name(c)],
+ getAllEntities: () => Object.keys(rows).map((k) => ent(Number(k))),
+ getCppRegistry: () => ({}),
+ getWasmModule: () => ({
+ mesh2d_localBounds: (_r: unknown, e: number) => meshBounds[e] ?? null,
+ }),
+ } as never;
+}
+
+const T = (x: number, y: number, z = 0) => ({
+ worldPosition: { x, y, z },
+ worldScale: { x: 1, y: 1, z: 1 },
+ worldRotation: { x: 0, y: 0, z: 0, w: 1 },
+});
+
+const sprite = (layer: number) => ({ size: { x: 100, y: 100 }, pivot: { x: 0.5, y: 0.5 }, layer });
+
+const down = (x: number, y: number) => ({ origin: { x, y, z: 1000 }, dir: { x: 0, y: 0, z: -1 } });
+
+describe('picking entities by ray', () => {
+ it('returns what the ray meets, ranked the way the frame stacked it', () => {
+ const world = fakeWorld({
+ 1: { [name(Transform)]: T(0, 0), [name(Sprite)]: sprite(0) },
+ 2: { [name(Transform)]: T(0, 0), [name(Sprite)]: sprite(3) },
+ });
+ expect(pickEntitiesByRay(world, down(0, 0))).toEqual([ent(2), ent(1)]);
+ });
+
+ it('leaves out what the ray misses', () => {
+ const world = fakeWorld({
+ 1: { [name(Transform)]: T(0, 0), [name(Sprite)]: sprite(0) },
+ 2: { [name(Transform)]: T(400, 0), [name(Sprite)]: sprite(0) },
+ });
+ expect(pickEntitiesByRay(world, down(0, 0))).toEqual([ent(1)]);
+ });
+
+ // The play realm boxed a model by its transform alone, so a click anywhere on
+ // an imported mesh landed on whatever was behind it.
+ it('takes a mesh by its geometry, in a realm that draws no icons', () => {
+ const world = fakeWorld(
+ { 1: { [name(Transform)]: T(0, 0), [name(Mesh2D)]: {} } },
+ { 1: { minX: -200, minY: -200, minZ: -200, maxX: 200, maxY: 200, maxZ: 200 } },
+ );
+ expect(pickEntitiesByRay(world, down(150, 150))).toEqual([ent(1)]);
+ expect(pickEntitiesByRay(world, down(250, 0))).toEqual([]);
+ });
+
+ it('only boxes what draws nothing when the realm draws a gizmo for it', () => {
+ const world = fakeWorld({ 1: { [name(Transform)]: T(0, 0) } });
+ expect(pickEntitiesByRay(world, down(10, 10))).toEqual([]);
+ expect(pickEntitiesByRay(world, down(10, 10), { iconHalf: 24 })).toEqual([ent(1)]);
+ });
+
+ // A gizmo is drawn over everything, so it is clicked before the sprite it
+ // sits on — and only in a realm that draws one.
+ it('ranks a gizmo above the sprite beneath it', () => {
+ const world = fakeWorld({
+ 1: { [name(Transform)]: T(0, 0), [name(Sprite)]: sprite(5) },
+ 2: { [name(Transform)]: T(0, 0) },
+ });
+ expect(pickEntitiesByRay(world, down(0, 0), { iconHalf: 24 })).toEqual([ent(2), ent(1)]);
+ });
+
+ it('drops what the realm refuses to select', () => {
+ const world = fakeWorld({
+ 1: { [name(Transform)]: T(0, 0), [name(Sprite)]: sprite(0) },
+ 2: { [name(Transform)]: T(0, 0), [name(Sprite)]: sprite(1) },
+ });
+ const only = pickEntitiesByRay(world, down(0, 0), { pickable: (e) => e === ent(1) });
+ expect(only).toEqual([ent(1)]);
+ });
+
+ // Depth is the ray's, not the cursor's plane: a sprite well behind another is
+ // still under the same pixel, and both were always meant to be reachable.
+ it('meets everything along the ray, at whatever depth', () => {
+ const world = fakeWorld({
+ 1: { [name(Transform)]: T(0, 0, 0), [name(Sprite)]: sprite(0) },
+ 2: { [name(Transform)]: T(0, 0, -900), [name(Sprite)]: sprite(0) },
+ });
+ expect(pickEntitiesByRay(world, down(0, 0))).toHaveLength(2);
+ });
+});
diff --git a/sdk/tests/mesh-box-integration.test.ts b/sdk/tests/mesh-box-integration.test.ts
index 4bd08c055..cb7e4c362 100644
--- a/sdk/tests/mesh-box-integration.test.ts
+++ b/sdk/tests/mesh-box-integration.test.ts
@@ -64,7 +64,7 @@ describe.skipIf(!HAS_WASM)('a mesh world box (WASM integration)', () => {
app.tick(1 / 60);
expect(meshWorldBox(app.world, e))
- .toEqual({ cx: 10, cy: 20, hw: 100, hh: 30, rot: 0 });
+ .toEqual({ cx: 10, cy: 20, cz: 0, hw: 100, hh: 30, hd: 0, rot: { x: 0, y: 0, z: 0, w: 1 } });
} finally {
dispose(app, registry);
}
diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cpp
index 5953513fa..ce847ec95 100644
--- a/src/esengine/bindings/RendererBindings.cpp
+++ b/src/esengine/bindings/RendererBindings.cpp
@@ -743,23 +743,27 @@ emscripten::val mesh2d_localBounds(ecs::Registry& registry, u32 entity) {
const auto* mesh = registry.tryGet<ecs::Mesh2D>(ent);
if (!mesh) return emscripten::val::null();
- glm::vec2 mn = mesh->localMin;
- glm::vec2 mx = mesh->localMax;
+ // The inline payload is authored as 2D positions and has no third dimension;
+ // resident geometry carries the one it was imported with.
+ glm::vec3 mn(mesh->localMin, 0.0f);
+ glm::vec3 mx(mesh->localMax, 0.0f);
if (mesh->mesh.isValid()) {
if (auto* rm = ctx().tryGet<resource::ResourceManager>()) {
if (const Mesh* res = rm->getMesh(mesh->mesh)) {
- mn = glm::vec2(res->localMin);
- mx = glm::vec2(res->localMax);
+ mn = res->localMin;
+ mx = res->localMax;
}
}
}
- if (!(mx.x > mn.x) && !(mx.y > mn.y)) return emscripten::val::null();
+ if (!(mx.x > mn.x) && !(mx.y > mn.y) && !(mx.z > mn.z)) return emscripten::val::null();
auto out = emscripten::val::object();
out.set("minX", mn.x);
out.set("minY", mn.y);
+ out.set("minZ", mn.z);
out.set("maxX", mx.x);
out.set("maxY", mx.y);
+ out.set("maxZ", mx.z);
return out;
}
diff --git a/src/esengine/bindings/RendererBindings.hpp b/src/esengine/bindings/RendererBindings.hpp
index 85fa80c4d..abff01fb0 100644
--- a/src/esengine/bindings/RendererBindings.hpp
+++ b/src/esengine/bindings/RendererBindings.hpp
@@ -125,7 +125,7 @@ u32 renderer_getDrawCalls();
/// GPU objects the device has not destroyed, for the resource census. Null when
/// no device is initialized — absent counters, not zeroed ones.
emscripten::val renderer_getLiveObjects();
-/// Local XY bounds of what a Mesh2D draws (resident geometry, else the inline
+/// Local bounds of what a Mesh2D draws (resident geometry, else the inline
/// payload). Null when it draws nothing — an editor boxes it by its icon then.
emscripten::val mesh2d_localBounds(ecs::Registry& registry, u32 entity);
#endif