Guide to Creating Asciiroth Maps

Although there's a perfectly good map editor and you should use that (it will even allow you to preview and play your maps), this guide will start by describing the game file format, because it provides some context as to what you're doing in the editor.

The maps are described in text files using the JavaScript Object Notation
language (JSON for short). It's a simple way to mark-up a map, and you don't
need to know anything about JavaScript to create a map file. It's best to show
an example file right up front, and we can then spend the rest of this guide
describing how it works.

There's some metadata about the map's connection to other maps, where
the player should be started on the map for debugging, and whether the
color scheme represents an outside or inside terrain;

There's a diagram of the map;

Each symbol in the diagram is mapped to a "key" that describes the
terrain;

There's a collection of pieces on the map (both agents and items),
described by their X/Y coordinate and a "key".

The map editor provides a visual means of laying out all the pieces, as well as a
dialog for linking the maps and providing the other metadata. But the keys for all the
terrain, agents and items are still entered by hand in the map editor, so I'll
describe those in more detail.

Game Pieces

There are three kinds of map pieces:

Terrain. Every cell of the map has one and only one
terrain, stuff like walls, floor, or even something like a crate. Terrain
governs how the player and other agents can move around, and terrain
interacts with agents and items as they are thrown, shot, walk around, etc.

Special terrain types are all implemented as a kind of "decoration" or
"wrapper" around another terrain. For example, a trigger wraps another
terrain, adding a trigger to that terrain's behavior.

Agents. Agents are defined by the fact that there can
only be one agent in a cell at a time. So trees are agents, by this
definition. However, most agents move around and try and kill the player.

Items. There can be any number of items on any given
cell, and the player can pick them up, move them around, throw them, use
them, etc.

All three kinds of pieces are describe by a "key" that includes the type
of the piece and then some parameters, separated by the pipe symbol. For
example, the key ColorTransformer|Orange|Purple describes a
terrain type called a Color Transformer... when the player walks across it,
any orange items will be transformed into purple items. Another example is
Shooter|west|Black|on, a more complicated piece. This describes
a piece called a Shooter that shoots west, turns on and off when it receives
the black color event, and starts "on" (firing in the case of this piece).

The map editor provides a "template" to help when creating these pieces.
The Color Transformer's template looks like
ColorTransformer|{color}|{color}. You replace everyting between
the braces with a valid value. The shooter's template looks like
Shooter|{direction}|{color}|{state}. If the value has a question
mark, it is optional, e.g. Squeaky|{color?} allows for valid
values either like Squeaky or Squeaky|Blue.

Finally, you can embed one key in another by escaping the nested key with
the caret (^) rather than a pipe. For example, Crate|Key^Blue
creates a crate that has a blue key inside it. It is a limitation of the game
that you can't nested more than one deep like this. (If you find yourself in
this situation... spread out what you're doing on the map and use utility
decorators like Flagger or Messenger.)

There is currently no complete list of game pieces, but they are described
in the javadocs, and they are all listed in the
Piece Library palette of the map editor. The arguments after the type in the
key map directly to the parameters passed to these pieces in their
constructors.

Metadata

A map is linked in four cardinal directions, as well as up and down, to
other maps, by six properties: north, south,
east, west, up and down.
These values are the names of other map files without their ".js" extension.
For example, if a map declares north: "cranston", then the game
will look for the file cranston.js. They are optional.

A scenario is contained entirely in a folder, and consists of one or more
maps. The "entry" map must be named start.js. The
start.js map and any other map you'd like to preview in the map
editor need to have a startX and startY property.
These tell the game where to start the player.

Finally, there is a boolean property, outside, that indicates
whether the color scheme of the map is outside or inside. Be aware that
terrain types tend to be for one or the other setting, and don't mix well
(e.g. outside terrain tends to be light, and expects the player's symbol will
be black).

Creating Scenarios

All of the maps in a scenario go into a single folder, along with any HTML files you wish to refer to through scrolls. One of these maps, the starting map for the scenario, must be saved as the file start.js. In the map editor, there are a number of fields that are required for a start map that you can edit in the metadata editor:

The player's initial starting X/Y position;

Any initial inventory you'd like the player to have;

The name of the scenario;

The creator of the scenario;

A brief description of the scenario;

In the AIR version of the game, from the new game dialog, you'll see a Load button. Using that, you can select the folder that contains your scenario, and play it from there. The only restriction is that you cannot move the folder or you'll invalidate any saved games using that scenario.

The web version must have the scenario included in the game distribution in order to work... which I'm more than happy to do, just let me know if you've got a scenario to include.