=head1 NAME

Vote40 Ent Generation Utility

=head1 DESCRIPTION

Vote40 is a map that allows players to choose which map to play
next. It can handle 1 to 40 different maps.

Voteent is a Perl script that takes as input a simple map listing, and
as output creates the proper entities for Vote40. These entities
enable sys admins to customize Vote40 to suit their particular needs.

In addition, Voteent will create the proper MAP.cfg files so that
custom options can be activated for each map. For example, you could
restrict the number of engineers on rock1 to 2, and allow unrestricted
engineers otherwise.

=head1 SYNOPSIS

% voteent.pl [-testing] [-map mapfile.txt] [-team] [-nocells]
             [-cycledir dir] [-health N]

% cp vote40.ent [dir containing vote40.bsp]

% cd [dir containing vote40.bsp]

% qbsp -onlyents vote40.ent

=head2 Windows

Windows people should run voteent as either:

D:\GAMES\QUAKE> perl voteent.pl [...]

D:\GAMES\QUAKE> voteent [...]

=head1 INSTALLATION

Simply unzip the Voteent.zip file into your fortress directory
(e.g. quake/fortress). There will be a number of supporting files and
some documentation associated with voteent. Voteent documentation will
be placed in the doc/ subdirectory of voteent.

=head1 USING VOTEENT

=over 4

=item 1

Run voteent.pl / voteent.exe with appropriate options. This will generate vote40.ent.

=item 2

Move vote40.ent to your maps directory. This will normally be quake/fortress/maps.

=item 3

Run qbsp on vote40, as follows: qbsp -onlyents vote40.ent. You'll probably need to 
do that from a MS-DOS prompt if you use windows.

=item 4

Adjust your server.cfg options. You can just put "map" as vote40, and make sure that qwmcycle dir
only has two files: map0.cfg and map1.cfg, which should be contain respectively:

=over 2

=item map0.cfg

map vote40

=item map1.cfg

samelevel 0

=back

=back

=head1 ADDITIONAL APPLICATIONS

Voteent is, unfortunately, not entirely self contained. But as a
sysadmin, you're undoubtably familiar with all the other helper
programs! :)

You will need Perl, which windows folks can get from
http://www.activestate.com. It's a free program, and really awesome to write
utilities in. I've included a .exe file of voteent compiled from the
perl2exe program, although I'm still experimenting with this as a
viable distribution method (thus I'm still using the shareware version
that has the obnoxious warning! :)

You will also need qbsp, a program from idsoftware that will compile
in the entities created by voteent into the map file, vote40.bsp. You
can get qbsp from ftp://ftp.idsoftware.com/idstuff/source/qutils.zip,
as well as other places.

=head1 MAPLIST

The file F<maplist.txt> (or alternative one, specified by the -map
flag) is a text file that contains one line per map. For example,
here's a quick 5-map file:

=begin text

	; Comments can also start with ; for lisp users
	# Comments are lines that start with # for shell users
	# 
	# Note: you don't have to lay this out in even columns, it just makes
	# it nice to read. :)
	#
	# Map	    "Map Desc"	    Health, Config
	well6	    "The Well"	    2000
	rock1			    2000
	localinfo cr_en 2
	
	spaz4	    "Spazball!"		
	serverinfo timelimit 15
	serverinfo fraglimit 50
	localinfo cr_en 0
	
	2tech4	    
	2fort5	    "2Fort5"	    10000

=end text

Notice a few things. First off, all you really need per line is the
map filename minus the .bsp, e.g. "2tech4" or "2fort5."
You can leave off the Health, in which case a
default health will be used (currently 5000, but you can set this with
the -health flag). You can also leave off the description, in which
case the mapname will be used. Or you can leave out both. Cool, huh?

In addition, you can specify map-specific options after the map
line. For example, if you want to limit the number of engineers in
rock1 to 2, you'd use the syntax shown above. You can also modify
serverinfo settings, like timelimit or fraglimit. The only restriction
is that the string begin with "serverinfo" or "localinfo." (This also
means there can never be a map named "serverinfo" or "localinfo" but
such is life). Otherwise, map defaults will be used (contained in the
file F<mapdefaults.txt>).

Remember that the MORE health there is, the HARDER it is for users to
select that map. So, if you want to make it easier for folks to pick
well6 over 2fort5, set the health of well6 low and the health of
2fort5 high.

=head1 FILES

=over 20

=item F<master10.txt>

Master Entity file for 1-10 maps

=item F<master20.txt>

Master Entity file for 1-20 maps

=item F<master30.txt>

Master Entity file for 1-30 maps

=item F<master40.txt>

Master Entity file for 1-40 maps


=item F<maplist.txt>

Configuration for maps (see L<"MAPLIST"> for details)

=item F<mapdefaults.txt>

Default map configuration (see L<"MAPLIST"> for details)

=back

=head1 AUTHORS

by B<Erik Selberg>
I<E<gt>VE<lt> SPEEDenator>
speed@cs.washington.edu

For use with Vote40
by B<Jim Kaufman>
I<Sgt. Thundercok>

Get the latest version from:
http://huskysearch.cs.washington.edu/fifth




