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.

style(comments): state the contract, not the story

yhh377afdb23473
diff --git a/pipeline/src/project/importSettings.ts b/pipeline/src/project/importSettings.ts
index c586d4d54..d49a072ab 100644
--- a/pipeline/src/project/importSettings.ts
+++ b/pipeline/src/project/importSettings.ts
@@ -86,10 +86,9 @@ const TEXTURE: ImporterFieldSpec[] = [
{ key: 'sliceBorder.right', label: 'Border Right', type: 'number', default: 0, min: 0, category: '9-Slice', advanced: true },
{ key: 'sliceBorder.top', label: 'Border Top', type: 'number', default: 0, min: 0, category: '9-Slice', advanced: true },
{ key: 'sliceBorder.bottom', label: 'Border Bottom', type: 'number', default: 0, min: 0, category: '9-Slice', advanced: true },
- // How this image is cut into cells, declared ONCE on the sheet rather than on
- // every Sprite that shows a frame of it. A cell size of 0 means "not a sheet",
- // which is what almost every texture is — so the section costs an unsliced image
- // nothing but a collapsed header.
+ // How this image is cut, declared ONCE on the sheet — not on every Sprite that
+ // shows a frame of it, which is how four numbers become four disagreeing copies.
+ // A cell size of 0 means "not a sheet", which is what most textures are.
{
key: 'sheet.cellWidth', label: 'Cell Width', type: 'number', default: 0, min: 0, category: 'Sheet',
tooltip: 'Width of one cell, in pixels. 0 = this image is not a sprite sheet. '
diff --git a/sdk/src/animation/AnimClipLoader.ts b/sdk/src/animation/AnimClipLoader.ts
index da885d780..7484382d1 100644
--- a/sdk/src/animation/AnimClipLoader.ts
+++ b/sdk/src/animation/AnimClipLoader.ts
@@ -127,10 +127,9 @@ export interface AnimClipAssetData {
// Sheet grid math
// =============================================================================
-// A clip's sheet is cut the way every sheet is cut, so the arithmetic is in
-// asset/sheetGrid.ts and these four are its `.esanim` spellings. Kept because
-// they are what the flipbook's own code reads; new callers should reach for the
-// neutral names, which do not ask a sprite to describe itself as an anim clip.
+// The arithmetic is asset/sheetGrid.ts's; these four are its `.esanim` spellings,
+// kept because the flipbook's own code reads them. New callers take the neutral
+// names — a sprite should not have to call itself an anim clip to find a cell.
/** @see sheetCols */
export function animClipSheetCols(sheet: AnimClipSheetData): number {
diff --git a/sdk/src/asset/sheetGrid.ts b/sdk/src/asset/sheetGrid.ts
index cc24c91d2..dedf15cb0 100644
--- a/sdk/src/asset/sheetGrid.ts
+++ b/sdk/src/asset/sheetGrid.ts
@@ -70,13 +70,11 @@ export function sheetCellRect(
}
/**
- * UV window of a cell — exactly what `Sprite.uvOffset` / `Sprite.uvScale` take,
- * and what a flipbook frame shows.
+ * UV window of a cell — exactly what `Sprite.uvOffset` / `Sprite.uvScale` take.
*
- * Y is flipped: a sheet is addressed from its TOP-left because that is where an
- * image's first pixel is, and UV space runs from the bottom. Cell 0 of a sheet is
- * therefore the HIGHEST v, which is the one thing about this that surprises
- * people reading a uvOffset in an inspector.
+ * Y is flipped: a sheet is addressed from its top-left, UV space runs from the
+ * bottom, so cell 0 carries the HIGHEST v. That is the one thing here that reads
+ * as wrong in an inspector until you remember which way an image is stored.
*/
export function sheetCellUv(
grid: SheetGrid,
diff --git a/sdk/tests/sheet-grid.test.ts b/sdk/tests/sheet-grid.test.ts
index e78b3643c..7493ed529 100644
--- a/sdk/tests/sheet-grid.test.ts
+++ b/sdk/tests/sheet-grid.test.ts
@@ -19,15 +19,10 @@ const plain: SheetGrid = {
};
/**
- * The same 4x2 grid, TIGHT: a 2px margin before the first cell and 2px between
- * them, and nothing after the last. 2 + 4*32 + 3*2 = 136 across, 2 + 2*32 + 2 = 68
- * down.
+ * The same 4x2 grid, TIGHT: 136 x 68, ending flush with the last cell.
*
- * Tight on purpose, and it is the whole point of this fixture. The first draft
- * gave the page 2px of trailing margin as well — and with that slack the
- * `+ spacing` term in the column count does nothing, so dropping it (the actual
- * off-by-one this arithmetic invites) left every assertion green. A sheet exported
- * with no trailing padding is the one that tells the two apart.
+ * The trap: give the page trailing margin and the `+ spacing` term in the column
+ * count stops mattering, so dropping it leaves every assertion here green.
*/
const padded: SheetGrid = {
cellWidth: 32, cellHeight: 32, margin: 2, spacing: 2, pageWidth: 136, pageHeight: 68,
diff --git a/sdk/tests/soak/dist-probes.test.ts b/sdk/tests/soak/dist-probes.test.ts
index de84075da..d9276dabc 100644
--- a/sdk/tests/soak/dist-probes.test.ts
+++ b/sdk/tests/soak/dist-probes.test.ts
@@ -22,11 +22,10 @@ const HAS_DIST = existsSync(DIST);
describe.skipIf(!HAS_DIST)('the built SDK', () => {
/**
- * The 5s default is a cap on IMPORTING a megabyte bundle, not on the claim.
- * Alone this takes ~0.9s; inside the full 527-file suite it has been measured
- * at 2.1s and has timed out — so at the default it reports the machine's load
- * as a missing census, which is the loudest possible way to be wrong about
- * something that is fine. Raised until it can only fire on a real hang.
+ * The claim is about CONTENT, so the timeout may only fire on a real hang. At
+ * the 5s default it fires on LOAD: importing this megabyte bundle is ~0.9s
+ * alone, 2.1s inside the full suite, and has timed out — reporting a missing
+ * census about an SDK whose census is fine.
*/
it('ships a census with its probes attached', async () => {
const sdk = await import(DIST) as {
diff --git a/tools/check-import-settings.mjs b/tools/check-import-settings.mjs
index 65ff1f901..2e8265bd0 100644
--- a/tools/check-import-settings.mjs
+++ b/tools/check-import-settings.mjs
@@ -57,11 +57,9 @@ const unverified = [];
const readers = files
.filter((f) => /\.(ts|tsx)$/.test(f) && !f.includes('generated') && f !== SPECS.split(path.sep).join('/'))
.map((f) => readFileSync(path.join(ROOT, f), 'utf8'))
- // `importer`, not `importer`: the word boundary excluded every file whose
- // accessor is NAMED for the thing — `importerFor`, `importerDefaults`,
- // `applyImporterEdit` — which is to say the files most likely to be readers.
- // A sheet grid read through `AssetRegistry.importerFor(path)?.sheet` was
- // reported as a knob that does nothing.
+ // `importer`, not `importer`: the boundary excluded `importerFor`,
+ // `importerDefaults`, `applyImporterEdit` — the accessors a setting is read
+ // through, and so the files most likely to hold a reader.
.filter((text) => /importer/i.test(text))
.join('\n');