JMazeML Tutorial

Until I get time to work on the editor, board loading will be accomplished through XML files. I've tried to make it as painless as possible. The editor will still be a lot easier though.

Anyway, here's a short how-to on the XML files. For a more formal spec, check out the DTD.

A good prerequisite to this is a little knowledge of XML, or at least HTML. If you have neither, you may want to read W3Schools' XML Tutorial first.

The root element in JMazeML is the jmaze element. It has a title and motif attribute. The title is just your title of the current maze, while the motif is the URL of the motif to load for the current maze. Currently the only value used for motif is default.jmtf. Both title and motif are required.

<jmaze title="This Maze" motif="default.jmtf">

Next comes the info. This element contains three subelements: author, website, and message. None of these are required, although an info tag is required. Here's an example:

<info>
  <author>Jesse Bahr</author>
  <website>http://students.cs.byu.edu/~jbahr/</website>
  <message>Try to find the hidden treasure room!</message>
</info>

As you can see, the author and website are purely informational. If there is a message, the game will display it at the beginning of the maze.

Next is the big part: the layout tag. This tag contains all the information about the actual maze. The layout tag attributes, width and height, define how many squares the maze has. So for a 5x5 maze, i would do

<layout width="5" height="5">

Under a layout tag, we have 3 different things: definitions, rowFills, and the maze itself. The rowFills and the maze required the definitions to be made first.

A definitions tag contains a palette of sorts. It has all the different kinds of squares you will use in your rowFills and the maze definition. Each square should have an id element, which is used later.

I'll publish another tutorial that contains all the different kinds of squares you can define. For now, just look at the following example.

<definitions>
    <normal id="n"/>
    <blue id="b"/>
    <end id="e">
    <green id="g"/>
    <orange id="o"/>
    <red id="r"/>
    <tport id="t" x="0" y="0"/>
    <wall id="w"/>
    <water id="W"/>
    <arrow id="d" direction="down"/>

    <normal id="q">
        <item>GreenKey</item>           
    </normal>
       
    <water id="B">
        <item>boat</item>
    </water>
           
    <green id="G">
        <item>BlueKey</item>
    </green>

    <switch id="s">
        <pressAction>
            <eventList>
                <changeSquareEvent x="0" y="0">
                    <normal>
                        <item>OrangeKey</item>
                    </normal>
                </changeSquareEvent>
                <changeSquareEvent x="1" y="0">
                    <normal>
                        <item>RedKey</item>
                    </normal>
                </changeSquareEvent>
            </eventList>
        </pressAction>
    </switch>
</definitions>

I know it's a lot. Let's break this down a little.

The normal, red, green, blue, and orange squares are pretty simple; they just put one of these kinds of squares down. The normal corresponds to a square that allows you to walk over it and doesn't require a key. The color squares require the same color key. Similarly, the wall and water squares are self-explanatory, but I'll explaing them anyway. They define a square with a wall or water. Both stop the player from moving, but the wall also stops boats from moving whereas water does not.

The arrow square is a little different - it requires a direction. This defines a square that pushes the player in the direction specified. Directions can be up, down, left or right.

<arrow id="d" direction="down"/>

The tport square is similar. It is a teleporter which teleports the player to a certain location, as specified by x and y. Note that these are 0-based, with the (0, 0) point being in the top-right corner of the maze.

<tport id="t" x="0" y="0"/>

After the arrow square, we have another normal square. This one is slightly different, though; it has an item. This particular square has a GreenKey item, which is simply the green key. Some other items include Boat, Treasure, and the other color keys. You can define an item for any of the squares, as you can see with the next few squares.

<normal id="q">
    <item>GreenKey</item>           
</normal>

Finally, we have the switch square. I'll get more into square actions and events in another post; suffice it to say that this defines a switch that when pressed, places the red and orange keys on the board.

Now that the definitions are finished, we can finally define the actual board. If you do single-character ID's for your square definitions like I've done above, the board can be defined as simply as this:

nnnnn
gBbdo
GWsdr
WWwde
qnwnt

This lays out each element from my palette above into the maze. Note that whitespace doesn't matter here; it simply lays out the squares from left to right, top to bottom until they're all laid out. (Extra squares would result in an error.) Actually, I could have just as easily done

nnnnngBbdoGWsdrWWwdeqnwnt

and it would have resulted in the same maze.

So the first 'n' in the top-right corner says to put the square with id 'n' in the top-right corner of the maze. Looking back to our definitions, this is

<normal id="n"/>

- simply a normal square. Continuing on, each character in my maze turns into the square with the matching id. So the next 4 n's turn into normal squares, then the 'g' turns into a green square. (and on and on and on.)

I'll go over what to do if you want to use multiple-character id's in another post.

Finally, close the layout and jmaze tags.

    </layout>
</jmaze>

When I post the new version of the game that actually does the maze loading, I'll post this maze and link from here to the source JMML of the maze.