How to make custom maps and episodes

Preamble

So, you have stumbled upon this document by accident, out of curiosity or maybe even because you actually want to make maps for this game. If the last option is closest to the truth, read on!
Because this game is quite small it doesn't have that many maps and no one will probably ever be interested in creating a few maps for this game, so I didn't bother creating a fancy pants map editor. That means that the maps are "manually" created in a text editor and saved into a text file but it's really not that bad in the end.
That said, I chose the easy route and wrote this tutorial so that I actually could advertise this game with the possibility of creating custom maps. But have no fear. I don't do bullet-point engineering and I can assure you that this tutorial is still good   (enough).
NOTE: If you want to make your maps NOW skip here: Making maps the fast way like there's no tomorrow!
ANOTHER NOTE: If you already have a map and it just doesn't work. Check this: Possible bugs and errors in your map

Good things to know about the game

Knowing these few things you can probably make maps a little easier:
There is an automatic saving system in the game so you won't be placing any checkpoints in your map. The game saves every time you land after jumping and when you load a checkpoint, the game rewinds back three of these checkpoints. There is little more to it however but that is the main idea. If there is a difficult part in your map you want to test, just jump a few times to get the checkpoint at your current position.
When you restart a level the game will reload the map from the map file. This way you can simply restart the map to test the changes you've made.

Set up your own episode

A map cannot exist without an episode. Luckily creating an episode is as simple as creating a new folder on a computer, literally. Just create a new folder into the content/maps folder and give it a name you want your episode to have. The episode will appear automatically into the game when there is at least one map in the episode. The maps have to be named '1.txt', '2.txt', '3.txt' and so on or they will not show up in the game. You will also get progress.dat file automatically into your episode folder so you don't have to worry about that.
Remember, you can always learn from the ready-made episodes and maps.

Create maps

This is the hard part. If the game crashes when you try to play your map it's your fault, so be precise!
Now to make a map, open one of the ready-made maps in your favourite text editor and copy paste everything into your own map. The game supports map files that are saved using either Windows style line breaks (/r/n) or Unix style line breaks (/n). Mac style line breaks (/r) don't work properly but if you just use Windows Notepad you are good to go! The ready made maps use Windows style line breaks.
Now that you have already copy pasted your own map from the ready-made ones you have encountered nothing but bugs and errors. Read on as I will tell you what all that mumbo jumbo in the map files is supposed to mean!

Map format

The first thing you type into your map file is the name of your map. After that comes a line break and the map itself should start from the second line onwards. The map itself should be a rectangle shaped ascii image of the map. After the map the rest of the file contains information about the stuff in the map. This is usually mostly about the lights as they are an important part of the game. This data may also contain some random text like comments you may want to type in. Every setting specified here should be on their own line. Lastly you should have a single line break at the end of the file.
The contents of your map file would look something like this:

[name of the map]
............................
.                          .
. [ascii image of the map] .
.                          .
............................
[map settings]
[map settings]
[map settings]

"Draw" your map

As already said the map should be a rectangle shaped ascii image of the map. If the map you "draw" is not rectangle shaped the missing parts of the rectangle will be filled with empty space. The map consists of the following symbols:

To get the proper idea of what the map should look like just look at the ready-made maps. However, you should remember that there should be exactly one start and exit point in the map and that you should use different letters for different lights. The image of the map will end at the first character that doesn't mean anything for the map image like most of the capital letters (A, B, C...), numbers (1, 2, 3...) and special characters (, ; - ! ...). I have usually placed '3' on the following line of the map image to end it. Note that the characters '1' and '2' have a special effect that is covered in the next section of this tutorial.

Map settings

These settings come after the ascii image of the map starting from the following line. For example you can set the music, place texts on the map and make different kinds of lights. These can be in any order you want but I'm gonna follow the order that I have usually used. Each of these settings should be on their own line after which should be a line break. If the thing you have typed in is not a valid setting it is considered a comment and has no effect.
These are the settings that exist:

ms [music name] makes a sound file with that name to play during the map. The sounds are in content/music.
tx [x] [y] [time] [text] places a text on the map at coordinates (x,y) to appear after [time] seconds. Coordinate (0,0) is at top left corner and width and height of a single block is 10.

Editing lights

Every light has to be edited separately by typing 'a:' before the settings to edit the light "a" for example. 'b:' for light "b", 'c:' for light "c" and so on. If a light is not edited it defaults to a static light with (near) infinite size.
sz [value] sets the initial size of the light. Width of a single block is 10.
ch [value] sets the changing speed for the size of a light. This can also be negative and is applied to the size once a tick (60 ticks per second).
If the light moves 'sp [value]' is used to set the initial movement speed of the light (per tick).
To make the light move you have to add one or more positions to make a path for the light that it follows. The first position of the path is the placement position on the map. Use 'ps [x] [y] [speed]' to add new positions for the light where [x] and [y] are the relative coordinates to the previous position and [speed] is the movement speed at that position. The light will automatically return to its initial position after the last position in the path and repeat the path infinitely. The path is also smoothed so that it doesn't look edgy. The light doesn't actually even ever go to the exact positions you have specified because of smoothing.
For example:

ps 20 0 0.5

will create a new position for the light's path 20 pixels (2 blocks) to the right from the previous position at speed 0.5 and

ps 0 -30 1.5

creates a new position 30 pixels (3 blocks) upwards from the previous position at speed 1.5.

Possible bugs and errors in your map

If the game crashes when you try to play your map you have probably screwed up some settings for the map. For example

tx 230 430 Why this crash?

WILL crash the map because there isn't enough values. It should be instead:

tx 230 430 0 No more crash!

If the game doesn't crash but the map doesn't seem to work at all make sure that you have ended the map image with some character (like '3') and that you have one line break at the end of the file.
If your map loads only partly in the game it's probably because you have accidentally placed a character in the map image that doesn't mean anything as that will end the image.


Making maps the fast way like there's no tomorrow!