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
style(compiler): the new comments state the contract, not the story
yhh73bb32e349c5
diff --git a/compiler/src/abi.ts b/compiler/src/abi.tsindex 5715c3988..355853d7e 100644--- a/compiler/src/abi.ts+++ b/compiler/src/abi.ts@@ -29,10 +29,9 @@ export const CMD_REMOVE = 2;/*** Words in `SysCtx` and in `QueryRows` (docs/REARCH_AOT_ABI.md §2.1, §2.2).- * Exported because THREE things count them — the host below, the code generator,- * and the handshake hash — and a contract whose field count has three authors- * is the drift this file exists to prevent. §6.3 makes the first of these a- * number that needs a reason to grow.+ * Exported because three things count them — this host, the code generator and+ * the handshake hash — and a field count with three authors is the drift this+ * file prevents. §6.3 makes the first a number that needs a reason to grow.*/export const SYSCTX_WORDS = 6;export const QUERYROWS_WORDS = 2;@@ -98,13 +97,10 @@ export class AbiMemory {}/**- * Reset the arena the host refills before every call. Row arrays and the- * SysCtx itself live here because §2.2 says they are valid for one call and- * the compiled code may not hold them; giving them a region that is thrown- * away each time is how that is enforced rather than merely stated.- *- * It grows DOWN from the end of the image while world data grows up, so the- * two allocators cannot silently overlap — they meet, and `alloc` says so.+ * 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+ * while world data grows up, so an overlap is caught by `alloc`, not silent.*/beginCall(): void {this.scratchNext = this.buffer.byteLength;@@ -230,13 +226,10 @@ export interface AbiCall {}/**- * Do the host's half of §2.1: pack the rows, resolve the resource addresses,- * zero the count, and write the SysCtx. Everything the compiled code will read- * is in linear memory when this returns, and it is the ONLY thing there for it.- *- * Row materialisation follows the strategy `View.hpp` already uses — walk the- * entities, keep the ones carrying every named component. The ABI exposes the- * existing strategy rather than inventing a second one.+ * The host's half of §2.1: pack the rows, resolve the resource addresses, 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.*/export function materialize(mem: AbiMemory, plan: SysPlan): AbiCall {mem.beginCall();@@ -274,12 +267,9 @@ export function materialize(mem: AbiMemory, plan: SysPlan): AbiCall {/*** The host a compiled system sees, reaching the world through NOTHING but the- * ctx `materialize` wrote. Every field access below is a load or store at a- * declared offset, and there is no engine call to make.- *- * It reads the packed row array rather than re-deriving the rows, so that the- * interpreter and the generated C consume the same bytes. A host that walked- * `mem.entities` again would agree with the compiled code only by coincidence.+ * ctx `materialize` wrote. It reads the packed row array rather than re-deriving+ * the rows, so the interpreter and the generated C consume the same bytes: a+ * host that walked `mem.entities` again would agree only by coincidence.*/export function abiHost(mem: AbiMemory, layout: AbiLayout, plan: SysPlan, call: AbiCall): EirHost {const leafAt = (owner: string, path: readonly string[]): Leaf => {@@ -361,12 +351,10 @@ export function runOnAbi(sys: EirSystem, mem: AbiMemory, layout: AbiLayout, fns:}/**- * The handshake constant of §2.5: EHT's component offsets, the shape of the- * three structs, and every system's parameter order, in one 64-bit number the- * loader compares before it maps anything. A mismatch is not a wrong answer —- * it is a read of a DIFFERENT FIELD — so this is refused, not warned about.- *- * FNV-1a, as `mkbc` and the asset hashes already use; not a new mechanism.+ * The §2.5 handshake: EHT's offsets, the shape of the three structs, and every+ * system's parameter order, in one number the loader compares before it maps+ * anything. A mismatch is a read of a DIFFERENT FIELD, not a wrong answer, so it+ * is refused. FNV-1a, as `mkbc` and the asset hashes use; not a new mechanism.*/export function abiHash(layout: AbiLayout, plans: readonly SysPlan[]): string {const parts: string[] = [diff --git a/compiler/src/builtins.ts b/compiler/src/builtins.tsindex 0ca23a6e0..4011287a3 100644--- a/compiler/src/builtins.ts+++ b/compiler/src/builtins.ts@@ -68,12 +68,10 @@ const TIME: CompShape = {};/**- * A stamp over EHT's table, for the §2.5 handshake. It hashes the OFFSETS- * themselves rather than importing `ABI_LAYOUT_HASH`, for two reasons: that- * constant lives in `component.generated.ts`, whose imports reach the whole SDK- * runtime and would make the compiler depend on it; and the raw table is- * strictly more information than a hash of it. Same property either way — it- * changes when the C++ structs change, which is the only thing asked of it.+ * EHT's table, flattened for the §2.5 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.*/export function ehtStamp(): string {const parts: string[] = [];diff --git a/compiler/tests/codegen.test.ts b/compiler/tests/codegen.test.tsindex 7149e565d..80b7d3f8a 100644--- a/compiler/tests/codegen.test.ts+++ b/compiler/tests/codegen.test.ts@@ -285,10 +285,9 @@ describe('the emitted C says what the interpreter says', () => {expect(same(byC, movedWorld(layout)), 'nothing moved, so agreeing proves nothing').toBe(false);});- // Every feature the subset gained after MoveSystem, each in a system that- // exercises it: branches and `&&`, ternaries and the exact half of Math,- // folded module constants with a shadowing local, an inlined helper, and the- // Math arguments where libm and ECMAScript give different answers.+ // Every feature the subset gained after MoveSystem: branches and `&&`,+ // ternaries, folded module constants with a shadowing local, an inlined+ // helper, and the Math arguments where libm and ECMAScript disagree.for (const name of ['FixtureDrift', 'FixtureClampSys', 'FixtureTuned', 'FixtureHelpers', 'FixtureMathOps']) {it(`${name}: the whole image agrees with the interpreter`, () => {const sys = systemOf(fixtures, name);