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.

feat(sdk): one author for how a sprite sheet is cut

yhh747c66bc52af
diff --git a/desktop b/desktop
index 56eab99da..cd583b0e0 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 56eab99da7ed2162f6a0ea02ce68281f69236b99
+Subproject commit cd583b0e07dfd650fa1c381f3a7702fe2809cf95
diff --git a/pipeline/src/project/importSettings.ts b/pipeline/src/project/importSettings.ts
index a6cfb1efb..c586d4d54 100644
--- a/pipeline/src/project/importSettings.ts
+++ b/pipeline/src/project/importSettings.ts
@@ -86,6 +86,21 @@ 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.
+ {
+ 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. '
+ + 'Setting it lets a Sprite pick a frame of this image instead of showing all of it.',
+ },
+ { key: 'sheet.cellHeight', label: 'Cell Height', type: 'number', default: 0, min: 0, category: 'Sheet',
+ tooltip: 'Height of one cell, in pixels. 0 = this image is not a sprite sheet.' },
+ { key: 'sheet.margin', label: 'Margin', type: 'number', default: 0, min: 0, category: 'Sheet',
+ tooltip: 'Padding before the first cell, on both axes.' },
+ { key: 'sheet.spacing', label: 'Spacing', type: 'number', default: 0, min: 0, category: 'Sheet',
+ tooltip: 'Gap between neighbouring cells. Paid between cells only, never after the last one.' },
];
// `cullingBounds` promises no pose of this skeleton leaves it. The runtime's
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 52447b49f..fa153bff3 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 92 beta · 1664 experimental · 3 deprecated
+Symbols: 113 public · 92 beta · 1670 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -7843,6 +7843,16 @@ Circle = 0
RoundedRect = 2
```
+## SheetGrid — interface @experimental
+```
+cellHeight: number
+cellWidth: number
+margin: number
+pageHeight: number
+pageWidth: number
+spacing: number
+```
+
## SideModuleDescriptor — interface @experimental
```
file: string
@@ -13324,6 +13334,31 @@ ServicesPlugin
(shape: Collider2DShape): Vec2
```
+## sheetCellCount — function @experimental
+```
+(grid: SheetGrid): number
+```
+
+## sheetCellRect — function @experimental
+```
+(grid: SheetGrid, cell: number): { x: number; y: number; width: number; height: number; }
+```
+
+## sheetCellUv — function @experimental
+```
+(grid: SheetGrid, cell: number): { uvOffset: { x: number; y: number; }; uvScale: { x: number; y: number; }; }
+```
+
+## sheetCols — function @experimental
+```
+(grid: SheetGrid): number
+```
+
+## sheetRows — function @experimental
+```
+(grid: SheetGrid): number
+```
+
## shortestAngleDelta — function @experimental
```
(from: number, to: number): number
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index b7f6131f1..41b6c6652 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.native
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 97 beta · 1683 experimental · 3 deprecated
+Symbols: 113 public · 97 beta · 1689 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -8036,6 +8036,16 @@ Circle = 0
RoundedRect = 2
```
+## SheetGrid — interface @experimental
+```
+cellHeight: number
+cellWidth: number
+margin: number
+pageHeight: number
+pageWidth: number
+spacing: number
+```
+
## SideModuleDescriptor — interface @experimental
```
file: string
@@ -13567,6 +13577,31 @@ ServicesPlugin
(shape: Collider2DShape): Vec2
```
+## sheetCellCount — function @experimental
+```
+(grid: SheetGrid): number
+```
+
+## sheetCellRect — function @experimental
+```
+(grid: SheetGrid, cell: number): { x: number; y: number; width: number; height: number; }
+```
+
+## sheetCellUv — function @experimental
+```
+(grid: SheetGrid, cell: number): { uvOffset: { x: number; y: number; }; uvScale: { x: number; y: number; }; }
+```
+
+## sheetCols — function @experimental
+```
+(grid: SheetGrid): number
+```
+
+## sheetRows — function @experimental
+```
+(grid: SheetGrid): number
+```
+
## shortestAngleDelta — function @experimental
```
(from: number, to: number): number
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 070792ddc..c6681318c 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.node
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 94 beta · 1663 experimental · 3 deprecated
+Symbols: 113 public · 94 beta · 1669 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -7838,6 +7838,16 @@ Circle = 0
RoundedRect = 2
```
+## SheetGrid — interface @experimental
+```
+cellHeight: number
+cellWidth: number
+margin: number
+pageHeight: number
+pageWidth: number
+spacing: number
+```
+
## SideModuleDescriptor — interface @experimental
```
file: string
@@ -13329,6 +13339,31 @@ ServicesPlugin
(shape: Collider2DShape): Vec2
```
+## sheetCellCount — function @experimental
+```
+(grid: SheetGrid): number
+```
+
+## sheetCellRect — function @experimental
+```
+(grid: SheetGrid, cell: number): { x: number; y: number; width: number; height: number; }
+```
+
+## sheetCellUv — function @experimental
+```
+(grid: SheetGrid, cell: number): { uvOffset: { x: number; y: number; }; uvScale: { x: number; y: number; }; }
+```
+
+## sheetCols — function @experimental
+```
+(grid: SheetGrid): number
+```
+
+## sheetRows — function @experimental
+```
+(grid: SheetGrid): number
+```
+
## shortestAngleDelta — function @experimental
```
(from: number, to: number): number
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index f7987d29a..64fd69b71 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/minigame
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 92 beta · 1685 experimental · 3 deprecated
+Symbols: 113 public · 92 beta · 1691 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -8084,6 +8084,16 @@ Circle = 0
RoundedRect = 2
```
+## SheetGrid — interface @experimental
+```
+cellHeight: number
+cellWidth: number
+margin: number
+pageHeight: number
+pageWidth: number
+spacing: number
+```
+
## SideModuleDescriptor — interface @experimental
```
file: string
@@ -13586,6 +13596,31 @@ ServicesPlugin
(shape: Collider2DShape): Vec2
```
+## sheetCellCount — function @experimental
+```
+(grid: SheetGrid): number
+```
+
+## sheetCellRect — function @experimental
+```
+(grid: SheetGrid, cell: number): { x: number; y: number; width: number; height: number; }
+```
+
+## sheetCellUv — function @experimental
+```
+(grid: SheetGrid, cell: number): { uvOffset: { x: number; y: number; }; uvScale: { x: number; y: number; }; }
+```
+
+## sheetCols — function @experimental
+```
+(grid: SheetGrid): number
+```
+
+## sheetRows — function @experimental
+```
+(grid: SheetGrid): number
+```
+
## shortestAngleDelta — function @experimental
```
(from: number, to: number): number
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 1d3bec1a0..3f6750c44 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/wechat
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 92 beta · 1675 experimental · 3 deprecated
+Symbols: 113 public · 92 beta · 1681 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -7845,6 +7845,16 @@ Circle = 0
RoundedRect = 2
```
+## SheetGrid — interface @experimental
+```
+cellHeight: number
+cellWidth: number
+margin: number
+pageHeight: number
+pageWidth: number
+spacing: number
+```
+
## SideModuleDescriptor — interface @experimental
```
file: string
@@ -13352,6 +13362,31 @@ ServicesPlugin
(shape: Collider2DShape): Vec2
```
+## sheetCellCount — function @experimental
+```
+(grid: SheetGrid): number
+```
+
+## sheetCellRect — function @experimental
+```
+(grid: SheetGrid, cell: number): { x: number; y: number; width: number; height: number; }
+```
+
+## sheetCellUv — function @experimental
+```
+(grid: SheetGrid, cell: number): { uvOffset: { x: number; y: number; }; uvScale: { x: number; y: number; }; }
+```
+
+## sheetCols — function @experimental
+```
+(grid: SheetGrid): number
+```
+
+## sheetRows — function @experimental
+```
+(grid: SheetGrid): number
+```
+
## shortestAngleDelta — function @experimental
```
(from: number, to: number): number
diff --git a/sdk/src/animation/AnimClipLoader.ts b/sdk/src/animation/AnimClipLoader.ts
index 96fd28988..da885d780 100644
--- a/sdk/src/animation/AnimClipLoader.ts
+++ b/sdk/src/animation/AnimClipLoader.ts
@@ -8,6 +8,9 @@
import type { SpriteAnimClip, SpriteAnimFrame } from './SpriteAnimator';
import { log } from '../util/logger';
+import {
+ sheetCols, sheetRows, sheetCellRect, sheetCellUv, type SheetGrid,
+} from '../asset/sheetGrid';
// =============================================================================
// .esanim File Format
@@ -51,14 +54,9 @@ export type AnimClipSizing = 'entity' | 'frame';
* `pageWidth`/`pageHeight` are baked by the editor from the image's natural
* size (UV normalization needs them; the runtime never reads the image).
*/
-export interface AnimClipSheetData {
+/** A clip's sheet: the cutting geometry every sheet has, plus the image it cuts. */
+export interface AnimClipSheetData extends SheetGrid {
texture: string;
- cellWidth: number;
- cellHeight: number;
- margin: number;
- spacing: number;
- pageWidth: number;
- pageHeight: number;
}
export interface AnimClipFrameData {
@@ -129,52 +127,35 @@ export interface AnimClipAssetData {
// Sheet grid math
// =============================================================================
-/** Columns the sheet grid fits (same stride math as the tileset atlas grid). */
+// 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.
+
+/** @see sheetCols */
export function animClipSheetCols(sheet: AnimClipSheetData): number {
- const stride = sheet.cellWidth + sheet.spacing;
- return stride > 0 ? Math.max(1, Math.floor((sheet.pageWidth - sheet.margin + sheet.spacing) / stride)) : 1;
+ return sheetCols(sheet);
}
-/** Rows the sheet grid fits. At least 1 so cell 0 always resolves. */
+/** @see sheetRows */
export function animClipSheetRows(sheet: AnimClipSheetData): number {
- const stride = sheet.cellHeight + sheet.spacing;
- return stride > 0 ? Math.max(1, Math.floor((sheet.pageHeight - sheet.margin + sheet.spacing) / stride)) : 1;
+ return sheetRows(sheet);
}
-/** Pixel rect of a grid cell, clamped into the valid cell range. */
+/** @see sheetCellRect */
export function animClipCellRect(
sheet: AnimClipSheetData,
cell: number,
): { x: number; y: number; width: number; height: number } {
- const cols = animClipSheetCols(sheet);
- const rows = animClipSheetRows(sheet);
- const clamped = Math.min(Math.max(0, Math.floor(cell)), cols * rows - 1);
- const col = clamped % cols;
- const row = Math.floor(clamped / cols);
- return {
- x: sheet.margin + col * (sheet.cellWidth + sheet.spacing),
- y: sheet.margin + row * (sheet.cellHeight + sheet.spacing),
- width: sheet.cellWidth,
- height: sheet.cellHeight,
- };
+ return sheetCellRect(sheet, cell);
}
-/** UV window (flipY space) of a grid cell — what a Sprite shows for that frame. */
+/** @see sheetCellUv */
export function animClipCellUv(
sheet: AnimClipSheetData,
cell: number,
): { uvOffset: { x: number; y: number }; uvScale: { x: number; y: number } } {
- const rect = animClipCellRect(sheet, cell);
- return {
- uvOffset: {
- x: rect.x / sheet.pageWidth,
- y: 1.0 - (rect.y + rect.height) / sheet.pageHeight,
- },
- uvScale: {
- x: rect.width / sheet.pageWidth,
- y: rect.height / sheet.pageHeight,
- },
- };
+ return sheetCellUv(sheet, cell);
}
// =============================================================================
diff --git a/sdk/src/asset/sheetGrid.ts b/sdk/src/asset/sheetGrid.ts
new file mode 100644
index 000000000..cc24c91d2
--- /dev/null
+++ b/sdk/src/asset/sheetGrid.ts
@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file sheetGrid.ts
+ * @brief How a sprite sheet is cut into cells — the one author for that stride.
+ *
+ * Three surfaces cut a sheet the same way and each had written the arithmetic
+ * down: the flipbook's `.esanim`, the tileset's atlas, and the particle emitter's
+ * `spriteColumns`/`spriteRows`. The stride is `margin + i * (cell + spacing)` in
+ * all of them, and it is the kind of expression that is wrong by one for a long
+ * time before anybody notices, because a sheet with no margin and no spacing —
+ * which is most of them — hides every mistake in both terms.
+ *
+ * So it lives here, named for what it is rather than for whoever asked first.
+ * `.esanim` keeps its own spellings as one-line delegates: this is the author,
+ * those are the aliases.
+ *
+ * A cell is addressed row-major from 0, the way every one of those surfaces
+ * already addresses it.
+ */
+
+/**
+ * A sheet's cutting geometry, in the image's own pixels. `pageWidth`/`pageHeight`
+ * are the whole image, which is what turns a pixel rect into a UV window.
+ */
+export interface SheetGrid {
+ cellWidth: number;
+ cellHeight: number;
+ margin: number;
+ spacing: number;
+ pageWidth: number;
+ pageHeight: number;
+}
+
+/** Columns the grid fits across the page. At least 1, so cell 0 always resolves. */
+export function sheetCols(grid: SheetGrid): number {
+ const stride = grid.cellWidth + grid.spacing;
+ // `+ spacing` because the last cell needs no trailing gap: a 64px page of two
+ // 32px cells with 0 margin and 0 spacing is two columns, and so is a 66px page
+ // of the same cells with 2px between them.
+ return stride > 0 ? Math.max(1, Math.floor((grid.pageWidth - grid.margin + grid.spacing) / stride)) : 1;
+}
+
+/** Rows the grid fits down the page. At least 1, for the same reason. */
+export function sheetRows(grid: SheetGrid): number {
+ const stride = grid.cellHeight + grid.spacing;
+ return stride > 0 ? Math.max(1, Math.floor((grid.pageHeight - grid.margin + grid.spacing) / stride)) : 1;
+}
+
+/** How many cells the grid holds — what a cell index is addressed against. */
+export function sheetCellCount(grid: SheetGrid): number {
+ return sheetCols(grid) * sheetRows(grid);
+}
+
+/** Pixel rect of a cell, clamped into the valid range so no index escapes the page. */
+export function sheetCellRect(
+ grid: SheetGrid,
+ cell: number,
+): { x: number; y: number; width: number; height: number } {
+ const cols = sheetCols(grid);
+ const clamped = Math.min(Math.max(0, Math.floor(cell)), sheetCellCount(grid) - 1);
+ const col = clamped % cols;
+ const row = Math.floor(clamped / cols);
+ return {
+ x: grid.margin + col * (grid.cellWidth + grid.spacing),
+ y: grid.margin + row * (grid.cellHeight + grid.spacing),
+ width: grid.cellWidth,
+ height: grid.cellHeight,
+ };
+}
+
+/**
+ * UV window of a cell — exactly what `Sprite.uvOffset` / `Sprite.uvScale` take,
+ * and what a flipbook frame shows.
+ *
+ * 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.
+ */
+export function sheetCellUv(
+ grid: SheetGrid,
+ cell: number,
+): { uvOffset: { x: number; y: number }; uvScale: { x: number; y: number } } {
+ const rect = sheetCellRect(grid, cell);
+ return {
+ uvOffset: {
+ x: rect.x / grid.pageWidth,
+ y: 1.0 - (rect.y + rect.height) / grid.pageHeight,
+ },
+ uvScale: {
+ x: rect.width / grid.pageWidth,
+ y: rect.height / grid.pageHeight,
+ },
+ };
+}
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index 1806fecad..b395e64fe 100644
--- a/sdk/src/core-content.ts
+++ b/sdk/src/core-content.ts
@@ -145,6 +145,9 @@ export {
} from './asset/builtinMeshes';
export { AssetScope, type AssetLease } from './asset/AssetLease';
export { createCanvasTexture, type CanvasTexture } from './asset/canvasTexture';
+export {
+ sheetCols, sheetRows, sheetCellCount, sheetCellRect, sheetCellUv, type SheetGrid,
+} from './asset/sheetGrid';
export type { GlImageSource } from './asset/glTextureUpload';
// =============================================================================
diff --git a/sdk/tests/sheet-grid.test.ts b/sdk/tests/sheet-grid.test.ts
new file mode 100644
index 000000000..e78b3643c
--- /dev/null
+++ b/sdk/tests/sheet-grid.test.ts
@@ -0,0 +1,115 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Cutting a sprite sheet into cells.
+ *
+ * The stride is `margin + i * (cell + spacing)`, and it is wrong by one for
+ * a long time before anyone notices: the sheets people test with have no
+ * margin and no spacing, which hides a mistake in BOTH terms. So the cases
+ * here all carry at least one of them.
+ */
+import { describe, it, expect } from 'vitest';
+import {
+ sheetCols, sheetRows, sheetCellCount, sheetCellRect, sheetCellUv, type SheetGrid,
+} from '../src/asset/sheetGrid';
+
+/** Four 32px cells across a 128px page, no margin, no spacing — the easy sheet. */
+const plain: SheetGrid = {
+ cellWidth: 32, cellHeight: 32, margin: 0, spacing: 0, pageWidth: 128, pageHeight: 64,
+};
+
+/**
+ * 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.
+ *
+ * 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.
+ */
+const padded: SheetGrid = {
+ cellWidth: 32, cellHeight: 32, margin: 2, spacing: 2, pageWidth: 136, pageHeight: 68,
+};
+
+describe('sheet grid', () => {
+ it('counts the cells a plain sheet holds', () => {
+ expect(sheetCols(plain)).toBe(4);
+ expect(sheetRows(plain)).toBe(2);
+ expect(sheetCellCount(plain)).toBe(8);
+ });
+
+ it('counts them the same when margin and spacing are paid for', () => {
+ expect(sheetCols(padded)).toBe(4);
+ expect(sheetRows(padded)).toBe(2);
+ });
+
+ it('counts the last column even when nothing follows it', () => {
+ // The tight page ends flush with the fourth cell. Counting as though every
+ // cell owed a trailing gap loses it — 3 columns for a sheet that has 4.
+ expect(sheetCols(padded)).toBe(4);
+ expect(sheetRows(padded)).toBe(2);
+ });
+
+ it('does not invent a column out of a trailing gap', () => {
+ // Room for a fifth cell's spacing, but not for the cell.
+ expect(sheetCols({ ...padded, pageWidth: 136 + 2 })).toBe(4);
+ // …and finds the fifth as soon as the page can hold it.
+ expect(sheetCols({ ...padded, pageWidth: 136 + 2 + 32 })).toBe(5);
+ });
+
+ it('addresses cells row-major from the top-left', () => {
+ expect(sheetCellRect(plain, 0)).toEqual({ x: 0, y: 0, width: 32, height: 32 });
+ expect(sheetCellRect(plain, 3)).toEqual({ x: 96, y: 0, width: 32, height: 32 });
+ expect(sheetCellRect(plain, 4)).toEqual({ x: 0, y: 32, width: 32, height: 32 });
+ });
+
+ it('pays margin once and spacing per gap', () => {
+ expect(sheetCellRect(padded, 0)).toMatchObject({ x: 2, y: 2 });
+ expect(sheetCellRect(padded, 1)).toMatchObject({ x: 36, y: 2 }); // 2 + 32 + 2
+ expect(sheetCellRect(padded, 4)).toMatchObject({ x: 2, y: 36 });
+ });
+
+ it('clamps an index that would walk off the page', () => {
+ expect(sheetCellRect(plain, 99)).toEqual(sheetCellRect(plain, 7));
+ expect(sheetCellRect(plain, -5)).toEqual(sheetCellRect(plain, 0));
+ expect(sheetCellRect(plain, 2.7)).toEqual(sheetCellRect(plain, 2));
+ });
+
+ it('survives a degenerate grid instead of dividing by zero', () => {
+ const dead: SheetGrid = { ...plain, cellWidth: 0, cellHeight: 0, spacing: 0 };
+ expect(sheetCols(dead)).toBe(1);
+ expect(sheetRows(dead)).toBe(1);
+ expect(() => sheetCellRect(dead, 3)).not.toThrow();
+ });
+
+ // Cell 0 is the sheet's TOP-left and UV runs from the bottom, so cell 0 is the
+ // HIGHEST v. This is the one thing about a uvOffset in an inspector that looks
+ // wrong until you remember which way an image is stored.
+ it('flips Y: the first cell is the top of the page, which is the top of UV space', () => {
+ const top = sheetCellUv(plain, 0);
+ expect(top.uvOffset).toEqual({ x: 0, y: 0.5 }); // 1 − (0 + 32)/64
+ expect(top.uvScale).toEqual({ x: 0.25, y: 0.5 });
+
+ const below = sheetCellUv(plain, 4); // directly under cell 0
+ expect(below.uvOffset).toEqual({ x: 0, y: 0 });
+ });
+
+ it('a full-page cell is the whole UV square', () => {
+ const whole: SheetGrid = {
+ cellWidth: 64, cellHeight: 64, margin: 0, spacing: 0, pageWidth: 64, pageHeight: 64,
+ };
+ expect(sheetCellUv(whole, 0)).toEqual({ uvOffset: { x: 0, y: 0 }, uvScale: { x: 1, y: 1 } });
+ });
+
+ it('tiles the page without gaps or overlap when nothing is padded', () => {
+ // Every cell's UV window abuts its neighbour's: the sum of the widths is 1.
+ const windows = Array.from({ length: sheetCols(plain) }, (_, i) => sheetCellUv(plain, i));
+ expect(windows.reduce((a, w) => a + w.uvScale.x, 0)).toBeCloseTo(1, 6);
+ for (let i = 1; i < windows.length; i++) {
+ expect(windows[i]!.uvOffset.x).toBeCloseTo(
+ windows[i - 1]!.uvOffset.x + windows[i - 1]!.uvScale.x, 6);
+ }
+ });
+});