A scenario is created with one or more maps that connect to one another
in the four cardinal directions, or up, or down. Once the game starts,
the player can move around the maps, saving as they go, until they die,
or until they trigger a color event that fires the
EndGame piece (both color events and pieces are described
below). The EndGame piece triggers the win or loss of the
game.
On start, every scenario initially loads a map named
start.json (maps are stored in JSON format). The start map
has metadata for the scenario as a whole that doesn’t need to be
duplicated on other maps:
scenarioName: the name of the scenario (see the new game
dialog);
creator: the name of the scenario’s creator (see the new
game dialog);
description: a description of the scenario (see the new
game dialog);
startX/startY: where the player is
positioned at the start of the game.
startInv: an array of item names that should be equipped
to the player at the start of the game (if any).
Here is the JSON of an example map:
{
"folder": "example",
"outside": false,
"north": "test2",
"east": "forest-test",
"west": "keys",
"down": "test3",
"diagram":[
"##########$#######.#####################",
"#####..............................#####",
"####&..............................#####",
"#####..............................#####",
"#####..............................'####",
"#####################....###############",
"#####################....###############",
"#####################.(..###############",
"#####################....###############",
"######################.#)###############",
"####.........#########*#.###############",
"####.........#########.#+###############",
"................,.......................",
"######.###.#####.............###########",
"######.###.#...-.................#######",
"#...#...##.#.###.............###.#######",
"#.../...##.#.#####.#######.#####.0######",
"#...#...##.#.#####.#######.#####.#######",
"######1###.#.....................#######",
"######2###.#############################",
"##########......########################",
"##########......########################",
"##########......########################",
"##########....3.########################",
"########################################"
],
"terrain": {
"#": "Wall",
"$": "Shooter|southeast|Black|on",
".": "Floor",
"&": "Shooter|east|Black|on",
"'": "Shooter|west|Black|on",
"(": "StairsUp",
")": "Door|Steel Blue|on",
"*": "Pit",
"+": "Door|Red|off",
",": "StairsDown",
"-": "Turnstile|east|Maroon",
".": "Turnstile|west|Maroon",
"/": "ColorTransformer|Orange|Purple",
"0": "Switch|Maroon|off",
"1": "KeySwitch|Orange|off",
"2": "ColorRelay|Wall|Orange|Steel Blue",
"3": "Crate|Bow"
},
"pieces": [
{"x":4, "y":10, "key":"Key|Orange"},
{"x":16, "y":13, "key":"Key|Red"},
{"x":18, "y":13, "key":"Boulder"},
{"x":19, "y":13, "key":"Gun"},
{"x":28, "y":13, "key":"Key|Steel Blue"},
{"x":24, "y":14, "key":"Pillar"},
{"x":15, "y":18, "key":"Squeaky"},
{"x":25, "y":18, "key":"Squeaky"},
{"x":32, "y":18, "key":"Squeaky"},
{"x":15, "y":20, "key":"BigHammer"}
]
}
As deployed, all the maps of the scenario are stored in one scenario
folder, or a sub-folder of that folder (for example,
myScenario/theDungeon2).
The outside flag indicates whether the map is underground
or not. The color of every piece and terrain can be adjusted to the
style of map, similar to the idea of “day” and “night” modes in user
interfaces.
The cardinal directions, as well as up and down, indicate the map to
load when the player leaves the map in that direction. If the token is
"seaorb" in a scenario with the folder "datum", then the
map loaded would be scenarios/datum/seaorb.json. The
current state of the map is saved when the player leaves, and reloaded
when the player re-enters the map.
The diagram and the terrain legend that
accompanies it provide the layout of all the terrain in the cells of the
map. Any ASCII character can key the diagram to the terrain. Initially
this was to make it easier to hand-edit the maps, but an editor now
exists for this purpose.
Finally, the pieces property describes the starting
position of all the agents and items located on the map. Only one agent
can be on any given cell, but there can be any number of items (the map
editor doesn’t support the stacking of anything in a given cell; this
still requires hand-editing the map files).
Both the terrain and pieces are described
using a pipe-delimited syntax. For example, the value
TriggerOnceOnDrop|Floor|Violet|Gold Coin describes a
terrain called TriggerOnceOnDrop—if the player drops a gold
coin on this terrain (which looks like a floor), it will fire a “violet”
color event (see below).
Some pieces require embedding other pieces, for example
Statue|Triffid^None|None is a statue that looks like a
Triffid. It embeds a completely defined Triffid piece, wrapping it to
create a statue. The Triffid’s pipes are converted to “^” symbols. You
cannot embed more than one level deep. Instead you can usually achieve
what you want through a combination of multiple utility terrains that
script the game.
The map editor provides a “template” to help when creating these pieces.
The TriggerOnceOnDrop’s template looks like
"TriggerOnceOnDrop|{terrain}|{color}|{itemName}". You replace everyting
between the braces with a valid value. If the value has a question mark,
it is optional, for example, Squeaky|{color?} can be
defined as Squeaky or Squeaky|Blue.
We’ve seen colors are defined for many pieces (including no color, or
None), which is a confusing aspect of the game’s design.
These colors are not typically setting anything visual about the
piece—they are describing the color of the event that the piece either
fires or responds to. There are a few pieces that change their color to
reflect this color property (for example, doors and their associated
keys), but most pieces do not show their color association (which is
desirable because this is how the game is scripted, and players don’t
see these mechanics occurring, only their resulting effects). When a
color event is fired, all pieces and terrain on a map can respond to
that event (events are always “scoped” to the current map as a whole).
For an example, take the following two pieces:
Switch|Purple|off Reflector|north|Purple
When the player moves into a Switch, it turns on and off,
and each time it does so, it fires a color event (in this example, a
“purple” event). The Reflector rotates clockwise one
quarter turn every time it receives a purple color event. Thus
the switch on this map can be used by the player to rotate the
reflector. They are tied together by the purple color event.
There is a long list of color names that can be used for events. There are many kinds of terrain to chain effects based on this simple event system, allowing you to script anything you would want to script in the game. For details on these “utility” terrains, as well as other pieces in the game, see the API docs (every piece in the editor has an Ⓗ link to the API documentation for that piece).
At this point
the map editor should start to
make sense. It provides a way to place terrain, agents, and items; there
is a metadata dialog to define other information; and there are
directional arrows to load an adjacent map while working to connect them
together. If your map is saved, you should be able to use the
Play button to play that map in isolation while testing it.
There are also brush tools in the upper right-hand corner of the editor.
After selecting a piece you can increase the size of the “brush” which
which you paint a terrain on the board (selecting a different piece
resets this brush to 1 cell). Your cursor’s position is given in x and y
so you can set the startX and startY of the
board in the metadata dialog.
Finally, right-clicking on any cell will select the terrain in that cell, so you can work with that terrain type.