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(editor): an entity's box has a third dimension, and one hit test uses it
yhh36947edb0566
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 editoreye could turn, and everything else about it was still pinned to z = 0: itorbited a point on that plane, panned across it, framed on it, and drew its griddiff --git a/desktop/src/engine/ViewportController.ts b/desktop/src/engine/ViewportController.tsindex 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.tsindex 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.tsindex 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.tsxindex 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.tsindex 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/openDataReheaimport { 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 | nconst 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 | nulif (!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 itdiff --git a/desktop/src/tools/alignTools.ts b/desktop/src/tools/alignTools.tsindex 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.tsindex 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.jsonindex 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.mdindex 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: numbercy: number+cz: number+hd: numberhh: numberhw: number-rot: number+rot: Quat```## EntityBoxOptions — interface @experimental@@ -2948,6 +2950,14 @@ static prototype: EntityEventQueueResourceDef<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 @@ ParticlePluginPerceptionPlugin```+## 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 @betadiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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: numbercy: number+cz: number+hd: numberhh: numberhw: number-rot: number+rot: Quat```## EntityBoxOptions — interface @experimental@@ -2956,6 +2958,14 @@ static prototype: EntityEventQueueResourceDef<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 @@ ParticlePluginPerceptionPlugin```+## 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 @betadiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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: numbercy: number+cz: number+hd: numberhh: numberhw: number-rot: number+rot: Quat```## EntityBoxOptions — interface @experimental@@ -2943,6 +2945,14 @@ static prototype: EntityEventQueueResourceDef<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 @@ ParticlePluginPerceptionPlugin```+## 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 @betadiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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: numbercy: number+cz: number+hd: numberhh: numberhw: number-rot: number+rot: Quat```## EntityBoxOptions — interface @experimental@@ -2943,6 +2945,14 @@ static prototype: EntityEventQueueResourceDef<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 @@ ParticlePluginPerceptionPlugin```+## 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 @betadiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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: numbercy: number+cz: number+hd: numberhh: numberhw: number-rot: number+rot: Quat```## EntityBoxOptions — interface @experimental@@ -2943,6 +2945,14 @@ static prototype: EntityEventQueueResourceDef<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 @@ ParticlePluginPerceptionPlugin```+## 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 @betadiff --git a/sdk/src/core-render.ts b/sdk/src/core-render.tsindex 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.tsindex 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.tsindex 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?: Entiif (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 | nuif (!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.tsnew file mode 100644index 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.tsindex 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 readsdiff --git a/sdk/src/physics3d/ColliderShape3D.ts b/sdk/src/physics3d/ColliderShape3D.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.cppindex 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.hppindex 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