Gameplay
Level maps
Draw tile maps from the scene, a .map.json file or a Tiled .tmx/.tmj with LevelMapComponent, give layers collision, and change tiles while the game runs.
A level map is layers of tiles. One LevelMapComponent puts a whole map in the level at its entity's position; the map is not rotated or scaled with the entity. Maps can be orthogonal, isometric, staggered or hexagonal (LevelMapOrientation), and MapGeometry places cells exactly as Tiled does, so a map looks and collides the same here as in Tiled. Tiles can be animated, flipped and rotated.
Two default systems run maps: LevelMapSystem (priority 110) loads and draws them, and MapCollisionSystem (108) builds their collision. Both are in DefaultSystems.all; for a world of your own, call registerLevelMapSystems(world) and add a RenderSystem to draw the layers.
Three ways to store a map
| Where the map lives | How you set it | Good for |
|---|---|---|
| In the scene | LevelMapComponent(inline: LevelMapData(...)), saved as the component's inline field | the editor's default: a level that is one file with one undo history |
A .map.json file | LevelMapComponent(mapPath: 'assets/maps/cave.map.json') | one map shared by several scenes |
| A Tiled file | LevelMapComponent(mapPath: 'assets/maps/cave.tmx'), or .tmj | maps made in Tiled |
While mapPath is set the inline map is ignored. Tilesets are .tileset.json files, or Tiled's .tsx. Older .tilemap.json files are still read. List every folder the map, its tilesets and their images live in under flutter: assets:; a folder entry does not include its subfolders.
A scene's own map is usually the entity called LevelMaps.primaryName (Level Map), which is how LevelMaps.primary(world) finds it.
Future<void> startLevel(World world) async {
world.createEntityWithComponents([
TransformComponent(),
LevelMapComponent(mapPath: 'assets/maps/level_01.tmx'),
], name: LevelMaps.primaryName);
// Load maps and tilesets before the first frame: otherwise the player
// can fall through ground that is still loading.
final failures = await LevelMaps.preload(world);
for (final failure in failures) {
debugPrint('Map ${failure.path} did not load: ${failure.error}');
}
}LevelMaps.preload loads every map in the world and its tilesets; images may still be arriving. A map that will not load does not stop the others: it is left without anything to draw or collide with, logged once, and returned in the list. When you move from level to level, call engine.releaseUnused() after the next level has loaded: it drops the maps and tilesets no map uses any more (LevelMaps.evictUnused(world), and the tileset images only those drew from), with the 2-D material files and 3-D models the old level alone used. Loading scenes is covered in Scenes.
Tiled maps
.tmx and .tmj maps load directly, with their tilesets embedded or as .tsx files, in any layer encoding Tiled saves (CSV, Base64, and Base64 compressed with zlib, gzip or Zstandard), and with object templates (.tx or .tj). Image paths are read relative to the file that names them. A layer whose data does not hold its width × height tiles is refused with a FormatException naming it. A few Tiled settings carry meaning:
- A tile layer with the bool custom property
collidesset to true gets physics bodies, and one withforegrounddraws in front of the level. - Tile collision comes from Tiled's tile collision editor: rectangles, ellipses and polygons. Lines and points are left out.
- A tile's collision kind is its
collisionstring property; failing that, the first shape's class when it names a registered kind; otherwisesolid. - Object layers become empty map layers. Their objects are not turned into entities.
To read the objects, parse the file with the just_tiled package and call TiledInterop.importMap. It returns a TiledImport with the converted map and tilesets, every object as a TiledObjectRecord (object, layerName, position, mapLayerId), the image layers and any warnings. TiledInterop.exportMap and exportTileset go the other way. Their signatures use just_tiled models, so add that package to call them.
Layers
Each layer is a MapLayerData with a name, visible, opacity, tint, offsetX and offsetY, parallaxX and parallaxY (less than 1 lags behind like a distant background), collides, className and custom properties. A layer sorts among the level's other drawing by sortLayerId (background, main or foreground), sortLayer and zOrder, so one map's background layer draws behind the player and its foreground layer in front.
An entity can sit on a layer: make it a child of the map's entity with LayerComponent(mapLayer: layerId), and it draws just above that layer's tiles and below the next layer's.
Tile collision
MapCollisionSystem gives every layer marked collides static bodies built from its tiles' collision shapes. The bodies are ordinary entities with a transform, a static RigidBody2DComponent, a Collider2DComponent and a MapBodyComponent that says which map, layer, kind, class and cells they came from. They are generated, never saved. Contacts with them are reported like any other, and standing on them grounds a character (see 2D physics). A layer's bodies are rebuilt at most once a frame when its cells, settings or tilesets change, or the map moves.
A ramp drawn with slope tiles (each filled below one line from its left side to its right, as the 45° and 22.5° slopes of the basic shapes are) becomes one convex body with the ground beneath it and the level ground at its top, so a running character meets no seam or buried corner on it; the bodies cover exactly what the tiles do.
The engine knows two collision kinds: MapCollisionKinds.solid, merged into as few boxes as possible, and MapCollisionKinds.oneWay, merged along rows and passed through from below. A kind nobody registered resolves to solid. Register your own in engine.context.collisionKinds before the maps load:
void addHazards(Engine engine) {
engine.context.collisionKinds.register(
MapCollisionKind(
id: 'hazard',
label: 'Hazard',
color: 0xFFE57373, // the editor's collision overlay
merge: TileMergeMode.none, // one body per tile
sensor: true,
decorate: (body, spec, properties) => body.addTag('hazard'),
),
);
engine.world.events.on<SensorEnter2DEvent>((e) {
final tile = e.sensor.getComponent<MapBodyComponent>();
if (tile?.kind == 'hazard' && e.other.hasTag('player')) {
debugPrint('${e.other.name} touched a hazard');
}
});
}decorate runs once each body is built and receives its tile's properties, such as a spike's damage. TileMergeMode is area, rows or none.
Change tiles at run time
LevelMaps.primary(world), or LevelMaps.of(world, entity) for any map, returns a LevelMapHandle once the map has loaded. Changes are the running game's own: the map file and the scene's saved map are untouched. Collision follows within the frame, and each change fires a TileChangedEvent with the map entity, the layer id and the changed cells.
/// Knocks out the tile under [point] on the "Ground" layer if its
/// tileset gives it the class "Breakable".
void hitBlock(World world, Offset point) {
final map = LevelMaps.primary(world);
final ground = map?.layer('Ground');
if (map == null || ground == null) return;
final cell = map.cellAt(ground, point);
if (map.tileAt(ground, cell)?.className == 'Breakable') {
map.setTile(ground, cell, TileCell.empty);
}
}tileAt returns a TileInfo with the tile's className, properties, tileset and localId, and tileAtPoint takes a world point. setTiles changes many cells with one event and one collision rebuild. cellCenter turns a cell back into a world point. setCellsHidden and setBodyHidden stop drawing cells without changing them, for a platform that crumbles and comes back. A cell value is made with TileCell.make(slot, localId), where slot is the tileset's index in the map's tilesets.
Terrain with Wang sets
LevelMapHandle.setTerrain(layer, targets, color, slot: ..., wangSet: ...) paints terrain from a tileset's Wang set, choosing tiles as the editor's terrain brush does. WangFiller does the work; targets are WangTarget.corner, WangTarget.edge or WangTarget.cell. It returns a WangResult with the cells it changed and any it could only match roughly. Hexagonal maps are not supported by the filler.
Block out with built-in shapes
BuiltInTilesets.basicShapes is a tileset the engine draws itself, so it needs no image or tileset file. Its 32 × 32 tiles are plain geometry for blocking out a level before there is art: a full block, half and quarter blocks, a one-way plank, 45° and 22.5° slopes for floors and ceilings, rounded corners, a circle, a triangle and a diamond. Every tile collides as it looks, and tile ids never change.
Entity addBlockout(World world) {
final map = LevelMapData(tilesets: [BuiltInTilesets.basicShapes]);
final ground = map.addLayer(name: 'Ground')..collides = true;
for (var x = -10; x < 10; x++) {
ground.cells.setCell(x, 4, TileCell.make(0, 0)); // a full block
}
ground.cells.setCell(2, 1, TileCell.make(0, 5)); // a one-way plank
return world.createEntityWithComponents([
TransformComponent(),
LevelMapComponent(inline: map),
], name: LevelMaps.primaryName);
}