A JavaScript, jQuery and RequireJS-based library for reading, manipulating and writing TMX (Tile Map XML) files.
JavaScript
Latest commit 6af4d5d Jan 13, 2014 @cdmckay Update README.md
Updated TMXjs Editor link to point to Tilecraft

README.md

TMXjs

TMXjs is a JavaScript, jQuery and RequireJS-based library for reading, manipulating, and writing TMX files.

To see an example of TMXjs code being used in a practical application, see the Tilecraft project.

To see TMXjs in action, please visit the Tilecraft demo site at cdmckay.org.

Getting Started

TMXjs isn't available as a single JavaScript file yet, so you'll need to download the entire src folder and place it in a folder, typically named tmxjs. Here's an example project layout that is used by Tilecraft:

js/
  lib/
    tmxjs/
      ...
    jquery.js
    require.js
    zlib.min.js
  main.js
index.html

TMXjs depends on jQuery, RequireJS, Zlib, so they all need to be shimmed in your RequireJS config for TMXjs to work. Here's an example index.html file:

<!doctype html>
<html>
<head>
    <title>...</title>
    <script type="text/javascript" src="js/lib/require.js" data-main="js/main"></script>
</head>
<body>
    ...
</body>
</html>

If you're not familiar with RequireJS, it may seem weird to only be including one JavaScript file, even though we have dependencies. These are taken care of in the main.js file:

require.config({
    paths: {
        "jquery": "lib/jquery",
        "zlib": "lib/zlib.min",
        "tmxjs": "lib/tmxjs",
    },
    shim: {
        zlib: { exports: "Zlib" }
    }
});

require([
    "jquery",
    "tmxjs/map",
], function (
    $,
    Map
) {
    // Code that uses TMXjs goes here.
});

Importing TMX Files

In order to use a TMX file with TMXjs you'll first need to download it using an XHR request. Since TMXjs requires jQuery, that library is typically used for this task:

require([
    "jquery",
    "tmxjs/map",
], function (
    $,
    Map
) {
    var url = "path/to/map.tmx";
    var options = {
        // Extracts the URL path. This is required to be passed to Map.fromXML(...) or
        // it will assume all resources like TSX files and images are in the current folder.
        dir: url.split("/").slice(0, -1) || "."
    };

    $.get(url, {}, null, "xml").done(function (xml) {
        // fromXML calls are asynchronous because TSX resources may need to be loaded by TMXjs.
        Map.fromXML(xml, options).done(function (map) {
            // Code that uses the Map object goes here.
        });
    });
});

Exporting TMX Files

The Map#toXML method is used to export a Map object to XML. Continuing from the import example:

require([
    "jquery",
    "tmxjs/map",
], function (
    $,
    Map
) {
    var url = "path/to/map.tmx";
    var options = {
        // Extracts the URL path. This is required to be passed to Map.fromXML(...) or
        // it will assume all resources like TSX files and images are in the current folder.
        dir: url.split("/").slice(0, -1) || "."
    };

    $.get(url, {}, null, "xml").done(function (xml) {
        // fromXML calls are asynchronous because TSX resources may need to be loaded by TMXjs.
        Map.fromXML(xml, options).done(function (map) {
            map.name = "Export Example!";

            // The Map#toXML method returns an XMLDocument object.
            var doc = map.toXML();
            var xmlString = doc.context.xml || new XMLSerializer().serializeToString(doc.context);
            console.log(xmlString);
        });
    });
});

...and that's it!

TMXjs Implementation Status

The TMXjs implementation of the TMX file format is incomplete.

The biggest omissions are lack of support for <objectgroup> and <imagelayer> elements.