A JavaScript, jQuery and RequireJS-based library for reading, manipulating and writing TMX (Tile Map XML) files.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.idea
examples
lib
src
test
LICENSE
README.md Update README.md Jan 13, 2014
index.html
main.js

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.