miaoda-game-isometric-core

Use this engine-independent coordinate helper for isometric tile games, tactics maps, builders, and management views. It projects continuous grid coordinates to screen coordinates, reverses that transform on a known elevation plane, picks cells, and returns cell diamonds for your renderer.

Install

pnpm add miaoda-game-isometric-core

Project and pick a cell

import { IsometricProjection } from 'miaoda-game-isometric-core';

const iso = new IsometricProjection({
  tileWidth: 64,
  tileHeight: 32,
  elevationHeight: 24,
  origin: { x: 640, y: 80 },
});

const screen = iso.worldToScreen({ x: 4.25, y: 7.5, z: 1 });
const cell = iso.screenToCell(pointerPosition, 0); // ground plane
const diamond = iso.cellDiamond(cell, 0);           // four draw vertices

The transform is:

screenX = originX + (worldX - worldY) * tileWidth / 2
screenY = originY + (worldX + worldY) * tileHeight / 2 - worldZ * elevationHeight

World (x, y) is continuous. Integer cell (x, y) is the top vertex of the area [x, x + 1) × [y, y + 1); screenToCell uses floor, including for negative coordinates.

Elevation matters

screenToWorld(screen, z) and screenToCell(screen, z) need the elevation plane you intend to pick. The same screen point can represent ground, a bridge, or a roof, so the projection cannot infer z from pixels alone. Keep tile storage, navigation, collision, and layer selection in your game or grid package.

tileWidth and tileHeight are independent; 64 × 32 is a common 2:1 diamond but is not required. elevationHeight controls how far one elevation unit moves upward on screen.

Rendering boundary

Use cellDiamond for tile drawing or hit-test overlays. Draw ordering depends on each object's footprint, height, overhangs, and bridge rules; this package intentionally does not prescribe a universal x + y + z sort key. Apply your engine's actual object bounds and layer policy.

Public API

IsometricProjection, IsoPoint, IsoCell, IsometricProjectionOptions, and Vec2 are exported. The core does not render sprites, store a map, navigate, or create engine nodes; compose it with miaoda-game-grid-core and your target engine's TileMap/scene APIs.