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
docs: code comments are self-contained — drop internal audit IDs
esengine4e9dfe1a080b
diff --git a/docs/CODE_COMMENTS.md b/docs/CODE_COMMENTS.mdindex 07de5c07a..77624ce5e 100644--- a/docs/CODE_COMMENTS.md+++ b/docs/CODE_COMMENTS.md@@ -12,7 +12,8 @@- **解释 why,不复述 what。** 注释讲"为什么这么写 / 不变量 / 陷阱 / 契约",不要把代码再用英文念一遍。- **简洁、现在时、完整句子,首字母大写。**- **不留注释掉的死代码** —— 删就删(git 记得住)。-- **带出处**:引用审计/设计依据时给标识,如 `audit A17`、`RC12 §E8`、`sceneManager.ts:264`。+- **自包含**:注释把"为什么"直接讲清楚,**能独立看懂**。+- **不要在注释里写内部/临时的流程代号**(审计编号如 `A20`、工单号、私有缩写)——代码读者查不到、而且会过时(那些文档常常根本没进仓库)。确需指向长期存在的**已提交**文档时,写**真实路径**,如 `docs/REARCH_EDITOR_REALM.md`;`file.ts:123` 这种可定位的引用可以。## 1. 文件头 `@file` / `@brief`@@ -56,10 +57,16 @@```ts// The loader keeps running even when the deadline wins the race; release-// whatever it produces so a post-deadline GL texture doesn't leak (audit A17).+// whatever it produces so a post-deadline GL texture doesn't leak.clearTimeout(timer);```+反例(**禁止**,注释里塞内部审计代号,读者无从查起):++```ts+// Release it instead of leaking it (audit A20). // ❌ "A20" 是什么?+```+反例(**禁止**,复述代码):```ts@@ -79,10 +86,10 @@ i++;## 5. TODO / FIXME-带上下文或标识,不留裸 `// TODO`:+说清"要做什么 / 为什么",不留裸 `// TODO`,也不要塞内部代号:```ts-// TODO(audit A15c): guard stride_ === 0 before the divide.+// TODO: guard against stride_ === 0 before the divide (lost-context path).```## 6. C++ 特例@@ -108,4 +115,4 @@ i++;- [ ] 新增/改动的导出 API 有 `/** */`,且讲的是 why/契约而非签名?- [ ] 内联注释解释的是"为什么",没有复述代码?- [ ] 没有注释掉的死代码、没有裸 TODO?-- [ ] 引用审计/设计点时带了标识(`audit A17` / `RC12 §E8` / `file:line`)?+- [ ] 注释**自包含**,没有内部流程代号(如 `audit A20`、工单号)?指向文档时用的是已提交文件的真实路径?diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.tsindex ac8ccd987..70379ca33 100644--- a/sdk/src/asset/Assets.ts+++ b/sdk/src/asset/Assets.ts@@ -141,7 +141,7 @@ export class Assets {private textureCache_ = new AsyncCache<TextureResult>((result) => {// A texture whose load finished after its getOrLoad timed out has no- // owner; release its GL handle so it doesn't leak VRAM (audit A17).+ // owner; release its GL handle so it doesn't leak VRAM.requireResourceManager().releaseTexture(result.handle);});private textureRefCounts_ = new Map<string, number>();diff --git a/sdk/src/asset/AsyncCache.ts b/sdk/src/asset/AsyncCache.tsindex d6a5b1440..85664e2fd 100644--- a/sdk/src/asset/AsyncCache.ts+++ b/sdk/src/asset/AsyncCache.ts@@ -20,7 +20,7 @@ export class AsyncCache<T> {* @param dispose_ Optional releaser for a value whose load finishes AFTER* its getOrLoad already timed out — the caller got the timeout rejection,* so that late value has no owner and would otherwise leak (e.g. a GL- * texture created past the deadline; audit A17). NOT called for+ * texture created past the deadline). NOT called for* invalidate()/clearAll(), whose in-flight results still reach the caller.*/constructor(private dispose_?: (value: T) => void) {}@@ -58,7 +58,7 @@ export class AsyncCache<T> {let timer: ReturnType<typeof setTimeout> | undefined;// The loader keeps running even when the deadline wins the race. If// it produces a value after timing out, that value has no owner —- // release it so it doesn't leak (audit A17).+ // release it so it doesn't leak.void loaderPromise.then((late) => { if (timedOut) this.disposeAbandoned_(key, late); },() => { /* loader rejected — nothing to release */ },diff --git a/sdk/tests/async-cache-leak.test.ts b/sdk/tests/async-cache-leak.test.tsindex 66c9975ca..201ea6435 100644--- a/sdk/tests/async-cache-leak.test.ts+++ b/sdk/tests/async-cache-leak.test.ts@@ -1,6 +1,6 @@/*** @file async-cache-leak.test.ts- * @brief Regression net for audit A17 — when a load times out, the loader+ * @brief When a load times out, the loader* keeps running; its late result used to be dropped on the floor (the* caller already got the timeout rejection), leaking whatever it had* allocated (e.g. a GL texture = VRAM). AsyncCache now releases such@@ -11,7 +11,7 @@ import { AsyncCache } from '../src/asset/AsyncCache';const after = (ms: number) => new Promise((r) => setTimeout(r, ms));-describe('AsyncCache abandoned-load disposal (A17)', () => {+describe('AsyncCache abandoned-load disposal', () => {it('disposes a value whose load finishes AFTER the timeout', async () => {const disposed: number[] = [];const cache = new AsyncCache<number>((v) => disposed.push(v));diff --git a/sdk/tests/plugin-cleanup.test.ts b/sdk/tests/plugin-cleanup.test.tsindex f0739d613..ca1ca564f 100644--- a/sdk/tests/plugin-cleanup.test.ts+++ b/sdk/tests/plugin-cleanup.test.ts@@ -1,6 +1,6 @@/*** @file plugin-cleanup.test.ts- * @brief Regression net for audit A19 — Physics/Spine plugins must release+ * @brief Physics/Spine plugins must release* their native module + world listeners on app teardown (App calls* plugin.cleanup() at shutdown). Before this, `_physics_shutdown` was* dead code, the spine backends were never disposed, and the@@ -12,7 +12,7 @@ import { SpineManager } from '../src/spine/SpineManager';import { SpinePlugin } from '../src/spine/SpinePlugin';import { PhysicsPlugin } from '../src/physics/PhysicsPlugin';-describe('SpineManager.dispose (A19)', () => {+describe('SpineManager.dispose', () => {it('shuts down every backend and clears all state, idempotently', () => {const mgr = new SpineManager({} as any, new Map());const backendA = { shutdown: vi.fn() };@@ -37,7 +37,7 @@ describe('SpineManager.dispose (A19)', () => {});});-describe('SpinePlugin.cleanup (A19)', () => {+describe('SpinePlugin.cleanup', () => {it('unsubscribes the despawn listener and disposes the spine manager', () => {const plugin = new SpinePlugin();const unsub = vi.fn();@@ -63,7 +63,7 @@ describe('SpinePlugin.cleanup (A19)', () => {});});-describe('PhysicsPlugin.cleanup (A19)', () => {+describe('PhysicsPlugin.cleanup', () => {it('shuts down the native physics world and nulls the module', () => {const plugin = new PhysicsPlugin('fake://physics.wasm');const shutdown = vi.fn();diff --git a/sdk/tests/scene-load-failure.test.ts b/sdk/tests/scene-load-failure.test.tsindex 6b9350384..50e195379 100644--- a/sdk/tests/scene-load-failure.test.ts+++ b/sdk/tests/scene-load-failure.test.ts@@ -1,11 +1,11 @@/*** @file scene-load-failure.test.ts- * @brief Regression net for the audit's A18 (scene lifecycle robustness):- * A18a — a load that throws partway must NOT wedge the scene (a retry- * has to start fresh, not resolve to undefined forever), and any- * entities spawned before the throw must be cleaned up.- * A18b — a user `cleanup` callback that throws must NOT abort unload's- * entity teardown (which would leak the scene's entities).+ * @brief Scene lifecycle robustness on failure paths:+ * (1) a load that throws partway must NOT wedge the scene — a retry has+ * to start fresh (not resolve to undefined forever), and any+ * entities spawned before the throw must be cleaned up;+ * (2) a user `cleanup` callback that throws must NOT abort unload's+ * entity teardown (which would leak the scene's entities).*/import { describe, expect, it, beforeEach, vi } from 'vitest';@@ -76,7 +76,7 @@ function createMockApp() {};}-describe('SceneManager load-failure recovery (A18a)', () => {+describe('SceneManager load-failure recovery', () => {let app: ReturnType<typeof createMockApp>;let manager: SceneManagerState;@@ -138,7 +138,7 @@ describe('SceneManager load-failure recovery (A18a)', () => {});});-describe('SceneManager unload teardown robustness (A18b)', () => {+describe('SceneManager unload teardown robustness', () => {let app: ReturnType<typeof createMockApp>;let manager: SceneManagerState;