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(docs): an import line the manual teaches has to exist

esengine4bedd69bbe3d
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1b9207479..e5866aa47 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -193,6 +193,18 @@ published separately; it ships inside the editor.
### Fixed
+- **The manual taught an import that does not exist.** `facingFromQuat` was
+ removed when perception moved to a dot-product cone, and four pages went on
+ importing it — including a complete turret example a reader would copy. It is
+ `quaternionToAngle2D`, the same arithmetic under the name that survived. Two
+ more imports named symbols that exist but were never exported:
+ `VideoBackendContext` (what a replacement video backend is handed) and
+ `wechatProfile` (the host profile you spread to change one thing) — both are
+ extension points the same pages teach, so they are exported now rather than
+ written out of the docs. New gate `check-doc-imports`: an import line in the
+ manual must name something the SDK exports, because a reader copies it
+ verbatim.
+
- **A C++ harness that had never been compiled.** `test_bitmap_font` asserts the
guard on `BitmapFont::createLabelAtlas` against degenerate dimensions — a
divide-by-zero that traps on wasm and fills the atlas with garbage where it does
diff --git a/docs/astro/src/content/docs/core-concepts/transforms.mdx b/docs/astro/src/content/docs/core-concepts/transforms.mdx
index 77971569a..ff2d478ab 100644
--- a/docs/astro/src/content/docs/core-concepts/transforms.mdx
+++ b/docs/astro/src/content/docs/core-concepts/transforms.mdx
@@ -153,12 +153,11 @@ const angle = Math.PI / 4; // 45° CCW
const rot = quat(Math.cos(angle / 2), 0, 0, Math.sin(angle / 2));
```
-To read the angle back, two equivalent helpers compute `2 * atan2(z, w)`:
+To read the angle back, `2 * atan2(z, w)`:
| Helper | Signature | Notes |
|---|---|---|
| `quaternionToAngle2D` | `(rz, rw) => number` | Z angle in radians from a quaternion's `z`/`w`. |
-| `facingFromQuat` | `(z, w) => number` | Same math; the AI/perception spelling. |
| `normalizeAngle` | `(a) => number` | Wrap any angle to `(-π, π]` — for shortest-turn deltas. |
A complete example — turrets tracking the cursor:
@@ -166,7 +165,7 @@ A complete example — turrets tracking the cursor:
```typescript
import {
defineSystem, defineTag, Query, Mut, Res,
- Transform, CameraView, quat, facingFromQuat, normalizeAngle,
+ Transform, CameraView, quat, quaternionToAngle2D, normalizeAngle,
} from 'esengine';
const Turret = defineTag('Turret');
@@ -182,7 +181,7 @@ const aim = defineSystem([Query(Mut(Transform)).with(Turret), Res(CameraView)],
t.rotation = quat(Math.cos(angle / 2), 0, 0, Math.sin(angle / 2));
// Or, to turn gradually: read the current facing and step toward the target.
- const facing = facingFromQuat(t.rotation.z, t.rotation.w);
+ const facing = quaternionToAngle2D(t.rotation.z, t.rotation.w);
const delta = normalizeAngle(angle - facing); // shortest signed turn
}
});
diff --git a/docs/astro/src/content/docs/gameplay/ai/advanced.mdx b/docs/astro/src/content/docs/gameplay/ai/advanced.mdx
index 3e7392771..0d53b6b8f 100644
--- a/docs/astro/src/content/docs/gameplay/ai/advanced.mdx
+++ b/docs/astro/src/content/docs/gameplay/ai/advanced.mdx
@@ -71,7 +71,7 @@ targets), or unit tests against a fake world:
- **`senseTarget(ox, oy, facing, tx, ty, range, halfFov, isBlocked?)`** — the pure
geometry: a range check, a FOV cone check (`halfFov` is *half* the cone in
radians; ≥ π means omnidirectional), then the optional occlusion callback.
-- **`facingFromQuat(z, w)`** — 2D facing angle in radians from a `Transform`
+- **`quaternionToAngle2D(z, w)`** — 2D facing angle in radians from a `Transform`
rotation quaternion's z/w components.
- **`makeLosCheck(physics)`** — builds the occlusion callback from a physics
raycast: occluded when any hit lands clearly short of the target
@@ -81,12 +81,12 @@ targets), or unit tests against a fake world:
the nearest visible one, and write the `Perception` component.
```typescript
-import { senseTarget, facingFromQuat, Transform, registerCondition } from 'esengine';
+import { senseTarget, quaternionToAngle2D, Transform, registerCondition } from 'esengine';
// A one-off sight check against a POINT — no PerceptionTarget needed.
registerCondition('seesShrine', (ctx) => {
const tf = ctx.get(Transform);
- const facing = facingFromQuat(tf.rotation.z, tf.rotation.w);
+ const facing = quaternionToAngle2D(tf.rotation.z, tf.rotation.w);
return senseTarget(
tf.position.x, tf.position.y, facing,
SHRINE.x, SHRINE.y,
diff --git a/docs/astro/src/content/docs/scripting/math.mdx b/docs/astro/src/content/docs/scripting/math.mdx
index 32e0a39b6..47bbf34f1 100644
--- a/docs/astro/src/content/docs/scripting/math.mdx
+++ b/docs/astro/src/content/docs/scripting/math.mdx
@@ -79,7 +79,7 @@ Also: `clamp`, `inverseLerp`, `rad2deg`, `approximately`, `mod`, `sign`.
handful of exports cover the angle ↔ quaternion round trip:
```typescript
-import { quat, quaternionToAngle2D, facingFromQuat, normalizeAngle } from 'esengine';
+import { quat, quaternionToAngle2D, normalizeAngle } from 'esengine';
// Angle -> quaternion. NOTE: the factory takes w FIRST — quat(w, x, y, z).
const a = Math.PI / 3;
@@ -87,7 +87,6 @@ const rot = quat(Math.cos(a / 2), 0, 0, Math.sin(a / 2));
// Quaternion -> angle (radians), from the z/w components.
const facing = quaternionToAngle2D(rot.z, rot.w); // Math.PI / 3
-facingFromQuat(rot.z, rot.w); // same math, the AI/perception spelling
// Wrap to (-π, π] — the shortest signed turn from facing toward a target angle.
const delta = normalizeAngle(targetAngle - facing);
@@ -97,7 +96,6 @@ const delta = normalizeAngle(targetAngle - facing);
|---|---|
| `quat(w?, x?, y?, z?)` | Quaternion factory; no arguments gives the identity `{w: 1, x: 0, y: 0, z: 0}`. |
| `quaternionToAngle2D(rz, rw)` | Z angle in radians from a quaternion's `z`/`w` (`2 * atan2(z, w)`). |
-| `facingFromQuat(z, w)` | Identical math under its AI/perception name. |
| `normalizeAngle(a)` | Wrap any angle to `(-π, π]` for shortest-turn comparisons. |
For direction *vectors* instead of rotations, stay in `v2`: `fromAngle` /
diff --git a/docs/astro/src/content/docs/ui/interaction.mdx b/docs/astro/src/content/docs/ui/interaction.mdx
index 18413689d..11140b8e8 100644
--- a/docs/astro/src/content/docs/ui/interaction.mdx
+++ b/docs/astro/src/content/docs/ui/interaction.mdx
@@ -222,7 +222,7 @@ const tooltip = defineSystem([GetWorld(), Res(UICameraInfo)], (world, camera) =>
| Helper | Returns | Use |
|---|---|---|
-| `uiHitTestWorld(world, x, y, …)` | Topmost **interactable** entity or `null` | The runtime raycast — same rules the interaction system uses. |
+| `uiHitTestWorld(world, x, y)` | Topmost **interactable** entity or `null` | The runtime raycast — same rules the interaction system uses. |
| `uiPickWorld(world, x, y)` | Topmost UI entity or `null` | Editor-style pick, ignores `Interactable`. |
| `uiPickAllWorld(world, x, y)` | All UI entities under the point, most specific first | Pick-through menus, debug overlays. |
| `screenToUiWorld(camera, glX, glY)` | `{ x, y }` world point | Project a GL-oriented screen point through the UI camera. |
diff --git a/docs/astro/src/content/docs/zh-cn/core-concepts/transforms.mdx b/docs/astro/src/content/docs/zh-cn/core-concepts/transforms.mdx
index 40fe214f6..397b45b64 100644
--- a/docs/astro/src/content/docs/zh-cn/core-concepts/transforms.mdx
+++ b/docs/astro/src/content/docs/zh-cn/core-concepts/transforms.mdx
@@ -143,7 +143,6 @@ const rot = quat(Math.cos(angle / 2), 0, 0, Math.sin(angle / 2));
| 辅助函数 | 签名 | 说明 |
|---|---|---|
| `quaternionToAngle2D` | `(rz, rw) => number` | 由四元数的 `z`/`w` 求 Z 角度(弧度)。 |
-| `facingFromQuat` | `(z, w) => number` | 同样的数学;AI/感知模块的写法。 |
| `normalizeAngle` | `(a) => number` | 把任意角度归一到 `(-π, π]`——用于最短转向差值。 |
完整示例——炮塔跟踪光标:
@@ -151,7 +150,7 @@ const rot = quat(Math.cos(angle / 2), 0, 0, Math.sin(angle / 2));
```typescript
import {
defineSystem, defineTag, Query, Mut, Res,
- Transform, CameraView, quat, facingFromQuat, normalizeAngle,
+ Transform, CameraView, quat, quaternionToAngle2D, normalizeAngle,
} from 'esengine';
const Turret = defineTag('Turret');
@@ -167,7 +166,7 @@ const aim = defineSystem([Query(Mut(Transform)).with(Turret), Res(CameraView)],
t.rotation = quat(Math.cos(angle / 2), 0, 0, Math.sin(angle / 2));
// Or, to turn gradually: read the current facing and step toward the target.
- const facing = facingFromQuat(t.rotation.z, t.rotation.w);
+ const facing = quaternionToAngle2D(t.rotation.z, t.rotation.w);
const delta = normalizeAngle(angle - facing); // shortest signed turn
}
});
diff --git a/docs/astro/src/content/docs/zh-cn/gameplay/ai/advanced.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/ai/advanced.mdx
index 00cb09e4c..20c6d4ca4 100644
--- a/docs/astro/src/content/docs/zh-cn/gameplay/ai/advanced.mdx
+++ b/docs/astro/src/content/docs/zh-cn/gameplay/ai/advanced.mdx
@@ -66,7 +66,7 @@ const grid = navGridFromTiles((x, y) => level.tiles[y][x], {
- **`senseTarget(ox, oy, facing, tx, ty, range, halfFov, isBlocked?)`**——纯几何:
先查距离,再查视野锥(`halfFov` 是锥角的*一半*,弧度;≥ π 表示全向),最后走可选的
遮挡回调。
-- **`facingFromQuat(z, w)`**——从 `Transform` 旋转四元数的 z/w 分量求 2D 朝向角
+- **`quaternionToAngle2D(z, w)`**——从 `Transform` 旋转四元数的 z/w 分量求 2D 朝向角
(弧度)。
- **`makeLosCheck(physics)`**——用物理射线构建遮挡回调:任何命中明显落在目标之前
(`fraction < 0.98`——最后约 2% 是目标自己)即视为遮挡。
@@ -75,12 +75,12 @@ const grid = navGridFromTiles((x, y) => level.tiles[y][x], {
`Perception` 组件。
```typescript
-import { senseTarget, facingFromQuat, Transform, registerCondition } from 'esengine';
+import { senseTarget, quaternionToAngle2D, Transform, registerCondition } from 'esengine';
// A one-off sight check against a POINT — no PerceptionTarget needed.
registerCondition('seesShrine', (ctx) => {
const tf = ctx.get(Transform);
- const facing = facingFromQuat(tf.rotation.z, tf.rotation.w);
+ const facing = quaternionToAngle2D(tf.rotation.z, tf.rotation.w);
return senseTarget(
tf.position.x, tf.position.y, facing,
SHRINE.x, SHRINE.y,
diff --git a/docs/astro/src/content/docs/zh-cn/scripting/math.mdx b/docs/astro/src/content/docs/zh-cn/scripting/math.mdx
index 78599e456..2bc90f74c 100644
--- a/docs/astro/src/content/docs/zh-cn/scripting/math.mdx
+++ b/docs/astro/src/content/docs/zh-cn/scripting/math.mdx
@@ -77,7 +77,7 @@ scalar.deg2rad(90); // degrees -> radians
角度 ↔ 四元数的往返:
```typescript
-import { quat, quaternionToAngle2D, facingFromQuat, normalizeAngle } from 'esengine';
+import { quat, quaternionToAngle2D, normalizeAngle } from 'esengine';
// Angle -> quaternion. NOTE: the factory takes w FIRST — quat(w, x, y, z).
const a = Math.PI / 3;
@@ -85,7 +85,6 @@ const rot = quat(Math.cos(a / 2), 0, 0, Math.sin(a / 2));
// Quaternion -> angle (radians), from the z/w components.
const facing = quaternionToAngle2D(rot.z, rot.w); // Math.PI / 3
-facingFromQuat(rot.z, rot.w); // same math, the AI/perception spelling
// Wrap to (-π, π] — the shortest signed turn from facing toward a target angle.
const delta = normalizeAngle(targetAngle - facing);
@@ -95,7 +94,6 @@ const delta = normalizeAngle(targetAngle - facing);
|---|---|
| `quat(w?, x?, y?, z?)` | 四元数工厂;不传参数得到单位四元数 `{w: 1, x: 0, y: 0, z: 0}`。 |
| `quaternionToAngle2D(rz, rw)` | 由四元数的 `z`/`w` 求 Z 角度(弧度,`2 * atan2(z, w)`)。 |
-| `facingFromQuat(z, w)` | 同样的数学,AI/感知模块的命名。 |
| `normalizeAngle(a)` | 把任意角度归一到 `(-π, π]`,用于最短转向比较。 |
如果需要的是方向*向量*而不是旋转,留在 `v2` 里就好:`fromAngle` / `angle` /
diff --git a/docs/astro/src/content/docs/zh-cn/ui/interaction.mdx b/docs/astro/src/content/docs/zh-cn/ui/interaction.mdx
index a3875a0db..65af8d72b 100644
--- a/docs/astro/src/content/docs/zh-cn/ui/interaction.mdx
+++ b/docs/astro/src/content/docs/zh-cn/ui/interaction.mdx
@@ -207,7 +207,7 @@ const tooltip = defineSystem([GetWorld(), Res(UICameraInfo)], (world, camera) =>
| 辅助函数 | 返回 | 用途 |
|---|---|---|
-| `uiHitTestWorld(world, x, y, …)` | 最顶层**可交互**实体或 `null` | 运行时射线——与交互系统同一套规则。 |
+| `uiHitTestWorld(world, x, y)` | 最顶层**可交互**实体或 `null` | 运行时射线——与交互系统同一套规则。 |
| `uiPickWorld(world, x, y)` | 最顶层 UI 实体或 `null` | 编辑器式拾取,无视 `Interactable`。 |
| `uiPickAllWorld(world, x, y)` | 该点下全部 UI 实体,最具体的在前 | 穿透式菜单、调试叠层。 |
| `screenToUiWorld(camera, glX, glY)` | `{ x, y }` 世界点 | 把 GL 朝向的屏幕点经 UI 相机投到世界。 |
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index 089f29977..a77a4e04f 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": 1621,
+ "experimental": 1623,
"deprecated": 3
},
- "total": 1807,
+ "total": 1809,
"subsystems": [
{
"id": "ecs",
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 59fe0b545..80ab93907 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 · 1527 experimental · 3 deprecated
+Symbols: 113 public · 66 beta · 1528 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -9305,6 +9305,12 @@ static new (backend: PlatformVideoBackend): VideoAPI
static prototype: VideoAPI
```
+## VideoBackendContext — interface @experimental
+```
+audio: (() => AudioAPI | null) | undefined
+sideModules: () => SideModuleHost | null
+```
+
## VideoData — interface @experimental
```
autoplay: boolean
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index d9d18d158..57d4cb71f 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 · 1517 experimental · 3 deprecated
+Symbols: 113 public · 66 beta · 1518 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -12360,6 +12360,11 @@ VideoPlugin
(category: string, message: string, data?: unknown): void
```
+## wechatProfile — const @experimental
+```
+MiniGameProfile
+```
+
## widgetToPrefab — function @experimental
```
(build: (world: World) => Entity, name: string): PrefabData
diff --git a/sdk/src/index.minigame.ts b/sdk/src/index.minigame.ts
index 5b4e12aed..f7cf006b3 100644
--- a/sdk/src/index.minigame.ts
+++ b/sdk/src/index.minigame.ts
@@ -68,7 +68,8 @@ export type {
export { initMiniGameRuntime, type MiniGameRuntimeConfig } from './runtime/miniGameRuntime';
// The family backends, exported so a profile can wrap or replace one rather than
-// write it from scratch.
+// write it from scratch — with what a replacement is handed at construction.
+export type { VideoBackendContext } from './video/PlatformVideoBackend';
export { MiniGameAudioBackend } from './audio/MiniGameAudioBackend';
export { MiniGameSocket } from './net/MiniGameSocket';
export { createMiniGameSideModuleHost, type MiniGameSideModuleFactories } from './sideModules';
diff --git a/sdk/src/index.wechat.ts b/sdk/src/index.wechat.ts
index 5f1e078fa..c218a2adf 100644
--- a/sdk/src/index.wechat.ts
+++ b/sdk/src/index.wechat.ts
@@ -38,3 +38,6 @@ export {
initWeChatRuntime,
type WeChatRuntimeConfig,
} from './runtime/wechatRuntime';
+
+// The host as data: spread it to keep everything but the one thing you replace.
+export { wechatProfile } from './platform/wechat';
diff --git a/tools/check-doc-imports.mjs b/tools/check-doc-imports.mjs
new file mode 100644
index 000000000..3fa6c4e33
--- /dev/null
+++ b/tools/check-doc-imports.mjs
@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file check-doc-imports.mjs
+ * @brief Anything the manual imports from the SDK has to be exported by it.
+ * @details A reader copies an import line verbatim, so one naming a symbol the
+ * package does not export is a broken first step. `facingFromQuat` was
+ * taught in four pages after the perception rewrite removed it.
+ *
+ * Run: node tools/check-doc-imports.mjs (exit 1 on an unexported symbol)
+ */
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const ETC = path.join(ROOT, 'sdk', 'etc');
+const DOCS = path.join(ROOT, 'docs', 'astro', 'src', 'content', 'docs');
+
+// The public surface, as the api-surface gate keeps it. Every entry at once: a
+// page names the module it imports from, and the snapshots are per entry.
+const exported = new Set();
+for (const f of readdirSync(ETC)) {
+ if (!f.endsWith('.api.md')) continue;
+ for (const m of readFileSync(path.join(ETC, f), 'utf8').matchAll(/^## (\w+)/gm)) exported.add(m[1]);
+}
+
+function pages(dir, out = []) {
+ for (const e of readdirSync(dir)) {
+ const p = path.join(dir, e);
+ // api-ts is generated FROM the surface, so it cannot disagree with it.
+ if (statSync(p).isDirectory()) { if (e !== 'api-ts') pages(p, out); }
+ else if (/\.mdx?$/.test(e)) out.push(p);
+ }
+ return out;
+}
+
+const problems = [];
+for (const file of pages(DOCS)) {
+ const text = readFileSync(file, 'utf8');
+ for (const m of text.matchAll(/import\s*(?:type\s*)?\{([^}]*)\}\s*from\s*['"](esengine[^'"]*)['"]/g)) {
+ for (let name of m[1].split(',')) {
+ name = name.trim().replace(/^type\s+/, '').split(/\s+as\s+/)[0].trim();
+ if (!name || !/^[A-Za-z_]\w*$/.test(name)) continue;
+ if (exported.has(name)) continue;
+ problems.push(` ${path.relative(ROOT, file)} imports ${name} from '${m[2]}'`);
+ }
+ }
+}
+
+if (problems.length > 0) {
+ console.error(`${problems.length} import(s) in the manual name a symbol the SDK does not export:\n`);
+ console.error([...new Set(problems)].join('\n'));
+ console.error('\nExport it, or teach the name that exists. A reader copies the line.');
+ process.exit(1);
+}
+
+console.log(`check-doc-imports: every symbol the manual imports is exported (${exported.size} public names).`);
diff --git a/tools/gates.mjs b/tools/gates.mjs
index 57b98932a..fc47ca5a3 100644
--- a/tools/gates.mjs
+++ b/tools/gates.mjs
@@ -34,6 +34,7 @@ export const GATES = [
{ id: 'sidemodule-gates', run: 'node tools/check-sidemodule-gates.mjs' },
{ id: 'engine-exports', run: 'node tools/check-engine-exports.mjs' },
{ id: 'fixture-scenes', run: 'node tools/check-fixture-scenes.mjs' },
+ { id: 'doc-imports', run: 'node tools/check-doc-imports.mjs' },
{
id: 'native-bindings',
run: 'node tools/check-native-bindings.mjs',