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): the manual builds again, and a gate reads what broke it - an apostrophe in Waterfall's summary ended its string and five links were written from the site's root, so 0.104.0 published with the manual not deployed; check-doc-sources parses the data files and reads every page's links without building the site

yhh6efb7eba72c5
diff --git a/docs/astro/src/content/docs/graphics/terrain.mdx b/docs/astro/src/content/docs/graphics/terrain.mdx
index 07947fa54..65c79465f 100644
--- a/docs/astro/src/content/docs/graphics/terrain.mdx
+++ b/docs/astro/src/content/docs/graphics/terrain.mdx
@@ -25,7 +25,7 @@ The ground is one of two kinds, chosen by `extent`:
| Field | What it does |
|---|---|
| `extent` | `Area` or `Infinite`, as above. |
-| `heightmap` | Area only. An image read as data: its bytes as the file holds them, with no colour conversion, so it ships as the PNG it is (a heightmap compressed on the way fails the terrain, saying so). Its texture is marked **Data** in its import settings when it is put here (see [Textures](/assets/textures/)): no size cap unless you set one, and a cap keeps the file's 16 bits. Empty makes the ground from noise. |
+| `heightmap` | Area only. An image read as data: its bytes as the file holds them, with no colour conversion, so it ships as the PNG it is (a heightmap compressed on the way fails the terrain, saying so). Its texture is marked **Data** in its import settings when it is put here (see [Textures](/docs/assets/textures/)): no size cap unless you set one, and a cap keeps the file's 16 bits. Empty makes the ground from noise. |
| `heightmapFormat` | How the heightmap holds its heights. **Grey**: the grey (or red) channel, at the depth of the file: 16 bits from a 16-bit PNG (what World Machine, Gaea and most tools export), 256 steps from an 8-bit one. **Red + green**: sixteen bits across red (high byte) and green (low byte) of an 8-bit image. |
| `sizeX`, `sizeZ`, `height` | An area's world size and the world height of its highest ground. For infinite ground `sizeX` is the span that `frequency` hills are spread over, and `sizeZ` is not used. |
| `cellSize` | The finest cell of the ground's mesh, in world units: what the ground is drawn at near the eye. Further off the cells double, level by level. |
diff --git a/docs/astro/src/content/docs/publishing/ads-sharing.mdx b/docs/astro/src/content/docs/publishing/ads-sharing.mdx
index f15fa07e0..2fa10f5cd 100644
--- a/docs/astro/src/content/docs/publishing/ads-sharing.mdx
+++ b/docs/astro/src/content/docs/publishing/ads-sharing.mdx
@@ -67,7 +67,7 @@ installed provider. Use it to hide the "watch ad" button honestly:
real pause/audio ceremony running. Your revive flow rehearses at your desk.
- **Android and iOS builds** — the ad SDK is your own native code, and the engine
links none. `available` is `true` once that code answers `ads.show`
- (see [Calling your own native code](/publishing/android-ios/#ads)).
+ (see [Calling your own native code](/docs/publishing/android-ios/#ads)).
- **Plain web and desktop builds** — no ad system, `available` is `false`.
## Sharing
diff --git a/docs/astro/src/content/docs/publishing/android-ios.mdx b/docs/astro/src/content/docs/publishing/android-ios.mdx
index 6dbd10800..5bfb472f5 100644
--- a/docs/astro/src/content/docs/publishing/android-ios.mdx
+++ b/docs/astro/src/content/docs/publishing/android-ios.mdx
@@ -358,7 +358,7 @@ A handler runs on the main thread.
### Ads
-The engine's [`Ads` service](/publishing/ads-sharing/#rewarded-ads) works on a device
+The engine's [`Ads` service](/docs/publishing/ads-sharing/#rewarded-ads) works on a device
as soon as your native code answers two names. Nothing else changes in the game:
`Ads.available` becomes `true`, and `showRewarded` pauses the game, silences it and
resumes it around the ad as it does in a mini-game.
diff --git a/docs/astro/src/content/docs/zh-cn/publishing/ads-sharing.mdx b/docs/astro/src/content/docs/zh-cn/publishing/ads-sharing.mdx
index 600f32e1e..237e78862 100644
--- a/docs/astro/src/content/docs/zh-cn/publishing/ads-sharing.mdx
+++ b/docs/astro/src/content/docs/zh-cn/publishing/ads-sharing.mdx
@@ -59,7 +59,7 @@ const reviveSystem = defineSystem([Res(Ads), GetWorld()], (ads, world) => {
- **编辑器 Play 模式**——自动安装 **mock provider**:`showRewarded`"播放"片刻后
resolve `completed: true`,真实的暂停/音频仪式照常运行。复活流程在工位上就能排练。
- **Android 与 iOS 构建**——广告 SDK 是你自己的原生代码,引擎一个都不链接。那段代码应答
- `ads.show` 之后 `available` 为 true(见[调用你自己的原生代码](/zh-cn/publishing/android-ios/#广告))。
+ `ads.show` 之后 `available` 为 true(见[调用你自己的原生代码](/docs/zh-cn/publishing/android-ios/#广告))。
- **普通 Web 与桌面构建**——没有广告系统,`available` 为 false。
## 分享
diff --git a/docs/astro/src/content/docs/zh-cn/publishing/android-ios.mdx b/docs/astro/src/content/docs/zh-cn/publishing/android-ios.mdx
index ba2377cc9..ea9f80ac0 100644
--- a/docs/astro/src/content/docs/zh-cn/publishing/android-ios.mdx
+++ b/docs/astro/src/content/docs/zh-cn/publishing/android-ios.mdx
@@ -303,7 +303,7 @@ android {
### 广告
-只要你的原生代码应答两个名字,引擎自带的 [`Ads` 服务](/zh-cn/publishing/ads-sharing/#激励视频)
+只要你的原生代码应答两个名字,引擎自带的 [`Ads` 服务](/docs/zh-cn/publishing/ads-sharing/#激励视频)
在真机上就能用,游戏里别的都不用改:`Ads.available` 变成 `true`,`showRewarded`
像在小游戏里一样,在广告前后暂停游戏、静音、再恢复。
diff --git a/docs/astro/src/data/componentDocs.ts b/docs/astro/src/data/componentDocs.ts
index 14d62aa56..f35e3cf78 100644
--- a/docs/astro/src/data/componentDocs.ts
+++ b/docs/astro/src/data/componentDocs.ts
@@ -111,7 +111,7 @@ export const COMPONENT_DOCS: Record<string, ComponentDoc> = {
MeshInstances: { category: 'graphics', summary: 'Draws the mesh of a MeshRenderer at many places as one renderable, culling each place and choosing its mesh by distance.', doc: 'graphics/foliage', anchor: 'placed-plants', anchorZh: '手摆植物' },
Floating: { category: 'graphics', summary: 'Holds a RigidBody3D up in water and carries it with the current, by forces at a few points of the body.', doc: 'graphics/water', anchor: 'floating', anchorZh: '漂浮' },
Spline: { category: 'graphics', summary: 'A curve through points, each with a width, read by what follows it (a river\'s WaterBody on the same entity); measured by the distance along it.', doc: 'graphics/water', anchor: 'splines', anchorZh: '样条' },
- Waterfall: { category: 'graphics', summary: 'Water falling from a lip: sheets thrown level at a speed and taken by gravity until they meet the ground or other water, drawn as the entity's own mesh.', doc: 'graphics/water', anchor: 'waterfalls', anchorZh: '瀑布' },
+ Waterfall: { category: 'graphics', summary: 'Water falling from a lip: sheets thrown level at a speed and taken by gravity until they meet the ground or other water, drawn as the mesh of the entity itself.', doc: 'graphics/water', anchor: 'waterfalls', anchorZh: '瀑布' },
WaterfallAnchor: { category: 'graphics', summary: 'Keeps a child of a Waterfall on the middle of the fall: at its foot wherever the water lands, or a share of the time down. Where the mist goes.', doc: 'graphics/water', anchor: 'waterfalls', anchorZh: '瀑布' },
WaterBody: { category: 'graphics', summary: 'An ocean, a lake or a river: where the water is, how high its waves stand and how it flows; drawn as part of its zone\'s one surface.', doc: 'graphics/water', anchor: 'the-component', anchorZh: '组件' },
WaterZone: { category: 'graphics', summary: 'The region the bodies of water are baked over and drawn from as one surface: the waves they share, the material, the mesh and the ripples.', doc: 'graphics/water', anchor: 'the-zone', anchorZh: '水体区域' },
diff --git a/tools/check-doc-sources.mjs b/tools/check-doc-sources.mjs
new file mode 100644
index 000000000..a54cd78f6
--- /dev/null
+++ b/tools/check-doc-sources.mjs
@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file check-doc-sources.mjs
+ * @brief What breaks the manual's build, found without building it: a data file that does not parse, a link with no /docs in front.
+ * @details The site is built and its links checked only by the docs workflow, which runs on a release. 0.104.0 published with the
+ * manual not deployed: an apostrophe in one summary of src/data/componentDocs.ts ended its string, and five links were
+ * written from the site's root, where no page lives. Both are a second's reading of the sources.
+ *
+ * Run: node tools/check-doc-sources.mjs (exit 1 on a finding)
+ */
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SITE = path.join(ROOT, 'docs', 'astro');
+const ts = createRequire(path.join(ROOT, 'sdk', 'package.json'))('typescript');
+const problems = [];
+
+const walk = (dir, test, out = []) => {
+ for (const e of readdirSync(dir)) {
+ const full = path.join(dir, e);
+ if (statSync(full).isDirectory()) walk(full, test, out);
+ else if (test(e)) out.push(full);
+ }
+ return out;
+};
+const rel = (file) => path.relative(ROOT, file).split(path.sep).join('/');
+
+// The data the pages are built from: hand-written tables a typo in a string takes down whole.
+const data = walk(path.join(SITE, 'src', 'data'), (name) => /\.(ts|mjs|js)$/.test(name));
+for (const file of data) {
+ const source = ts.createSourceFile(file, readFileSync(file, 'utf8'), ts.ScriptTarget.Latest, false);
+ for (const d of source.parseDiagnostics ?? []) {
+ const at = source.getLineAndCharacterOfPosition(d.start ?? 0);
+ problems.push(`${rel(file)}:${at.line + 1}:${at.character + 1} does not parse: ${ts.flattenDiagnosticMessageText(d.messageText, ' ')}`);
+ }
+}
+
+// Every page is served under /docs: a link written from the root names a page that is not there.
+const pages = walk(path.join(SITE, 'src', 'content', 'docs'), (name) => /\.mdx?$/.test(name));
+for (const file of pages) {
+ readFileSync(file, 'utf8').split('\n').forEach((line, i) => {
+ for (const m of line.matchAll(/\]\((\/(?!docs\/|\/)[^)\s]*)\)/g)) problems.push(`${rel(file)}:${i + 1} links to ${m[1]}, and every page is under /docs`);
+ });
+}
+
+if (problems.length > 0) {
+ console.error(`check-doc-sources: ${problems.length} finding(s) that fail the manual's build.\n`);
+ for (const p of problems) console.error(` ${p}`);
+ process.exit(1);
+}
+console.log(`check-doc-sources: ${data.length} data file(s) parse and ${pages.length} page(s) link under /docs.`);
diff --git a/tools/gates.mjs b/tools/gates.mjs
index 51593e941..5856a08eb 100644
--- a/tools/gates.mjs
+++ b/tools/gates.mjs
@@ -52,6 +52,7 @@ export const GATES = [
{ id: 'fixture-scenes', run: 'node tools/check-fixture-scenes.mjs' },
{ id: 'prefab-overrides', run: 'node tools/check-prefab-overrides.mjs' },
{ id: 'doc-imports', run: 'node tools/check-doc-imports.mjs' },
+ { id: 'doc-sources', run: 'node tools/check-doc-sources.mjs' },
{ id: 'architecture-doc', run: 'node tools/check-architecture-doc.mjs' },
{ id: 'native-bindings', run: 'node tools/check-native-bindings.mjs' },
// The generator's output is checked in, so its authority and its artifact can
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 50c30a9e5..4c58051cc 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -4702,6 +4702,8 @@ export const NOTED = {
{"note": "A picture made in the editor ships as a recipe."},
"fix(render): the built-in ripple map is drawn again after a device loss, and no copy of it is kept - every game held 256 KB for a map only water reads; and the checks that went red since: a cost scene with no criterion, TilemapLayer.lit in its defaults, NativeChannel frozen before it earned it, a wav encoder that refused read-only channels, a worker test with five seconds for twenty realms":
{"note": "A game no longer keeps a copy of the built-in ripple map."},
+ "fix(docs): the manual builds again, and a gate reads what broke it - an apostrophe in Waterfall's summary ended its string and five links were written from the site's root, so 0.104.0 published with the manual not deployed; check-doc-sources parses the data files and reads every page's links without building the site":
+ {"internal": "the manual's own build and a gate over its sources; no page a reader sees changed but the five links that now resolve"},
"fix(terrain): a ground with more pages wanted than it holds no longer throws every frame - the pages it had chosen to draw were marked in use only after new pages were made, so a new page took the slot of one about to be drawn and its node was placed on nothing":
{"note": "A large ground no longer throws every frame once its pages run out."},
"chore(gates): what the checks asked of this week's work - a disposition for esengine/image in a native script and its namespace there, Waterfall's width and its place in the corpus, the recipe worker's bundle as not a contract, shadeLight2D's inout against its return, and a test that named App as a type":