TADSMap is a TADS 2 "module," which is just a fancy way of saying a bunch of source files you can include in your own game. It does not currently work in TADS 3.
It allows you to have an HTML-based, graphical map of the locations in your game, created on-the-fly as the player explores.
Here is a small example:
Above, you can see the up and down arrows for the up and down exits, and the asterisk symbol that symbolizes that the room has some special quality. The room outlined in purple is the player's current location, and the broken line leading north means the player hasn't gone in that direction yet.
In the current version of TADSMap, only a portion of the entire map is shown at a time
In its default setup, it allows the player many configuration options, such as hiding or showing the map, resizing the portion of the map shown, and changing which portion of the window the map shows up in.
Additionally, if you click approximately on an exit graphic of the current room (including the up and down arrows), the correct command is generated for the player to go in that direction.
And if you include the CODE.T module as well (which is a separate download, but which is used by default by TADSMap), you can click on any location and automatically go there by the best (or at least a workable) route.
TADSMap requires an HTML-capable TADS interpreter. At the time of this writing, the only two compatible interpreters are HTML-TADS (for Windows) and HyperTADS (for Macintosh).
For HTML-TADS, you need the latest prerelease combined TADS 2 and TADS 3 version of HTML-TADS, available at http://www.tads.org/t3dl.htm. Look for the "Windows TADS 2+3 Player Kit Installer" link, which is currently http://www.tads.org/t3dl/pksetup.exe. You don't need the TADS 3 support, since TADSMap is only for TADS 2, but you need the HTML support fixes that aren't in the latest 2.5.6 build.
For HyperTADS, you need version 1.3 or later, currently available at http://www.hypertads.org/.
When TADSMap is described as working "on-the-fly", it means the map shown to the user is not a single static image created beforehand by the game author, but rather an image made up of lots of other tiny images, arranged in an HTML table.
The contents of each cell of the table are determined by TADSMap according to where the player is and what locations he or she has already seen.
More specifically, the main map table is made up of cells for each location, and each individual location is itself a nested table of, in the default configuration, 9 pieces. The picture below shows the 9 pieces that make up the location where the player is located in the above example.
Going left-to-right and then top-to-bottom, here are the image files that TADSMap uses to make the picture above:
tadsmap/square/nw_passage_center.pngtadsmap/square/n_passage_center.pngtadsmap/square/ne_passage_center.pngtadsmap/square/w_wall_center.pngtadsmap/square/cen_empty_center.pngtadsmap/square/e_wall_center.pngtadsmap/square/sw_wall_center.pngtadsmap/square/s_wall_center.pngtadsmap/square/se_wall_center.png<IMG SRC> inside the HTML table cells. Can you pick out the patterns?
tadsmap in the same directory as the game file. TADSMap will always look for its image files there (you can embed this directory structure either in your game file itself or in a resource file).square. This is the type of room that's being displayed. In the default images that come with TADSMap, there are also round rooms and small rooms, whose images are in their own directories (here, the round room is highlighted as if it were the player's location):
tadsmap_room_square, tadsmap_room_round, or tadsmap_room_small, or setting the maptype property to the strings that those TADSMap classes do.
passage in them, while sub-pieces that just portray the borders of the room have the string wall in them.center, which means use the highlighting for the center room which is the player's location.Luckily, getting started using TADSMap in your own game doesn't require intricate knowledge of how TADSMap works!
First, include the file TADSMap.h after you include adv.t and std.t in your main game TADS source file.
Next, download the GOTO module from the IF Archive. You can either go to http://www.ifarchive.org, find the nearest mirror, and then look for it under the TADS 2 examples, or you can try this direct link: ftp://ftp.ifarchive.org/if-archive/programming/tads2/examples/goto.zip.
Then, make sure every room inherits from tadsmap_room_basic instead of just room. The basic TADSMap room has a square shape on the map; you can customize this later.
Next, be sure that every room exit property you want TADSMap to show is either a cardinal direction (north,
ne,
east,
se,
south,
sw,
west, or
nw) or
up and down. You can also cause a room to use the asterisk symbol by setting its property map_has_special_symbol to true.
Next, take a minute to think about the layout of your map. Normally, all TADSMap rooms are located right next to each other, but sometimes they need to be spaced farther apart:
In the above example, the highlighted room and the "up" room are not right next to each other, but are separated by an additional room length. You need to set this distance property for both rooms, like so:
highlighted_room : tadsmap_room_basic
east_distance = 2
;
up_room : tadsmap_room_basic
west_distance = 2
;
You can also set longer distances as needed.
The properties for the cardinal directions are
north_distance,
south_distance,
east_distance,
west_distance,
nw_distance,
ne_distance,
sw_distance, and
se_distance.
Next, if you have any exits with conditional code in them, you need to change them so any text displayed to the user is only displayed when tadsmap.ismapping is not true. Otherwise, when TADSMap tries to evaluate the exit property for its map, the user text will be displayed!
Also, regarding special or conditionally blocked exits, normally such a property returns either the room the exit leads to or nil, right? With TADSMap, instead of returning nil, you should return true when tadsmap.ismapping is true: this tells TADSMap to show the passage, but not try to map any further. You can see several examples of this in the modified DITCH.T file, and here's an example below:
north =
{
if(tadsmap.ismapping = true)
return true; // Indicates passage is there, but no room is behind it.
"The door is closed and locked. Besides, do you really want to
be an \"Experimental Subject\"?";
return( nil );
}
Almost done!
Lastly, you need to make sure the TADSMap image files folder is in the same directory as your game. Just copy the tadsmap folder into your game file's location.
There are plenty of ways to customize TADSMap if you already know the code. Instead of trying to guess everyone's mind here for this first release, I invite you to email me at tadsmap@umbar.com with your questions and suggestions.
Please do not post this email address in any newsgroups or Web pages. If you want people to know how to contact me, please direct them to my Web site at http://www.umbar.com.
Finally, here's a treat; you can compare a hand-drawn Ditch Day Drifter map with the TADSMap version of the same thing.
Ditch Day Drifter original map (small)
Ditch Day Drifter TADSMap
Pretty neat, huh?
-- Andrew Pontious
September 5, 2002