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 livesHow you set itGood for
In the sceneLevelMapComponent(inline: LevelMapData(...)), saved as the component's inline fieldthe editor's default: a level that is one file with one undo history
A .map.json fileLevelMapComponent(mapPath: 'assets/maps/cave.map.json')one map shared by several scenes
A Tiled fileLevelMapComponent(mapPath: 'assets/maps/cave.tmx'), or .tmjmaps 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.

lib/level.dart
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 collides set to true gets physics bodies, and one with foreground draws 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 collision string property; failing that, the first shape's class when it names a registered kind; otherwise solid.
  • 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:

lib/hazards.dart
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.

lib/blocks.dart
/// 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.

lib/blockout.dart
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);
}
This page as Markdown