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
refactor(comments): a comment says what it means, not where to read it
esenginecf9012157032
diff --git a/bench/aot-stage0/bench.cpp b/bench/aot-stage0/bench.cppindex a36578cf6..61459f1d4 100644--- a/bench/aot-stage0/bench.cpp+++ b/bench/aot-stage0/bench.cpp@@ -4,11 +4,11 @@* @file bench.cpp* @brief Stage 0 of the AOT proposal: is compiling the system loop worth it?*- * @details `docs/REARCH_AOT.md` §10 makes Stage 0 a go/no-go, and §11 names the- * risk it exists to retire: the speedup may be mostly the BOUNDARY COPY,- * not the interpreter — and the copy has a fix that costs 5% of a- * compiler (§12.B). A benchmark that reports one number cannot tell- * those apart, so this one runs the same system four ways:+ * @details Stage 0 is a go/no-go, and the risk it exists to retire is that the+ * speedup may be mostly the BOUNDARY COPY rather than the interpreter —+ * the copy has an SDK-side fix (variant B below) that costs 5% of a+ * compiler. A benchmark that reports one number cannot tell those+ * apart, so this one runs the same system four ways:** A today's SDK path — fillTransform, body, writeTransform* B in-place view — accessors onto the bytes, nothing copied@@ -294,7 +294,7 @@ int main() {const bool thick = strEnvIs("BENCH_BODY", "thick");std::printf("================================================================\n");- std::printf("Estella AOT — Stage 0 loop benchmark (REARCH_AOT.md §10)\n");+ std::printf("Estella AOT — Stage 0 loop benchmark\n");std::printf(" interpreter : QuickJS %d.%d.%d (no JIT, on any platform)\n",QJS_VERSION_MAJOR, QJS_VERSION_MINOR, QJS_VERSION_PATCH);std::printf(" entities : %d\n", ENTITIES);@@ -402,7 +402,7 @@ int main() {};runJs("A", "SDK today (fill + body + write-back)", thick ? "variantA_thick" : "variantA");- runJs("B", "in-place view (SDK fix, §12.B)", thick ? "variantB_thick" : "variantB");+ runJs("B", "in-place view (the SDK-side fix)", thick ? "variantB_thick" : "variantB");runJs("B2", "raw indexing (interpreted floor)", thick ? "variantB2_thick" : "variantB2");runNative("C", "native C++ (the AOT ceiling)");@@ -441,14 +441,14 @@ int main() {std::printf("\n where the speedup actually comes from\n");std::printf(" ------------------------------------------------------------\n");- std::printf(" A -> B %6.2fx what a pure SDK change buys (§12.B)\n", sdkFix);+ std::printf(" A -> B %6.2fx what a pure SDK change buys\n", sdkFix);std::printf(" B -> B2 %6.2fx what the accessor layer costs\n", viewCost);std::printf(" B -> C %6.2fx what COMPILING buys <-- the Stage 0 question\n", compiled);std::printf(" A -> C %6.2fx total AOT ceiling\n", total);std::printf(" throughput A %.2f C %.2f M entity-updates/s\n",ENTITIES * (1000.0 / A) / 1e6, ENTITIES * (1000.0 / C) / 1e6);- // REARCH_AOT §10: >= 5x total, and at least half of it must NOT be the copy.+ // The bar: >= 5x total, and at least half of it must NOT be the copy.// "Half" in a ratio is geometric: sqrt(5) on each side.const double NEED_TOTAL = 5.0;const double NEED_COMPILED = 2.2360679775; // sqrt(5)@@ -461,7 +461,7 @@ int main() {std::printf(" B -> C >= %.2fx %6.2fx %s\n", NEED_COMPILED, compiled, passCompiled ? "PASS" : "FAIL");std::printf("\n VERDICT: %s\n", (passTotal && passCompiled)? "GO — compiling buys more than the SDK fix alone. Proceed to Stage 1."- : "STOP — take REARCH_AOT.md §12 instead, starting with B. Re-read the split above.");+ : "STOP — the SDK-side fix (variant B) buys most of it. Re-read the split above.");std::printf("================================================================\n");JS_FreeContext(ctx);diff --git a/bench/aot-stage0/frame-share-rendered.mjs b/bench/aot-stage0/frame-share-rendered.mjsindex 35683298c..32f96d0a0 100644--- a/bench/aot-stage0/frame-share-rendered.mjs+++ b/bench/aot-stage0/frame-share-rendered.mjs@@ -2,7 +2,7 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file frame-share-rendered.mjs- * @brief `c` — the C++ share of a REAL rendered frame (docs/REARCH_AOT.md §14).+ * @brief `c` — the C++ share of a REAL rendered frame.** @details frame-share.mjs runs headless, so the renderer is missing and the TS* share it reports is an upper bound. This drives the pixel-gate host@@ -124,7 +124,7 @@ const c = cpu > 0 ? cpp / cpu : 0;const gpu = median(frames.map((f) => (typeof f.gpuMs === 'number' ? f.gpuMs : -1)));console.log('\n' + '='.repeat(70));-console.log('Estella AOT — `c` from a rendered frame (REARCH_AOT.md §14)');+console.log('Estella AOT — `c` from a rendered frame');console.log(` frames : ${n} recorded, ${result.entityCount} entities, ${result.drawCalls} draw call(s)`);console.log(` runtime : wasm under V8 — see the header for which way that biases c`);console.log('='.repeat(70));@@ -168,7 +168,7 @@ console.log('');console.log(` compiled TS merely matches a JIT ........ ${floorX.toFixed(1)}x <- floor`);console.log(` compiled TS runs at native speed ........ ${ceilX.toFixed(1)}x <- ceiling`);console.log(`- gate (REARCH_AOT §13.4): >= 3x opens Stage 1 -> ${floorX >= 3 ? 'OPEN' : 'HOLD'}`);+ gate: >= 3x opens Stage 1 -> ${floorX >= 3 ? 'OPEN' : 'HOLD'}`);// This scene carries no game logic (VelocitySystem ~0.01 ms — the copies have no// Velocity), so c is at its RENDERING end; headless is the other end at ~4%. Thediff --git a/bench/aot-stage0/frame-share.mjs b/bench/aot-stage0/frame-share.mjsindex 277475687..98de0a5df 100644--- a/bench/aot-stage0/frame-share.mjs+++ b/bench/aot-stage0/frame-share.mjs@@ -2,7 +2,7 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file frame-share.mjs- * @brief Amdahl's denominator for the AOT proposal (docs/REARCH_AOT.md §14).+ * @brief Amdahl's denominator for the AOT proposal.** @details Stage 0 measured that compiling a system LOOP is worth 154-385x* under a no-JIT interpreter. That decides nothing alone: a loop 400x@@ -104,7 +104,7 @@ async function main() {}console.log('='.repeat(70));- console.log("Estella AOT — Amdahl's denominator (REARCH_AOT.md §10, Stage 0 follow-up)");+ console.log("Estella AOT — Amdahl's denominator (Stage 0 follow-up)");console.log(' runtime : node', process.versions.node, '(V8, WITH jit)');console.log(' entities :', ENTITIES);console.log(' frames :', FRAMES, `(+${WARMUP} warmup)`);diff --git a/bench/aot-stage0/variants.js b/bench/aot-stage0/variants.jsindex ee2e5e5f1..34cf79baa 100644--- a/bench/aot-stage0/variants.js+++ b/bench/aot-stage0/variants.js@@ -9,7 +9,7 @@//// A today's SDK path .... fillTransform -> user body -> writeTransform// B in-place view ....... a reused view object whose fields are accessors-// straight onto the component bytes (REARCH_AOT §12.B)+// straight onto the component bytes// B2 raw indexing ........ the interpreted floor: no object layer at all// C native .............. in bench.cpp, the AOT ceiling//@@ -111,7 +111,7 @@ globalThis.variantA = function (dt) {};// ----------------------------------------------------------------------------// B — in-place view (REARCH_AOT §12.B).+// B — in-place view.//// The game author's code is UNCHANGED: still `t.position.x += v.linear.x * dt`.// What changed is that `t.position` is a reused object whose x/y/z are accessorsdiff --git a/compiler/package.json b/compiler/package.jsonindex e12b86ded..614ac48bd 100644--- a/compiler/package.json+++ b/compiler/package.json@@ -3,7 +3,7 @@"version": "0.0.0","private": true,"type": "module",- "description": "Estella AOT — TypeScript to Estella IR (docs/REARCH_AOT.md)",+ "description": "Estella AOT — TypeScript to Estella IR","main": "src/index.ts","scripts": {"test": "vitest run",diff --git a/compiler/src/abi.ts b/compiler/src/abi.tsindex 6553ae720..8c51651d6 100644--- a/compiler/src/abi.ts+++ b/compiler/src/abi.ts@@ -2,7 +2,7 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file abi.ts- * @brief The Estella ABI, as an EirHost (docs/REARCH_AOT_ABI.md).+ * @brief The Estella ABI, as an EirHost.** @details Runs a system with nothing but what SysCtx provides: a packed row* array, resource pointers, a command buffer, and shared linear memory@@ -99,9 +99,9 @@ export class AbiMemory {}/**- * Reset the arena the host refills each call. §2.2 gives row arrays and the- * SysCtx a one-call lifetime, and a region thrown away each time ENFORCES- * that rather than restating it. It grows down from the end of the image+ * Reset the arena the host refills each call. A row array and a SysCtx have+ * a one-call lifetime, and a region thrown away each time ENFORCES that+ * rather than restating it. It grows down from the end of the image* while world data grows up, so an overlap is caught by `alloc`, not silent.*/beginCall(): void {@@ -189,8 +189,8 @@ function store(mem: AbiMemory, at: number, enc: LeafEnc, v: number | boolean): v/*** Which slot of `SysCtx` each of a system's parameters is. The order is the- * declaration order of `_params`, and §2.1 says it is burned into the handshake- * hash — so this function, not a convention, is what both the host and the code+ * declaration order of `_params`, and the manifest is what drives it at run+ * time — so this function, not a convention, is what both the host and the code* generator ask. Two readers of one answer; not two answers.*/export interface SysPlan {@@ -238,7 +238,7 @@ export interface AbiCall {}/**- * The host's half of §2.1: pack the rows, resolve the resource addresses, zero+ * The host's half of the contract: pack the rows, resolve the resources, zero* the count, write the SysCtx. When it returns, linear memory holds everything* the compiled code reads and nothing else it may reach. Rows are materialised* the way `View.hpp` already does — existing strategy, not a second one.@@ -363,7 +363,7 @@ export function runOnAbi(sys: EirSystem, mem: AbiMemory, layout: AbiLayout, fns:}/**- * The §2.5 handshake, as TWO numbers because the fixes differ: `engineAbi` means+ * The handshake, as TWO numbers because the fixes differ: `engineAbi` means* rebuild the module against this engine, `projectShapes` means rebuild the* project. Parameter order is in neither — the manifest DRIVES the layout at run* time, so it is followed rather than compared.diff --git a/compiler/src/builtins.ts b/compiler/src/builtins.tsindex 5fd4b4f7d..cfe8323e1 100644--- a/compiler/src/builtins.ts+++ b/compiler/src/builtins.ts@@ -7,7 +7,7 @@* @details PTR_LAYOUTS is generated from the C++ structs and is what the SDK's* accessors and the ABI hash already agree on. The compiler consumes it* for the same reason: a component's fields must have exactly one- * author (docs/REARCH_AOT.md §1.2).+ * author.** Resources have no such table yet — `Time` is spelled out below and* marked, because a shape with no generator is exactly the drift this@@ -92,7 +92,7 @@ export function resourceNames(): readonly string[] {}/**- * EHT's table, flattened for the §2.5 handshake. It stamps the OFFSETS rather+ * EHT's table, flattened for the handshake. It stamps the OFFSETS rather* than importing `ABI_LAYOUT_HASH`: that constant lives in* `component.generated.ts`, whose imports reach the whole SDK runtime. The raw* table is more information than a hash of it, and changes for the same reason.diff --git a/compiler/src/eir.ts b/compiler/src/eir.tsindex 151b3a576..3bf41a83f 100644--- a/compiler/src/eir.ts+++ b/compiler/src/eir.ts@@ -2,7 +2,7 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file eir.ts- * @brief Estella IR, high level — typed, and ECS-aware (docs/REARCH_AOT.md §4).+ * @brief Estella IR, high level — typed, and ECS-aware.** @details The reason this layer exists rather than lowering the TS AST straight* to LLVM: by LLVM IR a query is an opaque call, and the optimisations@@ -75,7 +75,7 @@ export type Expr =| { readonly e: 'call'; readonly target: CallTarget; readonly args: readonly Expr[]; readonly type: EirType };export type CallTarget =- /** Only the exactly-specified Math operations (§3.3). */+ /** Only the Math operations ECMAScript specifies exactly. */| { readonly k: 'math'; readonly fn: MathFn }| { readonly k: 'fn'; readonly name: string };diff --git a/compiler/src/frontend.ts b/compiler/src/frontend.tsindex 57dd401c8..62707fc89 100644--- a/compiler/src/frontend.ts+++ b/compiler/src/frontend.ts@@ -2,7 +2,7 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file frontend.ts- * @brief TypeScript AST -> EIR-high (docs/REARCH_AOT.md §4.1, §3.3).+ * @brief TypeScript AST -> EIR-high.** @details Uses the real `typescript` program and checker. Re-implementing TS* inference is the one decision that would sink this project.@@ -21,8 +21,8 @@** Nothing here throws on code it cannot handle. Anything outside the* subset produces a Diagnostic naming the line and the reason, and its- * system is simply not compiled — §3.2's no-cliff rule, which is what- * lets this ship before it is finished.+ * system is simply not compiled. Falling back rather than failing is+ * what lets this ship before it is finished.*/import { sep } from 'node:path';import ts from 'typescript';@@ -85,7 +85,8 @@ function marksCompiled(node: ts.Node): boolean {/*** The promises this program did not keep: every marked system that refused, plus* any that vanished without a diagnostic. A build fails on this list; an unmarked- * refusal stays a note, because §3.2's fallback is a design and not a defect.+ * refusal stays a note, because falling back to the interpreter is a design+ * and not a defect.*/export function brokenPromises(result: LowerResult): readonly Diagnostic[] {const compiled = new Set(result.module.systems.map((s) => s.name));@@ -177,7 +178,7 @@ function annotatedType(node: ts.TypeNode): EirType | null {}/**- * `permanent` = the contract has no place for it (REARCH_AOT_ABI.md §4), not a+ * `permanent` = the contract has no place for it, not a* todo. `pending` = the contract admits it, nobody lowered it yet. Default is* `pending`; every `permanent` below names what is missing.*/@@ -590,8 +591,8 @@ class SystemLowerer {}if (!ts.isPropertyAccessExpression(callee) || !ts.isIdentifier(callee.expression)|| callee.expression.text !== 'Math') {- // A method on a RESOURCE is pending: §2.3 says a service should be- // memory, so `input.isKeyDown('KeyW')` is a bit at a known offset.+ // A method on a RESOURCE is pending: a service is meant to be read+ // as memory, so `input.isKeyDown('KeyW')` is a bit at a known offset.// On anything else it needs an object model, which there is none of.const recv = ts.isPropertyAccessExpression(callee) && ts.isIdentifier(callee.expression)? this.tryLookup(callee.expression.text)@@ -680,7 +681,7 @@ class SystemLowerer {return { e: 'read', place: this.place(node), type: this.placeType(node) };}// String, array, object, new, await: each needs a heap, and the contract- // has no allocation (docs/REARCH_AOT_ABI.md §3).+ // has no allocation.throw new NotInSubset(node, `${ts.SyntaxKind[node.kind]} is not an expression this subset lowers`, 'permanent');}}diff --git a/compiler/src/inline.ts b/compiler/src/inline.tsindex 51959d4d7..3d1f36f83 100644--- a/compiler/src/inline.ts+++ b/compiler/src/inline.ts@@ -5,8 +5,8 @@* @brief The first EIR -> EIR pass: calls to pure functions become their bodies.** @details A helper called once per row must not still be a call by the time the- * backend sees it — §4.2's optimisations need the body visible, and a- * call boundary hides it.+ * backend sees it — copy elimination and archetype specialisation need+ * the body visible, and a call boundary hides it.** It is a PASS, not something the frontend does, and that is the point.* The frontend lowers faithfully; every optimisation after it is andiff --git a/compiler/src/interp.ts b/compiler/src/interp.tsindex 12f14b8e7..e5f841dd9 100644--- a/compiler/src/interp.ts+++ b/compiler/src/interp.ts@@ -2,7 +2,7 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file interp.ts- * @brief A reference interpreter for EIR-high (docs/REARCH_AOT.md §8.1).+ * @brief A reference interpreter for EIR-high.** @details Written before any code generation, for two reasons. It proves the IR* means something on its own, and it is the third implementation adiff --git a/compiler/src/verify.ts b/compiler/src/verify.tsindex ee363f8b8..98a82d584 100644--- a/compiler/src/verify.ts+++ b/compiler/src/verify.ts@@ -4,10 +4,9 @@* @file verify.ts* @brief Re-prove an EIR system's types, without looking at the TypeScript.*- * @details docs/REARCH_AOT.md §4.1 asks for this because tsc's types are not- * sound — structural typing, method bivariance and `any` leak through- * generics — so a pass has to prove, on the IR, that every value is the- * type it claims.+ * @details tsc's types are not sound — structural typing, method bivariance and+ * `any` all leak through generics — so a pass has to prove, on the IR,+ * that every value is the type it claims.** It reads only EIR, never the AST. That is the point: re-running the* frontend's own reasoning would agree with the frontend's own bugs,diff --git a/compiler/tests/abi.test.ts b/compiler/tests/abi.test.tsindex e8e08d72e..6c8d01a49 100644--- a/compiler/tests/abi.test.ts+++ b/compiler/tests/abi.test.ts@@ -2,7 +2,7 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file abi.test.ts- * @brief Is the ABI SUFFICIENT? (docs/REARCH_AOT_ABI.md)+ * @brief Is the ABI SUFFICIENT?** @details The same interpreter runs the same system twice: once over JS objects* and once over flat memory reached only through what SysCtx carries.@@ -161,6 +161,6 @@ describe('the ABI is sufficient for the systems the subset compiles', () => {});// "Zero calls into the engine" is not asserted here: it is a property of the- // shipped artifact (an empty wasm import section) that the build checks,- // per docs/REARCH_AOT_ABI.md §6.5.+ // shipped artifact — an empty wasm import section — and wasm.test.ts asks it+ // of the artifact itself.});diff --git a/compiler/tests/commands.test.ts b/compiler/tests/commands.test.tsindex 861663d29..c2f4d57d3 100644--- a/compiler/tests/commands.test.ts+++ b/compiler/tests/commands.test.ts@@ -2,7 +2,7 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file commands.test.ts- * @brief A per-frame system that despawns, run both ways (§8.2).+ * @brief A per-frame system that despawns, run both ways.** @details The oracle is examples/ecs-basics/src/systems/lifetime.ts — a real* per-frame Commands user, which is the shape AOT is for. Most of thediff --git a/compiler/tests/conformance.test.ts b/compiler/tests/conformance.test.tsindex 3215b777f..782d6826a 100644--- a/compiler/tests/conformance.test.ts+++ b/compiler/tests/conformance.test.ts@@ -2,7 +2,7 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file conformance.test.ts- * @brief Every subset feature run BOTH ways and compared (§8.2).+ * @brief Every subset feature run BOTH ways and compared.** @details move-system.test.ts covers the one shape a shipped system happens to* use. This covers what the subset gained after it — locals, if /diff --git a/compiler/tests/coverage.test.ts b/compiler/tests/coverage.test.tsindex 9ae8adf34..62e375e7d 100644--- a/compiler/tests/coverage.test.ts+++ b/compiler/tests/coverage.test.ts@@ -4,8 +4,8 @@* @file coverage.test.ts* @brief How much of the shipped corpus compiles — a number that may only rise.*- * @details §8.2's coverage gate. Without it the subset can quietly stop growing,- * or shrink under a refactor, and nothing says so: every other test here+ * @details Without this the subset can quietly stop growing, or shrink under a+ * refactor, and nothing says so: every other test here* passes just as well on a compiler that lowers one system.** It counts PER-FRAME systems. A startup system runs once, so compilingdiff --git a/compiler/tests/fixtures/dynamic-component.ts b/compiler/tests/fixtures/dynamic-component.tsindex 034d022d0..067a3e42b 100644--- a/compiler/tests/fixtures/dynamic-component.ts+++ b/compiler/tests/fixtures/dynamic-component.ts@@ -4,8 +4,8 @@* @file dynamic-component.ts* @brief A defineComponent whose shape is not a literal.*- * @details §3.3 makes it an intrinsic, so a shape the compiler cannot read at- * compile time is a fallback, not a guess.+ * @details `defineComponent` is an intrinsic, so a shape the compiler cannot+ * read at compile time is a fallback, not a guess.*/import { defineComponent } from 'esengine';diff --git a/compiler/tests/fixtures/outside-subset.ts b/compiler/tests/fixtures/outside-subset.tsindex 5e40c2106..69eb7f280 100644--- a/compiler/tests/fixtures/outside-subset.ts+++ b/compiler/tests/fixtures/outside-subset.ts@@ -4,7 +4,7 @@* @file outside-subset.ts* @brief Systems that must NOT compile.*- * @details Each names a rule from REARCH_AOT §3; subset.test.ts asserts the+ * @details Each names one rule of the subset; subset.test.ts asserts the* diagnostic points at the line and says why.*/import { defineComponent, defineSystem, Query, Mut, Res, Camera, Time, Transform } from 'esengine';diff --git a/compiler/tests/move-system.test.ts b/compiler/tests/move-system.test.tsindex 309eb2494..a12bc1418 100644--- a/compiler/tests/move-system.test.ts+++ b/compiler/tests/move-system.test.ts@@ -2,7 +2,7 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file move-system.test.ts- * @brief Stage 1's exit criterion, end to end (docs/REARCH_AOT.md §10).+ * @brief A shipped system, lowered and run — end to end.** @details Takes a real system out of examples/, lowers it to EIR, and holds* the interpreter's result against node's.diff --git a/compiler/tests/subset.test.ts b/compiler/tests/subset.test.tsindex cdac60f82..9b3ec0047 100644--- a/compiler/tests/subset.test.ts+++ b/compiler/tests/subset.test.ts@@ -4,9 +4,9 @@* @file subset.test.ts* @brief What the subset must REFUSE, and how it says so.*- * @details A checker that accepts everything is not a checker. Each case pins a- * rule from §3 and asserts the refusal names a line and a reason —- * §11's "coverage stalls low" is a diagnostics problem first.+ * @details A checker that accepts everything is not a checker. Each case pins+ * one rule of the subset and asserts the refusal names a line and a+ * reason — coverage that stalls low is a diagnostics problem first.*/import { describe, it, expect } from 'vitest';import { resolve } from 'node:path';@@ -72,7 +72,7 @@ describe('the subset refuses, and says why', () => {/*** `@compiled` does not change what the subset takes; it changes who has to act.- * An unmarked refusal is §3.2's design. A marked one is a build error.+ * An unmarked refusal is the design. A marked one is a build error.*/describe('a promise the author wrote down', () => {it('sees the marker, and only where it was written', () => {diff --git a/docs/CODE_COMMENTS.md b/docs/CODE_COMMENTS.mdindex f8585367d..d5bccee64 100644--- a/docs/CODE_COMMENTS.md+++ b/docs/CODE_COMMENTS.md@@ -15,7 +15,8 @@- **不留注释掉的死代码** —— 删就删(git 记得住)。- **不留"墓碑"注释。** 删/移代码时**不要**再加一句注释说明"某某被删除了/移到哪了/曾经是什么"(如 `// (X was removed ...)`)——git 历史记得住,这种注释只会变噪音 + 过时信息。直接删干净。- **自包含**:注释把"为什么"直接讲清楚,**能独立看懂**。-- **不要在注释里写内部/临时的流程代号**(审计编号如 `A20`、工单号、私有缩写)——代码读者查不到、而且会过时(那些文档常常根本没进仓库)。确需指向长期存在的**已提交**文档时,写**真实路径**,如 `docs/REARCH_EDITOR_REALM.md`;`file.ts:123` 这种可定位的引用可以。+- **不要在注释里写内部/临时的流程代号**(审计编号如 `A20`、工单号、章节号如 `§4.2`、私有缩写)——代码读者查不到、而且会过时。+- **不要引用读者打不开的文档。** 指向文档时那份文档必须是**仓库里已提交的文件**(`docs/CODE_COMMENTS.md`、`README.md` 这类);`docs/REARCH_*.md` 全都在 `.gitignore` 里,指向它们等于指向别人机器上的文件。注释要**自己把话说完**:把章节里那句判断直接写下来,而不是让读者去取一份他没有的文档。`file.ts:123` 这种可定位的引用可以。由 `tools/check-comment-style.mjs` 的 `unreachable-doc` 规则按 git 索引判,只看新增行。## 1. 文件头 `@file` / `@brief`@@ -117,4 +118,4 @@ i++;- [ ] 新增/改动的导出 API 有 `/** */`,且讲的是 why/契约而非签名?- [ ] 内联注释解释的是"为什么",没有复述代码?- [ ] 没有注释掉的死代码、没有裸 TODO?-- [ ] 注释**自包含**,没有内部流程代号(如 `audit A20`、工单号)?指向文档时用的是已提交文件的真实路径?+- [ ] 注释**自包含**,没有内部流程代号(如 `audit A20`、工单号、`§4.2`)?指向文档时那份文档确实已提交?diff --git a/examples/ecs-basics/src/systems/move.ts b/examples/ecs-basics/src/systems/move.tsindex 2b87f63d7..d05b7972f 100644--- a/examples/ecs-basics/src/systems/move.ts+++ b/examples/ecs-basics/src/systems/move.ts@@ -8,7 +8,7 @@ import { Mover } from '../components';** @compiled* A promise, not a hint: anything the subset cannot lower is a build error here- * rather than a silent fall back to the interpreter (REARCH_AOT_ABI.md §4.1).+ * rather than a silent fall back to the interpreter.*/export const moveSystem = defineSystem([Query(Mut(Transform), Mover), Res(Time)],diff --git a/pipeline/src/bundle/buildScripts.ts b/pipeline/src/bundle/buildScripts.tsindex a95d6d239..68a549a49 100644--- a/pipeline/src/bundle/buildScripts.ts+++ b/pipeline/src/bundle/buildScripts.ts@@ -1,7 +1,7 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/**- * @file Project-script bundler (REARCH_EDITOR_REALM.md Phase P1 / RC12 §E8-1).+ * @file Project-script bundler.** Bundles a project's `src/main.ts` into a single ESM with `esengine` left* EXTERNAL, written to `.esengine/cache/`. The bundle's bare `import ... fromdiff --git a/sdk/src/ecs/ScriptPool.ts b/sdk/src/ecs/ScriptPool.tsindex b7de8315c..5e722a1fd 100644--- a/sdk/src/ecs/ScriptPool.ts+++ b/sdk/src/ecs/ScriptPool.ts@@ -31,7 +31,7 @@ export interface PoolField {readonly kind: PoolKind;}-/** One f64 per field: what the ABI gives a host record (REARCH_AOT_ABI §2.4). */+/** One f64 per field: what the ABI gives a host record. */export const POOL_SLOT_BYTES = 8;/** A byte range the pool was given, and where it starts in the host's memory. */@@ -131,7 +131,7 @@ export class ScriptPool {* a constant stride, and a sparse table saying which slot an entity is in.* Every address is in the memory the pool allocated from.*- * Valid until the next growth, which is per call anyway (§2.2).+ * Valid until the next growth, which is per call anyway.*/span(): { rows: number; stride: number; sparse: number; sparseCount: number } {return {@@ -191,7 +191,7 @@ export class ScriptPool {* The address a host hands to compiled code: the row's offset in the memory* the pool allocated from, not in the pool's own view. The two differ by* `byteOffset` once the rows are carved out of a larger block. Valid until- * the next growth, which §2.2 requires anyway.+ * the next growth, which a one-call lifetime requires anyway.*/address(entity: Entity): number | undefined {const base = this.baseOf(entity);diff --git a/sdk/src/ecs/ScriptStorage.ts b/sdk/src/ecs/ScriptStorage.tsindex ac8329f59..3d5daad54 100644--- a/sdk/src/ecs/ScriptStorage.ts+++ b/sdk/src/ecs/ScriptStorage.ts@@ -24,7 +24,7 @@ export class ScriptStorage {* Components held as rows rather than objects, by id. A component qualifies* when its defaults are all scalars, which is exactly the set a compiled* system can reach — a compiled system addresses a component, and a JS- * object has no address (docs/REARCH_AOT_ABI.md §2.4).+ * object has no address.*/private pools_ = new Map<symbol, ScriptPool>();private poolMemory_: PoolMemory = HEAP_MEMORY;diff --git a/sdk/src/ecs/aot/AotContext.ts b/sdk/src/ecs/aot/AotContext.tsindex 4a907de61..e2569243b 100644--- a/sdk/src/ecs/aot/AotContext.ts+++ b/sdk/src/ecs/aot/AotContext.ts@@ -4,9 +4,8 @@* @file AotContext.ts* @brief The host half of the ABI, in the language that owns the maps.*- * @details docs/REARCH_AOT_ABI.md §2.1 gives the host four jobs: pack the rows,- * resolve the resource addresses, ready the command buffer, and fill a- * SysCtx. On web that host is TypeScript rather than C++, and not by+ * @details The ABI gives the host four jobs: pack the rows, resolve the resource+ * addresses, ready the command buffer, and fill a SysCtx. On web that host is TypeScript rather than C++, and not by* preference — the query's candidate set and the script pools' slot* maps are both here, so anything else would have to call back across* the boundary once per entity per frame, which is the cost AOT exists@@ -14,8 +13,8 @@** Everything it writes goes into the ENGINE's linear memory, because* that is where the compiled code reads. The arena is rebuilt per call:- * §2.2 gives a row array a one-call lifetime, and reusing the block- * rather than the contents is what keeps that free.+ * a row array has a one-call lifetime, and reusing the block rather+ * than the contents is what keeps that free.*/import type { PoolBlock, PoolMemory } from '../ScriptPool';@@ -28,7 +27,7 @@ export {SYSCTX_WORDS, QUERYROWS_WORDS, CMD_WORDS, CMD_DESPAWN, CMD_REMOVE,} from './abiDigest';-/** One record the compiled code appended (§2.3). */+/** One record the compiled code appended. */export interface AotCommand {readonly kind: number;readonly a: number;@@ -37,7 +36,7 @@ export interface AotCommand {/*** The per-call scratch, in engine memory. One instance per system is enough —- * a call is over before the next begins, and §2.2 says nothing may outlive it.+ * a call is over before the next begins, and nothing may outlive it.*/export class AotContext {private block: PoolBlock | null = null;diff --git a/sdk/src/ecs/aot/AotRuntime.ts b/sdk/src/ecs/aot/AotRuntime.tsindex fd4c8d3dc..78272e994 100644--- a/sdk/src/ecs/aot/AotRuntime.ts+++ b/sdk/src/ecs/aot/AotRuntime.ts@@ -33,8 +33,7 @@ export interface AotAddresses {/*** Installed by a shipping build, absent everywhere else. That absence is the* whole of the mode policy: with no twins there is nothing to dispatch to, so- * the editor and dev builds need no flag and take no branch worth measuring- * (docs/REARCH_AOT.md §9).+ * the editor and dev builds need no flag and take no branch worth measuring.*/export interface AotRuntime {readonly systems: AotSystems;diff --git a/sdk/src/ecs/aot/AotSystems.ts b/sdk/src/ecs/aot/AotSystems.tsindex 9c1ab7e3a..dc38f9a47 100644--- a/sdk/src/ecs/aot/AotSystems.ts+++ b/sdk/src/ecs/aot/AotSystems.ts@@ -4,12 +4,12 @@* @file AotSystems.ts* @brief The compiled twins a build produced, and how a system finds its own.*- * @details `REARCH_AOT.md` §9 settles when a twin is used: the editor's preview- * always interprets, and AOT is a shipping mode. So the runner has one- * rule — call the twin if there IS one — and the decision lives in who+ * @details When a twin is used is settled: the editor's preview always+ * interprets, and AOT is a shipping mode. So the runner has one rule —+ * call the twin if there IS one — and the decision lives in who* installs, which is the build, once, at load.*- * Installing verifies the handshake first (§2.5). A module whose+ * Installing verifies the handshake first. A module whose* contract hash disagrees is REFUSED, not warned about: mismatched* offsets do not produce an error, they produce a read of a different* field.diff --git a/sdk/src/ecs/aot/abiDigest.ts b/sdk/src/ecs/aot/abiDigest.tsindex 7a336070d..5eb8db462 100644--- a/sdk/src/ecs/aot/abiDigest.ts+++ b/sdk/src/ecs/aot/abiDigest.ts@@ -30,7 +30,7 @@import { PTR_LAYOUTS } from '../../wasm/ptrLayouts.generated';import { RESOURCE_SHAPES } from '../resourceShapes';-/** Sizes of the three ABI structs, in address-wide words (§2.1–2.3). */+/** Sizes of the three ABI structs, in address-wide words. */export const SYSCTX_WORDS = 6;export const QUERYROWS_WORDS = 2;/** A command is four u32 at every address width. */diff --git a/sdk/src/ecs/aot/installAot.ts b/sdk/src/ecs/aot/installAot.tsindex 3c315f457..ab4b364bf 100644--- a/sdk/src/ecs/aot/installAot.ts+++ b/sdk/src/ecs/aot/installAot.ts@@ -10,8 +10,8 @@* wiring that was waiting for the handshake to be decided.** The module IMPORTS the engine's memory, so there is nothing to link- * and no engine change: it reads the components where they already are- * (docs/REARCH_AOT.md §6.1).+ * and no engine change: it reads the components where they already+ * are.** Refuses rather than degrades. A module built for other offsets does* not produce a wrong answer, it produces a read of a different field,diff --git a/sdk/src/ecs/bridge/BuiltinBridge.ts b/sdk/src/ecs/bridge/BuiltinBridge.tsindex 08f3479af..160acfc4c 100644--- a/sdk/src/ecs/bridge/BuiltinBridge.ts+++ b/sdk/src/ecs/bridge/BuiltinBridge.ts@@ -683,7 +683,7 @@ export class BuiltinBridge {/*** Where `cppName`'s bytes are for an entity: what compiled code adds an EHT- * offset to (§2.4). Through the {@link MemoryProvider}, the seam the fast+ * offset to. Through the {@link MemoryProvider}, the seam the fast* accessors already use — an address resolved a second way can disagree.* Null where this backend serves no flat memory.*/diff --git a/sdk/src/ecs/component.ts b/sdk/src/ecs/component.tsindex eb989080e..0e8170ff5 100644--- a/sdk/src/ecs/component.ts+++ b/sdk/src/ecs/component.ts@@ -283,7 +283,7 @@ function classifyKeys(obj: object): { flatKeys: string[]; objectKeys: string[];// component storage instead of minting a fresh identity that silently misses every// existing entity. Component DATA stays isolated per-App at the World/storage layer,// not at the id, so sharing ids by name across contexts is safe — the same reason-// builtins share one global id across every App. See docs/REARCH_HOT_RELOAD.md §3.+// builtins share one global id across every App.const componentIdRegistry = new Map<string, symbol>();function componentId(name: string): symbol {let id = componentIdRegistry.get(name);diff --git a/sdk/src/ecs/resourceShapes.ts b/sdk/src/ecs/resourceShapes.tsindex 6f6023072..16ad3b392 100644--- a/sdk/src/ecs/resourceShapes.ts+++ b/sdk/src/ecs/resourceShapes.ts@@ -7,7 +7,7 @@* @details A compiled system reaches a resource by ADDRESS, so its fields need a* layout, and a layout needs exactly one author. This is that author:* `resource.ts` builds the resource from it, and the AOT compiler reads- * it for the offsets (docs/REARCH_AOT_ABI.md §2.4).+ * it for the offsets.** A resource belongs here when every field is a number or a boolean —* the same bar `defineComponent` shapes meet, and for the same reason:diff --git a/sdk/src/ecs/system.ts b/sdk/src/ecs/system.tsindex 2c12ff0c1..181ff281a 100644--- a/sdk/src/ecs/system.ts+++ b/sdk/src/ecs/system.ts@@ -408,7 +408,7 @@ export class SystemRunner {/*** Compiled twins, when a shipping build installed them. Absent in the editor* and in dev, which is the whole of the mode policy — with nothing installed- * there is nothing to dispatch to (docs/REARCH_AOT.md §9).+ * there is nothing to dispatch to.*/private aot_: AotRuntime | null = null;/** The compiled half of this runner: everything a twin needs around its calldiff --git a/sdk/src/ecs/world.ts b/sdk/src/ecs/world.tsindex 954a77795..f97535a98 100644--- a/sdk/src/ecs/world.ts+++ b/sdk/src/ecs/world.ts@@ -1168,7 +1168,7 @@ export class World {/*** @internal Where script-component rows are allocated from. A wasm runtime* installs linear memory here BEFORE any component is added, because- * compiled code cannot reach a JS-heap array (docs/REARCH_AOT_ABI.md §2.4).+ * compiled code cannot reach a JS-heap array.*/useScriptPoolMemory(memory: PoolMemory): void {this.scripts_.usePoolMemory(memory);diff --git a/src/esengine/aot/AotHost.hpp b/src/esengine/aot/AotHost.hppindex 19bfafff3..bf3633b90 100644--- a/src/esengine/aot/AotHost.hpp+++ b/src/esengine/aot/AotHost.hpp@@ -2,7 +2,7 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file AotHost.hpp- * @brief The host half of the Estella ABI (docs/REARCH_AOT_ABI.md §2.1).+ * @brief The host half of the Estella ABI.** @details A compiled system calls the engine ZERO times, which means everything* it reads has to be in memory before the call. This puts it there:@@ -15,8 +15,8 @@* without linking the engine.** The arena is reused across calls and rebuilt in each one, because- * §2.2 gives a row array a one-call lifetime. Nothing here allocates- * per row after the first frame at a given size.+ * a row array has a one-call lifetime. Nothing here allocates per row+ * after the first frame at a given size.*/#pragma once@@ -173,8 +173,8 @@ struct BoundSystem {/*** Resolve `decl` against this host. A component or resource the host cannot- * name leaves `fn` null: the system is simply not run, which is §3.2's fallback- * arriving one layer down rather than a crash at the first row.+ * name leaves `fn` null: the system is simply not run, which is the interpreter+ * fallback arriving one layer down rather than a crash at the first row.*/inline BoundSystem bind(const EsSystemDecl& decl,const ComponentLookup& components,@@ -212,7 +212,7 @@ inline std::span<const EsCmd> runBound(const BoundSystem& bound,/*** The constant a compiled artifact exports, as this host computes it. The* contract half comes from the artifact; the width is ours, and mixing it here- * is what stops a 32-bit artifact loading into a 64-bit host (§2.5).+ * is what stops a 32-bit artifact loading into a 64-bit host.*/inline std::uint64_t abiHash(std::uint64_t contract) {return contract ^ (0x9e3779b97f4a7c15ULL * sizeof(es_addr_t));diff --git a/src/esengine/aot/estella_abi.h b/src/esengine/aot/estella_abi.hindex ca92c3de5..04d6a0aa0 100644--- a/src/esengine/aot/estella_abi.h+++ b/src/esengine/aot/estella_abi.h@@ -1,5 +1,5 @@/* GENERATED by @estella/compiler — do not edit. */-/* The Estella ABI, C side. docs/REARCH_AOT_ABI.md */+/* The Estella ABI, C side. */#ifndef ESTELLA_ABI_H#define ESTELLA_ABI_H@@ -21,7 +21,7 @@mixed into the handshake so a 32-bit artifact cannot load into a 64-bit host.ES_ADDR_BASE is the other model: a host that owns one block and addresses it- by offset. A wasm2c deployment (§5) is one, and so is the differential+ by offset. A wasm2c deployment is one, and so is the differentialharness. Same structs, same offsets, one word wider or narrower. */#if defined(ES_ADDR_BASE)typedef uint32_t es_addr_t;@@ -32,14 +32,14 @@ typedef uintptr_t es_addr_t;#define ES_PTR(a) ((unsigned char *)(a))#endif-/* §2.2 — the packed rows the host materialised: for each row, the entity and+/* The packed rows the host materialised: for each row, the entity andthen one base address per component the query named, in that order. */typedef struct EsQueryRows {es_addr_t rows;es_addr_t count;} EsQueryRows;-/* §2.3 — four u32, sixteen bytes, at every address width. */+/* A command: four u32, sixteen bytes, at every address width. */typedef struct EsCmd {uint32_t kind;uint32_t a;@@ -50,7 +50,7 @@ typedef struct EsCmd {#define ES_CMD_DESPAWN 1u#define ES_CMD_REMOVE 2u-/* §2.1 — 6 addresses. §6.3 makes that a number needing a reason to grow. */+/* 6 addresses, and a number that needs a reason to grow. */typedef struct EsSysCtx {es_addr_t queries;es_addr_t resources;@@ -60,7 +60,7 @@ typedef struct EsSysCtx {es_addr_t events;} EsSysCtx;-/* §6: what a host needs in order to CALL a system without glue written by hand.+/* What a host needs in order to CALL a system without glue written by hand.The compiler knows a system's queries and resources -- that is what _paramsis -- so it says so here rather than leaving each host to be told twice. */typedef struct EsQueryDecl {@@ -78,8 +78,8 @@ typedef struct EsSystemDecl {uint32_t resourceCount;} EsSystemDecl;-/* §6.1 asks that the C and TS sides of these structs have ONE author, and that a- hand-written side fail to compile. The numbers below are written by that author+/* The C and TS sides of these structs have ONE author, and a side that drifts+ from it must fail to compile. The numbers below are written by that author(compiler/src/abi.ts) into this file; these three declarations are how C saysno if a struct above ever stops matching them. */typedef char es_check_sysctx[sizeof(EsSysCtx) == 6 * sizeof(es_addr_t) ? 1 : -1];diff --git a/tests/aot/test_aot_host.cpp b/tests/aot/test_aot_host.cppindex 18de7e237..2c0bba32e 100644--- a/tests/aot/test_aot_host.cpp+++ b/tests/aot/test_aot_host.cpp@@ -209,8 +209,8 @@ TEST_CASE("a system naming something this host cannot is simply not bound") {World w = makeWorld();const EsSystemDecl* decl = declOf("MoveSystem");REQUIRE(decl != nullptr);- // §3.2's fallback, one layer down: a host missing a component does not get- // a system that reads null, it gets no system.+ // The interpreter fallback, one layer down: a host missing a component does+ // not get a system that reads null, it gets no system.const aot::BoundSystem none = aot::bind(*decl, [](const char*) { return aot::ComponentAt{}; }, resourcesOf(w));CHECK(none.fn == nullptr);diff --git a/tools/check-comment-style.mjs b/tools/check-comment-style.mjsindex 242575115..016de420f 100644--- a/tools/check-comment-style.mjs+++ b/tools/check-comment-style.mjs@@ -47,8 +47,45 @@ const RULES = [test: /\b(RC\d+|P[0-3]\b|Phase \d|Batch [A-Z]\b|gap \d|audit [A-Z]\d)/,say: 'internal stage/roadmap codename — name the thing, not the plan it came from',},+ {+ id: 'unreachable-doc',+ // A pointer the reader cannot follow: a section sign is a codename wearing a+ // number, and an uncommitted markdown path names a file on somebody else's+ // disk — which the gitignored design docs here have always been.+ test: (text) => /§/.test(text) || docRefs(text).some((d) => !isTracked(d)),+ say: 'points at something the reader cannot open — say what it says, or cite a committed path',+ },];+/** Markdown paths named in a comment, as written. */+function docRefs(text) {+ return [...text.matchAll(/[\w./-]+\.md\b/g)].map((m) => m[0]);+}++/**+ * Every path git has, plus their basenames, because a comment cites a document+ * by bare filename as often as by its full path and both mean one file. Empty+ * means the question could not be asked, and a scan that cannot ask must not+ * answer green.+ */+const TRACKED = (() => {+ let out = '';+ try {+ out = execFileSync('git', ['ls-files'], { cwd: ROOT, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });+ } catch { /* reported below */ }+ const files = out.split('\n').filter(Boolean);+ if (files.length === 0) {+ console.error('check-comment-style: `git ls-files` gave nothing — cannot judge doc references.');+ process.exit(2);+ }+ return new Set([...files, ...files.map((f) => f.slice(f.lastIndexOf('/') + 1))]);+})();++function isTracked(ref) {+ const clean = ref.replace(/^\.\//, '');+ return TRACKED.has(clean) || TRACKED.has(clean.slice(clean.lastIndexOf('/') + 1));+}+/** Added lines per file, as [lineNumber, text]. */function addedLines() {let base = '';@@ -173,7 +210,8 @@ function scan(byFile) {block.push([n, text]);prev = n;for (const rule of RULES) {- if (rule.test.test(text)) findings.push({ file, line: n, id: rule.id, say: rule.say, text: text.trim() });+ const hit = typeof rule.test === 'function' ? rule.test(text) : rule.test.test(text);+ if (hit) findings.push({ file, line: n, id: rule.id, say: rule.say, text: text.trim() });}}flushBlock();diff --git a/tools/check-pipeline-boundary.mjs b/tools/check-pipeline-boundary.mjsindex f091bde81..0bfddbc2f 100644--- a/tools/check-pipeline-boundary.mjs+++ b/tools/check-pipeline-boundary.mjs@@ -26,7 +26,7 @@ const SOURCE = /\.(ts|mts|js|mjs)$/;/** Repo areas the pipeline is allowed to read: the engine it packages, the* format writers it packages with, and the AOT compiler — which is a thing that* BUILDS a project, the same category as build-tools, not a thing that edits- * one (docs/REARCH_AOT.md Stage 4). */+ * one. */const REACHABLE = ['sdk/src', 'build-tools', 'tools', 'compiler/src'];/** Packages that only exist inside a running editor. */diff --git a/tools/gates.mjs b/tools/gates.mjsindex cb0cd97b0..938ca5e84 100644--- a/tools/gates.mjs+++ b/tools/gates.mjs@@ -82,7 +82,7 @@ export const GATES = [// until the editor split, where a checkout without the editor ran none of them.{ id: 'engine-tests', run: 'pnpm run test' },// The AOT compiler carries its own oracle: a real example system lowered to- // EIR must move a world exactly the way node moves it (docs/REARCH_AOT.md §8.1).+ // EIR must move a world exactly the way node moves it.// It also compiles the emitted C and requires the same bytes back: natively// with any C compiler, and as wasm where emsdk is unpacked. Without either it// still passes and PRINTS that the differential did not run — read the log.