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.
reldens