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.

3.5 KB
Raw Blame
// 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.
 */

import { uvRectFromPixels } from '../render/uvRect';

/**
 * 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.
 *
 * 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,
    cell: number,
): { uvOffset: { x: number; y: number }; uvScale: { x: number; y: number } } {
    return uvRectFromPixels(sheetCellRect(grid, cell), grid.pageWidth, grid.pageHeight);
}