@codexo/exojs-tilemap 0.15.2 → 0.16.0

package/dist/esm/tileCollision.d.ts

@@ -0,0 +1,190 @@
+import type { ObjectPoint, TileMapObject } from './ObjectLayer';
+import { ObjectKind } from './ObjectLayer';
+import type { TileLayer } from './TileLayer';
+/**
+ * The geometry kinds a {@link TileCollisionShape} can carry. Tile (GID) and
+ * text objects describe no collision area and are never emitted, so they are
+ * excluded from the union.
+ * @advanced
+ */
+export type TileCollisionShapeKind = typeof ObjectKind.Rectangle | typeof ObjectKind.Ellipse | typeof ObjectKind.Polygon | typeof ObjectKind.Polyline | typeof ObjectKind.Point;
+/**
+ * A half-open tile-coordinate rectangle covering
+ * `[x, x + width)` × `[y, y + height)`.
+ *
+ * Used to scope {@link buildTileCollisionGeometry} to part of a layer - a
+ * streamed chunk, the tiles around the player, a hand-picked room - instead of
+ * always rebuilding the whole map.
+ * @advanced
+ */
+export interface TileRegion {
+    /** Leftmost tile column (inclusive). */
+    readonly x: number;
+    /** Topmost tile row (inclusive). */
+    readonly y: number;
+    /** Width in tiles. */
+    readonly width: number;
+    /** Height in tiles. */
+    readonly height: number;
+}
+/**
+ * An axis-aligned collision rectangle in tile-layer pixel space (+Y down),
+ * covering one or more whole tile cells.
+ *
+ * Rectangles are synthesized geometry, not source objects: a merged run has no
+ * single originating object, so it carries no object `id`/`name`/`properties` -
+ * only the `type` string shared by every shape merged into it. Anything that
+ * does not exactly cover whole cells stays a {@link TileCollisionShape}, which
+ * does keep its source object.
+ * @advanced
+ */
+export interface TileCollisionRect {
+    /** Left edge in layer pixel space. */
+    readonly x: number;
+    /** Top edge in layer pixel space. */
+    readonly y: number;
+    /** Width in pixels (a whole number of tile cells). */
+    readonly width: number;
+    /** Height in pixels (a whole number of tile cells). */
+    readonly height: number;
+    /** Class/type string shared by every source shape merged into this rectangle. */
+    readonly type: string;
+}
+/**
+ * A per-tile collision shape placed in tile-layer pixel space (+Y down).
+ *
+ * Emitted for every collision shape that does not exactly cover a whole tile
+ * cell: partial boxes, ellipses, polygons, polylines, points, and rotated
+ * geometry. Shapes are never merged with one another.
+ * @advanced
+ */
+export interface TileCollisionShape {
+    /** Geometry discriminant. */
+    readonly kind: TileCollisionShapeKind;
+    /** X of the shape origin in layer pixel space. */
+    readonly x: number;
+    /** Y of the shape origin in layer pixel space. */
+    readonly y: number;
+    /** Bounding width in px (`0` for polygons, polylines and points). */
+    readonly width: number;
+    /** Bounding height in px (`0` for polygons, polylines and points). */
+    readonly height: number;
+    /**
+     * Rotation in degrees, clockwise, about `(x, y)`, normalised to `[0, 360)`.
+     * Always `0` for polygons and polylines - their rotation is baked into
+     * {@link points}.
+     */
+    readonly rotation: number;
+    /** Polygon/polyline vertices relative to `(x, y)`; absent for other kinds. */
+    readonly points?: readonly ObjectPoint[];
+    /** Tile column the shape came from. */
+    readonly tx: number;
+    /** Tile row the shape came from. */
+    readonly ty: number;
+    /** The tile-local source object, for `name`/`type`/`properties` lookups. */
+    readonly source: TileMapObject;
+}
+/**
+ * Collision geometry extracted from a tile layer: whole-cell boxes merged into
+ * as few {@link TileCollisionRect}s as a greedy pass can manage, plus every
+ * other shape passed through individually.
+ * @advanced
+ */
+export interface TileCollisionGeometry {
+    /** Merged whole-cell rectangles, in row-major order. */
+    readonly rects: readonly TileCollisionRect[];
+    /** Non-whole-cell shapes, in the order their tiles were walked. */
+    readonly shapes: readonly TileCollisionShape[];
+}
+/**
+ * Per-cell collision classification for a tile layer, independent of the tiles
+ * the layer renders.
+ *
+ * Returns the class/type string for the cell, or `null` when the cell carries
+ * no collision. The string is opaque: it is the merge key for adjacent cells
+ * and reaches the consumer unchanged, exactly like the `type` of a tile
+ * collision object.
+ *
+ * A source is sampled while geometry is being built and is expected to answer
+ * identically for as long as the geometry is used. Changing what it returns
+ * does not invalidate geometry that was already built; rebuild instead.
+ * @advanced
+ */
+export type TileCellSource = (tx: number, ty: number) => string | null;
+/**
+ * Options for {@link buildTileCollisionGeometry}.
+ * @advanced
+ */
+export interface TileCollisionOptions {
+    /**
+     * Tile-coordinate region to walk. Defaults to the bounding box of the
+     * layer's currently loaded chunks, so an unbounded (streamed) layer works
+     * without the caller computing anything - or, with {@link cells} on a
+     * bounded layer, to the layer's full tile extent.
+     */
+    readonly region?: TileRegion;
+    /**
+     * Second occupancy source, consulted once per cell of the walked region in
+     * addition to the tiles' own collision shapes. Lets collision authored per
+     * cell rather than per tile reach the same geometry, without the layer
+     * having to render a tile there.
+     */
+    readonly cells?: TileCellSource | undefined;
+    /**
+     * Merge adjacent whole-cell boxes that share a `type` into larger
+     * rectangles. Default `true`. With `false`, every whole-cell box becomes its
+     * own single-cell rectangle.
+     */
+    readonly merge?: boolean;
+    /**
+     * Drop source shapes before any geometry is built (e.g. by a custom
+     * property). Return `true` to keep a shape. Default keeps all of them.
+     */
+    readonly accept?: (object: TileMapObject, tx: number, ty: number) => boolean;
+}
+/**
+ * Extract collision geometry from a tile layer's per-tile
+ * {@link import('./types').TileDefinition.collision} shapes.
+ *
+ * Every placed tile in `region` is resolved back to its tileset definition, and
+ * each collision shape is transformed from tile-local pixel space into layer
+ * pixel space (+Y down) - applying the tile's flip/rotation transform, the
+ * tileset draw offset, and the layer's pixel offset, so the geometry lands
+ * exactly where the tile is drawn.
+ *
+ * Shapes that end up covering exactly one whole tile cell are collected into an
+ * occupancy grid and merged into as few {@link TileCollisionRect}s as a greedy
+ * pass manages - a 200×200 solid region becomes one rectangle instead of 40 000.
+ * Cells only merge with neighbours whose source object carries the same `type`
+ * string, so a `water` run never fuses into an adjacent `solid` run. Everything
+ * else (partial boxes, ellipses, polygons, polylines, points, rotated geometry)
+ * passes through individually as a {@link TileCollisionShape}.
+ *
+ * A {@link TileCollisionOptions.cells} source feeds the same occupancy grid
+ * from outside the tiles, for collision authored per cell rather than per tile.
+ * It is consulted first, so a whole-cell tile box landing on a cell the source
+ * already claimed passes through as a shape rather than overwriting it. With a
+ * cell source and no explicit region, a bounded layer walks its full tile
+ * extent - a layer that renders nothing at all still produces geometry.
+ *
+ * This package has no physics dependency and builds no bodies: the result is
+ * plain geometry. Turning it into colliders is a short loop in application code.
+ *
+ * @param layer - The layer to walk.
+ * @param options - Region scoping, merge toggle, a source-shape filter, and an
+ *                  optional per-cell occupancy source.
+ * @returns Merged rectangles plus pass-through shapes; both empty when the
+ *          region holds no tile carrying collision data.
+ *
+ * @example
+ * ```ts
+ * const { rects, shapes } = buildTileCollisionGeometry(layer);
+ *
+ * for (const rect of rects) {
+ *   world.add(makeStaticBox(rect.x, rect.y, rect.width, rect.height));
+ * }
+ * ```
+ * @advanced
+ */
+export declare const buildTileCollisionGeometry: (layer: TileLayer, options?: TileCollisionOptions) => TileCollisionGeometry;
+//# sourceMappingURL=tileCollision.d.ts.map

package/dist/esm/tileCollision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tileCollision.d.ts","sourceRoot":"","sources":["../../src/tileCollision.ts"],"names":[],"mappings":"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"}

package/dist/esm/tileCollision.js

@@ -0,0 +1,367 @@
+import { ObjectKind } from "./ObjectLayer.js";
+
+//#region src/tileCollision.ts
+const DEGREES_TO_RADIANS = Math.PI / 180;
+/** Normalise degrees into `[0, 360)`. */
+const normaliseDegrees = (degrees) => {
+	const wrapped = degrees % 360;
+	return wrapped < 0 ? wrapped + 360 : wrapped;
+};
+/**
+* Cosine of an angle in degrees, exact on the quadrant multiples.
+* `Math.cos(Math.PI / 2)` is `6.1e-17`, not `0`; tile transforms produce those
+* quadrant angles constantly, and the whole-cell test below compares
+* coordinates exactly, so the noise has to stay out of the arithmetic.
+*/
+const cosDegrees = (degrees) => {
+	const angle = normaliseDegrees(degrees);
+	if (angle === 0) return 1;
+	if (angle === 90 || angle === 270) return 0;
+	if (angle === 180) return -1;
+	return Math.cos(angle * DEGREES_TO_RADIANS);
+};
+/** Sine of an angle in degrees, exact on the quadrant multiples. */
+const sinDegrees = (degrees) => {
+	const angle = normaliseDegrees(degrees);
+	if (angle === 0 || angle === 180) return 0;
+	if (angle === 90) return 1;
+	if (angle === 270) return -1;
+	return Math.sin(angle * DEGREES_TO_RADIANS);
+};
+/** `true` when the transform mirrors (an odd number of reflections). */
+const isMirrored = (transform) => {
+	return ((transform.flipX ? 1 : 0) + (transform.flipY ? 1 : 0) + (transform.diagonal ? 1 : 0)) % 2 === 1;
+};
+/**
+* Rotation in degrees contributed by a non-mirroring transform. Only the four
+* even-parity transforms are rotations: identity, `flipX+flipY` (180°),
+* `diagonal+flipX` (90°) and `diagonal+flipY` (270°).
+*/
+const transformRotation = (transform) => {
+	if (transform.diagonal) return transform.flipX ? 90 : 270;
+	return transform.flipX ? 180 : 0;
+};
+/**
+* Map a point from tile-local pixel space into the transformed tile-local
+* space of a placed tile. The diagonal flip (a transpose of the axes, which
+* also swaps the box dimensions) is applied first, then the axis mirrors -
+* the same order the renderer's orientation code implies.
+*/
+const mapLocalPoint = (px, py, boxWidth, boxHeight, transform) => {
+	let x = px;
+	let y = py;
+	let width = boxWidth;
+	let height = boxHeight;
+	if (transform.diagonal) {
+		const swapped = x;
+		x = y;
+		y = swapped;
+		width = boxHeight;
+		height = boxWidth;
+	}
+	if (transform.flipX) x = width - x;
+	if (transform.flipY) y = height - y;
+	return {
+		x,
+		y
+	};
+};
+/**
+* Layer-space position of a placed tile's top-left image corner. Mirrors the
+* renderer's placement (see `chunkGeometry`): the tileset's draw offset shifts
+* every tile, and a tile taller than the layer's cell is bottom-aligned within
+* it, so collision geometry lands exactly where the tile is drawn.
+*/
+const tileAnchor = (layer, tileset, tx, ty) => ({
+	x: tx * layer.tileWidth + layer.offsetX + tileset.offsetX,
+	y: ty * layer.tileHeight + layer.offsetY + layer.tileHeight - tileset.tileHeight + tileset.offsetY
+});
+/**
+* Place one tile-local collision object into layer pixel space, applying the
+* tile's flip/rotation transform, the tileset draw offset and the layer offset.
+* Returns `null` for kinds that carry no collision geometry.
+*/
+const placeShape = (object, layer, tileset, transform, tx, ty) => {
+	if (object.kind === ObjectKind.Tile || object.kind === ObjectKind.Text) return null;
+	const anchor = tileAnchor(layer, tileset, tx, ty);
+	const boxWidth = tileset.tileWidth;
+	const boxHeight = tileset.tileHeight;
+	const mirrored = isMirrored(transform);
+	const sourceCos = cosDegrees(object.rotation);
+	const sourceSin = sinDegrees(object.rotation);
+	if (object.kind === ObjectKind.Polygon || object.kind === ObjectKind.Polyline) {
+		const origin = mapLocalPoint(object.x, object.y, boxWidth, boxHeight, transform);
+		const originX = anchor.x + origin.x;
+		const originY = anchor.y + origin.y;
+		const points = object.points.map((point) => {
+			const localX = object.x + (sourceCos * point.x - sourceSin * point.y);
+			const localY = object.y + (sourceSin * point.x + sourceCos * point.y);
+			const mapped = mapLocalPoint(localX, localY, boxWidth, boxHeight, transform);
+			return {
+				x: anchor.x + mapped.x - originX,
+				y: anchor.y + mapped.y - originY
+			};
+		});
+		return {
+			kind: object.kind,
+			x: originX,
+			y: originY,
+			width: 0,
+			height: 0,
+			rotation: 0,
+			points: mirrored ? points.reverse() : points
+		};
+	}
+	if (object.kind === ObjectKind.Point) {
+		const mapped = mapLocalPoint(object.x, object.y, boxWidth, boxHeight, transform);
+		return {
+			kind: ObjectKind.Point,
+			x: anchor.x + mapped.x,
+			y: anchor.y + mapped.y,
+			width: 0,
+			height: 0,
+			rotation: 0
+		};
+	}
+	const halfWidth = object.width / 2;
+	const halfHeight = object.height / 2;
+	const centreLocalX = object.x + (sourceCos * halfWidth - sourceSin * halfHeight);
+	const centreLocalY = object.y + (sourceSin * halfWidth + sourceCos * halfHeight);
+	const centre = mapLocalPoint(centreLocalX, centreLocalY, boxWidth, boxHeight, transform);
+	const centreX = anchor.x + centre.x;
+	const centreY = anchor.y + centre.y;
+	const rotation = normaliseDegrees(mirrored ? -object.rotation : object.rotation + transformRotation(transform));
+	const swapAxes = mirrored && transform.diagonal;
+	const width = swapAxes ? object.height : object.width;
+	const height = swapAxes ? object.width : object.height;
+	if (rotation % 90 === 0) {
+		const axisWidth = rotation % 180 === 0 ? width : height;
+		const axisHeight = rotation % 180 === 0 ? height : width;
+		return {
+			kind: object.kind,
+			x: centreX - axisWidth / 2,
+			y: centreY - axisHeight / 2,
+			width: axisWidth,
+			height: axisHeight,
+			rotation: 0
+		};
+	}
+	const cos = cosDegrees(rotation);
+	const sin = sinDegrees(rotation);
+	return {
+		kind: object.kind,
+		x: centreX - (cos * (width / 2) - sin * (height / 2)),
+		y: centreY - (sin * (width / 2) + cos * (height / 2)),
+		width,
+		height,
+		rotation
+	};
+};
+/** The tile-coordinate bounding box of the layer's loaded chunks, or `null`. */
+const loadedTileRegion = (layer) => {
+	let minTx = Number.POSITIVE_INFINITY;
+	let minTy = Number.POSITIVE_INFINITY;
+	let maxTx = Number.NEGATIVE_INFINITY;
+	let maxTy = Number.NEGATIVE_INFINITY;
+	for (const chunk of layer.loadedChunks()) {
+		const startTx = chunk.cx * layer.chunkWidth;
+		const startTy = chunk.cy * layer.chunkHeight;
+		minTx = Math.min(minTx, startTx);
+		minTy = Math.min(minTy, startTy);
+		maxTx = Math.max(maxTx, startTx + chunk.width - 1);
+		maxTy = Math.max(maxTy, startTy + chunk.height - 1);
+	}
+	if (!Number.isFinite(minTx) || !Number.isFinite(minTy)) return null;
+	return {
+		x: minTx,
+		y: minTy,
+		width: maxTx - minTx + 1,
+		height: maxTy - minTy + 1
+	};
+};
+/**
+* Region a cell source spans on `layer`: the full tile extent of a bounded
+* layer, `null` when the layer is unbounded and the caller must scope the
+* walk itself. Chunk residency deliberately plays no part - the classification
+* lives outside the layer, so loaded chunks cannot define its domain.
+*/
+const cellSourceRegion = (layer) => {
+	if (layer.width === void 0 || layer.height === void 0) return null;
+	return {
+		x: 0,
+		y: 0,
+		width: layer.width,
+		height: layer.height
+	};
+};
+/**
+* The region to walk: the caller's, else the extent a cell source spans, else
+* whatever is currently resident. `null` when there is nothing to walk.
+*/
+const resolveRegion = (layer, options) => {
+	if (options.region !== void 0) return options.region;
+	return (options.cells !== void 0 ? cellSourceRegion(layer) : null) ?? loadedTileRegion(layer);
+};
+/** Claim every cell of `region` the source classifies, into the occupancy grid. */
+const claimSourceCells = (cells, region, source) => {
+	const endTx = region.x + region.width;
+	const endTy = region.y + region.height;
+	for (let ty = region.y; ty < endTy; ty++) for (let tx = region.x; tx < endTx; tx++) {
+		const type = source(tx, ty);
+		if (type !== null) cells.set(cellKey(tx, ty), type);
+	}
+};
+/** Key of a claimed cell in the occupancy grid. */
+const cellKey = (tx, ty) => `${tx},${ty}`;
+/**
+* `true` when a placed shape is an axis-aligned rectangle covering exactly the
+* tile cell at `(cellX, cellY)` - the only geometry the merging pass handles.
+*/
+const coversWholeCell = (placed, layer, cellX, cellY) => placed.kind === ObjectKind.Rectangle && placed.rotation === 0 && placed.x === cellX && placed.y === cellY && placed.width === layer.tileWidth && placed.height === layer.tileHeight;
+/** One single-cell rectangle per claimed cell, for `merge: false`. */
+const unmergedCells = (cells, layer) => {
+	const rects = [];
+	for (const [key, type] of cells) {
+		const [tx, ty] = key.split(",").map(Number);
+		rects.push({
+			x: tx * layer.tileWidth + layer.offsetX,
+			y: ty * layer.tileHeight + layer.offsetY,
+			width: layer.tileWidth,
+			height: layer.tileHeight,
+			type
+		});
+	}
+	return rects;
+};
+/**
+* Greedy rectangle merging over the claimed cells: walk row-major, grow each
+* unconsumed cell as far right as the type key allows, then as far down as a
+* full row of that width allows, and consume the block. Deliberately the plain
+* textbook pass - it is linear in the number of cells and always produces a
+* valid, non-overlapping cover, which matters more here than minimality.
+*/
+const mergeCells = (cells, region, layer) => {
+	const consumed = /* @__PURE__ */ new Set();
+	const rects = [];
+	const endTx = region.x + region.width;
+	const endTy = region.y + region.height;
+	for (let ty = region.y; ty < endTy; ty++) for (let tx = region.x; tx < endTx; tx++) {
+		const key = cells.get(cellKey(tx, ty));
+		if (key === void 0 || consumed.has(cellKey(tx, ty))) continue;
+		let width = 1;
+		while (tx + width < endTx && cells.get(cellKey(tx + width, ty)) === key && !consumed.has(cellKey(tx + width, ty))) width++;
+		let height = 1;
+		growDown: while (ty + height < endTy) {
+			for (let column = 0; column < width; column++) {
+				const candidate = cellKey(tx + column, ty + height);
+				if (cells.get(candidate) !== key || consumed.has(candidate)) break growDown;
+			}
+			height++;
+		}
+		for (let row = 0; row < height; row++) for (let column = 0; column < width; column++) consumed.add(cellKey(tx + column, ty + row));
+		rects.push({
+			x: tx * layer.tileWidth + layer.offsetX,
+			y: ty * layer.tileHeight + layer.offsetY,
+			width: width * layer.tileWidth,
+			height: height * layer.tileHeight,
+			type: key
+		});
+	}
+	return rects;
+};
+/**
+* Extract collision geometry from a tile layer's per-tile
+* {@link import('./types').TileDefinition.collision} shapes.
+*
+* Every placed tile in `region` is resolved back to its tileset definition, and
+* each collision shape is transformed from tile-local pixel space into layer
+* pixel space (+Y down) - applying the tile's flip/rotation transform, the
+* tileset draw offset, and the layer's pixel offset, so the geometry lands
+* exactly where the tile is drawn.
+*
+* Shapes that end up covering exactly one whole tile cell are collected into an
+* occupancy grid and merged into as few {@link TileCollisionRect}s as a greedy
+* pass manages - a 200×200 solid region becomes one rectangle instead of 40 000.
+* Cells only merge with neighbours whose source object carries the same `type`
+* string, so a `water` run never fuses into an adjacent `solid` run. Everything
+* else (partial boxes, ellipses, polygons, polylines, points, rotated geometry)
+* passes through individually as a {@link TileCollisionShape}.
+*
+* A {@link TileCollisionOptions.cells} source feeds the same occupancy grid
+* from outside the tiles, for collision authored per cell rather than per tile.
+* It is consulted first, so a whole-cell tile box landing on a cell the source
+* already claimed passes through as a shape rather than overwriting it. With a
+* cell source and no explicit region, a bounded layer walks its full tile
+* extent - a layer that renders nothing at all still produces geometry.
+*
+* This package has no physics dependency and builds no bodies: the result is
+* plain geometry. Turning it into colliders is a short loop in application code.
+*
+* @param layer - The layer to walk.
+* @param options - Region scoping, merge toggle, a source-shape filter, and an
+*                  optional per-cell occupancy source.
+* @returns Merged rectangles plus pass-through shapes; both empty when the
+*          region holds no tile carrying collision data.
+*
+* @example
+* ```ts
+* const { rects, shapes } = buildTileCollisionGeometry(layer);
+*
+* for (const rect of rects) {
+*   world.add(makeStaticBox(rect.x, rect.y, rect.width, rect.height));
+* }
+* ```
+* @advanced
+*/
+const buildTileCollisionGeometry = (layer, options = {}) => {
+	const cellSource = options.cells;
+	const region = resolveRegion(layer, options);
+	if (region === null || region.width <= 0 || region.height <= 0) return {
+		rects: [],
+		shapes: []
+	};
+	const accept = options.accept;
+	const cells = /* @__PURE__ */ new Map();
+	const shapes = [];
+	if (cellSource !== void 0) claimSourceCells(cells, region, cellSource);
+	for (const { tx, ty, tile } of layer.tilesInRect(region.x, region.y, region.width, region.height)) {
+		const definition = tile.tileset.getTileDefinition(tile.localTileId);
+		if (definition?.collision === void 0) continue;
+		const cellX = tx * layer.tileWidth + layer.offsetX;
+		const cellY = ty * layer.tileHeight + layer.offsetY;
+		for (const object of definition.collision) {
+			if (accept !== void 0 && !accept(object, tx, ty)) continue;
+			const placed = placeShape(object, layer, tile.tileset, tile.transform, tx, ty);
+			if (placed === null) continue;
+			const key = cellKey(tx, ty);
+			if (coversWholeCell(placed, layer, cellX, cellY) && !cells.has(key)) {
+				cells.set(key, object.type);
+				continue;
+			}
+			shapes.push({
+				kind: placed.kind,
+				x: placed.x,
+				y: placed.y,
+				width: placed.width,
+				height: placed.height,
+				rotation: placed.rotation,
+				...placed.points !== void 0 && { points: placed.points },
+				tx,
+				ty,
+				source: object
+			});
+		}
+	}
+	if (cells.size === 0) return {
+		rects: [],
+		shapes
+	};
+	return {
+		rects: options.merge === false ? unmergedCells(cells, layer) : mergeCells(cells, region, layer),
+		shapes
+	};
+};
+
+//#endregion
+export { buildTileCollisionGeometry };
+//# sourceMappingURL=tileCollision.js.map

package/dist/esm/tileCollision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tileCollision.js","names":[],"sources":["../../src/tileCollision.ts"],"sourcesContent":["import type { ObjectPoint, TileMapObject } from './ObjectLayer';\nimport { ObjectKind } from './ObjectLayer';\nimport type { TileLayer } from './TileLayer';\nimport type { TileSet } from './TileSet';\nimport type { TileTransform } from './types';\n\n/**\n * The geometry kinds a {@link TileCollisionShape} can carry. Tile (GID) and\n * text objects describe no collision area and are never emitted, so they are\n * excluded from the union.\n * @advanced\n */\nexport type TileCollisionShapeKind =\n  typeof ObjectKind.Rectangle | typeof ObjectKind.Ellipse | typeof ObjectKind.Polygon | typeof ObjectKind.Polyline | typeof ObjectKind.Point;\n\n/**\n * A half-open tile-coordinate rectangle covering\n * `[x, x + width)` × `[y, y + height)`.\n *\n * Used to scope {@link buildTileCollisionGeometry} to part of a layer - a\n * streamed chunk, the tiles around the player, a hand-picked room - instead of\n * always rebuilding the whole map.\n * @advanced\n */\nexport interface TileRegion {\n  /** Leftmost tile column (inclusive). */\n  readonly x: number;\n  /** Topmost tile row (inclusive). */\n  readonly y: number;\n  /** Width in tiles. */\n  readonly width: number;\n  /** Height in tiles. */\n  readonly height: number;\n}\n\n/**\n * An axis-aligned collision rectangle in tile-layer pixel space (+Y down),\n * covering one or more whole tile cells.\n *\n * Rectangles are synthesized geometry, not source objects: a merged run has no\n * single originating object, so it carries no object `id`/`name`/`properties` -\n * only the `type` string shared by every shape merged into it. Anything that\n * does not exactly cover whole cells stays a {@link TileCollisionShape}, which\n * does keep its source object.\n * @advanced\n */\nexport interface TileCollisionRect {\n  /** Left edge in layer pixel space. */\n  readonly x: number;\n  /** Top edge in layer pixel space. */\n  readonly y: number;\n  /** Width in pixels (a whole number of tile cells). */\n  readonly width: number;\n  /** Height in pixels (a whole number of tile cells). */\n  readonly height: number;\n  /** Class/type string shared by every source shape merged into this rectangle. */\n  readonly type: string;\n}\n\n/**\n * A per-tile collision shape placed in tile-layer pixel space (+Y down).\n *\n * Emitted for every collision shape that does not exactly cover a whole tile\n * cell: partial boxes, ellipses, polygons, polylines, points, and rotated\n * geometry. Shapes are never merged with one another.\n * @advanced\n */\nexport interface TileCollisionShape {\n  /** Geometry discriminant. */\n  readonly kind: TileCollisionShapeKind;\n  /** X of the shape origin in layer pixel space. */\n  readonly x: number;\n  /** Y of the shape origin in layer pixel space. */\n  readonly y: number;\n  /** Bounding width in px (`0` for polygons, polylines and points). */\n  readonly width: number;\n  /** Bounding height in px (`0` for polygons, polylines and points). */\n  readonly height: number;\n  /**\n   * Rotation in degrees, clockwise, about `(x, y)`, normalised to `[0, 360)`.\n   * Always `0` for polygons and polylines - their rotation is baked into\n   * {@link points}.\n   */\n  readonly rotation: number;\n  /** Polygon/polyline vertices relative to `(x, y)`; absent for other kinds. */\n  readonly points?: readonly ObjectPoint[];\n  /** Tile column the shape came from. */\n  readonly tx: number;\n  /** Tile row the shape came from. */\n  readonly ty: number;\n  /** The tile-local source object, for `name`/`type`/`properties` lookups. */\n  readonly source: TileMapObject;\n}\n\n/**\n * Collision geometry extracted from a tile layer: whole-cell boxes merged into\n * as few {@link TileCollisionRect}s as a greedy pass can manage, plus every\n * other shape passed through individually.\n * @advanced\n */\nexport interface TileCollisionGeometry {\n  /** Merged whole-cell rectangles, in row-major order. */\n  readonly rects: readonly TileCollisionRect[];\n  /** Non-whole-cell shapes, in the order their tiles were walked. */\n  readonly shapes: readonly TileCollisionShape[];\n}\n\n/**\n * Per-cell collision classification for a tile layer, independent of the tiles\n * the layer renders.\n *\n * Returns the class/type string for the cell, or `null` when the cell carries\n * no collision. The string is opaque: it is the merge key for adjacent cells\n * and reaches the consumer unchanged, exactly like the `type` of a tile\n * collision object.\n *\n * A source is sampled while geometry is being built and is expected to answer\n * identically for as long as the geometry is used. Changing what it returns\n * does not invalidate geometry that was already built; rebuild instead.\n * @advanced\n */\nexport type TileCellSource = (tx: number, ty: number) => string | null;\n\n/**\n * Options for {@link buildTileCollisionGeometry}.\n * @advanced\n */\nexport interface TileCollisionOptions {\n  /**\n   * Tile-coordinate region to walk. Defaults to the bounding box of the\n   * layer's currently loaded chunks, so an unbounded (streamed) layer works\n   * without the caller computing anything - or, with {@link cells} on a\n   * bounded layer, to the layer's full tile extent.\n   */\n  readonly region?: TileRegion;\n  /**\n   * Second occupancy source, consulted once per cell of the walked region in\n   * addition to the tiles' own collision shapes. Lets collision authored per\n   * cell rather than per tile reach the same geometry, without the layer\n   * having to render a tile there.\n   */\n  readonly cells?: TileCellSource | undefined;\n  /**\n   * Merge adjacent whole-cell boxes that share a `type` into larger\n   * rectangles. Default `true`. With `false`, every whole-cell box becomes its\n   * own single-cell rectangle.\n   */\n  readonly merge?: boolean;\n  /**\n   * Drop source shapes before any geometry is built (e.g. by a custom\n   * property). Return `true` to keep a shape. Default keeps all of them.\n   */\n  readonly accept?: (object: TileMapObject, tx: number, ty: number) => boolean;\n}\n\nconst DEGREES_TO_RADIANS = Math.PI / 180;\n\n/** Normalise degrees into `[0, 360)`. */\nconst normaliseDegrees = (degrees: number): number => {\n  const wrapped = degrees % 360;\n\n  return wrapped < 0 ? wrapped + 360 : wrapped;\n};\n\n/**\n * Cosine of an angle in degrees, exact on the quadrant multiples.\n * `Math.cos(Math.PI / 2)` is `6.1e-17`, not `0`; tile transforms produce those\n * quadrant angles constantly, and the whole-cell test below compares\n * coordinates exactly, so the noise has to stay out of the arithmetic.\n */\nconst cosDegrees = (degrees: number): number => {\n  const angle = normaliseDegrees(degrees);\n\n  if (angle === 0) return 1;\n  if (angle === 90 || angle === 270) return 0;\n  if (angle === 180) return -1;\n\n  return Math.cos(angle * DEGREES_TO_RADIANS);\n};\n\n/** Sine of an angle in degrees, exact on the quadrant multiples. */\nconst sinDegrees = (degrees: number): number => {\n  const angle = normaliseDegrees(degrees);\n\n  if (angle === 0 || angle === 180) return 0;\n  if (angle === 90) return 1;\n  if (angle === 270) return -1;\n\n  return Math.sin(angle * DEGREES_TO_RADIANS);\n};\n\n/** `true` when the transform mirrors (an odd number of reflections). */\nconst isMirrored = (transform: TileTransform): boolean => {\n  const flags = (transform.flipX ? 1 : 0) + (transform.flipY ? 1 : 0) + (transform.diagonal ? 1 : 0);\n\n  return flags % 2 === 1;\n};\n\n/**\n * Rotation in degrees contributed by a non-mirroring transform. Only the four\n * even-parity transforms are rotations: identity, `flipX+flipY` (180°),\n * `diagonal+flipX` (90°) and `diagonal+flipY` (270°).\n */\nconst transformRotation = (transform: TileTransform): number => {\n  if (transform.diagonal) {\n    return transform.flipX ? 90 : 270;\n  }\n\n  return transform.flipX ? 180 : 0;\n};\n\n/**\n * Map a point from tile-local pixel space into the transformed tile-local\n * space of a placed tile. The diagonal flip (a transpose of the axes, which\n * also swaps the box dimensions) is applied first, then the axis mirrors -\n * the same order the renderer's orientation code implies.\n */\nconst mapLocalPoint = (px: number, py: number, boxWidth: number, boxHeight: number, transform: TileTransform): ObjectPoint => {\n  let x = px;\n  let y = py;\n  let width = boxWidth;\n  let height = boxHeight;\n\n  if (transform.diagonal) {\n    const swapped = x;\n\n    x = y;\n    y = swapped;\n    width = boxHeight;\n    height = boxWidth;\n  }\n\n  if (transform.flipX) x = width - x;\n  if (transform.flipY) y = height - y;\n\n  return { x, y };\n};\n\n/**\n * Layer-space position of a placed tile's top-left image corner. Mirrors the\n * renderer's placement (see `chunkGeometry`): the tileset's draw offset shifts\n * every tile, and a tile taller than the layer's cell is bottom-aligned within\n * it, so collision geometry lands exactly where the tile is drawn.\n */\nconst tileAnchor = (layer: TileLayer, tileset: TileSet, tx: number, ty: number): ObjectPoint => ({\n  x: tx * layer.tileWidth + layer.offsetX + tileset.offsetX,\n  y: ty * layer.tileHeight + layer.offsetY + layer.tileHeight - tileset.tileHeight + tileset.offsetY,\n});\n\n/** A shape in layer pixel space, before it is classified as cell or shape. */\ninterface PlacedShape {\n  readonly kind: TileCollisionShapeKind;\n  readonly x: number;\n  readonly y: number;\n  readonly width: number;\n  readonly height: number;\n  readonly rotation: number;\n  readonly points?: readonly ObjectPoint[];\n}\n\n/**\n * Place one tile-local collision object into layer pixel space, applying the\n * tile's flip/rotation transform, the tileset draw offset and the layer offset.\n * Returns `null` for kinds that carry no collision geometry.\n */\nconst placeShape = (object: TileMapObject, layer: TileLayer, tileset: TileSet, transform: TileTransform, tx: number, ty: number): PlacedShape | null => {\n  if (object.kind === ObjectKind.Tile || object.kind === ObjectKind.Text) {\n    return null;\n  }\n\n  const anchor = tileAnchor(layer, tileset, tx, ty);\n  const boxWidth = tileset.tileWidth;\n  const boxHeight = tileset.tileHeight;\n  const mirrored = isMirrored(transform);\n  const sourceCos = cosDegrees(object.rotation);\n  const sourceSin = sinDegrees(object.rotation);\n\n  if (object.kind === ObjectKind.Polygon || object.kind === ObjectKind.Polyline) {\n    // Rotation is baked into the vertices: the source rotation pivots about the\n    // object origin, and the tile transform may mirror the whole tile, so an\n    // origin-plus-angle form would need a second angle convention. Absolute\n    // vertices are exact under both.\n    const origin = mapLocalPoint(object.x, object.y, boxWidth, boxHeight, transform);\n    const originX = anchor.x + origin.x;\n    const originY = anchor.y + origin.y;\n    const points = object.points.map(point => {\n      const localX = object.x + (sourceCos * point.x - sourceSin * point.y);\n      const localY = object.y + (sourceSin * point.x + sourceCos * point.y);\n      const mapped = mapLocalPoint(localX, localY, boxWidth, boxHeight, transform);\n\n      return { x: anchor.x + mapped.x - originX, y: anchor.y + mapped.y - originY };\n    });\n\n    return {\n      kind: object.kind,\n      x: originX,\n      y: originY,\n      width: 0,\n      height: 0,\n      rotation: 0,\n      // A mirror reverses the winding order; reversing the vertices restores\n      // the source orientation, which convex-hull/polygon consumers rely on.\n      points: mirrored ? points.reverse() : points,\n    };\n  }\n\n  if (object.kind === ObjectKind.Point) {\n    const mapped = mapLocalPoint(object.x, object.y, boxWidth, boxHeight, transform);\n\n    return {\n      kind: ObjectKind.Point,\n      x: anchor.x + mapped.x,\n      y: anchor.y + mapped.y,\n      width: 0,\n      height: 0,\n      rotation: 0,\n    };\n  }\n\n  // Rectangles and ellipses are symmetric about their centre, so placing the\n  // centre and re-deriving the origin handles every transform uniformly.\n  const halfWidth = object.width / 2;\n  const halfHeight = object.height / 2;\n  const centreLocalX = object.x + (sourceCos * halfWidth - sourceSin * halfHeight);\n  const centreLocalY = object.y + (sourceSin * halfWidth + sourceCos * halfHeight);\n  const centre = mapLocalPoint(centreLocalX, centreLocalY, boxWidth, boxHeight, transform);\n  const centreX = anchor.x + centre.x;\n  const centreY = anchor.y + centre.y;\n\n  // Conjugating a rotation by a mirror negates it; a non-mirroring transform is\n  // itself a rotation and simply adds. Only a mirror can swap the local axes,\n  // and then only when the diagonal flip is part of it.\n  const rotation = normaliseDegrees(mirrored ? -object.rotation : object.rotation + transformRotation(transform));\n  const swapAxes = mirrored && transform.diagonal;\n  const width = swapAxes ? object.height : object.width;\n  const height = swapAxes ? object.width : object.height;\n\n  if (rotation % 90 === 0) {\n    // Quadrant-aligned geometry is axis-aligned; re-express it without a\n    // rotation so whole-cell boxes on rotated tiles stay mergeable.\n    const axisWidth = rotation % 180 === 0 ? width : height;\n    const axisHeight = rotation % 180 === 0 ? height : width;\n\n    return {\n      kind: object.kind,\n      x: centreX - axisWidth / 2,\n      y: centreY - axisHeight / 2,\n      width: axisWidth,\n      height: axisHeight,\n      rotation: 0,\n    };\n  }\n\n  const cos = cosDegrees(rotation);\n  const sin = sinDegrees(rotation);\n\n  return {\n    kind: object.kind,\n    x: centreX - (cos * (width / 2) - sin * (height / 2)),\n    y: centreY - (sin * (width / 2) + cos * (height / 2)),\n    width,\n    height,\n    rotation,\n  };\n};\n\n/** The tile-coordinate bounding box of the layer's loaded chunks, or `null`. */\nconst loadedTileRegion = (layer: TileLayer): TileRegion | null => {\n  let minTx = Number.POSITIVE_INFINITY;\n  let minTy = Number.POSITIVE_INFINITY;\n  let maxTx = Number.NEGATIVE_INFINITY;\n  let maxTy = Number.NEGATIVE_INFINITY;\n\n  for (const chunk of layer.loadedChunks()) {\n    const startTx = chunk.cx * layer.chunkWidth;\n    const startTy = chunk.cy * layer.chunkHeight;\n\n    minTx = Math.min(minTx, startTx);\n    minTy = Math.min(minTy, startTy);\n    maxTx = Math.max(maxTx, startTx + chunk.width - 1);\n    maxTy = Math.max(maxTy, startTy + chunk.height - 1);\n  }\n\n  if (!Number.isFinite(minTx) || !Number.isFinite(minTy)) {\n    return null;\n  }\n\n  return { x: minTx, y: minTy, width: maxTx - minTx + 1, height: maxTy - minTy + 1 };\n};\n\n/**\n * Region a cell source spans on `layer`: the full tile extent of a bounded\n * layer, `null` when the layer is unbounded and the caller must scope the\n * walk itself. Chunk residency deliberately plays no part - the classification\n * lives outside the layer, so loaded chunks cannot define its domain.\n */\nconst cellSourceRegion = (layer: TileLayer): TileRegion | null => {\n  if (layer.width === undefined || layer.height === undefined) {\n    return null;\n  }\n\n  return { x: 0, y: 0, width: layer.width, height: layer.height };\n};\n\n/**\n * The region to walk: the caller's, else the extent a cell source spans, else\n * whatever is currently resident. `null` when there is nothing to walk.\n */\nconst resolveRegion = (layer: TileLayer, options: TileCollisionOptions): TileRegion | null => {\n  if (options.region !== undefined) return options.region;\n\n  const fromCells = options.cells !== undefined ? cellSourceRegion(layer) : null;\n\n  return fromCells ?? loadedTileRegion(layer);\n};\n\n/** Claim every cell of `region` the source classifies, into the occupancy grid. */\nconst claimSourceCells = (cells: Map<string, string>, region: TileRegion, source: TileCellSource): void => {\n  const endTx = region.x + region.width;\n  const endTy = region.y + region.height;\n\n  for (let ty = region.y; ty < endTy; ty++) {\n    for (let tx = region.x; tx < endTx; tx++) {\n      const type = source(tx, ty);\n\n      if (type !== null) cells.set(cellKey(tx, ty), type);\n    }\n  }\n};\n\n/** Key of a claimed cell in the occupancy grid. */\nconst cellKey = (tx: number, ty: number): string => `${tx},${ty}`;\n\n/**\n * `true` when a placed shape is an axis-aligned rectangle covering exactly the\n * tile cell at `(cellX, cellY)` - the only geometry the merging pass handles.\n */\nconst coversWholeCell = (placed: PlacedShape, layer: TileLayer, cellX: number, cellY: number): boolean =>\n  placed.kind === ObjectKind.Rectangle &&\n  placed.rotation === 0 &&\n  placed.x === cellX &&\n  placed.y === cellY &&\n  placed.width === layer.tileWidth &&\n  placed.height === layer.tileHeight;\n\n/** One single-cell rectangle per claimed cell, for `merge: false`. */\nconst unmergedCells = (cells: ReadonlyMap<string, string>, layer: TileLayer): TileCollisionRect[] => {\n  const rects: TileCollisionRect[] = [];\n\n  for (const [key, type] of cells) {\n    const [tx, ty] = key.split(',').map(Number) as [number, number];\n\n    rects.push({\n      x: tx * layer.tileWidth + layer.offsetX,\n      y: ty * layer.tileHeight + layer.offsetY,\n      width: layer.tileWidth,\n      height: layer.tileHeight,\n      type,\n    });\n  }\n\n  return rects;\n};\n\n/**\n * Greedy rectangle merging over the claimed cells: walk row-major, grow each\n * unconsumed cell as far right as the type key allows, then as far down as a\n * full row of that width allows, and consume the block. Deliberately the plain\n * textbook pass - it is linear in the number of cells and always produces a\n * valid, non-overlapping cover, which matters more here than minimality.\n */\nconst mergeCells = (cells: ReadonlyMap<string, string>, region: TileRegion, layer: TileLayer): TileCollisionRect[] => {\n  const consumed = new Set<string>();\n  const rects: TileCollisionRect[] = [];\n  const endTx = region.x + region.width;\n  const endTy = region.y + region.height;\n\n  for (let ty = region.y; ty < endTy; ty++) {\n    for (let tx = region.x; tx < endTx; tx++) {\n      const key = cells.get(cellKey(tx, ty));\n\n      if (key === undefined || consumed.has(cellKey(tx, ty))) {\n        continue;\n      }\n\n      let width = 1;\n\n      while (tx + width < endTx && cells.get(cellKey(tx + width, ty)) === key && !consumed.has(cellKey(tx + width, ty))) {\n        width++;\n      }\n\n      let height = 1;\n\n      growDown: while (ty + height < endTy) {\n        for (let column = 0; column < width; column++) {\n          const candidate = cellKey(tx + column, ty + height);\n\n          if (cells.get(candidate) !== key || consumed.has(candidate)) {\n            break growDown;\n          }\n        }\n\n        height++;\n      }\n\n      for (let row = 0; row < height; row++) {\n        for (let column = 0; column < width; column++) {\n          consumed.add(cellKey(tx + column, ty + row));\n        }\n      }\n\n      rects.push({\n        x: tx * layer.tileWidth + layer.offsetX,\n        y: ty * layer.tileHeight + layer.offsetY,\n        width: width * layer.tileWidth,\n        height: height * layer.tileHeight,\n        type: key,\n      });\n    }\n  }\n\n  return rects;\n};\n\n/**\n * Extract collision geometry from a tile layer's per-tile\n * {@link import('./types').TileDefinition.collision} shapes.\n *\n * Every placed tile in `region` is resolved back to its tileset definition, and\n * each collision shape is transformed from tile-local pixel space into layer\n * pixel space (+Y down) - applying the tile's flip/rotation transform, the\n * tileset draw offset, and the layer's pixel offset, so the geometry lands\n * exactly where the tile is drawn.\n *\n * Shapes that end up covering exactly one whole tile cell are collected into an\n * occupancy grid and merged into as few {@link TileCollisionRect}s as a greedy\n * pass manages - a 200×200 solid region becomes one rectangle instead of 40 000.\n * Cells only merge with neighbours whose source object carries the same `type`\n * string, so a `water` run never fuses into an adjacent `solid` run. Everything\n * else (partial boxes, ellipses, polygons, polylines, points, rotated geometry)\n * passes through individually as a {@link TileCollisionShape}.\n *\n * A {@link TileCollisionOptions.cells} source feeds the same occupancy grid\n * from outside the tiles, for collision authored per cell rather than per tile.\n * It is consulted first, so a whole-cell tile box landing on a cell the source\n * already claimed passes through as a shape rather than overwriting it. With a\n * cell source and no explicit region, a bounded layer walks its full tile\n * extent - a layer that renders nothing at all still produces geometry.\n *\n * This package has no physics dependency and builds no bodies: the result is\n * plain geometry. Turning it into colliders is a short loop in application code.\n *\n * @param layer - The layer to walk.\n * @param options - Region scoping, merge toggle, a source-shape filter, and an\n *                  optional per-cell occupancy source.\n * @returns Merged rectangles plus pass-through shapes; both empty when the\n *          region holds no tile carrying collision data.\n *\n * @example\n * ```ts\n * const { rects, shapes } = buildTileCollisionGeometry(layer);\n *\n * for (const rect of rects) {\n *   world.add(makeStaticBox(rect.x, rect.y, rect.width, rect.height));\n * }\n * ```\n * @advanced\n */\nexport const buildTileCollisionGeometry = (layer: TileLayer, options: TileCollisionOptions = {}): TileCollisionGeometry => {\n  const cellSource = options.cells;\n  const region = resolveRegion(layer, options);\n\n  if (region === null || region.width <= 0 || region.height <= 0) {\n    return { rects: [], shapes: [] };\n  }\n\n  const accept = options.accept;\n  const cells = new Map<string, string>();\n  const shapes: TileCollisionShape[] = [];\n\n  if (cellSource !== undefined) claimSourceCells(cells, region, cellSource);\n\n  for (const { tx, ty, tile } of layer.tilesInRect(region.x, region.y, region.width, region.height)) {\n    const definition = tile.tileset.getTileDefinition(tile.localTileId);\n\n    if (definition?.collision === undefined) {\n      continue;\n    }\n\n    const cellX = tx * layer.tileWidth + layer.offsetX;\n    const cellY = ty * layer.tileHeight + layer.offsetY;\n\n    for (const object of definition.collision) {\n      if (accept !== undefined && !accept(object, tx, ty)) {\n        continue;\n      }\n\n      const placed = placeShape(object, layer, tile.tileset, tile.transform, tx, ty);\n\n      if (placed === null) {\n        continue;\n      }\n\n      const key = cellKey(tx, ty);\n\n      // A second whole-cell box on the same tile cannot claim the cell twice;\n      // it falls through to the shape list so no geometry is silently dropped.\n      if (coversWholeCell(placed, layer, cellX, cellY) && !cells.has(key)) {\n        cells.set(key, object.type);\n        continue;\n      }\n\n      shapes.push({\n        kind: placed.kind,\n        x: placed.x,\n        y: placed.y,\n        width: placed.width,\n        height: placed.height,\n        rotation: placed.rotation,\n        ...(placed.points !== undefined && { points: placed.points }),\n        tx,\n        ty,\n        source: object,\n      });\n    }\n  }\n\n  if (cells.size === 0) {\n    return { rects: [], shapes };\n  }\n\n  const rects = options.merge === false ? unmergedCells(cells, layer) : mergeCells(cells, region, layer);\n\n  return { rects, shapes };\n};\n"],"mappings":"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"}

package/dist/esm/tileWord.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Tile word packing, shared by both backends and by the shader sources they
+ * fill: transform-buffer row in the low 29 bits, diagonal flip in bit 29.
+ * flipX/flipY are baked into the UV bounds at write time, so the shader only
+ * needs the diagonal axis swap.
+ *
+ * @internal
+ */
+export declare const TILE_ROW_MASK = 536870911;
+/** @internal */
+export declare const TILE_DIAGONAL_BIT = 536870912;
+//# sourceMappingURL=tileWord.d.ts.map

package/dist/esm/tileWord.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tileWord.d.ts","sourceRoot":"","sources":["../../src/tileWord.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,YAAa,CAAC;AAExC,gBAAgB;AAChB,eAAO,MAAM,iBAAiB,YAAa,CAAC"}

package/dist/esm/tileWord.js

@@ -0,0 +1,16 @@
+//#region src/tileWord.ts
+/**
+* Tile word packing, shared by both backends and by the shader sources they
+* fill: transform-buffer row in the low 29 bits, diagonal flip in bit 29.
+* flipX/flipY are baked into the UV bounds at write time, so the shader only
+* needs the diagonal axis swap.
+*
+* @internal
+*/
+const TILE_ROW_MASK = 536870911;
+/** @internal */
+const TILE_DIAGONAL_BIT = 536870912;
+
+//#endregion
+export { TILE_DIAGONAL_BIT, TILE_ROW_MASK };
+//# sourceMappingURL=tileWord.js.map

package/dist/esm/tileWord.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tileWord.js","names":[],"sources":["../../src/tileWord.ts"],"sourcesContent":["/**\n * Tile word packing, shared by both backends and by the shader sources they\n * fill: transform-buffer row in the low 29 bits, diagonal flip in bit 29.\n * flipX/flipY are baked into the UV bounds at write time, so the shader only\n * needs the diagonal axis swap.\n *\n * @internal\n */\nexport const TILE_ROW_MASK = 0x1fffffff;\n\n/** @internal */\nexport const TILE_DIAGONAL_BIT = 0x20000000;\n"],"mappings":";;;;;;;;;AAQA,MAAa,gBAAgB;;AAG7B,MAAa,oBAAoB"}