I was planning on writing the docs for this a bit later, but what the heck.

I don't feel like doing anything else at the moment, so let's see what happens.

---

I am working on the game a lot now (yes, we know that), so I should have a first release ready quite soon. At least a lot works now at the moment, but I just want it to be slightly more playable before packaging it

---

Anyway, here is a short reference on how to create your own costum maps and units for the game. If you want to test them, you can define which unit files to use in the game's setup script (this is a temporary testing solution. I'll make a UI generating the script when the game reaches a later stage).

Do note that the current file definitions are subject to change. There are some things that need improvement, so they might actually change. If they do, I'll edit this blog post according to the new definitions.

Making your own maps

The map file is formatted using XML.

See the spoiler for a sample map file:

<?xml version="1.0" encoding="utf-8"?>
<mapFile>
<meta>
<type>map file</type>
<encoding_version>1.0</encoding_version>
<file_version>1.0</file_version>
<description>basic test map</description>
<author>Bart</author>
</meta>

<options>
<height>22</height>
<width>28</width>
<numFeatures>14</numFeatures>
</options>

<map>
<row>1110011101101101111111111010</row>
<row>0101010101101101000010001010</row>
<row>1110110110111111111111111010</row>
<row>1111001101011011111111111111</row>
<row>1001011110010110100001001010</row>
<row>1101111011110111111111111010</row>
<row>1100101010110110100001001010</row>
<row>1101011011011111111111111010</row>
<row>1101110110110000100001001010</row>
<row>1111011111011011111111111010</row>
<row>1110011101101100100001001010</row>
<row>0101010101101101111111111010</row>
<row>1110110110111110100001001010</row>
<row>1111001101011011111111111010</row>
<row>1001011110010110100001001010</row>
<row>1101111011110111111111111010</row>
<row>1100101010110110100001001010</row>
<row>1101011011011111111111111010</row>
<row>1101110110110000100001001010</row>
<row>1111011111011011111111111010</row>
<row>1110011101101101111111111010</row>
<row>0101010101101101000010001010</row>
</map>

<features>
<feature type="credits" value="200" x="13" y="1"/>
<feature type="credits" value="100" x="9" y="5"/>
<feature type="credits" value="200" x="10" y="10"/>
<feature type="credits" value="100" x="4" y="5"/>

<feature type="startLocation" value="1" x="15" y="3"/>
<feature type="startLocation" value="1" x="15" y="4"/>
<feature type="startLocation" value="1" x="15" y="5"/>
<feature type="startLocation" value="1" x="15" y="6"/>
<feature type="startLocation" value="1" x="15" y="7"/>

<feature type="startLocation" value="2" x="1" y="6"/>
<feature type="startLocation" value="2" x="1" y="7"/>
<feature type="startLocation" value="2" x="1" y="8"/>
<feature type="startLocation" value="2" x="1" y="9"/>
<feature type="startLocation" value="2" x="1" y="10"/>
</features>
</mapFile>

And this is the result:

So here is a more deatiled definition of the file:

- do not forget the xml starting tag when creating an xml file! the app will throw an error in case it is missing

- The root node must be called mapFile

- the meta tag:

• map file.
  
• encoding_version: the map file definition version
  
• file_version: the version of your map
  
• description: the description of your map
  
• author: who made the map?
  

- options (at the moment you need to get these values right, but I think it is better to make the code read the numbers from the xml file itself (duh), which I'll add in one of the releases)

• height: the number of tile rows
  
• width: the number of tile columns
  

- map: the map tag is the actual map definition area. If you look at the sample map code, you can see that each row is enclosed by a <row> tag, which encloses a series of 1's and 0's. Logically, a 1 represents an enabled tile, while 0 represents an empty space

- features: Every map has some features. At the moment, you can add credits on a tile, or a startspot. I am not really sure yet what to make of the credits, since this game does not really have the same overall structure as seen in the original spybotics game, so suggestions are welcome

The startspot is important, however, and provides a place for a player to place his/her units.

The attribues are:

• x/y: the coordinate of the feature. The index starts counting at 1
  
• type: either "credits" or "startLocation"
  
• value: for credits, this is how much credits the spot is worth. For the start spot, this is where the players with id [value], starting at 1, can place his/her units. Other players won't be allowed to place anything there.
  

Making your own units

A sample unit file:

<?xml version="1.0" encoding="utf-8"?>
<unitFile>
<meta>
<type>unit file</type>
<encoding_version>1.0</encoding_version>
<file_version>1.0</file_version>
<description>basic test unit</description>
<author>Bart</author>
</meta>

<properties>
<speed>4</speed>
<maxSize>7</maxSize>
<name>test</name>
<description>test unit</description>
</properties>

<weapons>
<weapon name="throw" type="hit" range="2" power="2" minSize="0" healthCost="0" description="Damages the target by 1"/>
<weapon name="boost" type="boost" range="1" power="2" minSize="1" healthCost="1" description="Boosts the target by 1"/>
</weapons>

<visuals>
<picture>units/pics/unit.png</picture>
</visuals>
</unitFile>

Tag reference:

- unitFile is the required root node

- the meta part is pretty much the same as in the map file

- the unit properties:

• speed: the amount of tiles the unit is allowed to move each turn
  
• maxSize: the maximum size of the tail of the unit (the chain of sectors that follows the unit)
  
• name: the name of the unit
  
• the description of the unit that will be shown ingame
  

weapon tag syntax:

<weapon name="slash" type="hit" range="1" power="4" minSize="2" healthCost="1"/>

- name: name of the weapon, as it is displayed ingame

- weapon type (see below)

- range: how many squares away the weapon can reach. Must be equal or greater than 1

- power: magnitude of damage (also used for other purposes. See below for details)

- minSize: the minimum size the unit has to be before the weapon can be used. Must be set to 0 if there is no limit.

- Amount of sectors reduced from the unit when the weapon is used. Must be set to 0 if no health is reduced.

Supported weapon types:

- noAction

Does nothing at all. Is probably only going to be used by the default "no action" weapon

- hit

A regular weapon, that deals damage to the enemy

- mapOn

Adds a tile on the selected location on the map

- mapOff

Deletes a tile on the selected position on the map

- slow

slows down a unit (by the amount of power)

- boost

speeds up a unit

- addRange

increases the range of a unit by [power]

- decreaseRange

decreases the range of a unit by [power]

- addSize

increases the maximum size of the targeted unit by [power]

- decreaseSize

decreases the maximum size of the unit by [power]

- heal

adds a tile to the unit's

- selfDestruct

deals a large amount of damage (in that way same as hit), but kills the unit

A unit can have up to 5 weapons, but I am not sure about the other necessary restrains (so that you don't get units of 100 fire power, which is *slightly* overkill, and doesn't make the game fun to play)

creating the script.xml file

coming when I feel like writing something more. Buit when I have the UI finished, it will not be applicable anymore, since the game will generate it automatically.

At least I can post a sample script file for now:

<?xml version="1.0" encoding="utf-8"?>
<startupScript version="1.0">
<map src="maps/testmap.map" />
<player id="0" type="local" teamColour="0xFFFF00" name="Bart">
<unit src="units/testUnit.xml" x="14" y="5"/>
<unit src="units/testUnit.xml" x="1" y="5"/>
</player>
<player id="1" type="AI" teamColour="0xFF0000" name="AI-bot">
<unit src="units/testUnit.xml" x="1" y="3"/>
<unit src="units/testUnit.xml" x="1" y="4"/>
</player>
</startupScript>