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): a component's Chinese link points at a Chinese heading

esengine533064dab311
diff --git a/docs/astro/src/data/componentDocs.ts b/docs/astro/src/data/componentDocs.ts
index daade1bec..ee99ef7bb 100644
--- a/docs/astro/src/data/componentDocs.ts
+++ b/docs/astro/src/data/componentDocs.ts
@@ -107,13 +107,13 @@ export const COMPONENT_DOCS: Record<string, ComponentDoc> = {
SegmentCollider: { category: 'physics', summary: 'A single line segment — a one-sided wall or edge.', doc: 'gameplay/physics', anchor: 'colliders', anchorZh: '碰撞体' },
PolygonCollider: { category: 'physics', summary: 'A convex polygon collision shape from your own points.', doc: 'gameplay/physics', anchor: 'colliders', anchorZh: '碰撞体' },
ChainCollider: { category: 'physics', summary: 'A polyline of edges — open or looped — for static terrain.', doc: 'gameplay/physics', anchor: 'colliders', anchorZh: '碰撞体' },
- RigidBody3D: { category: 'physics', summary: 'Puts the entity under the 3D solver — its own component set, so a 2D scene keeps the world it already has.', doc: 'gameplay/physics-3d', anchor: 'bodies', anchorZh: 'bodies' },
- BoxCollider3D: { category: 'physics', summary: 'A box collision shape in 3D. Half-extents are in world units.', doc: 'gameplay/physics-3d', anchor: 'shapes', anchorZh: 'shapes' },
- SphereCollider3D: { category: 'physics', summary: 'A sphere collision shape in 3D.', doc: 'gameplay/physics-3d', anchor: 'shapes', anchorZh: 'shapes' },
- CapsuleCollider3D: { category: 'physics', summary: 'An upright capsule — what a 3D character is. Total height is 2*(halfHeight + radius).', doc: 'gameplay/physics-3d', anchor: 'shapes', anchorZh: 'shapes' },
+ RigidBody3D: { category: 'physics', summary: 'Puts the entity under the 3D solver — its own component set, so a 2D scene keeps the world it already has.', doc: 'gameplay/physics-3d', anchor: 'bodies', anchorZh: '刚体' },
+ BoxCollider3D: { category: 'physics', summary: 'A box collision shape in 3D. Half-extents are in world units.', doc: 'gameplay/physics-3d', anchor: 'shapes', anchorZh: '形状' },
+ SphereCollider3D: { category: 'physics', summary: 'A sphere collision shape in 3D.', doc: 'gameplay/physics-3d', anchor: 'shapes', anchorZh: '形状' },
+ CapsuleCollider3D: { category: 'physics', summary: 'An upright capsule — what a 3D character is. Total height is 2*(halfHeight + radius).', doc: 'gameplay/physics-3d', anchor: 'shapes', anchorZh: '形状' },
MeshCollider3D: { category: 'physics', summary: 'Collides against an imported mesh\u2019s own triangles — terrain, stairs, a room. Always static, and one-sided.', doc: 'gameplay/physics-3d', anchor: 'colliding-against-imported-geometry', anchorZh: '用导入的几何做碰撞' },
ConvexCollider3D: { category: 'physics', summary: 'Collides against the convex hull of an imported mesh — the shape a solver can push, unlike a mesh collider.', doc: 'gameplay/physics-3d', anchor: 'colliding-against-imported-geometry', anchorZh: '用导入的几何做碰撞' },
- CharacterController3D: { category: 'physics', summary: 'A kinematic 3D mover: swept against the world, climbs steps, stays glued to slopes, and reports the ground it is on.', doc: 'gameplay/physics-3d', anchor: 'characters', anchorZh: 'characters' },
+ CharacterController3D: { category: 'physics', summary: 'A kinematic 3D mover: swept against the world, climbs steps, stays glued to slopes, and reports the ground it is on.', doc: 'gameplay/physics-3d', anchor: 'characters', anchorZh: '角色' },
PointJoint3D: { category: 'physics', summary: 'Holds two 3D bodies at a shared point, free to turn on all three axes — a chain link, a ragdoll limb.', doc: 'gameplay/physics-3d', anchor: 'joints', anchorZh: '关节' },
HingeJoint3D: { category: 'physics', summary: 'One axis of rotation between two 3D bodies — a door or a driven wheel, with optional limits and a motor.', doc: 'gameplay/physics-3d', anchor: 'joints', anchorZh: '关节' },
SliderJoint3D: { category: 'physics', summary: 'One axis of travel between two 3D bodies — a lift or a piston, with optional limits and a motor.', doc: 'gameplay/physics-3d', anchor: 'joints', anchorZh: '关节' },
diff --git a/tools/component-reference.mjs b/tools/component-reference.mjs
index a22637bbd..d3245a59f 100644
--- a/tools/component-reference.mjs
+++ b/tools/component-reference.mjs
@@ -40,6 +40,7 @@ const SDK_SRC = join(ROOT, 'sdk', 'src');
const SDK_DIST = join(ROOT, 'sdk', 'dist', 'index.node.js');
const SNAPSHOT = join(ROOT, 'docs', 'astro', 'src', 'data', 'components.generated.json');
const CURATED = join(ROOT, 'docs', 'astro', 'src', 'data', 'componentDocs.ts');
+const DOC_PAGES = join(ROOT, 'docs', 'astro', 'src', 'content', 'docs');
// The editor's Details panel links each component header at its reference entry;
// the address is derived here so the two can never point at different pages.
const EDITOR_LINKS = join(ROOT, 'desktop', 'src', 'engine', 'componentDocs.generated.ts');
@@ -188,6 +189,57 @@ function curatedNames() {
return [...src.matchAll(/^ {2}([A-Za-z0-9_]+): \{/gm)].map((m) => m[1]).sort();
}
+/** Where each entry sends a reader: the guide, and the heading in each locale. */
+function curatedTargets() {
+ if (!existsSync(CURATED)) return [];
+ const src = readFileSync(CURATED, 'utf8');
+ const out = [];
+ for (const m of src.matchAll(/^ {2}([A-Za-z0-9_]+): \{(.*)$/gm)) {
+ const doc = /doc: '([^']+)'/.exec(m[2]);
+ if (!doc) continue;
+ out.push({
+ name: m[1],
+ doc: doc[1],
+ anchor: /anchor: '([^']*)'/.exec(m[2])?.[1],
+ anchorZh: /anchorZh: '([^']*)'/.exec(m[2])?.[1],
+ });
+ }
+ return out;
+}
+
+/** GitHub's heading-slug rule, which is what the site gives its headings:
+ * lowercase, drop everything that is not a letter, digit, `-` or `_`, and turn
+ * each surviving space into a hyphen — so "Text & code" is `text--code`, with
+ * two. Hand-written anchors get this wrong silently, and a Chinese heading
+ * slugs to its own characters, never to the English page's slug. */
+const slugOf = (heading) =>
+ heading
+ .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+ .replace(/[`*]/g, '')
+ .toLowerCase()
+ .replace(/[^\p{L}\p{N}\p{M}\s_-]/gu, '')
+ .trim()
+ .replace(/ /g, '-');
+
+const headingCache = new Map();
+/** The anchors one guide offers. Fenced blocks are skipped: a shell comment is
+ * not a heading. */
+function headingSlugs(file) {
+ let slugs = headingCache.get(file);
+ if (slugs) return slugs;
+ slugs = new Set();
+ let fenced = false;
+ for (const line of readFileSync(file, 'utf8').split('\n')) {
+ if (/^\s*(```|~~~)/.test(line)) fenced = !fenced;
+ else if (!fenced) {
+ const h = /^#{2,6}\s+(.+?)\s*$/.exec(line);
+ if (h) slugs.add(slugOf(h[1]));
+ }
+ }
+ headingCache.set(file, slugs);
+ return slugs;
+}
+
/** name -> category, read from the same curated table. */
function curatedCategories() {
const src = readFileSync(CURATED, 'utf8');
@@ -267,6 +319,25 @@ else {
for (const n of dCur.extra) problems.push(`componentDocs.ts describes "${n}", which is not a component`);
}
+// Where those entries send a reader. The built site's link check knows this too,
+// but it needs the site built and so only runs from the docs deploy — which a
+// release calls, making a dead anchor a failure at the moment of shipping.
+for (const t of curatedTargets()) {
+ for (const [locale, rel, anchor] of [
+ ['en', `${t.doc}.mdx`, t.anchor],
+ ['zh-cn', join('zh-cn', `${t.doc}.mdx`), t.anchorZh],
+ ]) {
+ const file = join(DOC_PAGES, rel);
+ if (!existsSync(file)) {
+ problems.push(`componentDocs.ts sends "${t.name}" to ${locale} ${t.doc}, which is not a page`);
+ continue;
+ }
+ if (anchor && !headingSlugs(file).has(anchor)) {
+ problems.push(`"${t.name}" links ${locale} ${t.doc}#${anchor}, which is not a heading there`);
+ }
+ }
+}
+
const links = editorLinkNames();
if (links === null) problems.push(`missing the editor's link table ${EDITOR_LINKS}`);
else {