Tile Map Optimizer

The @reldens/tile-map-optimizer package reduces tileset size by extracting only the tiles actually used in a Tiled map. This can reduce tileset image size by 50-90%, cutting load times and memory usage in your game.

What It Does

Given a Tiled JSON map file, the optimizer:

  • Scans all layers to identify which tile indices are actually used
  • Extracts only those tiles from the source tileset images
  • Composes a new compact tileset PNG containing only the used tiles
  • Remaps all tile references in the JSON to point to new indices
  • Preserves tile animations, tile properties, and wangsets
  • Optionally resizes the output by a scale factor (pixel-perfect nearest-neighbor)

The result is a drop-in replacement for your original map file, with a much smaller tileset image.

Installation

npm install @reldens/tile-map-optimizer

Basic Usage

const { TileMapOptimizer } = require('@reldens/tile-map-optimizer');
const originalJSON = require('./your-map.json');

const optimizer = new TileMapOptimizer({
    originalJSON,
    rootFolder: __dirname,
    generatedFolder: './generated'
});

await optimizer.generate();

The optimized map JSON and tileset PNG are written to the generatedFolder.

Configuration Options

  • originalJSON (required) - The Tiled map JSON object. Load with require() or JSON.parse().
  • rootFolder - Base folder for resolving tileset image paths. Defaults to __dirname.
  • generatedFolder - Output folder for the optimized files. Defaults to rootFolder/generated.
  • originalMapFileName - Used when auto-generating the output file name.
  • newName - Custom base name for output files. Defaults to optimized-map-{timestamp}.
  • mapFileName - Full path for the output JSON file. Overrides newName.
  • tileSheetFileName - Full path for the output PNG file. Overrides newName.
  • factor - Integer scale factor for resizing output (e.g. 2 doubles tile dimensions). Defaults to 1 (no resize).
  • transparentColor - Hex color to treat as transparent in source tilesets. Defaults to '#000000'.

Output Files

The optimizer always writes two files:

  • {newName}.json - Optimized Tiled map with remapped tile indices
  • {newName}.png - Compact tileset containing only used tiles

When factor is greater than 1, two additional files are written:

  • {newName}-x{factor}.json - Map with dimensions scaled
  • {newName}-x{factor}.png - Tileset scaled using nearest-neighbor interpolation

Input Requirements

The input must be a valid Tiled map exported as JSON with:

  • tilewidth and tileheight properties
  • A layers array (tile layers with data arrays)
  • A tilesets array with image references resolvable from rootFolder

Dependencies

  • sharp - High-performance image processing for tile extraction and composition
  • @reldens/utils - Logger and utilities
  • @reldens/server-utils - File operations

The package is used in the Reldens skeleton build pipeline to produce optimized tilesets for the default theme maps.

Go Up