CreepTD - Online Multiplayer Tower Defense

1. Introduction

In fact, most of the maps that are available in the game have been created by the community. So, if you have a really cool idea, feel free to try it by yourself.

2. Drawing the map background image

The basics: Maps must be sized 16x16, 32x16 or 32x32 cells. Other values cannot be used. The background image's size in pixels is always width=MAPWIDTH*20+1 and height=MAPHEIGHT*20+1. This is because every map cell has an outer size of 20x20 pixels and includes the outer left and top grid line only (not the outer right or bottom grid line which is drawn by the next cell). +1 because the last Cells at the right or the bottom end of the map do not contain the right and bottom grid line. So this is added to the background image. With this in mind, the inner dimension of a cell, where towers will be drawn, is 19x19 when not counting the grid lines at the top/left.

Image editors: You are free to use any image editing software you like (*) as long as you save the background image in JPEG format (at best in 75% quality) with a name of "{your map's lower case name}.jpg".

Even nicer 16x.. maps When creating 16x16 sized maps, the map image you draw will be shown for the top left player (player 1). For player 2 (top right) the image will be rotated by 90° in clockwise order, for player 3 (bottom right) by 180° and for player 4 (bottom left) by 270°. Because of this, best visual results will be achived by drawing a nice crossover at the right/bottom of your initial image. Likewise, the image of a 32x16 map is rotated by 180°.

You can use these plain 16x16, 32x16 or 32x32 empty grid images to get started with (download all).

(*) GIMP (free), Photoshop (non-free) etc. will work fine. You could even use MS Paint, but the result could be somewhat...you know.

3. Simple map file syntax

Creating your first 16x16 map is really easy. All you need is a background image sized 321x321 pixels and a corresponding map file. The background image is always named {lower case map name without blanks}.jpg and the map file {lower case map name without blanks}.map. Both will then be added to a ZIP-Archive named {lower case map name without blanks}.zip.

Path segments

In simple map file syntax, path segments are defined line by line using simple coordinates in the form of "X,Y". The upper left cell is indexed 0,0 and the bottom right cell 15,15. Just write your path to the .map-file. Creeps will follow the path from the beginning to the end. Example:

0,0
0,1
0,2
0,3
0,4

Blocked coordinates

Additionally you have the option to define so named blocked coordinates to cells where no towers can be placed. To define blocked coordinates, use a ";" instead of a "," to separate the x and the y coordinate. Example:

2;3
2;4
2;5

Comments

To add a comment to your map file, prepend a "#" to your comment's text. Example:

# This is a commented line 
0,1 # This is a trailing comment

Entirely blank lines are also possible.

This basically is all you have to do to create your first map in simple map file syntax. Please note: Simple map file syntax is limited to maps sized 16x16.

4. Advanced map file syntax

CreepTD version 1.0 introduces an advanced map file syntax that is completely backward compatible to the simple map file syntax. It allows the creation of alternative paths using labels, multiple start and end segments and underground sections of segments.

Extending simple map file syntax

Basic path segments and blocked coordinates are defined as known from simple map file syntax.

@author preparser option

Let others know that you are this map's author. Please use your player name. Example:

@author PlayerName

@size preparser option

Starting from version 1.0, maps can be sized 16x16, 32x16 or 32x32. Other values than these will cause the parser to fail. If omitted and not using strict mode, 16x16 will be assumed. To define your map's size, use:

@size 16x16

@strict preparser option

If you want to be sure that the parser will not accidentally fall back to simple map file syntax e.g. by guessing start and end segments of your path, ignoring invalid lines or try to fix anything you had not intended this way, you are able to enable strict parsing mode by adding:

@strict

In strict parsing mode, the parser will not tolerate any (accidentally) mistakes.

Start segments

With advanced map file syntax it is possible to define multiple start segments that will be choosen round-robin by incoming creeps. Example:

1,2 start

Hints: Creeps will appear in the middle of a start segment (to avoid this, see "underground segments" below). It's also possible to create weighted starts by defining one coordinate multiple times and merging the path afterwards using labels (see below). Furthermore, the very first declared segment in the map file will automatically be treated as a start when strict mode is disabled. If strict mode is enabled, you have to correctly define each start segment.

End segments

Similar to start segments, it is possible to define multiple end segments that will be reached by creeps using alternate paths. Example:

1,2 end

Hints: Creeps will disapear in the middle of an end segment (to avoid this, see "underground segments" below). When no end segment(s) are defined and strict mode is disabled, the parser will try to use the last declared segment as an end segment.

Labeled segments

If you plan to create alternate paths, you will have to define labels on path segments that are a "goto" target. Example:

1,2 A

Hints: Labels don't cause any immediate effect, they are just labels. Labels cannot contain white spaces.

Jump segments

To create alternate paths, you will require jump labels. When reaching a segment containing one or more jump labels, the creep will continue to walk the path at the defined labeled segment. Example:

1,2 goto A

Hints: It's also possible to create jump segments with multiple targets. Example:

1,2 goto A,A,B

Explanation:Creeps will choose to go to A or B with A weighted 2 (66%) and B weighted 1 (33%).

Underground segments

If you plan to create subways or tunnels, there are underground segments. Underground segments are declared by indenting the line at least by one blank space. When walking along an underground segment, creeps are hidden and cannot be shot by towers. Example:

   1,2
   1,2 start
   1,3 end
   ...

Hints: Underground segments may also be placed 1 index outside of the map (but no farther) e.g. " -1,-1 start" or " 4,16 end". In this example it will cause creeps to be displayed entering the map from the outside instead of spawning in the middle of a normal start segment. Example:

   0,-1 start
0,0
0,1
...
0,15
   0,16 end

Syntax mixing

It is possible to mix segment definitions with each other. Example:

   1,2 start A goto B,B,C

Explanation: The declared segment is an underground segment (see the indentation) at coordinates 1,2. It is a start. It is labeled "A" to be used as a jump target and creeps leaving the segment will jump to segments labeled B or C with B weighted 2 (66%) and C weighted 1 (33%).

The following is a special case example for declaring weighted starts:

1,1 start goto B
1,1 start
1,2 B
1,3
...

2,1 start
2,2
2,3
...

In this example creeps will start at 1,1 or 2,1 with 1,1 weighted 2 (66%) and 2,1 weighted 1 (33%).

Hints: End segments cannot be mixed with jump labels because they are...end segments. Start and end segments cannot be mixed either. The order of the mixed statements is important and must use the order shown in the first example.

Infinite loops

It is not possible to declare infinite loops (neither pure nor conditional) where creeps get stuck. If declared, the map is returned as invalid by the parser.

Last but not least: A map file example

The map file for the above example would look like this:

# Map TEST
# compiled by CreepTD PHP library 1.0.3
# at Wed, 12 Oct 2011 14:56:22 +0000

@author dcode
@size 16x16
@strict

1,1 start
2,1
3,1 goto A,B

# Route A
4,1 A
5,1 C
6,1
7,1 end

# Route B
3,2 B
3,3
4,3
5,3
5,2 goto C

For advanced insights into this topic you may have a look at the PHP library's sources (Path::validate).

5. Using a map editor

Instead of doing all these steps manually, you are also free to use the CreepTD Map Editor for all these heavy tasks. The official editor supports full advanced map file syntax.

• CreepTD Map Editor (AMFS)

6. Using the CreepTD PHP library

We provide you with the CreepTD PHP library that is able to parse, validate and compile CreepTD map files in simple and advanced map file syntax. Use this if you just want to validate a map file or use it as a starting point if you want to create your own parser, validator and/or compiler in another programming language.

• Download CreepTD PHP library

See the files "README" and "test.php" to get started:

README

=== CreepTD PHP library ===

== Contents ==

1. License
2. Installation
3. Usage
4. About CreepTD


== License ==

CreepTD PHP library Copyright (C) 2011 by
- Daniel Wirtz, virtunity media (http://virtunity.com)

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.


== Installation ==

Copy or upload the contained folder to a directory on your webserver. The
library requires PHP 5 to operate. Open the included test.php in your browser to
check if it's working.


== Usage ==

1. Include the CreepTD.php file in any PHP file you wish to access the library.
   e.g. include "folder/you/uploaded/to/CreepTD.php";
2. Use creeptd_validate_mapdata($mapdata, $warnings, $message) to validate map data.
   Use creeptd_validate_mapfile($mapfile, $warnings, $message) to validate a map file.
   Use CreepTD::parseMapdata($mapdata, $warnings, $message) to gain access to the
     parsed map object containing the traversable path and blocked coordinates.
   Use CreepTD::parseMapfile($mapfile, $warnings, $message) to do the above for a file.
   The variable $warnings will contain all parse and validation warnings.
   On success, the variable $message will contain the final validation message.
3. See CreepTD*.php for all available functionality.


== About CreepTD ==

CreepTD is an Open Source Online Multiplayer TowerDefense game for 1-4 players
playing on one map. It's the mother of all TD games.

Visit www.creeptd.com for more information!

test.php
<?php
include "CreepTD.php";

$mapfile = CREEPTD_BASE."/map_test.map";

echo "<pre>";
try {
    $valid = creeptd_validate_mapfile($mapfile, $warnings);
    echo "<b>Valid:</b ".(($valid) ? "yes" : "no")."\n";
    echo "<b>Warnings:</b>";
    if (empty($warnings)) {
        echo " none\n";
    } else {
        echo "\n";
        foreach ($warnings as $warning) {
            echo "- ".htmlspecialchars($warning)."\n";
        }
    }
    $map = CreepTD::parseMapfile($mapfile, $warnings, $message);
    if ($valid) {
        echo "<b>Map name:</b> ".htmlspecialchars($map->getName())."\n";
        echo "<b>Author:</b> ".htmlspecialchars($map->getAuthor())."\n";
        echo "<b>Validation message:</b> ".htmlspecialchars($message)."\n";
        echo "<b>Size:</b> ".$map->getWidth()."x".$map->getHeight()."\n";
        // $map->getPath() contains the full traversable path tree
        echo "\n";
        echo "<b>Parsed segments:</b>\n";
        foreach ($map->getPath()->getSegments() as $segment) {
            echo "  [".htmlspecialchars($segment->compile())."] depth=".$segment->getDepth()."\n";
        }
        echo "<b>Blocked coordinates:</b> "; print_r($map->getBlockedCoordinates());
        echo "<b>Compiler output:</b>\n";
        $compiledMap = $map->compile();
        echo htmlspecialchars($compiledMap);
        echo "\n<b>Re-Validation:</b> ".((creeptd_validate_mapdata($compiledMap)) ? "ok" : "failed")."\r\n";
    }
} catch (Exception $ex) {
    echo "Unable to parse map: ".htmlspecialchars($ex)."\n";
}
echo "</pre>";
?>