Tiled Dart #

A Dart Tiled library.

Install from Dart Pub Repository #

To include the package as a dependency in your pubspec.yaml, run the following (or add it manually):

dart pub add tiled

Usage #

Import the package like this:

    import 'package:tiled/tiled.dart';

Load Tmx Files #

Load a TMX file into a string by any means, and then pass the string to TiledMap.parseTmx():

    final String tmxBody = /* ... */;
    final TiledMap mapTmx = TiledMap.parseTmx(tmxBody);

Load Json Files #

Alternatively load a json file with TiledMap.parseJson():

    final String jsonBody = /* ... */;
    final TiledMap mapJson = TiledMap.parseJson(jsonBody);

External Files #

If your map references external files, like external tilesets (.tsx) or object templates (.tx), you have to pass one or more ParserProviders that resolve these files. Every time the parser encounters a reference to an external file, the first provider that canProvide the referenced path is asked for a Parser of its contents through getSource.

The path is always relative to the map file, also for files referenced from other external files, so a single provider can resolve any number of files, for example everything below a directory:

class DirectoryProvider extends ParserProvider {
  final String root;

  DirectoryProvider(this.root);

  @override
  bool canProvide(String path) => File('$root/$path').existsSync();

  @override
  Parser getSource(String path) {
    return Parser.fromString(File('$root/$path').readAsStringSync());
  }
}

Parser.fromString creates an XmlParser or a JsonParser depending on the contents. Every file is requested at most once per parsed map.

Objects that use a template inherit every value they do not specify themselves from the object of the template, and their gid is translated to the tilesets of the map. When the map does not contain the tileset of the template it is added to TiledMap.tilesets, like Tiled does when loading the map.

The providers are passed to parseTmx or parseJson:

    final TiledMap mapTmx = TiledMap.parseTmx(
      tmxBody,
      providers: [DirectoryProvider('assets/tiles')],
    );

Loading External Files Asynchronously #

When the external files can only be loaded asynchronously, for example from an asset bundle, use TiledMap.fromString instead. It parses either tmx or json and loads every referenced file, also the ones referenced from other external files, with the given loader before returning the map:

    final TiledMap map = await TiledMap.fromString(
      contents,
      (path) => rootBundle.loadString('assets/tiles/$path'),
    );

Implementation #

For further information and more usage examples, please take a look at the examples in flame_tiled.