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(ai): sensing is three-dimensional
esengine4d8117892b85
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 2c22b9dd0..1cd49ff2a 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -54,6 +54,18 @@ published separately; it ships inside the editor.### Fixed+- **AI sensing is three-dimensional.** A `Perceiver`'s range came from x and y,+ its cone from `atan2` in the same plane, and its facing from the Z half of a+ quaternion — so a guard saw through floors, and any rotation but a flat one+ computed a facing out of nothing. Range and cone are now measured in all three+ axes (the cone as a dot product, which is the same test where both lie in a+ plane), and `Perception` reports `targetZ` / `dirZ`. Line of sight goes through+ the 3D solver where a scene has one; `Perceiver.facingAxis` picks the entity+ axis the cone points down (`x` — screen-right, what a flat scene means — or+ `-z`, where an imported model faces), and `Perceiver.losLayers` is the layer+ mask the 3D sight ray is cast against, since a ray from inside the observer's+ own collider hits it first.+- **Network interest is a sphere.** `radiusInterest` measured the distance to aconnection's pawn in x and y, so two floors of a building were one place andevery connection streamed both — the saving the policy exists to make is the onediff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.jsonindex 146b61c5e..029f4f092 100644--- a/docs/astro/src/data/components.generated.json+++ b/docs/astro/src/data/components.generated.json@@ -2450,11 +2450,27 @@"type": "number","default": "360","range": "0–360"+ },+ {+ "key": "facingAxis",+ "type": "string",+ "default": "\"x\"",+ "doc": "'x' is screen-right (a flat scene); '-z' is where an imported model faces.",+ "advanced": true+ },+ {+ "key": "losLayers",+ "type": "number",+ "default": "0",+ "doc": "3D layer mask the sight ray may hit; 0 = every layer.",+ "range": "≥ 0",+ "advanced": true}],"animatable": ["range",- "fovDegrees"+ "fovDegrees",+ "losLayers"]},{@@ -2483,6 +2499,11 @@"type": "number","default": "0"},+ {+ "key": "targetZ",+ "type": "number",+ "default": "0"+ },{"key": "dirX","type": "number",@@ -2492,6 +2513,11 @@"key": "dirY","type": "number","default": "0"+ },+ {+ "key": "dirZ",+ "type": "number",+ "default": "0"}],"transient": true,@@ -2499,8 +2525,10 @@"distance","targetX","targetY",+ "targetZ","dirX",- "dirY"+ "dirY",+ "dirZ"]},{diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 593c0ee3c..21cc775b7 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -5019,7 +5019,9 @@ ComponentDef<PerceiverData>## PerceiverData — interface @experimental```+facingAxis: FacingAxisfovDegrees: number+losLayers: numberrange: number```@@ -5032,9 +5034,11 @@ ComponentDef<PerceptionData>```dirX: numberdirY: number+dirZ: numberdistance: numbertargetX: numbertargetY: number+targetZ: numbervisible: boolean```@@ -6830,8 +6834,7 @@ BuiltinComponentDef<SegmentColliderData>## SenseResult — interface @experimental```-dirX: number-dirY: number+dir: Vec3distance: numbervisible: boolean```@@ -10127,9 +10130,9 @@ EventBindingPlugin(entities: readonly ExtractEntity[], rootId: number, name: string, makeId?: (sourceId: number) => PrefabEntityId): PrefabData```-## facingFromQuat — function @experimental+## facingFromRotation — function @experimental```-(z: number, w: number): number+(rot: Quat, axis?: FacingAxis): Vec3```## fetchDecodePixels — function @experimental@@ -11564,7 +11567,7 @@ Plugin## senseTarget — function @experimental```-(ox: number, oy: number, facing: number, tx: number, ty: number, range: number, halfFov: number, isBlocked?: (ox: number, oy: number, tx: number, ty: number) => boolean): SenseResult+(observer: Vec3, facing: Vec3, target: Vec3, range: number, halfFov: number, isBlocked?: (from: Vec3, to: Vec3) => boolean): SenseResult```## serializeAnimClip — function @experimentaldiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 6373f2577..843ee0546 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -5202,7 +5202,9 @@ ComponentDef<PerceiverData>## PerceiverData — interface @experimental```+facingAxis: FacingAxisfovDegrees: number+losLayers: numberrange: number```@@ -5215,9 +5217,11 @@ ComponentDef<PerceptionData>```dirX: numberdirY: number+dirZ: numberdistance: numbertargetX: numbertargetY: number+targetZ: numbervisible: boolean```@@ -7023,8 +7027,7 @@ BuiltinComponentDef<SegmentColliderData>## SenseResult — interface @experimental```-dirX: number-dirY: number+dir: Vec3distance: numbervisible: boolean```@@ -10360,9 +10363,9 @@ EventBindingPlugin(entities: readonly ExtractEntity[], rootId: number, name: string, makeId?: (sourceId: number) => PrefabEntityId): PrefabData```-## facingFromQuat — function @experimental+## facingFromRotation — function @experimental```-(z: number, w: number): number+(rot: Quat, axis?: FacingAxis): Vec3```## fetchDecodePixels — function @experimental@@ -11807,7 +11810,7 @@ Plugin## senseTarget — function @experimental```-(ox: number, oy: number, facing: number, tx: number, ty: number, range: number, halfFov: number, isBlocked?: (ox: number, oy: number, tx: number, ty: number) => boolean): SenseResult+(observer: Vec3, facing: Vec3, target: Vec3, range: number, halfFov: number, isBlocked?: (from: Vec3, to: Vec3) => boolean): SenseResult```## serializeAnimClip — function @experimentaldiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 27e63ff90..dd2c8d9aa 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -5014,7 +5014,9 @@ ComponentDef<PerceiverData>## PerceiverData — interface @experimental```+facingAxis: FacingAxisfovDegrees: number+losLayers: numberrange: number```@@ -5027,9 +5029,11 @@ ComponentDef<PerceptionData>```dirX: numberdirY: number+dirZ: numberdistance: numbertargetX: numbertargetY: number+targetZ: numbervisible: boolean```@@ -6825,8 +6829,7 @@ BuiltinComponentDef<SegmentColliderData>## SenseResult — interface @experimental```-dirX: number-dirY: number+dir: Vec3distance: numbervisible: boolean```@@ -10122,9 +10125,9 @@ EventBindingPlugin(entities: readonly ExtractEntity[], rootId: number, name: string, makeId?: (sourceId: number) => PrefabEntityId): PrefabData```-## facingFromQuat — function @experimental+## facingFromRotation — function @experimental```-(z: number, w: number): number+(rot: Quat, axis?: FacingAxis): Vec3```## fetchDecodePixels — function @experimental@@ -11569,7 +11572,7 @@ Plugin## senseTarget — function @experimental```-(ox: number, oy: number, facing: number, tx: number, ty: number, range: number, halfFov: number, isBlocked?: (ox: number, oy: number, tx: number, ty: number) => boolean): SenseResult+(observer: Vec3, facing: Vec3, target: Vec3, range: number, halfFov: number, isBlocked?: (from: Vec3, to: Vec3) => boolean): SenseResult```## serializeAnimClip — function @experimentaldiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex eba6925c8..60656abad 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -5259,7 +5259,9 @@ ComponentDef<PerceiverData>## PerceiverData — interface @experimental```+facingAxis: FacingAxisfovDegrees: number+losLayers: numberrange: number```@@ -5272,9 +5274,11 @@ ComponentDef<PerceptionData>```dirX: numberdirY: number+dirZ: numberdistance: numbertargetX: numbertargetY: number+targetZ: numbervisible: boolean```@@ -7070,8 +7074,7 @@ BuiltinComponentDef<SegmentColliderData>## SenseResult — interface @experimental```-dirX: number-dirY: number+dir: Vec3distance: numbervisible: boolean```@@ -10372,9 +10375,9 @@ EventBindingPlugin(entities: readonly ExtractEntity[], rootId: number, name: string, makeId?: (sourceId: number) => PrefabEntityId): PrefabData```-## facingFromQuat — function @experimental+## facingFromRotation — function @experimental```-(z: number, w: number): number+(rot: Quat, axis?: FacingAxis): Vec3```## fetchDecodePixels — function @experimental@@ -11819,7 +11822,7 @@ Plugin## senseTarget — function @experimental```-(ox: number, oy: number, facing: number, tx: number, ty: number, range: number, halfFov: number, isBlocked?: (ox: number, oy: number, tx: number, ty: number) => boolean): SenseResult+(observer: Vec3, facing: Vec3, target: Vec3, range: number, halfFov: number, isBlocked?: (from: Vec3, to: Vec3) => boolean): SenseResult```## serializeAnimClip — function @experimentaldiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 517e98633..e35230124 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -5021,7 +5021,9 @@ ComponentDef<PerceiverData>## PerceiverData — interface @experimental```+facingAxis: FacingAxisfovDegrees: number+losLayers: numberrange: number```@@ -5034,9 +5036,11 @@ ComponentDef<PerceptionData>```dirX: numberdirY: number+dirZ: numberdistance: numbertargetX: numbertargetY: number+targetZ: numbervisible: boolean```@@ -6832,8 +6836,7 @@ BuiltinComponentDef<SegmentColliderData>## SenseResult — interface @experimental```-dirX: number-dirY: number+dir: Vec3distance: numbervisible: boolean```@@ -10149,9 +10152,9 @@ EventBindingPlugin(entities: readonly ExtractEntity[], rootId: number, name: string, makeId?: (sourceId: number) => PrefabEntityId): PrefabData```-## facingFromQuat — function @experimental+## facingFromRotation — function @experimental```-(z: number, w: number): number+(rot: Quat, axis?: FacingAxis): Vec3```## fetchDecodePixels — function @experimental@@ -11591,7 +11594,7 @@ Plugin## senseTarget — function @experimental```-(ox: number, oy: number, facing: number, tx: number, ty: number, range: number, halfFov: number, isBlocked?: (ox: number, oy: number, tx: number, ty: number) => boolean): SenseResult+(observer: Vec3, facing: Vec3, target: Vec3, range: number, halfFov: number, isBlocked?: (from: Vec3, to: Vec3) => boolean): SenseResult```## serializeAnimClip — function @experimentaldiff --git a/sdk/src/ai/perception/PerceptionPlugin.ts b/sdk/src/ai/perception/PerceptionPlugin.tsindex c35fa965a..9c1666dac 100644--- a/sdk/src/ai/perception/PerceptionPlugin.ts+++ b/sdk/src/ai/perception/PerceptionPlugin.ts@@ -18,7 +18,10 @@ import { playModeOnly } from '../../ecs/env';import { Transform } from '../../ecs/component';import type { AnyComponentDef, ComponentData } from '../../ecs/component';import { Physics, type PhysicsAPI } from '../../physics';-import { senseTarget, facingFromQuat } from './sense';+import { Physics3D } from '../../physics3d/Physics3DPlugin';+import type { Physics3DQueries } from '../../physics3d/Physics3DQueries';+import { senseTarget, facingFromRotation } from './sense';+import type { Vec3 } from '../../types';import { Perceiver, Perception, PerceptionTarget, type PerceptionData } from './components';/** The slice of `World` the perception step needs — lets tests inject a fake. */@@ -31,43 +34,48 @@ export interface PerceptionWorldView {}/**- * True when the line from (ox,oy) to (tx,ty) is occluded. `observer` and- * `target` are the two bodies at its ends — whatever they own is not what the- * check is asking about.+ * True when the line from `from` to `to` is occluded. `observer` and `target`+ * are the two bodies at its ends — whatever they own is not what the check is+ * asking about. `layers` is the 3D layer mask the caller wants cast against+ * (0 = every layer); a 2D check has no layers and ignores it.*/export type LosCheck = (- ox: number, oy: number, tx: number, ty: number,+ from: Vec3, to: Vec3,observer: Entity, target: Entity,+ layers: number,) => boolean;/** Update every Perceiver's Perception with the nearest visible target. */export function stepPerception(world: PerceptionWorldView, isBlocked?: LosCheck): void {const targets = world.getEntitiesWithComponents([PerceptionTarget, Transform]).map(e => {const t = world.get(e, Transform);- return { e, x: t.position.x, y: t.position.y };+ return { e, at: t.position as Vec3 };});for (const e of world.getEntitiesWithComponents([Perceiver, Transform])) {const cfg = world.get(e, Perceiver);const tf = world.get(e, Transform);- const ox = tf.position.x;- const oy = tf.position.y;- const facing = facingFromQuat(tf.rotation.z, tf.rotation.w);+ const at = tf.position as Vec3;+ const facing = facingFromRotation(tf.rotation, cfg.facingAxis);const halfFov = ((cfg.fovDegrees * Math.PI) / 180) / 2;- let best: { x: number; y: number; distance: number; dirX: number; dirY: number } | null = null;+ let best: { at: Vec3; distance: number; dir: Vec3 } | null = null;for (const t of targets) {if (t.e === e) continue;- const r = senseTarget(ox, oy, facing, t.x, t.y, cfg.range, halfFov,- isBlocked && ((ax, ay, bx, by) => isBlocked(ax, ay, bx, by, e, t.e)));+ const r = senseTarget(at, facing, t.at, cfg.range, halfFov,+ isBlocked && ((from, to) => isBlocked(from, to, e, t.e, cfg.losLayers)));if (r.visible && (!best || r.distance < best.distance)) {- best = { x: t.x, y: t.y, distance: r.distance, dirX: r.dirX, dirY: r.dirY };+ best = { at: t.at, distance: r.distance, dir: r.dir };}}const p: PerceptionData = best- ? { visible: true, distance: best.distance, targetX: best.x, targetY: best.y, dirX: best.dirX, dirY: best.dirY }- : { visible: false, distance: 0, targetX: 0, targetY: 0, dirX: 0, dirY: 0 };+ ? {+ visible: true, distance: best.distance,+ targetX: best.at.x, targetY: best.at.y, targetZ: best.at.z,+ dirX: best.dir.x, dirY: best.dir.y, dirZ: best.dir.z,+ }+ : { visible: false, distance: 0, targetX: 0, targetY: 0, targetZ: 0, dirX: 0, dirY: 0, dirZ: 0 };if (world.has(e, Perception)) world.set(e, Perception, p);else world.insert(e, Perception, p);@@ -81,16 +89,32 @@ export function stepPerception(world: PerceptionWorldView, isBlocked?: LosCheck)* counting that hides everyone approached from below.*/export function makeLosCheck(physics: PhysicsAPI): LosCheck {- return (ox, oy, tx, ty, observer, target) => {- const dx = tx - ox;- const dy = ty - oy;+ return (from, to, observer, target) => {+ const dx = to.x - from.x;+ const dy = to.y - from.y;const dist = Math.hypot(dx, dy);if (dist === 0) return false;- const hits = physics.raycast({ x: ox, y: oy }, { x: dx / dist, y: dy / dist }, dist);+ const hits = physics.raycast({ x: from.x, y: from.y }, { x: dx / dist, y: dy / dist }, dist);return hits.some(h => h.fraction < 0.98 && h.entity !== observer && h.entity !== target);};}+/**+ * The same check through the 3D solver, which answers with the NEAREST body+ * rather than every body on the line: a ray starting inside the observer's own+ * collider reports the observer and nothing behind it, and this has to read that+ * as "not blocked". `Perceiver.losLayers` is how a scene avoids the question.+ */+export function makeLosCheck3D(queries: Physics3DQueries): LosCheck {+ return (from, to, observer, target, layers) => {+ const dir = { x: to.x - from.x, y: to.y - from.y, z: to.z - from.z };+ if (dir.x === 0 && dir.y === 0 && dir.z === 0) return false;+ const hit = queries.raycast(from, dir, layers);+ if (!hit || hit.entity === observer || hit.entity === target) return false;+ return hit.fraction < 0.98;+ };+}+export class PerceptionPlugin implements Plugin {name = 'perception';@@ -100,8 +124,13 @@ export class PerceptionPlugin implements Plugin {defineSystem([GetWorld()],world => {+ // The 3D solver first where a scene has one: its bodies are the+ // walls of a 3D scene, and the 2D one knows nothing about them.+ const q3d = app.hasResource(Physics3D)+ ? app.getResource<Physics3DQueries | null>(Physics3D) : null;const physics = app.hasResource(Physics) ? app.getResource<PhysicsAPI>(Physics) : null;- stepPerception(world as PerceptionWorldView, physics ? makeLosCheck(physics) : undefined);+ const los = q3d ? makeLosCheck3D(q3d) : physics ? makeLosCheck(physics) : undefined;+ stepPerception(world as PerceptionWorldView, los);},{name: 'PerceptionSystem',diff --git a/sdk/src/ai/perception/components.ts b/sdk/src/ai/perception/components.tsindex 56b200867..9473ad1a2 100644--- a/sdk/src/ai/perception/components.ts+++ b/sdk/src/ai/perception/components.ts@@ -9,21 +9,35 @@*/import { defineComponent, defineTag } from '../../ecs/component';+import type { FacingAxis } from './sense';export interface PerceiverData {/** Sight range in world pixels. */range: number;/** Field-of-view cone in degrees; 360 = omnidirectional. */fovDegrees: number;+ /** Which of the entity's own axes the cone points down — see {@link FacingAxis}. */+ facingAxis: FacingAxis;+ /**+ * Physics layers the line-of-sight ray may hit (3D only; 0 = every layer).+ * A ray cast from inside the observer's own body hits it first and the check+ * has to let that through, so a 3D scene keeps sight honest by casting only+ * against the layers that actually block sight.+ */+ losLayers: number;}export const Perceiver = defineComponent<PerceiverData>('Perceiver', {range: 220,fovDegrees: 360,+ facingAxis: 'x',+ losLayers: 0,}, {fields: {range: { min: 0, unit: 'px', category: 'Perception' },fovDegrees: { min: 0, max: 360, unit: '°', category: 'Perception' },+ facingAxis: { category: 'Perception', advanced: true, tooltip: "'x' is screen-right (a flat scene); '-z' is where an imported model faces." },+ losLayers: { min: 0, category: 'Perception', advanced: true, tooltip: '3D layer mask the sight ray may hit; 0 = every layer.' },},});@@ -35,9 +49,11 @@ export interface PerceptionData {/** Seen target position in world pixels. */targetX: number;targetY: number;+ targetZ: number;/** Unit direction observer→target. */dirX: number;dirY: number;+ dirZ: number;}export const Perception = defineComponent<PerceptionData>('Perception', {@@ -45,8 +61,10 @@ export const Perception = defineComponent<PerceptionData>('Perception', {distance: 0,targetX: 0,targetY: 0,+ targetZ: 0,dirX: 0,dirY: 0,+ dirZ: 0,}, {// Runtime-only: the system rewrites it every frame.transient: true,diff --git a/sdk/src/ai/perception/index.ts b/sdk/src/ai/perception/index.tsindex 70d045047..eb03f8204 100644--- a/sdk/src/ai/perception/index.ts+++ b/sdk/src/ai/perception/index.ts@@ -5,7 +5,7 @@* @brief Perception barrel — pure sensing core + components + plugin.*/-export { senseTarget, facingFromQuat, normalizeAngle, type SenseResult } from './sense';+export { senseTarget, facingFromRotation, normalizeAngle, type SenseResult, type FacingAxis } from './sense';export {Perceiver, Perception, PerceptionTarget,type PerceiverData, type PerceptionData,diff --git a/sdk/src/ai/perception/sense.ts b/sdk/src/ai/perception/sense.tsindex 2b4318e22..90a724da5 100644--- a/sdk/src/ai/perception/sense.ts+++ b/sdk/src/ai/perception/sense.ts@@ -9,21 +9,34 @@* engine, a fake in tests) so the core stays free of any physics/wasm type. The* engine's perception system writes the result to a `Perception` component that* FSM conditions / BT leaves read via `ctx.get(Perception)`.+ *+ * Three-dimensional, with the flat case as its degenerate: a cone measured in+ * x and y sees through floors, and a scene the renderer and the solver both+ * treat as spatial has floors.*/+import type { Quat, Vec3 } from '../../types';+import { q } from '../../math/quat';export interface SenseResult {/** Target is within range, inside the cone, and not occluded. */visible: boolean;/** Distance to the target (always set, even when not visible). */distance: number;- /** Unit direction observer→target, or (0,0) when not visible. */- dirX: number;- dirY: number;+ /** Unit direction observer→target, or zero when not visible. */+ dir: Vec3;}-/** 2D facing angle (radians) from a Transform quaternion's z/w (rotation about Z). */-export function facingFromQuat(z: number, w: number): number {- return 2 * Math.atan2(z, w);+/**+ * Which of an entity's own axes its sensing cone points down. `x` is where a flat+ * scene's characters face (unrotated = screen-right); `-z` is where an imported+ * model faces, the convention the camera and lights use. Two conventions in one+ * engine, neither derivable from the other — the entity says which it means.+ */+export type FacingAxis = 'x' | '-z';++/** The world direction an entity with rotation `rot` faces along `axis`. */+export function facingFromRotation(rot: Quat, axis: FacingAxis = 'x'): Vec3 {+ return q.rotate(rot, axis === 'x' ? { x: 1, y: 0, z: 0 } : { x: 0, y: 0, z: -1 });}/** Wrap an angle to (-π, π]. */@@ -35,28 +48,36 @@ export function normalizeAngle(a: number): number {return a;}+const ZERO: Vec3 = { x: 0, y: 0, z: 0 };+/**- * Sense `target` from `observer`. `halfFov` is half the field-of-view in radians- * (≥ π means omnidirectional). `isBlocked(ox,oy,tx,ty)` returns true when the- * line of sight is occluded. An observer standing on the target is visible.+ * Sense `target` from `observer`, which faces along `facing` (need not be unit).+ * `halfFov` is half the field-of-view in radians (≥ π means omnidirectional).+ * `isBlocked(from, to)` returns true when the line of sight is occluded. An+ * observer standing on the target is visible.*/export function senseTarget(- ox: number, oy: number, facing: number,- tx: number, ty: number,+ observer: Vec3, facing: Vec3,+ target: Vec3,range: number, halfFov: number,- isBlocked?: (ox: number, oy: number, tx: number, ty: number) => boolean,+ isBlocked?: (from: Vec3, to: Vec3) => boolean,): SenseResult {- const dx = tx - ox;- const dy = ty - oy;- const dist = Math.hypot(dx, dy);- if (dist === 0) return { visible: true, distance: 0, dirX: 0, dirY: 0 };+ const dx = target.x - observer.x;+ const dy = target.y - observer.y;+ const dz = target.z - observer.z;+ const dist = Math.sqrt(dx * dx + dy * dy + dz * dz);+ if (dist === 0) return { visible: true, distance: 0, dir: ZERO };- const miss: SenseResult = { visible: false, distance: dist, dirX: 0, dirY: 0 };+ const miss: SenseResult = { visible: false, distance: dist, dir: ZERO };if (dist > range) return miss;if (halfFov < Math.PI) {- const delta = Math.abs(normalizeAngle(Math.atan2(dy, dx) - facing));- if (delta > halfFov) return miss;+ // The cone as a dot product rather than an angle difference: the same+ // test where both lie in a plane, and the only one that survives leaving it.+ const fl = Math.sqrt(facing.x * facing.x + facing.y * facing.y + facing.z * facing.z);+ if (fl === 0) return miss; // a cone with no axis points nowhere+ const cos = (dx * facing.x + dy * facing.y + dz * facing.z) / (dist * fl);+ if (cos < Math.cos(halfFov)) return miss;}- if (isBlocked?.(ox, oy, tx, ty)) return miss;- return { visible: true, distance: dist, dirX: dx / dist, dirY: dy / dist };+ if (isBlocked?.(observer, target)) return miss;+ return { visible: true, distance: dist, dir: { x: dx / dist, y: dy / dist, z: dz / dist } };}diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex d7f427ddb..2d0c6ac6e 100644--- a/sdk/src/core-content.ts+++ b/sdk/src/core-content.ts@@ -785,7 +785,7 @@ export {export {senseTarget,- facingFromQuat,+ facingFromRotation,normalizeAngle,Perceiver,Perception,diff --git a/sdk/tests/perception-los.test.ts b/sdk/tests/perception-los.test.tsindex dcb50b6e7..616b87266 100644--- a/sdk/tests/perception-los.test.ts+++ b/sdk/tests/perception-los.test.ts@@ -10,15 +10,20 @@* approach from below while leaving them able to see it from the side, which is* the shape of a bug nobody would think to look for in a raycast.*/-import { describe, it, expect } from 'vitest';-import { makeLosCheck } from '../src/ai/perception/PerceptionPlugin';+import { describe, it, expect, vi } from 'vitest';+import { makeLosCheck, makeLosCheck3D } from '../src/ai/perception/PerceptionPlugin';import type { PhysicsAPI, RaycastHit } from '../src/physics';-import type { Entity } from '../src/types';+import type { Physics3DQueries, Cast3DHit } from '../src/physics3d/Physics3DQueries';+import type { Entity, Vec3 } from '../src/types';const OBSERVER = 11 as Entity;const TARGET = 22 as Entity;const WALL = 33 as Entity;+const at = (x: number, y: number, z = 0): Vec3 => ({ x, y, z });+const FROM = at(0, 0);+const TO = at(100, 0);+const hit = (entity: Entity, fraction: number): RaycastHit => ({entity, fraction, point: { x: 0, y: 0 }, normal: { x: 0, y: 1 },});@@ -29,26 +34,62 @@ const physicsReturning = (hits: RaycastHit[]): PhysicsAPI =>describe('makeLosCheck', () => {it('is not blocked by the target it is looking at', () => {const los = makeLosCheck(physicsReturning([hit(TARGET, 0.6)]));- expect(los(0, 0, 100, 0, OBSERVER, TARGET)).toBe(false);+ expect(los(FROM, TO, OBSERVER, TARGET, 0)).toBe(false);});it('is not blocked by the observer it is looking from', () => {const los = makeLosCheck(physicsReturning([hit(OBSERVER, 0.02)]));- expect(los(0, 0, 100, 0, OBSERVER, TARGET)).toBe(false);+ expect(los(FROM, TO, OBSERVER, TARGET, 0)).toBe(false);});it('is blocked by anything else in between', () => {const los = makeLosCheck(physicsReturning([hit(WALL, 0.5)]));- expect(los(0, 0, 100, 0, OBSERVER, TARGET)).toBe(true);+ expect(los(FROM, TO, OBSERVER, TARGET, 0)).toBe(true);});it('still sees past a wall that is behind the target', () => {const los = makeLosCheck(physicsReturning([hit(WALL, 0.99)]));- expect(los(0, 0, 100, 0, OBSERVER, TARGET)).toBe(false);+ expect(los(FROM, TO, OBSERVER, TARGET, 0)).toBe(false);});it('needs no ray at all when the two are on the same spot', () => {const los = makeLosCheck(physicsReturning([hit(WALL, 0)]));- expect(los(50, 50, 50, 50, OBSERVER, TARGET)).toBe(false);+ expect(los(at(50, 50), at(50, 50), OBSERVER, TARGET, 0)).toBe(false);+ });+});++// The 3D solver answers with the NEAREST body rather than every body on the+// line, so the same three cases are decided by that one hit — and the ray has to+// carry all three axes, or a guard on the floor above is looked straight through.+const cast3d = (h: Cast3DHit | null) => {+ const raycast = vi.fn(() => h);+ return { queries: { raycast } as unknown as Physics3DQueries, raycast };+};+const hit3 = (entity: Entity, fraction: number): Cast3DHit => ({+ entity, fraction, x: 0, y: 0, z: 0, normalX: 0, normalY: 1, normalZ: 0,+});++describe('makeLosCheck3D', () => {+ it('is not blocked by the target, the observer, or an empty line', () => {+ expect(makeLosCheck3D(cast3d(hit3(TARGET, 0.6)).queries)(FROM, TO, OBSERVER, TARGET, 0)).toBe(false);+ expect(makeLosCheck3D(cast3d(hit3(OBSERVER, 0.02)).queries)(FROM, TO, OBSERVER, TARGET, 0)).toBe(false);+ expect(makeLosCheck3D(cast3d(null).queries)(FROM, TO, OBSERVER, TARGET, 0)).toBe(false);+ });++ it('is blocked by anything else in between, and not by what is past the target', () => {+ expect(makeLosCheck3D(cast3d(hit3(WALL, 0.5)).queries)(FROM, TO, OBSERVER, TARGET, 0)).toBe(true);+ expect(makeLosCheck3D(cast3d(hit3(WALL, 0.99)).queries)(FROM, TO, OBSERVER, TARGET, 0)).toBe(false);+ });++ it('casts the whole three-dimensional line, and the layers it was given', () => {+ const { queries, raycast } = cast3d(null);+ makeLosCheck3D(queries)(at(1, 2, 3), at(4, 6, 11), OBSERVER, TARGET, 0b1010);+ expect(raycast).toHaveBeenCalledWith({ x: 1, y: 2, z: 3 }, { x: 3, y: 4, z: 8 }, 0b1010);+ });++ it('needs no ray at all when the two are on the same spot', () => {+ const { queries, raycast } = cast3d(hit3(WALL, 0));+ expect(makeLosCheck3D(queries)(at(5, 5, 5), at(5, 5, 5), OBSERVER, TARGET, 0)).toBe(false);+ expect(raycast).not.toHaveBeenCalled();});});diff --git a/sdk/tests/perception-sense.test.ts b/sdk/tests/perception-sense.test.tsindex e3cb7648d..2a23bdeaa 100644--- a/sdk/tests/perception-sense.test.ts+++ b/sdk/tests/perception-sense.test.ts@@ -1,53 +1,99 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file What an observer can see — range, cone and occlusion.+ *+ * Three-dimensional, with the flat case as its degenerate: the 2D expectations+ * below are the same function called with equal z, which is what says the flat+ * behaviour was kept rather than re-implemented beside a 3D one.+ */import { describe, it, expect } from 'vitest';-import { senseTarget, facingFromQuat, normalizeAngle } from '../src/ai/perception/sense';+import { senseTarget, facingFromRotation, normalizeAngle } from '../src/ai/perception/sense';+import { q } from '../src/math/quat';+import type { Vec3 } from '../src/types';const OMNI = Math.PI; // halfFov ≥ π → omnidirectional+const at = (x: number, y: number, z = 0): Vec3 => ({ x, y, z });+const RIGHT = at(1, 0); // an unrotated entity's 'x' facingdescribe('senseTarget', () => {it('sees a target in range with clear line of sight', () => {- const r = senseTarget(0, 0, 0, 30, 40, 100, OMNI);+ const r = senseTarget(at(0, 0), RIGHT, at(30, 40), 100, OMNI);expect(r.visible).toBe(true);expect(r.distance).toBeCloseTo(50);- expect(r.dirX).toBeCloseTo(0.6);- expect(r.dirY).toBeCloseTo(0.8);+ expect(r.dir.x).toBeCloseTo(0.6);+ expect(r.dir.y).toBeCloseTo(0.8);});it('does not see a target out of range', () => {- const r = senseTarget(0, 0, 0, 200, 0, 100, OMNI);+ const r = senseTarget(at(0, 0), RIGHT, at(200, 0), 100, OMNI);expect(r.visible).toBe(false);expect(r.distance).toBeCloseTo(200);});it('respects the field-of-view cone', () => {- // Facing +X (0 rad), 45° half-cone. Target straight ahead is seen…- expect(senseTarget(0, 0, 0, 100, 0, 200, Math.PI / 4).visible).toBe(true);+ // Facing +X, 45° half-cone. Target straight ahead is seen…+ expect(senseTarget(at(0, 0), RIGHT, at(100, 0), 200, Math.PI / 4).visible).toBe(true);// …target directly behind is not.- expect(senseTarget(0, 0, 0, -100, 0, 200, Math.PI / 4).visible).toBe(false);+ expect(senseTarget(at(0, 0), RIGHT, at(-100, 0), 200, Math.PI / 4).visible).toBe(false);// …target to the side, just outside the cone.- expect(senseTarget(0, 0, 0, 0, 100, 200, Math.PI / 4).visible).toBe(false);+ expect(senseTarget(at(0, 0), RIGHT, at(0, 100), 200, Math.PI / 4).visible).toBe(false);});it('honors an occlusion callback', () => {- const blocked = senseTarget(0, 0, 0, 50, 0, 100, OMNI, () => true);+ const blocked = senseTarget(at(0, 0), RIGHT, at(50, 0), 100, OMNI, () => true);expect(blocked.visible).toBe(false);- const clear = senseTarget(0, 0, 0, 50, 0, 100, OMNI, () => false);+ const clear = senseTarget(at(0, 0), RIGHT, at(50, 0), 100, OMNI, () => false);expect(clear.visible).toBe(true);});it('treats standing on the target as visible', () => {- const r = senseTarget(10, 10, 0, 10, 10, 100, Math.PI / 8);+ const r = senseTarget(at(10, 10), RIGHT, at(10, 10), 100, Math.PI / 8);expect(r.visible).toBe(true);expect(r.distance).toBe(0);});++ // Depth is a distance like any other. A range that drops z sees a guard two+ // floors up as standing next to you.+ it('measures range through depth', () => {+ expect(senseTarget(at(0, 0, 0), RIGHT, at(0, 0, 200), 100, OMNI).visible).toBe(false);+ expect(senseTarget(at(0, 0, 0), RIGHT, at(0, 0, 50), 100, OMNI).distance).toBeCloseTo(50);+ });++ // …and the cone is a cone, not a wedge extruded through every floor: straight+ // up is outside a forward-facing 45° half-cone however close it is.+ it('closes the cone in every direction, not just in the plane', () => {+ expect(senseTarget(at(0, 0, 0), RIGHT, at(0, 0, -30), 200, Math.PI / 4).visible).toBe(false);+ expect(senseTarget(at(0, 0, 0), RIGHT, at(0, 30, 0), 200, Math.PI / 4).visible).toBe(false);+ // On the axis, at depth, inside the cone: seen, and the direction says so.+ const r = senseTarget(at(0, 0, 0), at(0, 0, -1), at(0, 0, -100), 200, Math.PI / 4);+ expect(r.visible).toBe(true);+ expect(r.dir.z).toBeCloseTo(-1);+ });++ it('sees nothing through a cone with no axis', () => {+ expect(senseTarget(at(0, 0), at(0, 0, 0), at(10, 0), 100, Math.PI / 4).visible).toBe(false);+ });});-describe('facingFromQuat', () => {- it('reads the 2D angle from a Z rotation quaternion', () => {- expect(facingFromQuat(0, 1)).toBeCloseTo(0); // identity- // 90° about Z: z=sin(45°), w=cos(45°)- expect(facingFromQuat(Math.SQRT1_2, Math.SQRT1_2)).toBeCloseTo(Math.PI / 2);+describe('facingFromRotation', () => {+ // Two conventions that both exist in this engine: a flat scene's character+ // faces screen-right, an imported model faces −Z. Neither derives the other.+ it("'x' is an unrotated entity's screen-right, turned by a Z rotation", () => {+ const flat = facingFromRotation({ w: 1, x: 0, y: 0, z: 0 }, 'x');+ expect(flat.x).toBeCloseTo(1);+ expect(flat.y).toBeCloseTo(0);+ const turned = facingFromRotation(q.axis('z', Math.PI / 2), 'x');+ expect(turned.x).toBeCloseTo(0);+ expect(turned.y).toBeCloseTo(1);+ });++ it("'-z' is where a model faces, turned by a Y rotation", () => {+ const ahead = facingFromRotation({ w: 1, x: 0, y: 0, z: 0 }, '-z');+ expect(ahead.z).toBeCloseTo(-1);+ const turned = facingFromRotation(q.axis('y', Math.PI / 2), '-z');+ expect(turned.x).toBeCloseTo(-1);+ expect(Math.abs(turned.z)).toBeLessThan(1e-6);});});diff --git a/sdk/tests/perception-step.test.ts b/sdk/tests/perception-step.test.tsindex 03a820f1a..2e21e8d83 100644--- a/sdk/tests/perception-step.test.ts+++ b/sdk/tests/perception-step.test.ts@@ -36,11 +36,11 @@ class FakeWorld implements PerceptionWorldView {}}-const tf = (x: number, y: number) => ({ position: { x, y, z: 0 }, rotation: { x: 0, y: 0, z: 0, w: 1 } });-const spawnPerceiver = (w: FakeWorld, x: number, y: number, range = 200, fov = 360) =>- w.spawn([[Perceiver, Perceiver.create({ range, fovDegrees: fov })], [Transform, tf(x, y)]]);-const spawnTarget = (w: FakeWorld, x: number, y: number) =>- w.spawn([[PerceptionTarget, {}], [Transform, tf(x, y)]]);+const tf = (x: number, y: number, z = 0) => ({ position: { x, y, z }, rotation: { x: 0, y: 0, z: 0, w: 1 } });+const spawnPerceiver = (w: FakeWorld, x: number, y: number, range = 200, fov = 360, z = 0) =>+ w.spawn([[Perceiver, Perceiver.create({ range, fovDegrees: fov })], [Transform, tf(x, y, z)]]);+const spawnTarget = (w: FakeWorld, x: number, y: number, z = 0) =>+ w.spawn([[PerceptionTarget, {}], [Transform, tf(x, y, z)]]);describe('stepPerception', () => {it('writes a visible target into the Perception component', () => {@@ -81,13 +81,45 @@ describe('stepPerception', () => {const p = spawnPerceiver(w, 0, 0);const t = spawnTarget(w, 80, 0);const ends: Array<[number, number]> = [];- stepPerception(w, (_ox, _oy, _tx, _ty, observer, target) => {+ stepPerception(w, (_from, _to, observer, target) => {ends.push([observer, target]);return false;});expect(ends).toEqual([[p, t]]);});+ // The layer mask is the perceiver's, and it is the only thing standing between+ // a 3D sight ray and the observer's own collider.+ it('hands the perceiver own LOS layers to the occlusion check', () => {+ const w = new FakeWorld();+ w.spawn([[Perceiver, Perceiver.create({ losLayers: 0b110 })], [Transform, tf(0, 0)]]);+ spawnTarget(w, 80, 0);+ const seen: number[] = [];+ stepPerception(w, (_from, _to, _o, _t, layers) => { seen.push(layers); return false; });+ expect(seen).toEqual([0b110]);+ });++ it('sees, and reports, in three dimensions', () => {+ const w = new FakeWorld();+ const p = spawnPerceiver(w, 0, 0, 200);+ spawnTarget(w, 0, 0, 100);+ stepPerception(w);+ const per = w.get(p, Perception);+ expect(per.visible).toBe(true);+ expect(per.targetZ).toBe(100);+ expect(per.dirZ).toBeCloseTo(1);+ expect(per.distance).toBeCloseTo(100);+ });++ // The one a flat range check gets wrong: same x/y, two floors apart.+ it('does not see a target that is only out of range in depth', () => {+ const w = new FakeWorld();+ const p = spawnPerceiver(w, 0, 0, 100);+ spawnTarget(w, 0, 0, 300);+ stepPerception(w);+ expect(w.get(p, Perception).visible).toBe(false);+ });+it('picks the nearest visible target', () => {const w = new FakeWorld();const p = spawnPerceiver(w, 0, 0);diff --git a/tools/check-component-fields.mjs b/tools/check-component-fields.mjsindex 507222413..740f346e0 100644--- a/tools/check-component-fields.mjs+++ b/tools/check-component-fields.mjs@@ -40,6 +40,10 @@ const DECLARED_GAPS = {+ ' own built-in shader and never consult the table','SpineAnimation.material': 'see ParticleEmitter.material','DragonBonesAnimation.material': 'see ParticleEmitter.material',+ 'Perception.targetZ': 'sensing is three-dimensional and nothing ACTS on the third'+ + ' axis yet: the navigation the built-in chase drives is a 2D grid, so a game'+ + ' reads the pair it can walk to. Closed by 3D navigation (a navmesh)',+ 'Perception.dirZ': 'see Perception.targetZ',};const components = JSON.parse(