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
fix(3d): sound and the camera measure the world in three dimensions
esengine558b65d4418f
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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, andlisted the variants merely present on disk — so building `-t web` vouched for adiff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex 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.jsonindex 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.mdindex 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: numberdeadzone: number+followZ: booleanoffsetX: numberoffsetY: number+offsetZ: numbertarget: 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): Entitydiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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: numberdeadzone: number+followZ: booleanoffsetX: numberoffsetY: number+offsetZ: numbertarget: 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): Entitydiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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: numberdeadzone: number+followZ: booleanoffsetX: numberoffsetY: number+offsetZ: numbertarget: 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): Entitydiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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: numberdeadzone: number+followZ: booleanoffsetX: numberoffsetY: number+offsetZ: numbertarget: 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): Entitydiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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: numberdeadzone: number+followZ: booleanoffsetX: numberoffsetY: number+offsetZ: numbertarget: 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): Entitydiff --git a/sdk/src/audio/AudioPlugin.ts b/sdk/src/audio/AudioPlugin.tsindex 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 Teamimport 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.tsindex 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.tsindex 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.tsindex 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 zoneconst 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.tsindex 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.tsindex 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 30expect(p.x).toBeCloseTo(70); // target now sits 30 units from the cameraexpect(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.tsindex 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.mjsindex 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.mjsindex 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);}