Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Other skills

melonjs-tilemaps

Use this skill for Tiled maps in melonJS — loading TMX/TSX levels, spawning entities from Tiled objects, collision shapes authored in Tiled, isometric and hexagonal maps, and image layers, and reading or changing tiles while the game runs. Covers registerTiledObjectClass and the pool.register name contract, camera bounds, compressed maps needing the inflate plugin, and the level director API. Triggers on: Tiled, TMX, TSX, tilemap, setTile, clearTile, cellAt, getTile, getTileById, change a tile, tile at run time, game board, grid, tile properties at run time, getTileProperties, map properties, level.load, level.load async, await level.load, tileset, ImageLayer, isometric, hexagonal, staggered, pool.register, Collectable, Trigger, object layer, collision layer, parallax, registerTiledObjectClass, registerTiledObjectFactory, TMXObject, resolvedProperty, resolvedProperties, tile class, tile properties.

melonjs · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add melonjs/melonJS --skill melonjs-tilemaps

About this skill


name: melonjs-tilemaps description: "Use this skill for Tiled maps in melonJS — loading TMX/TSX levels, spawning entities from Tiled objects, collision shapes authored in Tiled, isometric and hexagonal maps, and image layers, and reading or changing tiles while the game runs. Covers registerTiledObjectClass and the pool.register name contract, camera bounds, compressed maps needing the inflate plugin, and the level director API. Triggers on: Tiled, TMX, TSX, tilemap, setTile, clearTile, cellAt, getTile, getTileById, change a tile, tile at run time, game board, grid, tile properties at run time, getTileProperties, map properties, level.load, level.load async, await level.load, tileset, ImageLayer, isometric, hexagonal, staggered, pool.register, Collectable, Trigger, object layer, collision layer, parallax, registerTiledObjectClass, registerTiledObjectFactory, TMXObject, resolvedProperty, resolvedProperties, tile class, tile properties." license: MIT

Tiled maps

melonJS's flagship content pipeline. Maps are authored in Tiled and loaded through the level director — you rarely touch the TMX* classes directly.

Loading a level

Preload the map and everything it references — the .tmx, any external .tsx tilesets, and the tileset images:

await loader.preload([
    { name: "map1",    type: "tmx", src: "data/map/map1.tmx" },
    { name: "tileset", type: "tsx", src: "data/map/tileset.tsx" },
    { name: "tiles",   type: "image", src: "data/img/tiles.png" },
]);

level.load("map1");           // inside Stage.onResetEvent

Asset type is "tmx" for maps and "tsx" for external tilesets — those are the only two type strings the loader knows. The file can be .tmx / .tsx (XML), or .json / .tmj / .tsj; the parser branches on the extension, not on the type. type: "tmj" throws unknown or invalid resource type. You can also skip src and pass the map inline via data (with format: "json" or "xml").

level.load(levelId, options) accepts container (default game.world), onLoaded (default game.onLevelLoaded), flatten (default game.mergeGroup), setViewportBounds (default true) and async (default false). It throws level <id> not found for an unknown id — synchronously, in both forms, because that is a typo rather than a load failure.

Those game. defaults are the engine's own, and game is whichever Application finished init() last. Pass container explicitly from a Stage, which has the right one: level.load("map", { container: this.app.world }).

level.load is deferred while the game loop is running. It calls state.stop() and finishes the load on a timer, after the current frame, so by default it returns true before anything is in the world. Two ways to sequence work after it:

// await it
await level.load("map1", { async: true });
// the world is populated here

// ...or use the callback / event, which fire in both forms
level.load("map1", { onLoaded: () => this.spawnPlayer() });

async: true is the only thing that changes the return value — everything else behaves identically, onLoaded included. Without it the call returns a boolean, so await level.load("map1") is not an error and does not await the load: await true resolves immediately, while the load is still sitting on a timer. Pass the flag when you mean to await.

level.reload(), level.next() and level.previous() take the same async option and resolve the same value they return — so if (level.next()) becomes if (await level.next({ async: true })). Running out of levels reports false either way rather than throwing. level.getCurrentLevelId() and level.levelCount() round out the namespace. flatten: false wraps each Tiled object group in its own Container named after the group.

Spawning entities from Tiled objects

Objects are matched against a factory registry, in this order: the object's Tiled class, then its name, then, for a tile object with no class of its own, its tile's class, then the structural fallbacks "text", "tile" and "shape".

import { registerTiledObjectClass, registerTiledObjectFactory } from "melonjs";

registerTiledObjectClass("Enemy", Enemy);   // ← matches Tiled class OR name
registerTiledObjectFactory("Spine", (settings, map) => { /* → Renderable */ });
level.load("map1");

These are the entry points to use. The registry is Tiled's own, held by the object factory, and has nothing to do with object pooling.

pool.register(className, classObj) also works and registers a Tiled factory as a side effect, under the name and again under an me.-prefixed alias, unless you set pool.autoRegisterTiled = false. That is the older spelling, kept working for maps and games written against it, and it now prints a one-off deprecation notice: me.pool is deprecated since 18.0.0.

Its third argument no longer buys anything here. It used to make Tiled objects recyclable; they are constructed directly now, and the container returns children to typed pools rather than to the name-keyed one. To pool a class you spawn constantly, give it a createPool and register it for Tiled separately:

registerTiledObjectClass("mainPlayer", PlayerEntity);

Register before loading. With no match the object falls through to the structural factory and becomes a plain Renderable with a static body — it does not error, it just has none of your behaviour.

registerTiledObjectClass throws if you register a different constructor under a name already taken (re-registering the same one is a no-op). registerTiledObjectFactory overwrites and only console.warns, so it is the one to use for replacing something already registered.

Overriding a built-in name always works. The engine's own classes are DEFAULTS: they fill a name nothing else has claimed, and yours takes it over whenever you register, before or after a map has l

Read the complete source ↗