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.

5.9 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    tileGeometry.ts
 * @brief   Orientation-aware tile-cell geometry mirroring the native TileGrid.
 *
 * The renderer draws each tile as a layer-local axis-aligned tileWidth×tileHeight quad;
 * only its CENTER moves per orientation (orthogonal / isometric / staggered /
 * hexagonal). {@link tileCellCenter} reproduces that center (layer-local, y-up —
 * the caller applies the layer's world Z rotation and origin), so the editor brush ghost lands
 * exactly where the runtime will draw the tile.
 *
 * The CELL itself is a rect (orthogonal), a diamond (isometric / staggered), or a
 * hexagon (hexagonal). {@link tileCellOutline} returns that polygon as offsets
 * around the center — the same shape for every cell — so the editor grid overlay
 * and shaped ghost draw the true cell boundary. One geometry seam drives both.
 */

// Grid orientation, single-sourced from the C++ ES_ENUM via the generated module:
// the number a cell placement switches on is the number the engine's grid uses.
export { TilemapOrientation, TilemapStaggerAxis, TilemapStaggerIndex } from '../wasm/wasm.generated';
import { TilemapOrientation } from '../wasm/wasm.generated';

/** The layout inputs a cell placement needs — a subset of the TilemapLayer component. */
export interface TileGridParams {
    /** 0 orthogonal · 1 isometric · 2 staggered · 3 hexagonal. */
    orientation: number;
    tileWidth: number;
    tileHeight: number;
    /** Hex edge along the stagger axis, bounded by that tile dimension (0 → tileHeight/2). */
    hexSideLength?: number;
    /** staggerAxis === X: columns stagger (else rows). Staggered + hex. */
    staggerAxisX?: boolean;
    /** staggerIndex === Even carries the half-cell shift (else odd). Staggered + hex. */
    staggerIndexEven?: boolean;
}

export interface Vec2Like {
    x: number;
    y: number;
}

/** Layout without cell dimensions, for consumers that already receive tile width/height. */
export type TileGridLayout = Omit<TileGridParams, 'tileWidth' | 'tileHeight'>;

/** The effective hex side length: the authored value, or the regular-hex fallback (th/2). */
function hexSide(p: TileGridParams): number {
    const side = p.hexSideLength && p.hexSideLength > 0 ? p.hexSideLength : p.tileHeight * 0.5;
    return Math.min(side, p.staggerAxisX ? p.tileWidth : p.tileHeight);
}

/**
 * Cell center in layer-local pixels (y-up, origin at 0,0), matching native TileGrid.
 * Apply the layer's world rotation and position to obtain world coordinates.
 */
export function tileCellCenter(p: TileGridParams, tx: number, ty: number): Vec2Like {
    const hw = p.tileWidth * 0.5;
    const hh = p.tileHeight * 0.5;
    switch (p.orientation) {
        case TilemapOrientation.Isometric:
            return { x: (tx - ty) * hw, y: -(tx + ty) * hh };
        case TilemapOrientation.Staggered:
        case TilemapOrientation.Hexagonal: {
            const side = p.orientation === TilemapOrientation.Hexagonal ? hexSide(p) : 0;
            if (p.staggerAxisX) {
                const colW = (p.tileWidth + side) * 0.5;
                const staggered = ((tx & 1) !== 0) !== !!p.staggerIndexEven;
                return { x: tx * colW + hw, y: -(ty * p.tileHeight + (staggered ? hh : 0) + hh) };
            }
            const rowH = (p.tileHeight + side) * 0.5;
            const staggered = ((ty & 1) !== 0) !== !!p.staggerIndexEven;
            return { x: tx * p.tileWidth + (staggered ? hw : 0) + hw, y: -(ty * rowH + hh) };
        }
        default: // Orthogonal
            return { x: tx * p.tileWidth + hw, y: -(ty * p.tileHeight + hh) };
    }
}

/**
 * The cell outline as offsets around its center (y-up, world units) — the same polygon
 * for every cell of a given layout. Rect (orthogonal), diamond inscribed in the tile box
 * (isometric / staggered), or a Tiled hexagon whose flat edges (length = side) run along
 * the stagger axis (hexagonal). Draw it translated to each {@link tileCellCenter}.
 */
export function tileCellOutline(p: TileGridParams): Vec2Like[] {
    const hw = p.tileWidth * 0.5;
    const hh = p.tileHeight * 0.5;
    switch (p.orientation) {
        case TilemapOrientation.Isometric:
        case TilemapOrientation.Staggered:
            // Diamond: top, right, bottom, left.
            return [{ x: 0, y: hh }, { x: hw, y: 0 }, { x: 0, y: -hh }, { x: -hw, y: 0 }];
        case TilemapOrientation.Hexagonal: {
            const s = hexSide(p);
            const hs = s * 0.5;
            if (p.staggerAxisX) {
                // Flat-top hex: horizontal flat edges (length s) top and bottom, points left/right.
                return [
                    { x: -hs, y: hh }, { x: hs, y: hh }, { x: hw, y: 0 },
                    { x: hs, y: -hh }, { x: -hs, y: -hh }, { x: -hw, y: 0 },
                ];
            }
            // Pointy-top hex: vertical flat edges (length s) left and right, points top/bottom.
            return [
                { x: 0, y: hh }, { x: hw, y: hs }, { x: hw, y: -hs },
                { x: 0, y: -hh }, { x: -hw, y: -hs }, { x: -hw, y: hs },
            ];
        }
        default: // Orthogonal rect: tl, tr, br, bl (y-up).
            return [{ x: -hw, y: hh }, { x: hw, y: hh }, { x: hw, y: -hh }, { x: -hw, y: -hh }];
    }
}

/** True when the layout is anything other than a plain orthogonal square grid. */
export function isNonOrthogonal(orientation: number): boolean {
    return orientation !== TilemapOrientation.Orthogonal && orientation !== undefined;
}

/** True for the layouts that read the stagger axis/index (staggered + hexagonal). */
export function usesStagger(orientation: number): boolean {
    return orientation === TilemapOrientation.Staggered || orientation === TilemapOrientation.Hexagonal;
}

/** True for the hexagonal layout (the only one that reads the hex side length). */
export function isHexOrientation(orientation: number): boolean {
    return orientation === TilemapOrientation.Hexagonal;
}