Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(ai): sensing is three-dimensional

esengine4d8117892b85
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 a
connection's pawn in x and y, so two floors of a building were one place and
every connection streamed both — the saving the policy exists to make is the one
diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.json
index 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.md
index 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: FacingAxis
fovDegrees: number
+losLayers: number
range: number
```
@@ -5032,9 +5034,11 @@ ComponentDef<PerceptionData>
```
dirX: number
dirY: number
+dirZ: number
distance: number
targetX: number
targetY: number
+targetZ: number
visible: boolean
```
@@ -6830,8 +6834,7 @@ BuiltinComponentDef<SegmentColliderData>
## SenseResult — interface @experimental
```
-dirX: number
-dirY: number
+dir: Vec3
distance: number
visible: 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 @experimental
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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: FacingAxis
fovDegrees: number
+losLayers: number
range: number
```
@@ -5215,9 +5217,11 @@ ComponentDef<PerceptionData>
```
dirX: number
dirY: number
+dirZ: number
distance: number
targetX: number
targetY: number
+targetZ: number
visible: boolean
```
@@ -7023,8 +7027,7 @@ BuiltinComponentDef<SegmentColliderData>
## SenseResult — interface @experimental
```
-dirX: number
-dirY: number
+dir: Vec3
distance: number
visible: 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 @experimental
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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: FacingAxis
fovDegrees: number
+losLayers: number
range: number
```
@@ -5027,9 +5029,11 @@ ComponentDef<PerceptionData>
```
dirX: number
dirY: number
+dirZ: number
distance: number
targetX: number
targetY: number
+targetZ: number
visible: boolean
```
@@ -6825,8 +6829,7 @@ BuiltinComponentDef<SegmentColliderData>
## SenseResult — interface @experimental
```
-dirX: number
-dirY: number
+dir: Vec3
distance: number
visible: 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 @experimental
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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: FacingAxis
fovDegrees: number
+losLayers: number
range: number
```
@@ -5272,9 +5274,11 @@ ComponentDef<PerceptionData>
```
dirX: number
dirY: number
+dirZ: number
distance: number
targetX: number
targetY: number
+targetZ: number
visible: boolean
```
@@ -7070,8 +7074,7 @@ BuiltinComponentDef<SegmentColliderData>
## SenseResult — interface @experimental
```
-dirX: number
-dirY: number
+dir: Vec3
distance: number
visible: 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 @experimental
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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: FacingAxis
fovDegrees: number
+losLayers: number
range: number
```
@@ -5034,9 +5036,11 @@ ComponentDef<PerceptionData>
```
dirX: number
dirY: number
+dirZ: number
distance: number
targetX: number
targetY: number
+targetZ: number
visible: boolean
```
@@ -6832,8 +6836,7 @@ BuiltinComponentDef<SegmentColliderData>
## SenseResult — interface @experimental
```
-dirX: number
-dirY: number
+dir: Vec3
distance: number
visible: 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 @experimental
diff --git a/sdk/src/ai/perception/PerceptionPlugin.ts b/sdk/src/ai/perception/PerceptionPlugin.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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' facing
describe('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.ts
index 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.mjs
index 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(