# @reldens/tile-map-optimizer

> Reldens - Tile Map Optimizer

Latest version **0.50.0** (published 2026-09-07) · MIT license · 0 weekly downloads

## Install

```sh
npm install @reldens/tile-map-optimizer
pnpm add @reldens/tile-map-optimizer
yarn add @reldens/tile-map-optimizer
bun add @reldens/tile-map-optimizer
```

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.50.0 |
| Published | 2026-09-07 |
| First published | 2024-02-27 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 521.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | Damian A. Pastorini |
| Maintainers | dpastorini |
| Keywords | reldens, tile, map, tiled, optimize, random, game, nodejs, javascript |

## Links

- npm: https://www.npmjs.com/package/@reldens/tile-map-optimizer
- Repository: https://github.com/damian-pastorini/tile-map-optimizer
- Issues: https://github.com/damian-pastorini/tile-map-optimizer/issues
- npm.io page: https://npm.io/package/@reldens/tile-map-optimizer

## Dependencies (3)

- [sharp](https://npm.io/package/sharp.md) 0.35.4
- [@reldens/utils](https://npm.io/package/@reldens/utils.md) ^0.58.0
- [@reldens/server-utils](https://npm.io/package/@reldens/server-utils.md) ^0.57.0

## Recent versions

- 0.50.0 (latest) — 2026-09-07
- 0.49.0 — 2026-08-10
- 0.48.0 — 2026-07-24
- 0.47.0 — 2026-06-21
- 0.46.0 — 2026-06-10
- 0.45.0 — 2026-05-27
- 0.44.0 — 2026-05-27
- 0.43.0 — 2026-05-15
- 0.42.0 — 2026-05-08
- 0.41.0 — 2026-04-22
- 0.40.0 — 2026-03-17
- 0.39.0 — 2026-03-10
- 0.38.0 — 2026-02-01
- 0.37.0 — 2026-01-15
- 0.36.0 — 2026-01-06
- … 35 more at https://npm.io/package/@reldens/tile-map-optimizer/versions

## README

[![Reldens - GitHub - Release](https://www.dwdeveloper.com/media/reldens/reldens-mmorpg-platform.png)](https://github.com/damian-pastorini/reldens)

# 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](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/](https://www.reldens.com/documentation/tile-map-optimizer/)

## Installation

```bash
npm install @reldens/tile-map-optimizer
```

## Quick Start

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

```javascript
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:
```bash
$ 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](https://github.com/damian-pastorini/reldens/ "Reldens")

##### [By DwDeveloper](https://www.dwdeveloper.com/ "DwDeveloper")

---
_Source: https://npm.io/package/@reldens/tile-map-optimizer · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._