Bird's-eye view of a PuzzleScript file

A puzzlescript file is divided into 8 sections:

Levels

Here's where all the fun happens.

Structure of the section

A level section of a file looks something like this:


LEVEL
TITLE A tough start
#########
#.......#
#.*.*.O.#
#..*..O.#
#.P.*.*.#
#.......#
#########

MESSAGE Woah, that was tough, eh?!

LEVEL lvl two
#########
#.....@.#
#.P.*.O.#
#.......#
#########

TITLE:NOHEADER This is the last level
#########
#.....@.#
#.P.*.O.#     
#.......#
#########

MESSAGE Thank you for playing the game.

Levels are separated by blank lines and preceded with an optional short name (LEVEL) and a description of a title screen for that level (TITLE). You can also display messages if you want to, before or after the level (MESSAGE).

Specifying the content of a level

The content of the levels themselves are defined with a grid of characters, using the definitions in the legend section. Notably, if you want to have several objects occupying a single tile, you can specify this in the legend using and:

@ = Crate and Target

If you hold CTRL (or, on a Mac, CMD) and left click on the level in the text editor, it will load it in game. You can then open the level editor with E.

Level names

With the LEVEL command you can introduce a new level and give it a name (if you don't, it will be named Level N, where N is the index of the level in the list). This name will appear in the pause menu and in the "continue from" option of the game's title screen. For that reason, it should be short (maximum 16 characters) and make sense for the player.

Title screens for levels

You can generate title screens to introduce your levels, and there are two ways to do it: explicitly or automatically.

You can generate explicitly a title screen for a level with a command like:

TITLE Where our hero meets his destiny

By default, the text following the TITLE keyword will be displayed below the level's name in a message screen (styling options will soon be available). You can change this default with the preamble option LEVEL_TITLE_STYLE, by setting it to header or noheader. The default is header, where a header with the level's name is added before the title text (which can be empty). noheader only displays the title text without header (if there is no text, it will use the level's name, but not styled as a header).

You can also use the commands TITLE:HEADER and TITLE:NOHEADER to use the corresponding style instead of the default for a specific level.

You can also generate title screens automatically for each levels or for the levels that have been named. This is equivalent to (but more practical than) adding a TITLE command (without text following it) for each level or for each named level. You can decide which levels will automatically get a title screen with one of these preamble options:

AUTO_LEVEL_TITLES (all levels)
AUTO_LEVEL_TITLES named (only the levels that have been given a name with a LEVEL command)
(just don't write any of the above to get the default behavior: generating title screens only when a TITLE, TITLE:HEADER, or TITLE:NOHEADER command is used in a level)

The automatic generation of a title screen can be prevented for specific levels by using the command TITLE:NONE in them.

What stuff is hard to do?

Branching. I have no support for it in terms of this level structure. If you want a continuous open world you can set zoomscreen or flickscreen in the prelude.

If you can think of an elegant way to implement level branching in the engine, let me know, and I'll consider it : )