Graphical Map by Xavid


This extension allows you to have a window with a map image in it, and to draw icons on the map based on the location of the player or whatever other things you want.

It requires Flexible Windows by Jon Ingold.

Chapter 1 - Usage

Section 1 - A Map

To use this extension, you must first create a map image. You can make it in the graphics program of your choice, such as Inkscape, or with Inform's built-in map functionality. Either way, the map can be as elaborate as you want, but rooms should be based around a regular grid. Save your map image to the Figures directory of your materials directory. Import this as a figure called Map with something like:

Figure of Map is the file "Map.png".

You also need to tell Graphical Map some information about the map that it can use for layout: the width and height of the image, the distance between the upper left corners of the rooms in your grid, and the padding, the horizontal and vertical distance from the upper left of your image to the top left of the room grid. All distances are in pixels.

The map grid size is 50.
The map padding is { 20, 10 }.

About the room grid: this extension assumes that the rooms in your map are assigned to adjacent squares that are all the same size. The image doesn't have to draw them as squares, of course, but the extension will treat them as squares for purposes of placing map icons (for the PC and so on). If, like Inform's Index map, your map has lines connecting rooms instead of placing them adjacent to each other, you should include the space for those connectors in the map grid size.

The map window isn't shown by default, in case you want to have some introductory sequence before it appears. To make it visible, you can do something like:

When play begins:
     Open the map window.

Section 2 - Rooms

The above is enough to display a static map. But to draw things on it, first we need to know what space in the map grid each Inform room corresponds to. We do this by setting the grid position of a room to its horizontal and vertical position in the map grid, for example:

The grid position of the Crossroads is { 3, 1 }.

This puts the room in the third column and first row on the map.

(If you want the upper left space in the map grid be { 0, 0 } instead of { 1, 1 }, you can add the "Use zero-based map grid." option.)

Section 3 - Mapping Things

To have the player show up on the map, you also need to make an icon to represent them. This also needs to be declared as a figure. It should generally be a PNG with a transparent background so it looks good overlaid on the map. You assign this figure as the map icon of the player. You also need to define the map offset of the player, the horizontal and vertical distance from the top left of a room to where the icon should appear.

The map icon of yourself is the Figure of PC.
The map offset of yourself is { 25, 12 }.

You can assign map icons and map offsets to anything, not just the PC. Giving different things different map offsets will allow them to appear in the same room without the icons being on top of each other.

Section 4 - Mapping Doors

Doors are another thing you might want to be indicated on your map. Doors work a little differently than other things. Because they're not really in a single room, the map offset of a door is relative to the overall map grid, not a particular room. Also, a door is only drawn when the door is closed, not when it's open.

Section 5 - Exploration

By default, the whole map is visible from the start of game. If your game is exploration-based, you may want to hide rooms that have not been visited. Basic support for this functionality can be obtained with:

Use hide unvisited rooms in map.

This just erases the map grid corresponding to any unvisited room.

To make this work nicely when you have connector lines between rooms in your map, you should calculate the map padding so that the rooms on your map image are centered in the boxes of the map grid, and thus half of each connector is in the box for each of the connected rooms. (It's ok if the map padding needs to be negative to accomplish this.)

Section 6 - Scrolling

Many games may have a map too big to display all at once. If the map is taller than conveniently fits on the screen all at once, you should give the map window an explicit height with something like:

The measurement of the map window is 100.

The map will automatically scroll around to keep the room the player is currently in centered. The same applies if the map image is wider than fits in the window.

The map always scrolls when the hide unvisited rooms in map option is active, to avoid spoiling the fact that the player's at the edge of the map.

If you want to disable scrolling, for example because you use a wide map image to avoid white bars on the edge for wider screens but it's fine for the edges to get cut off on smaller screens, say "use fixed map".

Section 7 - Multiple Maps

You can have multiple maps, for example for different floors in a building or if your game has different discontinuous areas. To use a figure other than the Figure of Map for a room, say something like:

The map figure of the Attic is Figure of Attic.

Section 8 - Legend

You can have a fixed image like a legend/key that doesn't move with the rest of the map. To do this, say something like:

The right map overlay is the Figure of Compass.

Chapter 2 - Bugs and Comments

This extension is hosted in Github at https://github.com/i7/extensions/tree/master/Xavid. Feel free to email me at extensions@xavid.us with questions, comments, bug reports, suggestions, or improvements.

Example: * Simple Map - Mapping a two-room world.

"Simple Map"

Include Graphical Map by Xavid.

The map grid size is 50.
The map padding is { 10, 10 }.

Use hide unvisited rooms in map.

Figure of Map is the file "Map.png".
Figure of PC is the file "PC.png".
Figure of Door is the file "Door.png".

The map icon of yourself is the Figure of PC.
To decide which list of numbers is the computed room offset of (T - yourself):
     decide on { 12, 12 }.

Balcony is a room.
The grid position is { 1, 1 }.

An open door called the glass door is south of Balcony.
The map position is { 0, 49 }.
The map icon is the figure of Door.

Bedroom is south of the glass door.
The grid position is { 1, 2 }.

When play begins:
     Open the map window.

Test me with "s / close door / open door".

Example: * Scrolling Map - A map that is too tall to fit on screen all at once.

"Scrolling Map"

Include Graphical Map by Xavid.

The measurement of the map window is 100.
The map grid size is 50.
The map padding is { 10, 10 }.

Figure of Map is the file "Tall Map.png".
Figure of PC is the file "PC.png".

The map icon of yourself is the Figure of PC.
The room offset of yourself is { 12, 12 }.

Arlington Heights is a room.
The grid position is { 1, 1 }.

Park Ave is south of Arlington Heights.
The grid position is { 1, 2 }.

Daniels St is south of Park Ave.
The grid position is { 1, 3 }.

Appleton St is south of Daniels St.
The grid position is { 1, 4 }.

Quincy St is south of Appleton St.
The grid position is { 1, 5 }.

Menotomy Rd is south of Quincy St.
The grid position is { 1, 6 }.

Mt Vernon St is south of Menotomy Rd.
The grid position is { 1, 7 }.

Lockeland Ave is south of Mt Vernon St.
The grid position is { 1, 8 }.

Newman Way is south of Lockeland Ave.
The grid position is { 1, 9 }.

Academy St is south of Newman Way.
The grid position is { 1, 10 }.

When play begins:
     Open the map window.

Test me with "s / s / s / s / s / s / s".