NAME

Games::TMX::Parser - parse tiled game maps from http://www.mapeditor.org

SYNOPSIS

    use Games::TMX::Parser;

    $map = Games::TMX::Parser->new(
        map_dir  => 'maps',
        map_file => 'tower_defense.tmx',
    )->map;

    # ----- the map ------------------
    $width       = $map->width; # all sizes in pixels
    $height      = $map->height;
    $tile_width  = $map->tile_width;
    $tile_height = $map->tile_height;

    $tileset     = $map->tilesets->[3];
    $tile        = $map->get_tile('some_tile_id'); # find in all tilesets
    $layer       = $map->get_layer('some_layer_name');

    # ----- a tileset of tiles --------
    $tile        = $tileset->tiles->[2];
    $image       = $tileset->image; # image file name in map_dir directory
    $width       = $tileset->width;
    $height      = $tileset->height;
    $tile_width  = $tileset->tile_width;
    $tile_height = $tileset->tile_height;
    $tile_count  = $tileset->tile_count;

    # ----- a tile from a tileset -----
    %props       = %{ $tile->properties };
    $value       = $tile->get_prop('some_tile_property_name');
    $tileset     = $tile->tileset;

    # ----- a layer on the map --------
    $cell        = $layer->get_cell($column, $row);
    $cell        = $layer->rows->[$row]->[$column]; # same as above
    @cells       = $layer->find_cells_with_property('some_tile_property_name');
    @cells       = $layer->all_cells;

    # ----- a cell in a layer ---------
    $tile        = $cell->tile;
    $layer       = $cell->layer;
    ($col, $row) = $cell->xy;
    $cell        = $cell->left;
    $cell        = $cell->right;
    $cell        = $cell->above;
    $cell        = $cell->below;
    $cell        = $cell->seek_next_cell; # follow a path of tiled cells on a layer

DESCRIPTION

From http://www.mapeditor.org:

    Tiled is a general purpose tile map editor. It's built to be easy to use,
    yet flexible enough to work with varying game engines, whether your game is
    an RPG, platformer or Breakout clone.

This package provides Perl access to the maps generated by Tiled, the general purpose tile map editor. You could use it for drawing you perl game maps in Tiled, or for writing Perl scripts which improve/analyze maps- extract waypoints, decorate corners with shadows, add random trees, etc.

Drawing your maps in Tiled is more fun that writing your own map format and then drawing ASCII art.

The TMX map format documentation describes the main entities:

    https://github.com/bjorn/tiled/wiki/TMX-Map-Format

HOW TO USE

In Tiled, draw your map and place properties as markers on special tiles you want to read in Perl. Then in your Perl game, read the map and use:

    my @cells = $map->get_layer('layer_with_stuff')
                    ->find_cells_with_property('my_special_tile_marker');
 

To find your special cells (spawn points, enemy locations, etc.).

Draw a layer by iteating over:

    @{ $layer->rows };

Which will give you an ARRAY ref of cells, one per column. Then you can find the tile of the cell using:

    $cell->tile;

And then access its properties, or cut the correct image from the tileset image file:

    $tile->tileset->image;

EXAMPLE

The distribution contains an example which computes creep waypoint column/row for any map with a simple path drawn on it.

TODO

No support for base64 or compression of maps, uncheck the correct check boxes in Tiled before you save.

No support for object layers.

DEVELOPMENT

Send pull requests to:

    https://github.com/eilara/Games-TMX-Parser

AUTHOR

Ran Eilam <eilara@cpan.org>

A big hug to mst for namespacing help.

COPYRIGHT AND LICENSE

Copyright (C) 2011 by Ran Eilam

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.1 or, at your option, any later version of Perl 5 you may have available.

cpanm Games::TMX::Parser

perl -MCPAN -e shell
install Games::TMX::Parser