AutoMAP v1.5
(29/11/97)

----------------------------------------------------------------------
Introduction
----------------------------------------------------------------------

If you are going to be using AutoMAP then you should already be 
familiar with Anthony Bailey's ReMaic, Yonatan Donner's AutoCam, and 
Uwe Girlich's LMPC. Because of this I will not try to explain the 
process involved in decompiling and re-recording Quake demos. I will 
just explain how to use AutoMAP.

----------------------------------------------------------------------
Description
----------------------------------------------------------------------

AutoMAP has two main uses, the most likely one of which is for level 
designers who wish to create ACM scripts for their levels. They can 
then release that script with their level so that anyone recording a 
demo on it can easily re-record it in the 3rd person perspective.

The other main use of AutoMAP is for people who wish to create ACM 
scripts for levels that they do not have the MAP file for. Rather than 
writing the ACM script manually, they can create the area definitions 
and camera / viewpoint entities in a level editor and then use AutoMAP 
to create the ACM script directly from the MAP file. The process will 
still be quite time-consuming but it will be easier than creating the 
script manually.

----------------------------------------------------------------------
How it works
----------------------------------------------------------------------

AutoMAP uses a combination of three entity definitions. These are:

  Area definitions:

  {
    "classname"    "automap_area"
    "name"         "<string>"
    "style"        "<integer>"
    "message"      "<string>"
    {
      <brush definition>
    }
  }

  Camera position:

  {
    "classname"    "automap_camera"
    "target"       "<string>"
    "viewpoint"    "<string>"
  }

  Viewpoint position:

  {
    "classname"    "automap_viewpoint"
    "name"         "<string>"
  }

If you use Worldcraft then you can add these entity definitions by 
adding the "automap.fgd" file contained in this archive to the end of 
the "quake.fgd" file in your Worldcraft directory.

No matter what level editor you use, the process in creating autocam 
entities is exactly the same.

1.

Create a brush to represent an area and set it to be an "autocam_area" 
entity. Give it a Name ("name") and set the Style ("style") to either 
1 (rectangular) or 2 (spherical). You can also add a Comment 
("message") which will be added as a comment to the ACM file before 
the line that represents this area.

2.

Create an "automap_camera" entity and set the Area ("target") to the 
name of the area that you want this camera to be used for. If you want 
this camera to look at a particular viewpoint, rather than following 
the player's movements, also set the Viewpoint ("viewpoint") to the 
name of the viewpoint.

3.

If you want this area's camera to look at a viewpoint then create an 
"automap_viewpoint" entity and set the Name ("name") to the same value 
as the camera's Viewpoint ("viewpoint").

You can add as many areas / cameras / viewpoints as you want.

----------------------------------------------------------------------
Points to remember when creating areas
----------------------------------------------------------------------

1.

You do not have to assign a camera to an area. If an area has no 
related camera then the camera will automatically be set to the exact 
centre of the area.

2.

If you set an area to be spherical then the radius will be set to half 
of the widest dimension of the brush. For instance, if you create a 
rectangular brush that is 64 wide, 64 deep, and 256 high, the radius 
will be set to 128 (half of 256). When creating spherical areas it is 
probably a good idea to use brushes with equal X, Y and Z dimensions.

3.

You can define an area with any shape of brush and with any number of 
sides. For instance, you could define an area using a 16-sided 
cylinder. Remember, though, that AutoCam only handles rectangular and 
spherical areas. If you were to create an area using a cylinder (or 
any other shape), AutoMAP will convert it to a rectangle or sphere 
of the appropriate size when it creates the ACM script.

4.

If you want multiple areas to use the same camera then you can either 
create multiple entities with the same name or one entity that 
contains several brushes. If you create several entities then they can 
be a combination of rectangles and spheres. If you create one entity 
that contains several brushes then all brushes will be the same shape.

----------------------------------------------------------------------
Command line parameters
----------------------------------------------------------------------

Brace yourself - there's a lot of them. :)

 -i <filename>

The MAP file to be read. If you do not specify a file extension then 
"MAP" will be used.

 -m <filename>

The MAP file to be written. If you are writing either an ACM or an ENT 
file then you can use this option to create a MAP file with the 
AutoMAP entities removed. You could also use it to "clean up" MAP 
files that have become corrupted or have been created by level editors 
that write MAP files in an untidy format. If you do not specify a file 
extension then "MAP" will be used.

 -a <filename>

The ACM file to be written. If you do not specify a file extension 
then "ACM" will be used.

 -e <filename>

The ENT file to be written. You can use this option to create a file 
containing only the AutoMAP entities from the input MAP file. The file 
will be written in the standard MAP format but with the "ENT" 
extension, although you can specify the "MAP" extension if you wish. 
If you do not specify a file extension then "ENT" will be used.

 -raisecameras <X>

Raise all cameras by X units. Use a negative number to lower all 
cameras.

 -raiseviews <X>

Raise all viewpoints by X units. Use a negative number to lower all 
viewpoints.

 -expandareas <X>

Expand the edges of all areas by X units. This effectively expands an 
area by 2*X in all dimensions. For instance, a 16 * 32 * 64 rectangle 
expanded by 10 units would become a 36 * 52 * 84 rectangle. A sphere 
with a radius of 64 (diameter of 128) would become a sphere with a 
radius of 74 (diameter of 148). Use a negative number to shrink all 
areas. Please note that no error checking is done when compressing 
areas so using a value that causes any areas to "invert" will produce 
an ACM script that may not work with AutoCam.

 -nocameras

Force all cameras to be ignored. The cameras for all areas will be set 
to the exact centre of the area.

 -noviews

Force all viewpoints to be ignored. All cameras will follow the 
player's movements.

 -writefullmap

By default, the output MAP file will have the AutoMAP entities removed 
if an ACM or ENT file is also being written. Use this option to force 
all entities to be written regardless of what other files are being 
written.

 -stripents

By default, the output MAP file will be written with all entities from 
the input MAP file if neither an ACM or ENT file is being written. Use 
this option to strip all AutoMAP entities even if neither an ACM or 
ENT file is being written.

 -notab

By default, MAP and ENT files will be written using tabs. Entity tags 
will be indented with one tab and brush definitions will be indented 
with two tabs. Use this option to force MAP and ENT files to be 
written without tabs.

 -?, /?

Display online help.

----------------------------------------------------------------------
Examples
----------------------------------------------------------------------

1.

Read the file "input.map" and create the ACM file "output.acm":

  automap -i input -a output

2.

Read the file "input.map" and write the MAP file "output.map":

  automap -i input -m output

3.

Read the file "input.map", write the MAP file "output.map" with the 
AutoMAP entities removed, and write the ACM file "output.acm":

  automap -i input -m output -a output

4.

Read the file "input.map" and write the MAP file "output.map", without 
tabs, and with the AutoMAP entities removed:

  automap -i input -m output -notab -stripents

5.

Read the file "input.map" and write the ACM file "output.acm", raising 
all cameras by 10 units and lowering all viewpoints by 20 units:

  automap -i input -a output -raisecameras 10 -raiseviews -20

6.

Read the file "input.map" and write the MAP file "output.map" and the 
ACM file "output.acm", keeping all the AutoMAP entities in the output 
MAP file.

  automap -i input -m output -a output -writefullmap

----------------------------------------------------------------------
Version changes and bug fixes
----------------------------------------------------------------------

v1.5

Added "-expandareas" option to allow automatic expanding and shrinking 
of all areas. This is useful if you want to create a MAP file with 
area definitions that match exactly. You can then use this option to 
produce an ACM script with areas that overlap.

Fixed the online help system so that using both the -? and /? options 
wouldn't display the online help text twice.

v1.4

Outputs ACM scripts in the new format for Autocam 1.2 and above.

Now only reports which output files are being written. Doesn't report
which ones aren't.

v1.3

Area definitions were being written incorrectly. Fixed.

----------------------------------------------------------------------
Comments / questions / bug reports
----------------------------------------------------------------------

If you would like to make any comments about AutoMAP, or there are 
features that you think should be added or improved, then please feel 
free to contact me.

Also contact me if you find any bugs.

If AutoMAP crashes while reading a MAP file then please check that the 
MAP file has not become corrupted. Some level editors output empty 
brush definitions or incomplete entities and that sort of thing may 
crash AutoMAP. If you can't find any problem with your MAP file but 
AutoMAP will still not read it then feel free to send me the MAP file 
and I'll try to find why AutoMAP isn't working.

Andrew Smith
andrew@amorph.demon.co.uk
