The full Glimmr download package includes a compiled file, Basic Floorplan Toolkit.gblorb, that is intended to allow authors to produce floor plans for (indoor) interactive fiction games. The Basic Floorplan Toolkit is an instance of the Glimmr Canvas Editor that is preloaded with a set of images representing rooms, hallways, stairways, and doors. The floor plans that the Toolkit produces are based on the feelie maps Emily Short produced for her game Bronze. The design is quite simple, but it also gets us a good way beyond your purely functional box-and-line IF map. Here’s an example:
As with other instances of the Canvas Editor, you build your floor plan visually in Basic Floorplan Toolkit, and then export Inform 7 source code which, when pasted into your game, will recreate your composition. If you tweak a few things while setting up your plan, the map will be self-revealing, with each room appearing on the map only after the player has visited it. You can also set up a little Parcheesi piece to represent the player, and its movement through the map will be automated.
Detailed instructions for the use of the Canvas Editor can be found in that extension’s documentation. This tutorial is intended to allow interested folks to get into using the Basic Floorplan Toolkit with a minimum of background reading. You can download a game file (gblorb format) of the map we will be creating here.
The Toolkit is designed for use with Glimmr Canvas-Based Drawing, the centerpiece of the Glimmr system of extensions. The basic idea is that we place individual “graphic elements”—e.g., images representing rooms, hallways, staircases—to a “canvas” object. The canvas is really just a coordinate system, an imaginary rectangle 600 units wide, say, by 400 units high. The canvas, along with whatever elements have been placed on it, is drawn to a Glulx graphics window. Glimmr Canvas-Based Drawing automatically scales the canvas to fit in the available window space (though this can be customized). Graphic elements are represented by objects, and we can move them around, change their size, hide them, or whatever at will, which allows for the kinds of dynamic maps that the Basic Floorplan Toolkit is designed to produce.
Getting Started with Basic Floorplan Toolkit
To get started with the Toolkit, just open the gblorb file in a glulx interpreter such as Gargoyle, Zoom, or Windows Git (links). Try to get the most recent version you can, as a number of bugs in these interpreters have been fixed during the development of Glimmr. (A few bugs still remain to be fixed—Zoom displays some colors incorrectly, for example.)
An introductory screen appears. You can enter the dimensions of the canvas you are building here if you like, but for now just type SKIP to go straight to the editor (the editor will choose dimensions for you).
The black window pane that takes up most of the space is the editor window, which shows the canvas (outlined in white); this is where we will build the floor plan. Off to the right is the image library window. Click on an image in the library to add a copy of it to the canvas (it will appear in the editor window). Another way to get graphic elements onto the canvas is to draw them using the drawing tools window. The control panel, in the lower left, provides most of the commands needed to use the Toolkit. Nearly all commands can also be entered textually in the command line window, and feedback about commands always appears here whether entered were entered using button presses or typed commands. Finally, the layers window shows the vertical stacks into which the canvas is divided. At the start there are only 2 layers, but the editor allows up to 24; elements placed on higher layers appear “on top” of other elements.
Positioning room elements
We’re ready to dive in. To give us some focus, let’s recreate this section of the map from Zork (don’t worry, it’s from early in the game so it shouldn’t spoil you too badly if you haven’t yet played it). I7 source code for the section we’ll recreate can be found here. Let’s start with the Round Room, at the center of the mini-map.
Click on the smooth round shape toward the top of the image library window (on the right side of the screen). A copy of the room outline will appear in the center of the editor window; in fact, newly added images always appear at the center of the editor. Since the Round Room is also at the center of our little map, let’s just leave it there for now.
So now we have the Round Room, the lynchpin of our map, in place. Let’s add the Loud Room, to the east. Click on the short horizontal hallway image to add it to the map (in the screenshot at left, this is the third element in the second row of the library). The image will appear highlighted in blue on top of the Round Room icon. We’ll want to move it to the right so that it can serve as the connector between the Round and Loud rooms. To do this, be sure that the “Move” tab is selected in the control panel (to select the tab, just click on Move in the bottom right of the control panel). When the Move tab is active, the editor is in Move mode, meaning that clicks in the editor window will be interpreted as attempts to move the selected element to that location.
Try it now: with the new hallway element still highlighted in blue, click in various places in the editor window to move it around the screen. Note that the location clicked marks the upper left corner of the element, which is known as the origin of the element. When an element is selected, its origin coordinate is displayed in the green bar just beneath the editor window.
When you’ve had enough of practicing, click on the right side and just above the center of the Round Room icon to place the horizontal connector there. Allow the connector to overlap the round shape by a couple of pixels. The result should look something like the image at right.
The easiest way to position things precisely is to use the Nudge buttons, which you can find toward the center of the Move tab (see image at left). Press the arrows to move the selected element(s) 1 pixel in the indicated direction. (The number of pixels moved per nudge can be changed using the “Nudge amount” button.) Get as close as you can to the proper position by clicking in the editor window, and then make fine adjustments using nudges.
Next, click on the vertically oriented rectangular room outline (row 1, last image in the image library screenshot above). Now move it to the right of the short connector. Again, allow the images to overlap by a couple of pixels.
The Loud Room looks pretty large compared to the Round Room, and we’re going to need to put passages and rooms both north and south of it. Let’s resize it a little. The Loud Room should already be selected; if it isn’t, click on the Select tab in the control panel. Click in the empty space around the elements to deselect anything else that might be selected, and then click on the Loud Room outline.
Now bring up the Scale tab in the control panel. When the Scale tab is active, clicking in the editor window will adjust the size of the selected image. Basically, a click to the right and below the origin of the image will be considered as its ideal “endpoint” (lower right corner). However, this is subject to whether or not the image is being scaled symmetrically or asymmetrically. If the image is being scale symmetrically, then only the width is considered—the shape (or aspect ratio) of the image will not change. If on the other hand we scale asymmetrically, the aspect ratio of the image will be changed, and the location where we click will be taken as the lower right corner of the image. (Currently, only sprites and image-rendered strings can be resized in this way. Future versions will add the capability to primitives as well.)
So, in the Scale tab, click on the Asymmetrical Scaling radio button: we want to change the shape of the Loud Room. Then click a bit up from the bottom of the image, as shown by the red dot here:
A blue outline indicates that the image has been resized. You can type INFO now to see details about the Loud Room outline. The scaling line should show the ratios for both the x and y axes. Mine says “scaling: 1.0000 (x) by 0.8333 (y)”.
The locations north, south, and west of the Round Room are actually passageways. While they would be depicted as boxes like all other rooms on a schematic IF map, we don’t face the same constraints. We can use long hallways to depict them.
But looking in the image library, we find that the horizontal and vertical hallways images are quite short—far too short for this. Again, the solution is to resize them. Click on the short horizontal hallway in the library to bring a copy up in the editor. Now stretch it just as you did the Loud Room, this time clicking to the right of the image boundary so that the size increases.
Do the same with two vertically oriented hallways, and place them according to our model. The result should something like this:
The Toolkit includes a set of rough-hewn images for use in depicting caves and the like. The room to the southeast of the Round Room is called the Engravings Cave, so perhaps the more cavernous imagery is appropriate there. Add two short, diagonal rough-hewn hallways to the editor—you may need to click on the arrow in the upper right corner of the image library to find the image. Place these together so that they look like a single, long hallway to the southeast of the Round Room (you will probably want to use the Nudge tools to get these to line up correctly). Finally, add one of the squarish rough rooms and overlap the lower half of the hallway with it. Our map should now look like this:
Now let’s add a few more details. The room (hallway) to the north of the Round Room, the North-South Passage, has another hall that branches off from it toward the northwest, and we need connectors going east from both the Loud Room and the Engravings Cave. Add all of these to produce this:
So far, we’ve been working only on display-layer number 1. Now let’s superimpose some elements on the map using other layers. In the layer indicator window, on the far right of the screen, click on the second circle from the bottom. This will highlight layer 2, making it the default layer; that is, the layer on which new elements will be placed as they are added. Now type DEFAULT LAYER 3. A new layer bubble will be added above layer 2, and this layer 3 bubble is the new default layer.
Now let’s place an element on layer 3. In the image library, page to the staircase icons (these will probably be on the final page in the library). Click on the vertically oriented staircase to add it to the editor. When it appears, look at the layer indicator. A blue dot will appear in the bubble representing layer 3; this indicates that there is at least one element—the new one we just added—selected on our default layer.
This staircase is pretty large, so let’s scale it down. Rather than use the GUI to do this, we’ll use a typed command. With the staircase icon still selected, type SCALE 0.7500; this will scale the staircase symmetrically to a less overwhelming size. Place it in the upper right corner of the Loud Room outline.
Now repeat the process with a new staircase. After resizing, place the icon on the north side of the East-West Passage (to the west of the Round Room). This represents a stairway going down to the Chasm; we won’t include that room on our map, but it will be useful to show this stair. The map will now look something like this:
Our second stairway looks a bit odd, overlapping the background like that. Let’s put a white background behind it, to unify it visually with the rest of the map. We’ll do this by repurposing one of the rectangular room outlines.
Click on the layer 2 bubble to set layer 2 as the default layer. The stairway is on layer 3, so we will be putting our backdrop underneath the staircase. Now click on the vertical rectangular room (third in the first row in this screenshot of the image library) to add it to the map. Activate the Move tab, and click on the upper left corner of the stairway to place the new outline there. Now select the Scale tab, and click on the lower right corner of the staircase to resize the backdrop to the staircase. If the position isn’t quite correct, just click again to adjust. You may be able to see better if you deselect the element: type D or DESELECT at the command line. To select the element again, just click on it.
When you finish, the map should look more or less like this:
Let’s quickly recap the layers we’ve used so far.
2 Backdrop to staircase icon
1 Room and hallway outlines
Click on the eyeball icon at the top of the layer indicator. This button “reveals” the layer of each element in the editor window by placing a number in the upper left corner of the element. This view can be extremely useful for checking your work. Click on the eyeball again to turn off the layer numbers.
Our basic map is now complete, but we need to tweak a few things to get it working with the special-purpose mapping code.
In programming with Inform, we often want to separate objects into different kinds, to make it easier to assign special behavior to each: Containers can contain things, supporters may have items placed on top of them, and so on. Glimmr allows us to do this with graphic elements. The images we have been working with in this tutorial are called sprites, but we can also assign—within the editor—one sub-kind as well. The special-purpose mapping code expects that any sprite that is associated with a room, including room outlines, connectors, and staircases, should be of the sub-kind room-sprite. All of the sprites on our map fall into that category, so let’s label them appropriately: Activate the Select tab in the control panel, then click on the Select All button. With all the elements selected, click on the icon to bring up the Tools menu, then click on the CHANGE KIND button. A message in the command line window will ask you to enter the name of the kind. Type ROOM-ELEMENT. Click on the Tools menu icon again to dismiss the menu.
The special purpose mapping code also needs to know which room-elements are associated with which rooms in our game. When the player moves into a new room for the first time, we display all of that room’s associated room-elements. This allows for the map to unfold dynamically as the player moves through the world, and all it requires of us is that we tag the sprites appropriately. We could do this by hand in our code, but it is easier and faster to assign tags in the editor. Here’s how:
Activate the Select tab in the control panel, then deselect any elements that might still be highlighted by clicking in the black area of the canvas, away from the map (or type D or DESELECT at the command line). Now, select the Round Room, and then the five hallways that radiate off of the Round Room. We want all of the selected sprites to appear when the player enters the Round Room. (Note that because the hallways to north, south, and west are also separate rooms, a better design might have been to have stub hallways surrounding the Round Room, and separate, longer hallways to serve as the main graphics for the hallway rooms. But this simpler setup works fine for the example.)
With these selected, type TAG ROUND ROOM at the command line. This will tag all of these rooms with the text “Round Room.” When it generates source code, the Toolkit will use the tag to write a sentence like this for each tagged element: “The associated room of the element is the Round Room.” (If you compile your own instance of the editor using the Glimmr Canvas Editor extension, you can specify yourself what property the tag should represent.)
Next, deselect all elements and select those elements that that player should only see after entering the Loud Room: the room outline, the staircase icon, and the connector leading east. Type TAG LOUD ROOM to tag these rooms.
Deselect again, and this time select the room outline and eastern connection of the Engravings Cave (in the lower right corner). TAG this as ENGRAVINGS CAVE.
After deselecting the Engravings Cave elements, select the passage leading toward the northeast (at the top of the map). This passage is in the North-South Passage location. We don’t want the player to see it before arriving there, so TAG it appropriately: NORTH-SOUTH PASSAGE. Deselect all elements again.
Finally, we need to tag the staircase on the west side of the map (in the East-West Passage location). This is a bit trickier, since the two sprites that make it up (staircase and white backdrop) are exactly superimposed. This allows us to demonstrate another feature of the editor: the ability to hide and show elements. Click on the staircase icon to select it, then press the Hide button on the Select tab (or just type HIDE). The staircase will disappear. Now select the white backdrop, then press the Show All button (or type SHOW ALL). The staircase will reappear. Select it again; the backdrop also remains selected. Type TAG EAST-WEST PASSAGE to tag these last elements. (There is a sixth room, the Narrow Passage to the south of the Round Room, but there are no special features that should become visible when we enter there.)
That is all the preparation that is needed to make the map dynamic.
The player’s avatar
We can also add a little Parcheesi piece to represent the player’s current location. We will move it around over our sprite composition as needed to indicate which room the player is in. The editor provides special functionality to allow us to record the various positions that the icon will need to take as we move it around the map. We can register separate instances for a single element. Each instance records all of the attributes of the element at that moment, such as its position, its size, and so on. Since the editor can’t know what precisely we want to do with this information, all instances of a particular element are
To begin, let’s add the avatar icon to the map. Click on the fourth layer bubble to make layer 4 the default layer. This will insure that the avatar icon floats over everything else on the map. Our final layer stack is as follows:
4 Avatar icon
2 Backdrop to staircase icon
1 Room and hallway outlines
Now click on the small version of the yellow player’s icon in the image library (you may need to page to the end of the library to find it). The icon will appear at the center of the editor. The source code generated by the Toolkit presumes that the player’s avatar will be called PC avatar. With the icon selected, type RENAME PC AVATAR at the command line. The name on the left side of the green status line should change to reflect the new name. (If you like, you can also rename the room-element sprites in the same way. This is not necessary, and probably not worth the time unless you strongly prefer sprite names that reflect your story world rather than names like “Orthogonal_Room_Round_1″.)
The player will start the game in the Round Room, so we’ll record that instance last. Click on the Move tab, and place the avatar icon in the Loud Room. Position it as you’d like it to look (see right for my placement), then type REGISTER LOUD ROOM, or just R LOUD ROOM. (If you prefer, you can open up the Tools menu and press the Register button instead.) An instance of the sprite has now been registered with the reference “Loud Room”.
Now move the icon to the North-South Passage (the intersection north of the Round Room outline) and register that positioning: REGISTER NORTH-SOUTH PASSAGE. Do the same thing for the other three locations, ending with the Round Room.
When you are done, you can type INSTANCES to see a list of the instances you’ve recorded for the avatar. Here’s my list, alongside a composite image of all of the locations where they were recorded:
Finally, type TAG ROUND ROOM to tag the avatar as associated with the Round Room. This isn’t strictly necessary, but currently Inform will produce an error if we don’t do so (hopefully this infelicity will be corrected in a future version of the software). If you like, you can change the sub-kind of the avatar icon as well, by typing, for example, KIND AVATAR-ELEMENT.
Putting the map in its initial game-state
We have nearly finished our work in the editor. There’s just one more thing we need to do. Our map as it is currently shows all of the rooms, which means there won’t be anything to reveal dynamically in the game—the player will see the whole thing at once. We need to set the map up so that it reflects the initial state of the game before we generate the source code. To do this, we HIDE all of the elements that shouldn’t be visible to the player at the outset. These hidden rooms will be revealed only when the player moves into the room.
Activate the Select tab in the control panel, then click on all of the elements that are not associated with the Round Room to select them. Type HIDE to hide the selected elements. (You will need to select the backdrop to the western staircase after hiding the staircase icon.) The image below shows, in the left panel, the elements selected for hiding, and in the right the initial state of the map:
Generating the source code
We have now completed our work in the editor. Type GENERATE SOURCE CODE to save a text file to your hard drive containing the source code for the map. Different interpreters follow different conventions, but the file should be named GlimmrSource, and will usually be saved to the same directory as the Toolkit’s gblorb file. Some interpreters will save to your home folder, however, and others to the root folder of your hard drive.
Finalizing the source code
The source code that the editor exports is almost, but not quite, ready to compile. But there are a few tasks we need to take care of first:
- We need to combine the exported source code with the code for our world model; that is, with the Inform 7 description of the geography of the world.
- Inform isn’t capable of storing the image filenames for us, so we need to paste the list of figure name definitions into our project’s source code.
- We need to convert the information on the stored avatar instances into an Inform 7 table that our code can make use of.
To begin, open Inform 7 and create a new Glulx Inform project. Copy the Basic Floorplan Toolkit images into the project’s Materials->Figures directory (you may need to create this folder). Now open the source code file output by the Toolkit in a text editor (the code produced by my session can be downloaded here). Delete the first line, which will look something like “* //1BC4BA63-B4EB-475F-9188-23A93FE93A7F// GlimmrSource”, then copy the remaining text and paste it into your new Inform project. Change the story’s title if you like. Close the text editor.
Now, open up this text file, which includes the geography and room descriptions for our mini-world. Copy everything but the first line (the title), and paste it into the Inform 7 project, replacing the text “Starting Room is a room.]”.
Next, open up the list of figure name definitions. Inform isn’t able to store the filenames of images, so it’s not possible for the editor to auto-generate this list. Replace the text “[Paste the list of figure definitions here (e.g., Figure of Error is the file "Error.png")]” in your Inform project (under the chapter heading Figure Definitions) with the list of figures. It is no longer necessary to copy the list of figures as this is included in the generated source code in the version of the Basic Floorplan Toolkit found in release 3 of the full Glimmr release zip archive. You will need to do so, though, if you generate your own editor gblorb using Glimmr Canvas Editor.
Finally, scroll to the bottom of the project. There will be a chunk of tabular data at the bottom, commented out. This is the information about the instances of the avatar icon. Copy only the tabular data and paste it into an empty spreadsheet (Excel, Numbers, Google Spreadsheets, etc.). Now copy only the “reference” and “origin” columns and paste them back into your Inform project. They should paste correctly from most spreadsheet programs. If they do not, make sure there is one tab (and only one tab) between each entry. Change the column headings to “locale” and “coord” and title the table “Table of Avatar Coordinates”. This Google spreadsheet shows what both the full instance data and the reduced table should look like.
And that should be everything! (See what the final source code looks like here, and this page shows a diff of all of the changes made to the exported code.) Press your project’s Go button to compile, and you should now be able to walk around our mini-map, revealing rooms as you go. Download a gblorb of the finished product.