@reldens/tile-map-optimizer

Reldens - Tile Map Optimizer

A powerful tool to optimize Tiled JSON maps by removing unused tiles, merging multiple tilesets into a single optimized image, and significantly reducing file sizes.

Need some specific feature?

Request a feature here: https://www.reldens.com/features-request

---

Features

• Tile Map Optimization: Analyzes Tiled JSON maps and identifies used tiles
• Unused Tile Removal: Removes unused tiles from tilesets to reduce file size
• Tileset Merging: Combines multiple source tilesets into a single optimized image
• Image Compression: Uses Sharp library for high-performance image processing
• Tile Remapping: Automatically updates all tile indices in map layers
• Animation Preservation: Maintains tile animations, properties, and wangsets
• Optional Scaling: Resize output by any factor with nearest-neighbor interpolation
• Significant Size Reduction: Typically achieves 50-90% file size reduction

Documentation

https://www.reldens.com/documentation/tile-map-optimizer/

Installation

npm install @reldens/tile-map-optimizer

Quick Start

Create a file to configure the optimizer with the map to be optimized:

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

let options = {
    originalJSON,
    originalMapFileName: 'reldens-town',
    factor: 2,
    transparentColor: '#000000',
    rootFolder: __dirname
};

let tileMapOptimizer = new TileMapOptimizer(options);

tileMapOptimizer.generate().catch((error) => {
    Logger.error(error);
}).then(() => {
    Logger.info('Map saved! Check generated folder.');
});

Run it:

$ node ./optimize-example.js

Look for your optimized maps in the "generated" folder.

Configuration Options

Required Options

• originalJSON: The Tiled JSON map object to optimize

Optional Options

• originalMapFileName: Name of the original map file (used in output naming)
• newName: Custom name for optimized output files (default: auto-generated with timestamp)
• factor: Resize factor for output scaling (default: 1, no resize)
• transparentColor: Transparent color for tileset (default: '#000000')
• rootFolder: Root folder path for finding source tileset images (default: __dirname)
• generatedFolder: Output folder for optimized files (default: rootFolder/generated)
• mapFileName: Custom path for output map JSON (default: auto-generated)
• tileSheetFileName: Custom path for output tileset image (default: auto-generated)

How It Works

1. Parse Map: Analyzes all layers to identify which tiles are actually used
2. Extract Tiles: Extracts only the used tiles from source tilesets
3. Create Tileset: Builds a new compact tileset image with optimal layout
4. Remap Indices: Updates all tile references in the map JSON
5. Preserve Features: Maintains animations, properties, and wangset data
6. Generate Output: Saves optimized map JSON and tileset PNG
7. Optional Resize: Scales output by factor if specified (e.g., 2x, 3x)

What counts as "actually used"

Step 1 only collects tile ids found in a top level layer data array, plus the frames referenced by tile animations. A tile that appears only in the tileset tiles annotations, or only as a wangtile inside a wangset, is not used and is dropped, and every reference to it goes with it: createNewJSON() resolves each annotation and each wangset.tile through fetchNewImagePositionForTile(), which returns false for a dropped tile.

This is why a composite that annotates or terrain maps a tile it never draws must park that tile somewhere in a layer. The Reldens composites do this with a dedicated tileset-ref layer, and tile-map-generator excludes that layer from its elements because layer names with fewer than three dash separated parts are skipped in ElementsProvider.splitByLayerName().

The practical consequence when authoring composites: adding or removing a parked tile repacks the sheet, so every optimized gid after it shifts. Committed expected maps and the tileset image next to them must be regenerated together, or the map will render against a mismatched sheet.

Output Files

The optimizer generates:

• Optimized Map JSON: Updated Tiled map with new tile indices
• Optimized Tileset PNG: Compact image containing only used tiles
• Resized Versions (if factor > 1): Scaled map and tileset for different resolutions

All files are timestamped to prevent accidental overwriting.

Use Cases

• Optimize maps created with Tiled editor before deployment
• Reduce asset file sizes for web-based games
• Remove unused tiles from large tileset collections
• Merge multiple tilesets into a single optimized image
• Generate multiple scaled versions from a single source
• Prepare maps for the Reldens platform

Dependencies

• sharp: High-performance image processing
• @reldens/utils: Logging, shortcuts, error handling
• @reldens/server-utils: File operations

Related Packages

• @reldens/tile-map-generator: Generates random tile maps
• Reldens: MMORPG platform that uses these optimized maps

---

Reldens

By DwDeveloper