@web-engine-dev/tilemap

Tile-based map rendering with chunked storage, auto-tiling, and isometric support.

Features

• Chunked Storage: Infinite map support
• Auto-Tiling: Automatic tile selection based on neighbors
• Isometric Support: Diamond and staggered isometric
• Multiple Layers: Unlimited render layers
• Animated Tiles: Frame-based tile animation
• Tiled Import: TMX/JSON format support

Installation

npm install @web-engine-dev/tilemap
# or
pnpm add @web-engine-dev/tilemap

Quick Start

import { Tilemap, Tileset, TilemapRenderer } from '@web-engine-dev/tilemap';

// Load tileset
const tileset = await Tileset.load('tiles.json');

// Create tilemap
const map = new Tilemap({
  tileWidth: 16,
  tileHeight: 16,
  chunkSize: 32,
});

// Set tiles
map.setTile(0, 0, 'ground', tileset.getTile('grass'));
map.setTile(1, 0, 'ground', tileset.getTile('dirt'));

// Create renderer
const renderer = new TilemapRenderer(device);

// Render
renderer.render(map, camera);

API Overview

Tilemap

const map = new Tilemap({
  tileWidth: 16,
  tileHeight: 16,
  chunkSize: 32, // Tiles per chunk
  infinite: true,
});

// Layer operations
map.addLayer('ground', { zIndex: 0 });
map.addLayer('objects', { zIndex: 1 });

// Tile operations
map.setTile(x, y, 'ground', tile);
map.getTile(x, y, 'ground');
map.removeTile(x, y, 'ground');

// Area operations
map.fill(0, 0, 10, 10, 'ground', tile);
map.clear('ground');

Tileset

// Load from JSON
const tileset = await Tileset.load('tileset.json');

// Get tiles
const grass = tileset.getTile('grass');
const water = tileset.getTile('water');

// Animated tiles
const waterAnim = tileset.getTile('water_animated'); // Auto-animates

Auto-Tiling

// Define auto-tile rules
const terrain = new AutoTileset({
  tiles: tileset,
  rules: [
    { neighbors: 0b1111, tile: 'center' },
    { neighbors: 0b0111, tile: 'top' },
    { neighbors: 0b1011, tile: 'bottom' },
    // ... bitmask patterns
  ],
});

// Use auto-tiling
map.setAutoTile(x, y, 'ground', terrain);

Isometric

const isoMap = new Tilemap({
  tileWidth: 64,
  tileHeight: 32,
  type: 'isometric', // 'orthogonal', 'isometric', 'staggered'
  staggerAxis: 'y',
  staggerIndex: 'odd',
});

// World to tile conversion
const tilePos = isoMap.worldToTile(worldX, worldY);

// Tile to world conversion
const worldPos = isoMap.tileToWorld(tileX, tileY);

Tiled Import

import { TiledLoader } from '@web-engine-dev/tilemap';

const map = await TiledLoader.load('level1.tmx');
// or
const map = await TiledLoader.loadJSON('level1.json');

Peer Dependencies

• @web-engine-dev/math - Vector math (optional)