Created map basics (markdown)

map-basics.md

@@ -0,0 +1,56 @@
+# 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 about 2000 x 2000 pixels in size. If you want to be as compatible as possible, make sure the file is [[power-of-2-sized|power-of-2-size]].
+
+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:
+
+![Example map template](https://web.archive.org/web/20180420024953if_/http://aquariawiki.ryanballantyne.name/wiki/images/Template.png)
+
+# Create a map
+
+In the following paragraph we want to create a map _awesome.xml_. Create & edit the map template.
+
+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 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 will become solid  black blocks). Next, press F12. This will distribute wall tiles taken from the [[tileset|tilesets]] along the walls. This process can take a few seconds for very large maps.
+
+What happens in detail:
+* Delete all tiles on [[Layer 5|layers]]
+* Find edges between wall and free space and determine [surface normals](https://en.wikipedia.org/wiki/Normal_(geometry))
+* Place tiles on [[Layer 5|layers]] so that all edges on the map are covered and the tiles are properly rotated.
+
+Whenever you change the map template you need to repeat this process (_F11_+_F12_). Therefore you should not place your own tiles on [[Layer 5|layers]] and instead keep this layer free for the auto-placed tiles.
+
+After pressing F12, 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 put 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 as long as you don't touch [[Layer 5|layers]] manually.
+
+### 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.
+
+
+