CTF map overview generator

Introduction

The basics

The CTF map overview generator is a system used to generate overhead shots with a user-controlled entities display, like the Threewave map overviews. Being familiar with the way those overviews work will help a great deal in understanding the system and this manual. It will probably help to keep those overviews available for reference in another browser window. If you have Threewave installed, for better speed you'll want to reference the map overviews that were installed along with the Threewave mod manual on your computer locally, instead of using the online version at the link above.

There's basically three reasons a CTF mapper would want to use this system:

It automatically checks map entities for 60 different potential problems. Some of these are related only to the generation of the overview, some are "style warnings", and some are warnings of fundamental errors.

The overview display helps you think about item placement and spot potential problems, for example asymmetrical spawnpoints in a symmetrical map.

Also, the overview is a nice extra to help describe or hype a map to people who haven't downloaded it yet, and to help players learn the map more quickly.

Stripped down to basics, the system is conceptually very simple: take an "overhead view" screenshot of the map using a Quake 3 mod (Birdseye), then run the .map file through a Perl script (Entifier) to find the entities and place them on the overhead view. And for an error-free map with no unusual entity behavior, using the generator actually is just about that simple. But there are a lot of options available if you want or need to use them, and some style rules to follow to generate the best overview. (That's why this is a six-page manual rather than a short readme.)

Manifest

You should have unzipped this archive in a manner that preserved its folder structure. As a result, these are the files and folders that should have been created:

birdseye The Quake 3 mod used to help generate overhead-view map images; this folder contains birdseye.pk3 and source.zip.

changelog.txt A file showing the current version number and version history.

docs The folder containing the six pages of this manual.

entifier.pl The Perl script Entifier, which generates the overview Web page and checks the map entities.

entity.cfg A configuration file used by Entifier; it describes the properties of the standard map entities

entity_icons A folder containing 38 GIF image files: 37 icons used to represent entities in the map overview (small versions of the Quake 3 item icons), and transpixel.gif used in displaying label text.

entity_lists For example purposes, a folder containing containing the original entity lists and their annotated versions for all 39 map overviews from the Threewave manual.

genpages.sh For example purposes, a shell script showing the command lines used to generate the Threewave map overviews.

iconmanager.js The JavaScript used by overview pages.

page_graphics A folder containing 5 miscellaneous graphics files used by overview pages.

The non-graphics files in this distribution, except for these Web pages, use "Unix style" linefeeds instead of "DOS style". Most text editors should not have a problem with interpreting the linefeeds correctly. Windows Notepad will be confused though. (So use something else.)

Installation

Move the "birdseye" folder (along with its contents) to your Quake 3 folder; this is the simple Quake 3 mod Birdseye that you will use in the first part of the process. You should be using Quake 3 version 1.30 or later.

The rest of the files do not have to even be on the same computer as Quake 3; the important thing is that they need to be on a computer that has a Perl interpreter, version 5 or later. Perl usually is part of the standard setup on Unix/Linux platforms, but if you want to use it on Windows or Mac platforms you'll probably have to download and install it. This manual will not cover the process of installing or using Perl. Fortunately installing Perl is pretty easy these days, as there are precompiled executables available for several platforms. Personally I have only used this system with Perl 5.6.0 and Red Hat Linux 7.1, but (famous last words) I see no reason why it would not work with any version of Perl 5 on any supported platform.

Entifier, the Perl script used in this system, requires three modules: Getopt::Long, Image::Size, and Math::Geometry. The first of those is standard and should already be installed if you have Perl 5. The other two can be grabbed from CPAN, from the Image and Math categories. I am currently using version 2.93 of Image::Size, and version 0.02 of Math::Geometry; if there are later versions available and you want to try those, be my guest, but obviously I can't guarantee success with versions other than the ones I have tested. If you don't know how to install a Perl module, read the handy documentation at perldoc.com. It's easiest if you have the ability and permission to install modules for global use on your computer, i.e. to install them alongside the standard Perl modules, although there are other options (discussed a little bit in that documentation). Note that neither of these modules requires compiling any C code; all you need in order to build them is the Perl interpreter itself.

Finally, you will want to manually create a folder named "overheads" and a folder named "levelshots", as subfolders to the folder containing "entifier.pl", for later use.

Instructions

This manual is both for describing the basic procedure for using the overview generator system, and also for providing a complete reference to all the options. And besides describing the technical aspects, the text will also cover "good practices" (style rules used in generating the Threewave map overviews).

If this is your first time looking at the manual, you should go through the sections in order. And the manual will make more sense if you actually have a CTF map available to try this out on.

Step 1: Generating the map image
Step 2: Annotating your map entities
Step 3: Creating a Web page
Step 4: Interpreting the messages
Step 5: Packaging for upload

birdseye	The Quake 3 mod used to help generate overhead-view map images; this folder contains birdseye.pk3 and source.zip.
changelog.txt	A file showing the current version number and version history.
docs	The folder containing the six pages of this manual.
entifier.pl	The Perl script Entifier, which generates the overview Web page and checks the map entities.
entity.cfg	A configuration file used by Entifier; it describes the properties of the standard map entities
entity_icons	A folder containing 38 GIF image files: 37 icons used to represent entities in the map overview (small versions of the Quake 3 item icons), and transpixel.gif used in displaying label text.
entity_lists	For example purposes, a folder containing containing the original entity lists and their annotated versions for all 39 map overviews from the Threewave manual.
genpages.sh	For example purposes, a shell script showing the command lines used to generate the Threewave map overviews.
iconmanager.js	The JavaScript used by overview pages.
page_graphics	A folder containing 5 miscellaneous graphics files used by overview pages.