Zinnia is a Javascript program that lets you create maps of interactive fiction games. The input to the program is some Zinnia code that describes the map. The output is a block of Javascript that you can cut-and-paste into your webpage; this code (with the help of zinnia.js) draws your map using HTML5's canvas element. The author of Zinnia is David Welbourn.
(DHTML code appears here)
General goals.
General principles.
There are four types of statements:
Objects are drawn in this order on the map: auras first, rooms second, paths third, and all the text last.
A set-statement has this syntax:
Set property to value.
Set property of something to value.
Set-statements change properties of the map itself, overriding predefined settings. Set-statements must be listed first in the code before any other statements.
Examples of each set-property:
Set id to groundFloor. | You should declare what id you want for your map canvas; this should be a unique name as far as your webpage is concerned. This is also used as a base for constructing a few javascript variables. If omitted, the default id is myMap. |
Set room-height to 50. | This sets the height of a default room cell in pixels (default is 60; min. 20; max. 200). |
Set room-width to 60. | This sets the width of a default room cell in pixels (default is 90; min. 20; max. 200). |
Set gutter to 30. | This sets the gutter width/height in pixels (default is 20; min. 5; max. 200). Gutters are the narrow columns and rows between room cells, where paths are expected to be drawn. |
Set padding to 5. | This sets the padding width/height in pixels (default is 20; min. 0; max. 50). If the map uses slides or animation, the minimum padding is 20 so the map's control buttons have somewhere to be drawn. |
Set grid to regular. | This sets all cells to be room cells; "gutter" is ignored except for the outer frame (default is irregular). |
Set height of row C to 70. | This sets the height of just the specified row in pixels (default is room-height). |
Set width of column 2 to 70. | This sets the width of just the specified column in pixels (default is room-width). |
Set back-color to aqua. | This sets the background color of the entire canvas (default is white). |
Set fore-color to navy. | This sets the default color used for room borders, paths, and text (default is black). |
Set font to Arial. | This sets the default font used for all the text (default is sans-serif).
Enclose the font name in quotes if it has more than one word; eg: Set font to "Times New Roman". |
Set size to 14. | This sets the default font-size used for all the text (default is 12; min. 6; max. 72). |
A define-statement has this syntax:
Define new-adjective as adjectives.
Define-statements define new adjectives that you can use in cell-statements. Your new adjectives will mean the same as whichever existing adjectives you defined them as. You don't ever need to use define-statements, but they can be a time-saver when creating larger maps.
For example, you might write:
Define maze as rounded lawngreen darkgreen-texted.
A1: maze room "Hedge Maze".
A2: -
A3: maze room "Hedge Maze".
etc.
If you decide that lawngreen was the wrong colour to use, it's easier to change what "maze" means in the define-statement than change lawngreen to limegreen, say, in all the room-statements.
Some restrictions:
Slide statements are very simple:
Slide slidenumber.
A slide is one map in a collection of maps that are presented together in a slideshow. Most Zinnia maps don't need slides, but it's useful for those games whose maps undergo major transformations in their maps.
Slide-statements are used at the beginning of the set of cell-statements that describe that slide. Slides are numbered beginning with 1, however "slide 0" is understood to refer to cells that belong to all slides.
A cell-statement has this syntax:
Cell: something.
Cell to Cell: something.
A cell is a rectangular area of the map, specified by row and column.
A range of cells also refers to a rectangular area of the map, using the top-left corner of the first named cell to the bottom-right corner of the second.
The something after the colon describes either a room, a path, or an aura.
You may describe rooms, paths, and auras in any order; however, all auras are drawn first (in the order described), then all rooms (in the order described), then all paths (in the order described).
letter number , e.g.: B5 or G12,
where the letter names the row, and the number refers to the column.
Row names go from A to Z, then AA to ZZ. The top row is row A.
Columns are numbered from 1 to 99. The leftmost column is column 1.
Note that the padding around the outer edge of the map cannot be refered to with cell references.
Of course, this is just a recommendation, not a restriction. You may place rooms and paths in whichever cells you want and use set-statements
to resize specific rows and columns. You can also use Set grid to regular if you want a regular cell grid.
In essence, one is permitted to subdivide a cell into nine parts, by imagining a vertical gutter and horizontal gutter running through its center and middle. For example:
A'1 refers to the top slice of cell A1.
A''1 refers to the horizontally middle slice of cell A1.
A'''1 refers to the bottom slice of cell A1.
A1' refers to the left slice of cell A1.
A1'' refers to the vertically center slice of A1.
A1''' refers to the right slice of cell A1.
Note that gutter cells cannot be so subdivided within their smaller dimension.
A room-statement has this syntax:
Cell (to Cell): adjectives room ((with) text-phrase, …)
standard room.
Several predefined adjectives for rooms are meant to convey information about the rooms:
dim means the room is dimly lit. This is indicated with a silver background.dark means the room is unlit. This is indicated with a black background and white text.wet usually means the room is filled with water. This is indicated with an aquamarine background.region means the "room" is actually a region of several rooms in the game. This is indicated with a 5px dashed border and italic text.virtual or fake means the room is only implied by the game; the player-character can't stand there.
This is indicated with a thin dashed border and unbolded italic text.comment means the "room" isn't a room at all, but just a comment we want on the map.
This is indicated with no border at all, transparent background, and unbolded italic text.A couple other adjectives control shapes and shadows:
rectangular means draw a rectangular room border (the default shape, coded as shape 1).rounded means draw the room border with rounded corners (shape 2).oval means draw the room border with an oval shape (shape 3).octagonal means draw the room border with an octagon shape (shape 4).cross means draw the room border with a cross shape (shape 5).abcd-shaped means to draw a custom border, where each corner is based on a standard shape.
The corners are specified clockwise from top-left to bottom-left; the shapes are indicated by the digits 1 through 5, as above.
For example: 1122-shaped gives us rectangular top corners and rounded bottom corners,
while 1414-shaped results in a rectangle with the top-right and bottom-left corners cut off diagonally.shadowed means add a shadow to the right and bottom edges of the room.Some adjectives control the thickness of the border:
borderless for no border (0 pixels),thin for a 1-pixel border (the default),thick for a 2-pixel border,very-thick for a 3-pixel border,heavy for a 4-pixel border, andvery-heavy for a 5-pixel border.And there's color adjectives. Be a bit careful with colors: are you trying to set the background-color, the border-color, or the text-color of the room?
color means to set the background-color of the room to color.color-bordered means to set the border-color of the room to color.color-texted means to set the default color of text in this room to color.color-directionward means we want a gradient background, using this second color and direction.
For example, black blue-eastward means a linear gradient from black to blue, west to east.
For a circular gradient, we can use out or in as our direction, eg: darkblue black-outward.
These work slightly different; out uses the larger dimension of the cell for the outer circle,
where in uses the smaller dimension of the cell instead. We can also use side
and level as directions to indicate vertical and horizontal splits, with the first color in the center
and the second color at opposite outer edges.transparent means to have no background-color; let the canvas (or aura) color show through.Finally, some adjectives set default properties of the text:
bold for bold text,italic for italic text,plain for text that is neither bold nor italic, andnumberpx sets the default font-size, eg: 20px.Note that adjectives are applied in the order specified in a statement, so "bold plain" is rendered plain, but "plain bold" is rendered bold.
A path-statement has this syntax:
Cell (to Cell): adjectives path (from) direction (via direction) to direction (with text-phrase, …)
Adjectives for paths control its appearance or style:
one-way = An arrowhead should be drawn on the head end.two-way = Arrowheads should be drawn at both ends.thin = Draw the path line with 1 pixel thickness (default).thick = Draw the path line with 2 pixel thickness.very-thick = Draw the path line with 3 pixel thickness.solid = Draw the path as a solid line (default).dashed = Draw the path with dashes, a broken line.color = Draw the path with that color (default is "black", unless overridden with a set fore-color statement).straight = Draw the path as one straight line between the anchor points (default).bent = Make a small circular arc at the "via" anchor point (instead of a sharp angle).curved = The entire path is drawn as a curve (requires a "via" anchor point).u-turn = The path is U-shaped; the path returns to the same room. By default, a u-turn is clockwise and its endpoints are on
either side of the from anchor point, rather than on the point itself.from describes where the tail end of the path is.via, if specified, describes where a midpoint of the path is.to describes where the head end of the path is.| NW | NWbN | NNW | NbW | N | NbE | NNE | NEbN | NE |
| NWbW | NEbE | |||||||
| WNW | mNW | mN | mNE | ENE | ||||
| WbN | EbN | |||||||
| W | mW | C | mE | E | ||||
| WbS | EbS | |||||||
| WSW | mSW | mS | mSE | ESE | ||||
| SWbW | SEbE | |||||||
| SW | SWbS | SSW | SbW | S | SbE | SSE | SEbS | SE |
Second, direction names a specific point relative to the cell's border:
nw, nwbn, nnw, nbw, n, nbe, nne, nebn,
ne, nebe, ene, ebn, e, ebs, ese, sebe,se, sebs, sse, sbe, s, sbw, ssw, swbs,
sw, swbw, wsw, wbs, w, wbn, wnw, and nwbw;
mnw, mn, mne, me,
mse, ms, mw, and mw;
c.tail, via, and head.
Path text-phrases use this syntax:
adjectives "text" on/over/above/under/below/left/right/direction (of) head/via/tail
The adjectives for path text-phrases are the same as for room text-phrases: bold, italic, plain, color, etc.
The various prepositions attempt to pick both a point relative to the path's control point and associated justification:
on or center = Use the path's control point as is with centered justification, deliberately putting text overtop of the drawn line.over or above = Is interpreted as one of northwest (if at right edge of the cell),
northeast (left edge), or north (otherwise).under or below = Is interpreted as one of southwest (if at right edge of the cell),
southeast (left edge), or south (otherwise).left = Is interpreted as one of northwest (if at bottom edge of the cell),
southwest (top edge), or west (otherwise).right = Is interpreted as one of northeast (if at bottom edge of the cell),
southeast (top edge), or east (otherwise).northwest = Pick a point slightly up and to the left of the control point and print with bottom right justification.north = Pick a point slight above ... with bottom centered justification.northeast = Pick a point slightly up and to the right ... with bottom left justifcation.west = Pick a point slightly to the left ... with middle right justification.east = Pick a point slightly to the right ... with middle left justification.southwest = Pick a point slightly down and to the left ... with top right justification.south = Pick a point slightly below ... with top center justification.southeast = Pick a point slightly down and to the right ... with top left justification.A quick-path-statement has this syntax:
Cell (to Cell): pathcode
Some path types are so common, it's useful to have short syntaxes for them.
| Pathcode | Path equivalent |
|---|---|
| | Path from north to south |
- | Path from west to east |
\ | Path from nw to se |
/ | Path from ne to sw |
X | Path from nw to se. Path from ne to sw |
There are no provisions for modifying quick-paths in any way with adjectives. If a quick-path can't describe the path you want, use standard path(s) instead.
n, north, s, south, w, west, e, east, nw, northwest, ne, northeast, sw, southwest, se, southeast, c, center.
Directions mean different things depending on context. In a path definition:
adjectives "text" preposition somewhere
To be more specific, room text-descriptions use this syntax:
adjectives "text" on/at direction
Path text-phrases use this syntax:
adjectives "text" on/over/above/under/below/left/right/direction (of) head/via/tail
The adjectives defined for text are:
bold for boldface text (the default for room text),italic for italic text,plain for text that is neither italic or in boldface (plain is the default for path text), andblack, red, etc. for text in that color. Text color is usually black unless overriden by a set fore-color
statement or a room adjective like dark (which sets room text to white).x+number, x-number, y+number, y-number nudge the text a little
bit further right, left, down, or up respectively by number pixels. (Yeah, I know, "x+2" isn't an adjective that rolls easily off the tongue.
You try to invent more appropriate adjectives.)Text in rooms is oriented on or at one of nine points in the room's rectangle: the four corners, the center,
and the midpoints of each side. Each of these nine points is named with the appropriate direction. Text printed on a point is centered
both horizontally and vertically around that point. Text printed at a point is printed within the border, pulled slightly towards the center
to avoid overlap, and the text is suitably justified.
Multiple text-descriptions are separated by commas or the word "and", e.g.:
Room "Middle\nof Stairs" with "[utri]" at ne and "[dtri]" at se.
You probably won't use auras much, but they have their uses. Auras are colored rectangles drawn on the map before any rooms or paths, and they're always drawn just a big bigger than the cells defining them. The syntax of an aura-statement is simple:
Cell (to Cell): adjectives aura.
The predefined adjectives for an aura are:
big for a bigger aura (a 12 pixel glow; the default is 8 pixels),small for a small aura (a 4 pixel glow),rectangular, rounded, oval, octagonal, cross,
and nnnn-shaped for the aura's shape, same as for a room. The default shape is rectangular.red, aqua, etc. for the color of the aura. The default color for an aura is white.Note that if you declare small auras inside regular auras, where the small auras are the same color as the canvas, this creates a colored outline around your chosen cells.
I thought 147 colors ought to be plenty for making maps with, but in case it isn't, you can also use #rrggbb color names. For example, I really wanted to use these colors for one map set at night:
#440000 #004400 #000044
Special characters in text strings...