Zinnia v3

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.




[ERROR: This map editor requires HTML5's canvas element.]
(DHTML code appears here)

General Goals and Principles

General goals.

  1. Easy to read and edit code.
  2. Concise code for common map requirements.
  3. Giving myself more options for my maps; for example: rounded rectangles, dashed lines, curved lines, putting symbols at or on room corners, etc.
  4. Let other people use this tool if they want to.

General principles.

  1. A grid. Because I was used to creating maps with <table> elements, I wanted to continue using a grid for map layout. Alignment is attractive. So rooms can't be placed just anywhere on the canvas; they must be aligned with the grid's cells.
  2. No math. I don't want to have to do any calculations to figure out (x,y) co-ordinates of anything. I just want to describe my maps; let the program figure out all those numbers.
  3. Natural language. Readability has to trump conciseness for more complicated constructions. I found it very difficult to develop algebraic or computerese syntaxes to describe paths, for example, without it looking like gibberish. Also, adjectives are amazing.
  4. Compass directions. Corners, sides, and subdivisions of cells are refered to with compass directions. I much prefer "from west to east" over "from left-middle to right-middle".

Zinnia Syntax

  1. Zinnia code is a list of statements, one statement per line. Statements cannot be broken across two or more lines. Statements can end in periods, but they're not needed.
  2. 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".


    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).

    [ERROR: This map requires HTML5's canvas element.]
    1. Cell names. A cell name is usually of the form: letternumber , 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.

    2. Irregular cell grid. By default, the cells on the grid are not all the same size. The odd rows are taller than the even rows, and the odd columns are wider than the even columns. It is expected that you will want to place most rooms at the intersection of odd rows and odd columns where the cells are at their largest; the even rows and even columns are called "gutters" and reserved for paths.

      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.

    3. Sub-cell references (ADVANCED). A cell reference can also refer to partial cells by using upto three prime-marks after the row or column reference.

      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, …)

    1. Room-adjectives. By default, rooms are drawn with white backgrounds, a thin solid black rectangular border, and centered bold black text. This is the 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.
      [ERROR: This map requires HTML5's canvas element.]

      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, and
      • very-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, and
      • numberpx 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, …)

    1. Path-adjectives. By default, a path is straight, thin, solid, black, and unadorned.

      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.
    2. From, Via, and To. This is how we roughly describe where the path goes. First of all:
      • 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.

      Second, direction names a specific point relative to the cell's border:

      • On the border of the cell, starting clockwise from the top-left corner:
        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;
      • In the middle of the cell, these midpoints are halfway between the border and center:
        mnw, mn, mne, me, mse, ms, mw, and mw;
      • And the center point: c.
    3. Text-phrases. Text-phrases are specified a bit differently for paths than for rooms. Where a room has nine control points where text can be placed, paths have only three: 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.

    PathcodePath equivalent
    |Path from north to south
    -Path from west to east
    \Path from nw to se
    /Path from ne to sw
    XPath 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.

  10. Direction is any compass direction (or its standard abbreviation) or "center" (or its abbreviation "c"):

    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:

  11. One or more text-descriptions may be specified with a room or a path; these are usually small bits of text to be displayed. The general syntax of a text-description is:

    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:

    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:

    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.

  13. Colors are usually refered to only by name, using the 147 HTML Color Names that all browsers should know:

    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 

  14. Special characters in text strings...