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(golden): audio is certified, by a run that can tell sound from silence

esengine2d7de40333d7
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 029e09099..40b309ebf 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -50,7 +50,7 @@ published separately; it ships inside the editor.
- **A verdict per subsystem, at the size a creator builds in.** Nobody asks
whether `AudioSource` is frozen; they ask whether they can build their game's
- audio on this, and 1462 experimental symbols answer that the same way whether a
+ audio on this, and some 1460 experimental symbols answer that the same way whether a
subsystem was weighed or nobody looked. The reference now carries 22 subsystems
with a tier and the reason for it — required for anything not frozen, because
"not frozen" is a decision and has to read like one. `entry` names the symbols
@@ -109,12 +109,23 @@ published separately; it ships inside the editor.
keyboard and pad twin of the pinch gesture already there — and its rebind now
offers mouse buttons.
-- **Audio, animation and materials are declared corpus gaps.** Each was claimed by
- a project that did not exercise it. No example in the repository uses audio at
- all; `sprite-animation` and `cutscene` animate and neither is certified;
- `effects-gallery` is the only example with a material. The suite now reads 28 of
- 33 capabilities covered against 5 declared gaps, where it read 31 of 33 against
- 2 — nothing regressed, the difference is what the false claims were covering.
+- **Animation and materials are declared corpus gaps.** Each was claimed by a
+ project that did not exercise it: `sprite-animation` and `cutscene` animate and
+ neither is certified, and `effects-gallery` is the only example with a material.
+ The suite reads 29 of 33 capabilities covered against 4 declared gaps, where it
+ read 31 of 33 against 2 — nothing regressed, the difference is what the false
+ claims were covering.
+
+- **`examples/audio-demo` joins the certification corpus, and a run proves sound
+ came out.** It was the one example that uses audio and it was outside the suite,
+ so the pillar shipped uncertified while `space-shooter` claimed it. Certifying it
+ needed a claim pixels cannot settle: the control that starts a sound redraws
+ itself whether anything played or not, and a one-shot drum hit is over before the
+ capture. So the project declares an `audio` block — a toggle to click for a
+ sustained source, and a spectrum bar the game writes from an analyser bin of the
+ master bus. The run reads that bar's height: 36.6 against a silent floor of 6.
+ Aim the toggle at empty background and it reads 6, which is what makes the check
+ a check.
### Fixed
diff --git a/desktop/src/gameHost.ts b/desktop/src/gameHost.ts
index c7494c339..5a6b56a18 100644
--- a/desktop/src/gameHost.ts
+++ b/desktop/src/gameHost.ts
@@ -15,7 +15,7 @@ import {
createWebApp, setEditorMode, setPlayMode, Assets,
indexPackagedManifest, createPackagedAssetSource, applyAssetRefResolvers, initRuntime,
HttpBackend, fetchDecodePixels, registerPackagedSideModules,
- packagedAppOptions, packagedRuntimeInit, Transform, SceneManager, Nav,
+ packagedAppOptions, packagedRuntimeInit, Transform, SceneManager, Nav, UINode,
} from 'esengine';
import type { SceneData, AddressableManifest, PackagedGameConfig } from 'esengine';
import type { ESEngineModule } from 'esengine/wasm';
@@ -103,9 +103,9 @@ async function boot(): Promise<void> {
probe(names: string[] = []): {
scene: string | null;
transitioning: boolean;
- at: Record<string, { x: number; y: number }>;
+ at: Record<string, { x: number; y: number; w?: number; h?: number }>;
} {
- const at: Record<string, { x: number; y: number }> = {};
+ const at: Record<string, { x: number; y: number; w?: number; h?: number }> = {};
for (const name of names) {
const entity = app.world.findEntityByName(name);
if (entity === null || !app.world.has(entity, Transform)) continue;
@@ -114,6 +114,14 @@ async function boot(): Promise<void> {
const t = app.world.get(entity, Transform);
const p = t.worldPosition ?? t.position;
at[name] = { x: p.x, y: p.y };
+ // A node's own size, for a claim about a value the game COMPUTED rather
+ // than about where it ended up — a spectrum bar barely moves while its
+ // height carries the whole answer.
+ if (app.world.has(entity, UINode)) {
+ const node = app.world.get(entity, UINode);
+ at[name].w = node.width?.value;
+ at[name].h = node.height?.value;
+ }
}
const scenes = app.hasResource(SceneManager) ? app.getResource(SceneManager) : null;
// A scene arrives entity by entity, and a driver polling from outside
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index 363c1d1fd..52fa8bbbd 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -2,8 +2,8 @@
"note": "Generated by tools/api-stability.mjs from sdk/etc/*.api.md — do not edit.",
"counts": {
"public": 111,
- "beta": 57,
- "experimental": 1462,
+ "beta": 58,
+ "experimental": 1461,
"deprecated": 3
},
"total": 1630,
@@ -196,13 +196,11 @@
"id": "audio",
"title": "Audio",
"titleZh": "音频",
- "tier": "experimental",
- "why": "NO example in the repository uses audio, so nothing would notice a break in it. Beta would claim a support we cannot give until something certifies it",
- "whyZh": "仓库里没有任何一个例子用音频,所以它坏了不会有人发现。在有东西认证它之前,Beta 会是一个我们给不出的支持承诺",
+ "tier": "beta",
+ "why": "a certified run drives a loop and reads the master bus analyser, so a break is noticed — but the corpus reaches a handful of twenty-three audio symbols",
+ "whyZh": "已有被认证的运行会驱动一个循环并读取 master 总线的 analyser,所以它坏了会被发现——但语料只触到 23 个音频符号里的少数几个",
"entry": [
- "Audio",
- "AudioSource",
- "AudioListener"
+ "Audio"
]
},
{
@@ -1650,6 +1648,18 @@
"minigame"
]
},
+ {
+ "name": "Audio",
+ "kind": "const",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
{
"name": "Camera",
"kind": "const",
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 1d7995dce..ac1b01896 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: 111 public · 50 beta · 1347 experimental · 3 deprecated
+Symbols: 111 public · 51 beta · 1346 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -805,7 +805,7 @@ Inverse = 1
Linear = 0
```
-## Audio — const @experimental
+## Audio — const @beta
```
ResourceDef<AudioAPI>
```
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 825075d6a..7ca5788d8 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: 111 public · 55 beta · 1366 experimental · 3 deprecated
+Symbols: 111 public · 56 beta · 1365 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -805,7 +805,7 @@ Inverse = 1
Linear = 0
```
-## Audio — const @experimental
+## Audio — const @beta
```
ResourceDef<AudioAPI>
```
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 236381408..063e040e8 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: 111 public · 52 beta · 1346 experimental · 3 deprecated
+Symbols: 111 public · 53 beta · 1345 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -800,7 +800,7 @@ Inverse = 1
Linear = 0
```
-## Audio — const @experimental
+## Audio — const @beta
```
ResourceDef<AudioAPI>
```
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index c35377fc6..08bf90754 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: 111 public · 50 beta · 1367 experimental · 3 deprecated
+Symbols: 111 public · 51 beta · 1366 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -800,7 +800,7 @@ Inverse = 1
Linear = 0
```
-## Audio — const @experimental
+## Audio — const @beta
```
ResourceDef<AudioAPI>
```
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index afb7ec466..434aeca07 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: 111 public · 50 beta · 1357 experimental · 3 deprecated
+Symbols: 111 public · 51 beta · 1356 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -800,7 +800,7 @@ Inverse = 1
Linear = 0
```
-## Audio — const @experimental
+## Audio — const @beta
```
ResourceDef<AudioAPI>
```
diff --git a/sdk/src/audio/Audio.ts b/sdk/src/audio/Audio.ts
index 8f16d42eb..d1e8fd9c7 100644
--- a/sdk/src/audio/Audio.ts
+++ b/sdk/src/audio/Audio.ts
@@ -708,9 +708,10 @@ export class AudioAPI {
/**
* Playback, buses and mixing, as `Res(Audio)` hands it over.
*
- * Deliberately NOT `@beta`, which would claim the shape is supported: no example
- * in the repository uses audio at all, so nothing would notice a break in it. It
- * stays experimental until something certifies it — see the `audio` entry in
- * KNOWN_GAPS.
+ * `@beta`: a certified run now drives a loop and reads the master bus's analyser,
+ * so a break here is noticed — but the corpus reaches a handful of twenty-three
+ * audio symbols, which is thin evidence for freezing the shape.
+ *
+ * @beta
*/
export const Audio = defineResource<AudioAPI>(null!, 'Audio');
diff --git a/tools/apiSubsystems.mjs b/tools/apiSubsystems.mjs
index 63b0c606a..bbf309410 100644
--- a/tools/apiSubsystems.mjs
+++ b/tools/apiSubsystems.mjs
@@ -141,10 +141,10 @@ export const SUBSYSTEMS = [
id: 'audio',
title: 'Audio',
titleZh: '音频',
- tier: 'experimental',
- why: 'NO example in the repository uses audio, so nothing would notice a break in it. Beta would claim a support we cannot give until something certifies it',
- whyZh: '仓库里没有任何一个例子用音频,所以它坏了不会有人发现。在有东西认证它之前,Beta 会是一个我们给不出的支持承诺',
- entry: ['Audio', 'AudioSource', 'AudioListener'],
+ tier: 'beta',
+ why: 'a certified run drives a loop and reads the master bus analyser, so a break is noticed — but the corpus reaches a handful of twenty-three audio symbols',
+ whyZh: '已有被认证的运行会驱动一个循环并读取 master 总线的 analyser,所以它坏了会被发现——但语料只触到 23 个音频符号里的少数几个',
+ entry: ['Audio'],
},
{
id: 'animation',
diff --git a/tools/check-golden.mjs b/tools/check-golden.mjs
index 698616a2f..d698eccd2 100644
--- a/tools/check-golden.mjs
+++ b/tools/check-golden.mjs
@@ -50,6 +50,7 @@ function projectText(id) {
/** Capabilities a packaged frame cannot show, and the declaration whose run reads them. */
const NEEDS_RUN = {
'texture-atlas': 'atlas',
+ audio: 'audio',
'safe-area': 'safeArea',
'pause-resume': 'suspend',
'hot-update': 'runBy',
@@ -168,6 +169,18 @@ for (const g of GOLDEN) {
}
}
}
+ const au = g.audio;
+ if (au) {
+ const t = au.toggle;
+ if (!t || !(t.x >= 0 && t.x <= 1 && t.y >= 0 && t.y <= 1)) {
+ fail(`"${g.id}" declares audio without a toggle inside the surface — x/y are fractions`);
+ }
+ if (!au.bar) fail(`"${g.id}" declares audio without a bar to read — then nothing says signal arrived`);
+ // A floor of 0 would pass on a bar the layout never sized, which is the same
+ // reading as silence.
+ if (!(au.floor > 0)) fail(`"${g.id}" declares audio with floor ${au.floor} — the silent height has to be a real one`);
+ }
+
const sa = g.safeArea;
if (sa) {
if (!sa.entity || !sa.reference) fail(`"${g.id}" declares safeArea without both an entity and a reference`);
diff --git a/tools/goldenProjects.mjs b/tools/goldenProjects.mjs
index fcbb83a8a..38902be34 100644
--- a/tools/goldenProjects.mjs
+++ b/tools/goldenProjects.mjs
@@ -78,7 +78,9 @@ export const EVIDENCE = {
animation: /\b(SpriteAnimator|Animator|spriteAnim|Flipbook|TimelinePlayer|AnimClip)\b/,
ecs: /\b(defineComponent|defineSystem)\b/,
particles: /\bParticleEmitter\b/,
- audio: /\b(AudioSource|AudioListener|AudioBus|playSound|audioPlugin|Mixer)\b/,
+ // Components OR the resource: audio-demo takes Res(Audio) and never inserts a
+ // component, and a pattern that only knew the components read it as unused.
+ audio: /\b(AudioSource|AudioListener|AudioAPI|audioPlugin)\b|Res\(Audio\)/,
'ui-layout': /\b(UINode|Canvas|spawnUIEntity|FlexContainer)\b/,
text: /\bText\b/,
localization: /\b(Localization|i18nKey|setLocale)\b/,
@@ -122,9 +124,8 @@ export const KNOWN_GAPS = {
// Measured: hello-world exports a 2.82MB single file, video-puzzle 3.22MB — so
// the floor is the runtime, not the game, and no project reaches the 2MB cap.
'startup-size': 'the playable runtime floor (~2.8MB) exceeds the 2MB default profile cap; see REARCH_EXPORT',
- // The three EVIDENCE found being claimed by a project that did not exercise
- // them. Each is now a hole somebody has to read rather than a word in a list.
- audio: 'NO example in the repository uses audio at all — not a golden one, not a sample. The pillar ships (buses, ducking, the cooked MP3 path, the Mixer panel) with nothing certifying any of it',
+ // What EVIDENCE found being claimed by a project that did not exercise it.
+ // Each is now a hole somebody has to read rather than a word in a list.
animation: 'sprite-animation and cutscene exercise it, and neither is in the corpus; platformer claimed it and contains no animation',
material: 'effects-gallery is the only example with a material, and it is not in the corpus; spine-demo claimed it and has none',
};
@@ -274,6 +275,17 @@ export const GOLDEN = [
tier: 'release',
interact: { keys: ['KeyD'], frames: 40 },
},
+ {
+ id: 'audio-demo',
+ certifies: ['audio'],
+ targets: ['web', 'desktop'],
+ tier: 'release',
+ interactGap: 'a pad plays a sound and draws nothing of its own — the audio block below is the run that reads the result',
+ // What certifies audio, since pixels cannot — the toggle redraws itself either
+ // way. Click for a SUSTAINED source (a one-shot ends before the capture), then
+ // read the bar the visualizer writes from an analyser bin.
+ audio: { toggle: { x: 0.5, y: 0.41 }, bar: 'Bar0', floor: 6, frames: 60 },
+ },
];
/**
@@ -335,6 +347,11 @@ export function parityFor(g) {
}
/** The input a project's package must answer, or null when it opted out. */
+/** The audio claim, or null. See the `audio` block on audio-demo. */
+export function audioFor(g) {
+ return g.audio ?? null;
+}
+
export function interactFor(g) {
if (g.interactGap || !g.interact) return null;
return {
diff --git a/tools/verify-golden.mjs b/tools/verify-golden.mjs
index 572e81b65..d33abbcad 100644
--- a/tools/verify-golden.mjs
+++ b/tools/verify-golden.mjs
@@ -19,7 +19,7 @@
import { spawnSync } from 'node:child_process';
import { mkdirSync, rmSync, readFileSync, existsSync } from 'node:fs';
import path from 'node:path';
-import { atTier, projectDir, parityFor, interactFor, suspendFor, safeAreaFor, atlasFor, ROOT } from './goldenProjects.mjs';
+import { atTier, projectDir, parityFor, interactFor, audioFor, suspendFor, safeAreaFor, atlasFor, ROOT } from './goldenProjects.mjs';
import { frameDistance, frameCellMax, readPNG } from './frameCompare.mjs';
import { retryOnDeadGpu } from './lib/deadGpu.mjs';
@@ -179,6 +179,29 @@ for (const { id, target } of pairs) {
});
console.log(`${ok ? '✓' : '✗'} ${id} ${target} — atlas: ${packed} texture(s) packed into a page`);
}
+ // Did anything reach the audio output? A frame cannot answer it: the control
+ // that starts the sound redraws itself either way. So drive the toggle and read
+ // the height the game wrote from an analyser bin — silence leaves it on its floor.
+ const audio = audioFor(golden);
+ if (audio && target === 'web') {
+ const probed = launchPackage(id, target, [
+ '--dir', out,
+ '--input', JSON.stringify({ pointer: { x: audio.toggle.x, y: audio.toggle.y }, frames: audio.frames ?? 60 }),
+ '--probe', audio.bar,
+ ]);
+ const found = /probe: (\{.*\})/.exec(probed.stdout || '');
+ let height = null;
+ try { height = found ? JSON.parse(found[1]).at?.[audio.bar]?.h ?? null : null; } catch { height = null; }
+ const ok = typeof height === 'number' && height > audio.floor;
+ results.push({
+ id, target, stage: 'audio', ok,
+ why: ok ? '' : height === null
+ ? `${audio.bar} did not report a height — the probe saw no such UI node`
+ : `${audio.bar} stayed at ${height} (floor ${audio.floor}); nothing reached the output`,
+ });
+ console.log(`${ok ? '✓' : '✗'} ${id} ${target} — audio: ${audio.bar} at ${height ?? 'nothing'} (silent floor ${audio.floor})`);
+ }
+
const tolerance = COMPARABLE.has(target) && !NO_PARITY ? parityFor(golden) : null;
const editorPng = path.join(WORK, `${id}-editor.png`);
const editor = tolerance != null ? captureEditorFrame(id, editorPng) : null;