Creating a Web page
The basicsNow you have a map overview image, and a description of your map's entities (probably your .map file). Time to make the overview page itself.
The tool for this is the Perl script "entifier.pl" that came with this distribution, referred to (unsurprisingly) as Entifier throughout this manual. To use it, you'll need to have a Perl 5 interpreter installed on your system, and you'll need to know how to run a Perl script and give it command-line arguments. That's one of the topics I won't be covering in any detail. On a Unix/Linux system, the procedure for invoking Entifier with arguments is just like with any other program or script. On other platforms, I don't know the specifics of how the Perl interpreter likes to be told how to run scripts. Keep in mind that you don't have to figure out how to make the script itself executable; if necessary, you should just be able to directly run the Perl interpreter itself with the pathname of the script as the first argument, and the arguments for Entifier as subsequent arguments.
When you run Entifier, it will generate the overview Web page (unless you tell it not to) and probably print out many warning messages. You'll want to pay attention to those messages, then perhaps add to or change the annotations for your entities and run Entifier again, until you have the results that you want. The next section of the manual goes into more detail about what those messages mean; this section concentrates on how to use Entifier.
Setup
If this is your first time using Entifier, you may want to take a minute to make the script itself executable. As I mentioned above, this is not strictly necessary, but it is a minor convenience. On a Unix/Linux system, first of course you need to use chmod to make sure that the script has execute permissions set. Then open the script in a text editor and replace "/usr/bin/perl" on the first line with the path of the Perl interpreter that you wish to use. (If you don't know the path, try executing the command "which perl" to find it.) That should do it. For making the script executable on other platforms... you're on your own. If you can't figure out how to make the script executable, you should probably remove that first line.
If you intend to view the overview Web page immediately after creating it, make sure that all the graphics files are in place. You can change these locations using various Entifier arguments, but I'll describe the default setup here. The overview Web page will be created in the current working directory of Entifier, which should be the same folder where the "entifier.pl" script is located. The map image is expected to be in a subfolder of the working directory named "overheads". A 128x128 JPG with the same root name as your map image should be placed in a subfolder of the working directory named "levelshots"; typically for this image you would use the levelshot seen when loading the map in Quake 3. Finally, the icon graphics are expected to be in the "entity_icons" subfolder; they are already there, so no need to move or copy them anywhere if you are going with the default setup.
Some aspects of the Web page are not configurable by the command-line arguments. The "iconmanager.js" file must be in in the same folder as the Web page, and the page also needs a "page_graphics" subfolder containing miscellaneous image files used by every overview page. Of course, if necessary you can manually edit the generated page to change these paths.
The essentials
Run Entifier with the "--help" argument and you'll get a list of the available arguments in excruciating detail. You'll see that there are default values for most of the arguments; in normal use many of these default values should be acceptable, which reduces the number of arguments you actually need to specify when using Entifier.
For a practical example of using Entifier, have a look at the file "genpages.sh", which is what I used (as a Bash shell script) to make all the map overviews for the Threewave manual. Note that you won't be able to actually run genpages yourself unless a) you have a shell that will interpret it and b) you copy the relevant images from the Threewave manual's "overheads" and "levelshots" subfolders into the folders that Entifier and the generated Web page will be using (by default, the "overheads" and "levelshots" subfolders below the location of "entifier.pl").
Really the "--help" output and the genpages example give you all you need to know about running Entifier. Instead of redundantly describing all the options, I'll just comment on some of the aspects of using it.
- If your map does not have a specific item layout for Classic CTF, use the "--nocctf" option. Same for lack of Team Arena support and the "--nota" option. These options remove the unused gametype buttons from the output Web page, and they also make sure that you don't see irrelevant warning messages. There is not an option to remove standard CTF (like you might want for a TA-only map); sorry about that. Even the JavaScript used with the Web page assumes that standard CTF is the default mode. This isn't that bad of an assumption, really, since any CCTF or TA map will also work in standard CTF.
- I usually use the "--nowrite" argument the first time I run Entifier for a map. This means that Entifier doesn't have to bother making a Web page; instead it just shows the various warning messages that indicate things I may need to fix or tweak with the entities. With "--nowrite" enabled you don't have to specify any other arguments except for "--entfile" and "--entcfg" (and the default for "--entcfg" is probably fine). Although if "--nocctf" and/or "--nota" are relevant, it's good to use them too, to improve the accuracy of the warning messages.
- If you're just making an overview for one map, you don't need the navigation buttons at the bottom of the page, so you can use the "--nonav" option to make those go away. Note that if you do have multiple pages, and therefore want to use the nav buttons, it is assumed that you will also create some index page to tie them together (specifed by "--toppage"). This index page is not autogenerated; it's something you must create separately. If you're not going to have an index page, but you do still want the nav buttons for going back and forth between multiple overview pages, well, hmm. I don't have an option for just making the up-button alone vanish. You could always manually edit it out of the generated pages I guess.
- If you were wondering when you were going to use those setviewpos values that you wrote down back at the beginning of this process, now's the time. They are used as values for the "--altitude", "--yaw", "--xshift", and "--yshift" arguments.
- Any argument that expects a filepath ("--entfile", "--mapimage", "--entcfg") or a directory/folder ("--icondir", "--htmldir") is for specifying a file or directory that Entifier will use while doing its thing. These must be correct for Entifier to operate. This is in contrast to any argument that expects a URL path ("--mappath", "--thumbpath", "--iconpath") or an HTML file root name ("--prevpage", "--nextpage", "--toppage") which are all about specifying how the directories and files will be set up when viewing the Web page. The latter kinds of arguments don't have to have any contact with reality until and unless you want to view the Web page.
- The "entity.cfg" file that came with the distribution is the entity configuration file (specified by the "--entcfg" argument). It describes almost all the properties of the Quake 3 entities that Entifier needs to know about, although there is still some entity information hardcoded into the script. (E.g. many of the warning messages are from entity-specific checks; also, trigger_teleport, misc_teleporter_dest, and flag and obelisk entities get some special treatment in the entity processing.) You will almost certainly want to leave this alone for normal Q3CTF/CCTF/TA maps. But if you're making a map for some Q3 mod that uses other entities, you'll probably want to add new icons for those entities to the icons folder, and add new descriptions of those entities to this file. It should be straightforward to figure out how the entities are represented there.
If Entifier complains about not being able to find the necessary files, double-check that the default locations will be OK and/or that you are specifying the correct locations with command-line arguments. If you are using paths relative to the current working directory (like the defaults are), investigate to see if the current working directory is indeed what you think it is, and try using full paths instead of relative paths.
Good practices: automation
Once you have the correct arguments arranged for Entifier, they are generally not going to change as you fiddle with your map, unless you later make a new overhead image with different setviewpos arguments. So you don't want to bother typing in all the arguments each time you want to use Entifier. Set up a shell script, or a batch file, or a shortcut, or whatever works on your platform of choice to automate running Entifier with the correct arguments. Obviously this was a necessity for me when I was generating the 39 overviews seen in the Threewave manual, but even when working with just one map it will be a worthwhile time-saver.
Good practices: sharing paths
If you're going to be creating multiple overview pages, it's best that the "--mappath", "--thumbpath", and "--iconpath" values used for one page be the same values used for all the pages. Using the same set of URL paths across multiple overview pages means that the pages will be easier to organize, and they will share the same icon files, which saves on file space and also reduces the amount of downloading someone would have to do to view them online.
< Annotating your map entities Interpreting the messages >