Map basics

A map is an XML file in the maps directory. It contains placed tiles, entities, nodes, fish schools, and collision data. A map file is loaded by the game whenever a map is entered.

A map template is a black-and-white PNG image in the maptemplates directory. It is used by the map editor to generate and populate a map file with basic tile data.

White: Water/air
Black: Wall

You can create a map template in any paint program. (It's recommended to disable anti-aliasing if your paint program enables this by default. You want jagged edges here.)

Map template files can be up to 2048 x 2048 pixels in size. If you want to be as compatible as possible, make sure the file is power-of-2-sized.

Important: Always save the map template as 32-bit PNG. Exactly 32-bit PNG, or the game might be unable to load it later.

Note that it is always possible to extend a map template size to the bottom right later if it turns out that you started too small. Try not to move contents of a map template around later as this can be a huge hassle when you have already placed your own things on a map).

Example map template:

Create a map

In the following section we want to create a map awesome.xml. Create & edit the map template.

To create the actual map, the safest way is to copy an existing empty map file (e.g. _mods/aquariatemplate/maps/template.xml), save that in your own mod, and start form there. Whenever you create a new map you can copy the file, rename the copy, and then modify it to your liking.

[OSE only] You can use the editor to enter a map that does not have a XML file yet. The editor will be unhappy and show an error background, but from there you can save the map and the XML file will be created. You'll have to adjust more things by hand later but at least it will create the basic file structure. This does not work in older versions -- they will just crash when you attempt to save a non-existing map.

Assuming you copied the template.xml file to your mod's maps directory: Copy template.xml again and name the copy awesome.xml. Next, load up your mod if you haven't already, enter the editor with Tab, press Shift+F1 to open the load-map prompt, enter awseome and press Return. This will enter the map but it will not look like your awesome map template.

Modify a map

After entering the map, open the editor (Tab) and press F11. If your map template is correctly set up this will load the map template, and populate the map with wall data (i.e. black pixels in the PNG will become solid black blocks in the game). Next, press F12. This will distribute wall tiles taken from the tileset along the walls. This process can take a few seconds for very large maps.

What happens in detail:

Delete all tiles with tileset ID 1-4 (border tiles) on Layer 5
- Tiles outside of this range are not affected; while you can place other tiles safely on this layer it's better to not use it unless you absolutely have to.
Find edges between wall and free space and determine surface normals
Place tiles on Layer 5 so that all walls on the map are covered and the tiles are properly rotated.

Whenever you change the map template you need to repeat this process (F11, then F12). Therefore you should not place your own tiles on Layer 5 and instead keep this layer free for the auto-placed tiles.

Afterwards, save the map with F2, and reload it (F1). You'll always want to reload the map after you change & apply the map template, as map boundary and camera settings are only applied on map load and might be incorrect if the map size is changed.

In case you are making a map like the energy temple, where you cover the walls yourself with elongated wall tiles and you don't want the auto-placed wall tiles: Too bad. The whole map is re-filled whenever you press F12. You'll have to delete all the tiles you don't want afterwards. Every time. So it's good to get your map template right as early as possible on this kind of map. You could only press F11 and place tiles manually but this might be very tedious.

When the map template is applied and the wall tiles are generated you can start to place your own tiles. It's safe to alternate between modifying & applying the map template (F11, F12) and placing your own tiles at any time. Just don't forget to save often.

Common pitfalls

Remember that every time you save the map from the in-game editor, the XML file is updated. If you have the map open in a text editor at the same time make sure your editor picks up the file change, otherwise you might lose data if you save via map XML file in the text editor later.
Same thing applies when you modify the map in a text editor. Reload the map in-game afterwards; if you just continue editing, your changes will be gone the next time the map is saved.

Editing map files by hand

For some things, editing map files by hand is necessary.

Schools of fish

TODO