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.

fix(3d): sound and the camera measure the world in three dimensions

esengine558b65d4418f
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7598e8e57..093e88389 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -54,6 +54,23 @@ published separately; it ships inside the editor.
### Fixed
+- **Spatial audio and camera follow are three-dimensional.** Both measured the
+ world in x and y only, so in a 3D scene a source across the room was as loud as
+ one in your ear, and a camera lost its target the moment it walked in depth.
+ `spatialDistance` now takes all three axes, `calculatePanning` projects onto the
+ LISTENER'S own right (an unturned listener's right is world +X, so a flat scene
+ is unchanged) and `followStep` damps a 3D point through a spherical dead zone.
+ `FollowTarget` gains `offsetZ` and a `followZ` switch — off by default, because
+ a flat scene's camera z is how far back it stands, and following it would walk
+ the camera into the plane its content lives on.
+
+- **A gate that reads a build product says when that product is stale.**
+ `component-reference --check` re-derives field data from `sdk/dist` "when a
+ built SDK happens to be present", and never asked how old it was — two fields
+ added to a TS component read as clean against a dist that predated them. It now
+ compares the build against `sdk/src` and reports the field data as *not checked*
+ rather than passing. `newestSource` is shared with the wasm freshness gate.
+
- **The engine-freshness gate answers per build variant.** `wasm.manifest.json`
carried one `builtAt`, stamped whenever the manifest was last written, and
listed the variants merely present on disk — so building `-t web` vouched for a
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index 65dce59f2..b05a97ec6 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": 1595,
+ "experimental": 1596,
"deprecated": 3
},
- "total": 1781,
+ "total": 1782,
"subsystems": [
{
"id": "ecs",
diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.json
index 2b65106d2..146b61c5e 100644
--- a/docs/astro/src/data/components.generated.json
+++ b/docs/astro/src/data/components.generated.json
@@ -1432,6 +1432,16 @@
"type": "number",
"default": "0"
},
+ {
+ "key": "offsetZ",
+ "type": "number",
+ "default": "0"
+ },
+ {
+ "key": "followZ",
+ "type": "boolean",
+ "default": "false"
+ },
{
"key": "deadzone",
"type": "number",
@@ -1447,6 +1457,7 @@
"target",
"offsetX",
"offsetY",
+ "offsetZ",
"deadzone",
"damping"
]
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 43af42ae6..568f42fd6 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 · 1481 experimental · 3 deprecated
+Symbols: 113 public · 66 beta · 1482 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -3228,8 +3228,10 @@ ComponentDef<FollowTargetData>
```
damping: number
deadzone: number
+followZ: boolean
offsetX: number
offsetY: number
+offsetZ: number
target: number
```
@@ -9457,7 +9459,7 @@ BtPlugin
## calculatePanning — function @experimental
```
-(sourceX: number, sourceY: number, listenerX: number, listenerY: number, maxDistance: number): number
+(source: Vec3, listener: Vec3, right: Vec3, maxDistance: number): number
```
## cameraFrustumCorners — function @beta
@@ -11795,6 +11797,11 @@ ServicesPlugin
(raw: number): TileStamp
```
+## spatialDistance — function @experimental
+```
+(source: Vec3, listener: Vec3): number
+```
+
## spawnUIEntity — function @beta
```
(init: UIEntityInit): Entity
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 1f6662702..70211e99a 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 · 1500 experimental · 3 deprecated
+Symbols: 113 public · 71 beta · 1501 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -3236,8 +3236,10 @@ ComponentDef<FollowTargetData>
```
damping: number
deadzone: number
+followZ: boolean
offsetX: number
offsetY: number
+offsetZ: number
target: number
```
@@ -9665,7 +9667,7 @@ BtPlugin
## calculatePanning — function @experimental
```
-(sourceX: number, sourceY: number, listenerX: number, listenerY: number, maxDistance: number): number
+(source: Vec3, listener: Vec3, right: Vec3, maxDistance: number): number
```
## cameraFrustumCorners — function @beta
@@ -12038,6 +12040,11 @@ ServicesPlugin
(raw: number): TileStamp
```
+## spatialDistance — function @experimental
+```
+(source: Vec3, listener: Vec3): number
+```
+
## spawnUIEntity — function @beta
```
(init: UIEntityInit): Entity
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 2dcce0089..917e92eea 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 · 1480 experimental · 3 deprecated
+Symbols: 113 public · 68 beta · 1481 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -3223,8 +3223,10 @@ ComponentDef<FollowTargetData>
```
damping: number
deadzone: number
+followZ: boolean
offsetX: number
offsetY: number
+offsetZ: number
target: number
```
@@ -9452,7 +9454,7 @@ BtPlugin
## calculatePanning — function @experimental
```
-(sourceX: number, sourceY: number, listenerX: number, listenerY: number, maxDistance: number): number
+(source: Vec3, listener: Vec3, right: Vec3, maxDistance: number): number
```
## cameraFrustumCorners — function @beta
@@ -11800,6 +11802,11 @@ ServicesPlugin
(raw: number): TileStamp
```
+## spatialDistance — function @experimental
+```
+(source: Vec3, listener: Vec3): number
+```
+
## spawnUIEntity — function @beta
```
(init: UIEntityInit): Entity
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 5c4845ee2..2b4a54253 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 · 1501 experimental · 3 deprecated
+Symbols: 113 public · 66 beta · 1502 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -3223,8 +3223,10 @@ ComponentDef<FollowTargetData>
```
damping: number
deadzone: number
+followZ: boolean
offsetX: number
offsetY: number
+offsetZ: number
target: number
```
@@ -9697,7 +9699,7 @@ BtPlugin
## calculatePanning — function @experimental
```
-(sourceX: number, sourceY: number, listenerX: number, listenerY: number, maxDistance: number): number
+(source: Vec3, listener: Vec3, right: Vec3, maxDistance: number): number
```
## cameraFrustumCorners — function @beta
@@ -12050,6 +12052,11 @@ ServicesPlugin
(raw: number): TileStamp
```
+## spatialDistance — function @experimental
+```
+(source: Vec3, listener: Vec3): number
+```
+
## spawnUIEntity — function @beta
```
(init: UIEntityInit): Entity
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 26d113c85..9f1dc439f 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 · 1491 experimental · 3 deprecated
+Symbols: 113 public · 66 beta · 1492 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -3223,8 +3223,10 @@ ComponentDef<FollowTargetData>
```
damping: number
deadzone: number
+followZ: boolean
offsetX: number
offsetY: number
+offsetZ: number
target: number
```
@@ -9479,7 +9481,7 @@ BtPlugin
## calculatePanning — function @experimental
```
-(sourceX: number, sourceY: number, listenerX: number, listenerY: number, maxDistance: number): number
+(source: Vec3, listener: Vec3, right: Vec3, maxDistance: number): number
```
## cameraFrustumCorners — function @beta
@@ -11822,6 +11824,11 @@ ServicesPlugin
(raw: number): TileStamp
```
+## spatialDistance — function @experimental
+```
+(source: Vec3, listener: Vec3): number
+```
+
## spawnUIEntity — function @beta
```
(init: UIEntityInit): Entity
diff --git a/sdk/src/audio/AudioPlugin.ts b/sdk/src/audio/AudioPlugin.ts
index 366ac1b66..c01ccaab9 100644
--- a/sdk/src/audio/AudioPlugin.ts
+++ b/sdk/src/audio/AudioPlugin.ts
@@ -1,14 +1,15 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import type { App, Plugin } from '../app/app';
-import type { Entity } from '../types';
+import type { Entity, Vec3 } from '../types';
import { defineSystem, Schedule } from '../ecs/system';
import { Res, Time, type TimeData } from '../ecs/resource';
import { Audio, AudioAPI } from './Audio';
import { AudioSource, AudioListener, type AudioSourceData, type AudioListenerData } from './AudioComponents';
import { WorldTransform, type WorldTransformData } from '../ecs/component';
import { platformCreateAudioBackend, platformOnMemoryWarning } from '../platform/base';
-import { calculateAttenuation, calculatePanning, type SpatialAudioConfig, AttenuationModel } from './SpatialAudio';
+import { q } from '../math/quat';
+import { calculateAttenuation, calculatePanning, spatialDistance, type SpatialAudioConfig, AttenuationModel } from './SpatialAudio';
import type { AudioHandle } from './PlatformAudioBackend';
import { isEditor, isPlayMode } from '../ecs/env';
import { log } from '../util/logger';
@@ -99,16 +100,18 @@ export class AudioPlugin implements Plugin {
const world = app.world;
- let listenerX = 0;
- let listenerY = 0;
+ let listenerAt: Vec3 = { x: 0, y: 0, z: 0 };
+ // Which way is the listener's right, for the stereo image. Its own,
+ // not the world's: turn the camera and the room turns with it.
+ let listenerRight: Vec3 = { x: 1, y: 0, z: 0 };
let hasListener = false;
const listeners = world.getEntitiesWithComponents([AudioListener, WorldTransform]);
for (const entity of listeners) {
const listener = world.get(entity, AudioListener) as AudioListenerData;
if (listener.enabled) {
const wt = world.get(entity, WorldTransform) as WorldTransformData;
- listenerX = wt.position.x;
- listenerY = wt.position.y;
+ listenerAt = wt.position;
+ listenerRight = q.rotate(wt.rotation, { x: 1, y: 0, z: 0 });
hasListener = true;
break;
}
@@ -159,11 +162,8 @@ export class AudioPlugin implements Plugin {
}
const wt = world.tryGet?.(entity, WorldTransform) as WorldTransformData | undefined;
- const srcX = wt?.position.x ?? 0;
- const srcY = wt?.position.y ?? 0;
- const dx = srcX - listenerX;
- const dy = srcY - listenerY;
- const distance = Math.sqrt(dx * dx + dy * dy);
+ const sourceAt: Vec3 = wt?.position ?? { x: 0, y: 0, z: 0 };
+ const distance = spatialDistance(sourceAt, listenerAt);
const spatialConfig: SpatialAudioConfig = {
model: source.attenuationModel as AttenuationModel,
@@ -173,11 +173,7 @@ export class AudioPlugin implements Plugin {
};
const attenuation = calculateAttenuation(distance, spatialConfig);
- const pan = calculatePanning(
- srcX, srcY,
- listenerX, listenerY,
- source.maxDistance
- );
+ const pan = calculatePanning(sourceAt, listenerAt, listenerRight, source.maxDistance);
handle.setVolume(source.volume * attenuation);
handle.setPan(pan);
diff --git a/sdk/src/audio/SpatialAudio.ts b/sdk/src/audio/SpatialAudio.ts
index e90365cf1..56d24c9bd 100644
--- a/sdk/src/audio/SpatialAudio.ts
+++ b/sdk/src/audio/SpatialAudio.ts
@@ -1,5 +1,14 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file SpatialAudio.ts — where a sound is, relative to who is hearing it.
+ *
+ * Three-dimensional throughout. A scene has depth whether or not its art does,
+ * and a distance that drops z reports a source across the room as being in the
+ * listener's ear.
+ */
+import type { Vec3 } from '../types';
+
export enum AttenuationModel {
Linear = 0,
Inverse,
@@ -50,12 +59,29 @@ export function calculateAttenuation(
return Math.max(0, Math.min(1, result));
}
+/** How far apart two points are, in the three dimensions a scene has. */
+export function spatialDistance(source: Vec3, listener: Vec3): number {
+ const dx = source.x - listener.x;
+ const dy = source.y - listener.y;
+ const dz = source.z - listener.z;
+ return Math.sqrt(dx * dx + dy * dy + dz * dz);
+}
+
+/**
+ * Stereo pan for a source heard by a listener whose own right points along
+ * `right`: how far along that right the source sits, over the audible radius.
+ * Against the LISTENER'S right, not world +X — a listener that has turned hears
+ * the world turn with it, and an unturned one's right IS world +X.
+ */
export function calculatePanning(
- sourceX: number, sourceY: number,
- listenerX: number, listenerY: number,
+ source: Vec3,
+ listener: Vec3,
+ right: Vec3,
maxDistance: number
): number {
- const dx = sourceX - listenerX;
+ const along = (source.x - listener.x) * right.x
+ + (source.y - listener.y) * right.y
+ + (source.z - listener.z) * right.z;
// Guard maxDistance: 0 would yield NaN, which StereoPannerNode.pan throws on.
- return Math.max(-1, Math.min(1, dx / Math.max(maxDistance, 1e-3)));
+ return Math.max(-1, Math.min(1, along / Math.max(maxDistance, 1e-3)));
}
diff --git a/sdk/src/audio/index.ts b/sdk/src/audio/index.ts
index c549e03e0..549215683 100644
--- a/sdk/src/audio/index.ts
+++ b/sdk/src/audio/index.ts
@@ -15,7 +15,7 @@ export {
export { AudioPool, type PooledAudioNode } from './AudioPool';
export { AudioPlugin, audioPlugin, type AudioPluginConfig } from './AudioPlugin';
export { AudioSource, AudioListener, type AudioSourceData, type AudioListenerData } from './AudioComponents';
-export { AttenuationModel, calculateAttenuation, calculatePanning, type SpatialAudioConfig } from './SpatialAudio';
+export { AttenuationModel, calculateAttenuation, calculatePanning, spatialDistance, type SpatialAudioConfig } from './SpatialAudio';
export { WebAudioBackend } from './WebAudioBackend';
export { MiniGameAudioBackend } from './MiniGameAudioBackend';
export { NativeAudioBackend } from './NativeAudioBackend';
diff --git a/sdk/src/camera/FollowTarget.ts b/sdk/src/camera/FollowTarget.ts
index e4f88965c..83b09e69a 100644
--- a/sdk/src/camera/FollowTarget.ts
+++ b/sdk/src/camera/FollowTarget.ts
@@ -12,7 +12,7 @@
*/
import { defineComponent, Transform } from '../ecs/component';
import type { World } from '../ecs/world';
-import type { Entity } from '../types';
+import type { Entity, Vec3 } from '../types';
export interface FollowTargetData {
/** Entity to follow (-1 = none). */
@@ -20,6 +20,14 @@ export interface FollowTargetData {
/** World-space offset added to the target position. */
offsetX: number;
offsetY: number;
+ offsetZ: number;
+ /**
+ * Follow the target's DEPTH as well. Off for a flat scene, where the camera's z
+ * is how far back it stands and following it would walk it into the content
+ * plane. Its own switch rather than "offsetZ ≠ 0": standing level with the
+ * target is a legal 3D offset.
+ */
+ followZ: boolean;
/** The target may move within this radius (world units) without the camera following. */
deadzone: number;
/** Damping time-constant in seconds (larger = smoother/slower; 0 = snap). */
@@ -30,6 +38,8 @@ export const FollowTarget = defineComponent<FollowTargetData>('FollowTarget', {
target: -1,
offsetX: 0,
offsetY: 0,
+ offsetZ: 0,
+ followZ: false,
deadzone: 0,
damping: 0.25,
});
@@ -39,23 +49,26 @@ export const FollowTarget = defineComponent<FollowTargetData>('FollowTarget', {
* (target + offset), the dead zone, the damping time-constant, and dt, returns
* the camera's next position. Moves the camera only by the part of the gap that
* exceeds the dead zone, eased by a frame-rate-independent damping factor.
+ *
+ * Three-dimensional, and the dead zone with it: a sphere, so a target circling a
+ * 3D camera at the dead-zone radius stays inside it the whole way round. A flat
+ * scene hands in equal z on both sides and gets exactly what it always did.
*/
export function followStep(
- camX: number,
- camY: number,
- desiredX: number,
- desiredY: number,
+ cam: Vec3,
+ desired: Vec3,
deadzone: number,
damping: number,
dt: number,
-): { x: number; y: number } {
- const dx = desiredX - camX;
- const dy = desiredY - camY;
- const dist = Math.hypot(dx, dy);
- if (dist === 0 || dist <= deadzone) return { x: camX, y: camY };
+): Vec3 {
+ const dx = desired.x - cam.x;
+ const dy = desired.y - cam.y;
+ const dz = desired.z - cam.z;
+ const dist = Math.sqrt(dx * dx + dy * dy + dz * dz);
+ if (dist === 0 || dist <= deadzone) return { x: cam.x, y: cam.y, z: cam.z };
const beyond = 1 - deadzone / dist; // fraction of the gap past the dead zone
const k = damping > 0 ? 1 - Math.exp(-dt / damping) : 1; // frame-rate-independent
- return { x: camX + dx * beyond * k, y: camY + dy * beyond * k };
+ return { x: cam.x + dx * beyond * k, y: cam.y + dy * beyond * k, z: cam.z + dz * beyond * k };
}
/** Advance every FollowTarget camera by one damped step (called by the follow system). */
@@ -67,20 +80,18 @@ export function followUpdate(world: World, dt: number): void {
if (ft.target < 0 || !world.valid(target) || !world.has(target, Transform)) continue;
const camT = world.get(e, Transform);
const tgtT = world.get(target, Transform);
+ // A camera that does not follow depth is asked for the depth it already has,
+ // so the step's own arithmetic leaves it there — no second code path.
+ const desiredZ = ft.followZ ? tgtT.position.z + ft.offsetZ : camT.position.z;
const next = followStep(
- camT.position.x,
- camT.position.y,
- tgtT.position.x + ft.offsetX,
- tgtT.position.y + ft.offsetY,
+ camT.position,
+ { x: tgtT.position.x + ft.offsetX, y: tgtT.position.y + ft.offsetY, z: desiredZ },
ft.deadzone,
ft.damping,
dt,
);
- if (next.x !== camT.position.x || next.y !== camT.position.y) {
- world.set(e, Transform, {
- ...camT,
- position: { ...camT.position, x: next.x, y: next.y },
- });
+ if (next.x !== camT.position.x || next.y !== camT.position.y || next.z !== camT.position.z) {
+ world.set(e, Transform, { ...camT, position: next });
}
}
}
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index becf941ef..d7f427ddb 100644
--- a/sdk/src/core-content.ts
+++ b/sdk/src/core-content.ts
@@ -450,6 +450,7 @@ export {
AttenuationModel,
calculateAttenuation,
calculatePanning,
+ spatialDistance,
type AudioHandle,
type AudioBufferHandle,
type PlayConfig,
diff --git a/sdk/tests/camera-follow.test.ts b/sdk/tests/camera-follow.test.ts
index 0f0b4c856..b15a01a97 100644
--- a/sdk/tests/camera-follow.test.ts
+++ b/sdk/tests/camera-follow.test.ts
@@ -3,34 +3,66 @@
/**
* @file Camera follow — the damped, dead-zoned follow step (the procedural
* per-camera behaviour). Pure math, deterministic.
+ *
+ * Three-dimensional: a 3D scene's target walks in depth, and a step that drops
+ * z leaves the camera behind on exactly the axis the game moved along. The flat
+ * cases below are the same function with equal z, which is what says the 2D
+ * behaviour is unchanged rather than re-implemented.
*/
import { describe, it, expect } from 'vitest';
import { followStep } from '../src/camera/FollowTarget';
+import type { Vec3 } from '../src/types';
+
+const at = (x: number, y: number, z = 0): Vec3 => ({ x, y, z });
describe('followStep', () => {
it('snaps to the desired position with no damping and no dead zone', () => {
- expect(followStep(0, 0, 100, 0, 0, 0, 0.016)).toEqual({ x: 100, y: 0 });
+ expect(followStep(at(0, 0), at(100, 0), 0, 0, 0.016)).toEqual(at(100, 0));
});
it('keeps the target at the dead-zone boundary (snap)', () => {
- const p = followStep(0, 0, 100, 0, 30, 0, 0.016); // dead zone 30
+ const p = followStep(at(0, 0), at(100, 0), 30, 0, 0.016); // dead zone 30
expect(p.x).toBeCloseTo(70); // target now sits 30 units from the camera
expect(p.y).toBeCloseTo(0);
});
it('does not move while the target is within the dead zone', () => {
- expect(followStep(0, 0, 20, 0, 30, 0.25, 0.016)).toEqual({ x: 0, y: 0 });
+ expect(followStep(at(0, 0), at(20, 0), 30, 0.25, 0.016)).toEqual(at(0, 0));
});
it('damps partially toward the target', () => {
- const p = followStep(0, 0, 100, 0, 0, 0.25, 0.016);
+ const p = followStep(at(0, 0), at(100, 0), 0, 0.25, 0.016);
expect(p.x).toBeCloseTo(100 * (1 - Math.exp(-0.016 / 0.25)));
});
it('is frame-rate independent (two dt/2 steps == one dt step)', () => {
- const a1 = followStep(0, 0, 100, 0, 0, 0.25, 0.016);
- const a2 = followStep(a1.x, a1.y, 100, 0, 0, 0.25, 0.016);
- const b = followStep(0, 0, 100, 0, 0, 0.25, 0.032);
+ const a1 = followStep(at(0, 0), at(100, 0), 0, 0.25, 0.016);
+ const a2 = followStep(a1, at(100, 0), 0, 0.25, 0.016);
+ const b = followStep(at(0, 0), at(100, 0), 0, 0.25, 0.032);
expect(a2.x).toBeCloseTo(b.x, 5);
});
+
+ it('follows depth the same way it follows width', () => {
+ expect(followStep(at(0, 0, 0), at(0, 0, 100), 0, 0, 0.016)).toEqual(at(0, 0, 100));
+ });
+
+ // The dead zone is a sphere, not a cylinder: a target circling the camera at
+ // the dead-zone radius must stay inside it whichever plane it circles in.
+ it('measures the dead zone in all three axes', () => {
+ expect(followStep(at(0, 0, 0), at(0, 0, 20), 30, 0.25, 0.016)).toEqual(at(0, 0, 0));
+ const p = followStep(at(0, 0, 0), at(0, 0, 100), 30, 0, 0.016);
+ expect(p.z).toBeCloseTo(70);
+ });
+
+ // A gap spread over three axes is one distance, so the dead zone bites on the
+ // diagonal exactly as it does on an axis — 3-4-12 is 13 away, not 5.
+ it('takes the diagonal of all three axes as the distance', () => {
+ expect(followStep(at(0, 0, 0), at(3, 4, 12), 13, 0.25, 0.016)).toEqual(at(0, 0, 0));
+ expect(followStep(at(0, 0, 0), at(3, 4, 12), 12.9, 0, 0.016).x).toBeGreaterThan(0);
+ });
+
+ it('leaves a flat scene exactly where it was', () => {
+ const p = followStep(at(10, 20, 7), at(110, 20, 7), 0, 0, 0.016);
+ expect(p).toEqual(at(110, 20, 7)); // z is handed in equal and comes back equal
+ });
});
diff --git a/sdk/tests/spatial-audio.test.ts b/sdk/tests/spatial-audio.test.ts
index a7b1542c1..00c80398b 100644
--- a/sdk/tests/spatial-audio.test.ts
+++ b/sdk/tests/spatial-audio.test.ts
@@ -5,8 +5,15 @@ import {
AttenuationModel,
calculateAttenuation,
calculatePanning,
+ spatialDistance,
type SpatialAudioConfig,
} from '../src/audio/SpatialAudio';
+import { q } from '../src/math/quat';
+import type { Vec3 } from '../src/types';
+
+const at = (x: number, y: number, z = 0): Vec3 => ({ x, y, z });
+/** World +X — the right of a listener that has not turned. */
+const RIGHT: Vec3 = { x: 1, y: 0, z: 0 };
describe('SpatialAudio', () => {
describe('calculateAttenuation', () => {
@@ -111,33 +118,68 @@ describe('SpatialAudio', () => {
});
});
+ // The scene has three dimensions whether or not its art does. A distance that
+ // drops z puts a source across the room in the listener's ear — and every 3D
+ // scene the engine now renders, simulates and lights is such a room.
+ describe('spatialDistance', () => {
+ it('measures depth like it measures width', () => {
+ expect(spatialDistance(at(0, 0, 300), at(0, 0, 0))).toBeCloseTo(300);
+ expect(spatialDistance(at(300, 0, 0), at(0, 0, 0))).toBeCloseTo(300);
+ });
+
+ it('is the diagonal of all three, not of two', () => {
+ expect(spatialDistance(at(3, 4, 12), at(0, 0, 0))).toBeCloseTo(13);
+ });
+
+ it('is zero at the listener', () => {
+ expect(spatialDistance(at(7, -2, 5), at(7, -2, 5))).toBe(0);
+ });
+ });
+
describe('calculatePanning', () => {
it('should return 0 when source is directly above/below listener', () => {
- expect(calculatePanning(100, 200, 100, 0, 1000)).toBeCloseTo(0);
+ expect(calculatePanning(at(100, 200), at(100, 0), RIGHT, 1000)).toBeCloseTo(0);
});
it('should return positive for source to the right', () => {
- const pan = calculatePanning(600, 0, 100, 0, 1000);
+ const pan = calculatePanning(at(600, 0), at(100, 0), RIGHT, 1000);
expect(pan).toBeGreaterThan(0);
expect(pan).toBeCloseTo(0.5);
});
it('should return negative for source to the left', () => {
- const pan = calculatePanning(-400, 0, 100, 0, 1000);
+ const pan = calculatePanning(at(-400, 0), at(100, 0), RIGHT, 1000);
expect(pan).toBeLessThan(0);
expect(pan).toBeCloseTo(-0.5);
});
it('should clamp to -1', () => {
- expect(calculatePanning(-2000, 0, 0, 0, 1000)).toBe(-1);
+ expect(calculatePanning(at(-2000, 0), at(0, 0), RIGHT, 1000)).toBe(-1);
});
it('should clamp to 1', () => {
- expect(calculatePanning(2000, 0, 0, 0, 1000)).toBe(1);
+ expect(calculatePanning(at(2000, 0), at(0, 0), RIGHT, 1000)).toBe(1);
});
it('should return 0 when source equals listener', () => {
- expect(calculatePanning(100, 100, 100, 100, 1000)).toBe(0);
+ expect(calculatePanning(at(100, 100), at(100, 100), RIGHT, 1000)).toBe(0);
+ });
+
+ // A listener that has turned hears the room turn with it. Straight ahead in
+ // a 3D scene is −Z, and a quarter turn about Y puts what was on the right
+ // in front — where a stereo image has nothing to say.
+ it('pans against the listener own right, not world +X', () => {
+ const turned = q.rotate(q.axis('y', Math.PI / 2), { x: 1, y: 0, z: 0 });
+ // Source out on world +X: dead ahead once the listener faces it.
+ expect(calculatePanning(at(500, 0, 0), at(0, 0, 0), turned, 1000)).toBeCloseTo(0);
+ // And what is now to that listener's right is out on −Z.
+ expect(calculatePanning(at(0, 0, -500), at(0, 0, 0), turned, 1000)).toBeCloseTo(0.5);
+ });
+
+ // The 2D case is the same formula with an unturned listener, which is what
+ // makes this one function rather than a 2D one and a 3D one.
+ it('is unchanged for a flat scene with an unturned listener', () => {
+ expect(calculatePanning(at(600, 40), at(100, -70), RIGHT, 1000)).toBeCloseTo(0.5);
});
});
});
diff --git a/tools/component-reference.mjs b/tools/component-reference.mjs
index 8b5e7fe17..ebe5f5bba 100644
--- a/tools/component-reference.mjs
+++ b/tools/component-reference.mjs
@@ -29,10 +29,11 @@
* field data and diffs that too, so a changed field is caught wherever the
* stronger check can run.
*/
-import { readFileSync, writeFileSync, readdirSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync, readdirSync, existsSync, statSync } from 'node:fs';
import { fileURLToPath, pathToFileURL } from 'node:url';
import { dirname, join, resolve } from 'node:path';
import { componentNamesFromSource } from './lib/componentNames.mjs';
+import { newestSource } from './lib/engineBuild.mjs';
const here = dirname(fileURLToPath(import.meta.url));
const ROOT = resolve(here, '..');
@@ -353,9 +354,18 @@ else {
for (const n of dLink.extra) problems.push(`the editor links docs for "${n}", which is not a component`);
}
-// The strongest check, where a built SDK makes it possible.
-let deep = 'names only (no built SDK)';
-if (existsSync(SDK_DIST)) {
+// The strongest check, where a built SDK makes it possible — and only while that
+// build is newer than what it came from: a stale one answers about components
+// nobody has. Not having checked is reported, never rounded down to a pass.
+const distAt = existsSync(SDK_DIST) ? statSync(SDK_DIST).mtimeMs : 0;
+const newestTs = newestSource(ROOT, ['sdk/src'], /\.ts$/);
+const distIsCurrent = distAt > 0 && newestTs.at <= distAt;
+if (distAt > 0 && !distIsCurrent) {
+ console.log(`component-reference: the built SDK predates ${newestTs.file} — field data NOT checked.`
+ + '\n build it: pnpm --filter ./sdk build');
+}
+let deep = distAt > 0 ? 'names only (the built SDK is stale)' : 'names only (no built SDK)';
+if (distIsCurrent) {
const fresh = await snapshotFromSdk();
const a = JSON.stringify(fresh.components), b = JSON.stringify(snap.components);
if (a !== b) {
diff --git a/tools/lib/engineBuild.mjs b/tools/lib/engineBuild.mjs
index a82984004..47919bfd8 100644
--- a/tools/lib/engineBuild.mjs
+++ b/tools/lib/engineBuild.mjs
@@ -15,22 +15,33 @@ import path from 'node:path';
/** Compiled into the engine wasm. Tool-only trees (tools/*-wasm) are not. */
const ENGINE_SOURCE = ['src'];
+const ENGINE_EXT = /\.(c|cc|cpp|h|hpp|inl|esshader|wgsl)$/;
-function newestSource(root) {
+/**
+ * The newest source file under `dirs` that a build takes as INPUT, `{ at, file }`
+ * — `at: 0` when there is none. Shared with every other "is this artifact older
+ * than what it was built from" check: the answer is the same question about a
+ * different tree, and a second copy is how one of them stops being maintained.
+ */
+export function newestSource(root, dirs = ENGINE_SOURCE, ext = ENGINE_EXT) {
let newest = { at: 0, file: null };
const walk = (dir) => {
for (const entry of readdirSync(dir, { withFileTypes: true })) {
const full = path.join(dir, entry.name);
- if (entry.isDirectory()) { walk(full); continue; }
- // A generated header is an output of the build, not an input to it: its
- // mtime says when the build last ran, which would make every build stale.
+ if (entry.isDirectory()) {
+ if (entry.name === 'node_modules' || entry.name === 'dist') continue;
+ walk(full);
+ continue;
+ }
+ // A generated file is an output of the build, not an input to it: its mtime
+ // says when the build last ran, which would make every build stale.
if (entry.name.includes('.generated.')) continue;
- if (!/\.(c|cc|cpp|h|hpp|inl|esshader|wgsl)$/.test(entry.name)) continue;
+ if (!ext.test(entry.name)) continue;
const at = statSync(full).mtimeMs;
if (at > newest.at) newest = { at, file: path.relative(root, full).split(path.sep).join('/') };
}
};
- for (const dir of ENGINE_SOURCE) {
+ for (const dir of dirs) {
const abs = path.join(root, dir);
if (existsSync(abs)) walk(abs);
}