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(docs): an import line the manual teaches has to exist
esengine4bedd69bbe3d
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 theguard on `BitmapFont::createLabelAtlas` against degenerate dimensions — adivide-by-zero that traps on wasm and fills the atlas with garbage where it doesdiff --git a/docs/astro/src/content/docs/core-concepts/transforms.mdx b/docs/astro/src/content/docs/core-concepts/transforms.mdxindex 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° CCWconst 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:```typescriptimport {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.mdxindex 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 puregeometry: a range check, a FOV cone check (`halfFov` is *half* the cone inradians; ≥ π 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 physicsraycast: 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.mdxindex 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.mdxindex 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.mdxindex 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));```typescriptimport {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.mdxindex 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.mdxindex 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.mdxindex 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.jsonindex 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.mdindex 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): VideoAPIstatic prototype: VideoAPI```+## VideoBackendContext — interface @experimental+```+audio: (() => AudioAPI | null) | undefined+sideModules: () => SideModuleHost | null+```+## VideoData — interface @experimental```autoplay: booleandiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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): PrefabDatadiff --git a/sdk/src/index.minigame.ts b/sdk/src/index.minigame.tsindex 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.tsindex 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.mjsnew file mode 100644index 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.mjsindex 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',