---===  QUAKEMAP  ===---        for Windows 95

Version 2.0  (beta 4)

This is the documentation for the QuakeMap Editor only.
See EXPLORER.TXT for documentation about the QuakeMap Explorer.

QuakeMap Editor is a basic level editor for the game Quake from id
Software. It provides for full 3D editing of .map files, allowing
you to build levels by using polyhedrons with any number of sides
with any angle: you are not restricted to cubes.


What's new (non-exhaustive list) :
- Entities now displayed with a cross on the map.
- Entity list is now hierarchical.  Entities can be arranged by
  groups.
- Grouping of brushes.
- Clipboard operations (copy, cut and paste).
- Brush rotation and scaling.
- Streamlined interface with new buttons.
- Brush substraction.
- Unlimited UNDO/REDO.


 * Introduction *

The screen you see when you first open Quake Map is this Quake
Map Explorer.  If you open a .qme file, the left portion of the
screen will display the items (such as text descriptions,
patches, etc.) that are included.  From here, you can open the
map to work on the level.  You can also directly open a .map file
and work on it.

When you open a map, you see the QuakeMap Editor. The main screen 
is divided into 3 regions. The two regions at the right shows you
the level you are currently editing. The bottom window has a yellow
background and is a top view of the level.The top region, which is
green, is a front view (this "side" view can be rotated throughout
360 degrees, not limiting you to just XY or XZ views). The
level is drawn in wireframe. The left region shows you various
parameters, such as the view scale, the grid, some editing
icons, the compass, and the currently selected object.

To understand basic Quake editing principles, open an already
existing .map or .qme file, like the included sample Test.qme.
Use the "file" menu to open the desired map. Note that the file
Models.qme is used internally by QuakeMap, to hold, among other,
the list of standard entities, and contains no real map itself.

To play a level, choose "GO!" in the "Quake" menu. There are other
options, but the first one is a summary of the next ones : it extracts
the necessary textures in a wad file, launches QBSP and then Quake.
You will be asked where the QBSP/VIS/LIGHT utilities are on your hard
disk.

As long as no object (entity or polyhedron) is selected, the bottom
left region of the screen lists all of the entities of the map. An
entity is either a particular Quake item, enemy, light spot, etc, or a
solid object like a door, a switch, or the map itself. The former
are shown beside a sphere, and the latter are shown beside a cube.
Independant entities are associated with a particular spot in the
level, which is the starting point of the item or monster. These
entities are shown on the map as a cross, or +.  If you click on
one of these entities, the spot will be shown on both views
of the map as a sphere. You can drag it elsewhere with the mouse.
Moveable entities, i.e. those associated with solid objects like
doors and platforms, are not associated with a starting point, but
with some of the polyhedrons that constitute the level ("brushes").
If you click on one of these entities, the corresponding polyhedrons
will be highlighted. The first entity in a Quake level is always
"worldspawn", and it owns all the polyhedrons of the level except
the ones owned by doors and buttons.

The entities may be organized in a hierarchical design, to help you
work on the level. You can group polyhedrons and/or entities together.
These are called "groups" and are displayed with a "cube in a folder"
icon. Groups do not correspond to anything for Quake; they are only
useful for you while you are making your maps.

Although some effort will be made here to educate the user on Quake
editing, that is not the real purpose.  For current information
regarding the types of entities, and the variables associated with
them, please refer to a site such as Quake Map Specifications,
http://www.infi.net/~nichd/qmapspec.html.  In addition, you may want
to look at the maps included in sqeam.zip and qtricks.zip at
ftp.cdrom.com for some examples to learn by.


  * Working with polyhedrons *

Here lies the real "basics" of creating a Quake level.  Before your
level can be populated with monsters, weapons and powerups, there has
to be a "world" for these items to exist in.  In id's terms, these
polyhedrons, coupled with textures make a "brush".  Throughout this
document, these terms may be used interchangably.


  -= Basics =-

In .map files, polyhedrons are represented by the definition of each
of their sides. Apart from the texture, a side is only defined by the
plane in which it lies. This program uses the same concept. This mean
you cannot manipulate vertexes of the polyhedrons, but only sides, or
more exactly only the planes which define the sides. Only convex
polyhedrons are allowed and the whole polyhedron is determined by the
set of planes. You work by moving, resizing or rotating these planes,
and the program will compute the new vertexes and display the
resulting polyhedron.

A convex polyhedron is any multisided object, that does
not have any sides that fold toward itself.  The easiest way to
understand this is with a simple test.   If you draw a straight line
through a convex polyhedron, regardless of the angle or position of
the polyhedron, the line will only enter once, and exit once. 

To select a polyhedron, first click on the green side view at the
desired polyhedron's height. This set a red reference line across the
width of the view window. Next click on the yellow top view inside the
desired polyhedron. This click is converted into a 3D position: the
X and Y coordinates are those of the point where you clicked in the top
view, and the Z coordinate is the coordinate of the red reference line
in the side view. If this leads to a 3D point which is inside of an
existing polyhedron, then the polyhedron is selected and shown darker.
Once a polyhedron is selected, in addition to changing to a darker
color, a black handle is displayed in the center of the polyhedron,
and white handles are shown at the center of each face.

IMPORTANT: by clicking with the right mouse button on either an entity
in the entity list or on a polyhedron or on one of the handles, you
will bring up a context-sensitive menu. Not only are these right-button
menus very useful, but they also sometimes contains commands that are
not found in menus. So do not forget to right-click everywhere.

You can move a polyhedron by dragging the center black handle or by
changing the "center" value in the information area at the left of
the screen. This will not cause any distortion to the polyhedron.
To change the polyhedrons shape, you have to select one particular
side by clicking on one of the white handles. In addition to showing
a white handle, you will see a normal vector and yellow lines from
the handle to each vertex, defining the selected side. You can
move the plane defining that side by dragging the handle. This
will resize the polyhedron.  You can change the side's orientation
and angle by clicking on the end (gray circle) of the white normal
vector handle.  When a face of a polyhedron is selected, the side's
texture name and parameters are shown in the information area at
the left of the screen. For any side, you can choose any texture
and any texture offsets, texture rotation angle, and texture scaling
factors. You can also pick a texture from the texture browser;
see below.

You can always cancel what you have done by using the UNDO function.
It may be found either in the Edit menu, or by clicking on one of
the buttons at the left of the screen. You can UNDO and REDO the last
25 (by default) operations you made.


  -= Operations between polyhedrons =-

Adding a new side to a polyhedron allow you to have more than the
default 6-sides to your polyhedron.  IMPORTANT: altought the old
"split up this side" command is still available, I recommend not
using it any more. Here are the easier, alternate ways. Let's start
with this example. Let's say you have built a wall, and want to make
a hole in it. To do this, you use "brush substraction". You create a
cube, move it into the wall exactly where you want the hole to be,
and "subtract" the cube from the wall. To do this, click on the wall,
then hold down the Shift key and click on the cube. This operation
starts a group-selection. More on this later. For now, just see how
both the wall and the cube are selected. Then, choose "Substract" in
the Edit menu. This will split up the wall into as many convex
polyhedrons as required to make a wall with a hole. Don't forget to
remove the cube you used as substracter.

Let's come now to how to add a new side to a polyhedron. The easier
way is to pick up another polyhedron, move it over the previous one,
and do brush substraction. For example, if you want to cut one corner
of a cube, you will do this :

       +-----+/\
     A |     |  \
       |    /|   \           +-----+
       +-----+   /           |     +  resulting A
          /     /            |    /
          \    /  B          +---+
           \  /
            \/

Substracting polyhedron B from polyhedron A will leave polyhedron A
with one more side, as shown at the right.

You can also cut a polyhedron in two parts along a plane. This gives
you another way to do some operations like cutting just a corner
off of a cube, separating a wall in two parts for assigning them
different textures, etc.

To cut a polyhedron, you have to choose the plane you'll use as the
separation plane first. To do so, select a side of another
polyhedron and choose "tag this side" by right-clicking on its
handle. Then, select the polyhedron to cut and choose "Cut along
plane" in the menu or in the context-menu. With the example above,
you would select polyhedron B, right-click on the handle of the side
that goes through polyhedron A, and choose "Tag this side"; the
tagged handle is shown as a red square. Then, right-click on
polyhedron A a choose "Cut along plane".


  -= Other operations =-

Additional functions can be done through the use of the Tool Palette.
You can start the Tool Palette by clicking on the icon on the left
side of the screen.  This will provide you a selection of tools for
moving, resizing and rotating brushes.

Brush rotation is very simple.   With the desired brush selected,
just click on the appropriate rotation direction button.  The
default rotation increment is 15 degrees, but you may change the
rotation increment setting for all three axis. 

Once you have created a few brushes that form a single object, such
as stairs, a well, an arch, etc., you can select multiple brushes to
work with by clicking on each desired polyhedron while holding
either the shift or ctrl key.  This group will be displayed on screen
as highlighted with a dashed line in both map views and given the
temporary group name of "(selection)".  If you wish to save this
grouping, simply change the name from "(selection)" to your name
of choice.  This will save your group information in .qme files. 
Keep in mind, if you save or export your map into .map format, group
information WILL NOT be saved.

The use of the clipboard for cut, copy and paste operations can make
duplication of repetitive objects (pillars, arches, etc.) much easier.
These operations can be done on entities, polyhedrons, or a group.
To copy a brush or group, after selecting the desired items, press
ctrl-c.  If you want to cut, then press ctrl-x.  Both of these actions
places the selected information onto the Windows clipboard.  To paste
This information, center the two map views on where you want the items
placed, then press ctrl-v.  This can be very handy for making stairs,
for example.  After creating your first step, click once or twice on
the scroll bar arrows to offset in the appropriate direction, and
paste.  This method makes for very consistant spacing on stairs,
pillars, etc.

Although Quake Map does not support multiple maps open at one time, you
can still cut and paste between maps.  Simply select the items to copy
and press ctrl-c.  Then open the destination map, and press ctrl-v to
paste.  This is possible since the operation uses the Windows clipboard.


  -= Textures =-

Using textures has been made easier than ever.  You no longer need to
have a texture .wad file to hold your textures.  The first time you
access the texture list, Quake Map will ask you to specify where
Quake resides on your hard drive.  It will then directly access the
textures from within Quake's .pak files.  The texture browser has also
been improved to allow you to view multiple textures at one time.
These textures are grouped by type, for easier use.  In the future,
you will also be able to work with user-specific texture wads.

To directly apply a texture from the texture browser to the side of a
polyhedron, right-click on the handle of the side, and choose
"Texture..." in the context-menu, or click on the small "..." button
near the Texture Edit box. You can also click on one of the buttons at
the left of the screen. The Textures dialog box appears, and if you
select a texture by double-clicking on it, will be applied to the
selected side. Note that you can also apply a texture to a whole
polyhedron; this assigns the same texture to each of its sides. You can
even apply a texture to a whole group, or even to "worldspawn" itself,
but be careful ! This replaces every texture in the group by the choosen
texture. Anyway, don't forget that you can always UNDO a wrong
operation.


  * Working with entities *

If you double-click on one of the entities in the list, you'll be
shown the list of parameters associated with this entity. Parameters
are pairs of Spec-Arg: a Specific is a parameter name, and an
Argument is this parameter's value. Double-click on a Specific to
edit the associated Arg's value. For example, every entity must have
a "classname" Specific, whose Argument specifies the type of entity,
like "light" or "weapon_rocketlauncher"; and most entities have an
"origin" Specific, whose Arg specifies the coordinates of the
starting point or location of the entity. This is the Specific which
is used to show the cross on the map.  If you move the cross, it
will modify the associated Arg. 

Some entities may have Specifics whose meaning depends on the
classname. For example, lights can have a "light" Specific, whose Arg
specifies the light power. For more information about which Specifics
are meaningful with which classnames, look for other sources, like
the QuakeSpecs (see QMAP20.TXT). Parts of these informations may also
be included in future versions of QuakeMap.


  -= Groups =-

A group is a particular item in the hierarchical list that is used to
hold other entities. If you select several polyhedrons and/or entities,
by holding down the Ctrl or the Shift key while clicking on them, you
will create a temporary "(selection)" group. If you rename this group
to something else, you will create a non-temporary group. Such a group
is only used to hold other entities, unlike "brush items" like doors
and lifts. Doors and lifts are made of an entity containing moving
polyhedrons, so they are "groups" in the sense that they can contain
sub-items. Every polyhedron owner by a door of lift entity is
considered to be part of the door or the lift, and will move with it.
Note that you may also use doors and lifts entities like true groups
and put other entities or sub-groups into them, as well as polyhedrons.

You can move entities, polyhedrons and even sub-groups into or outside
groups by dragging their icon in the entity list. This should be
intuitive enough. The only delicate point is that polyhedrons are not
represented by icons in this list, so they can't be dragged like
entities and sub-groups. You need to either click on the "group" button
or use the Shift key to select the polyhedron(s) as "(selection)". When
this is done, you have something to drag elsewhere : the (selection)
group itself.

When you create a new polyhedron or a new entity, it is created as
sub-item of the currently selected group. That is, you have two ways to
associate polyhedrons with doors or lifts, i.e. to build doors and
lifts : either you click on the icon of the said door and then choose
the "new" button, which will create the new polyhedron directly
associated with the door; or, to change associations later, you first
have to select the polyhedron(s) in a "multi-selection" manner. This
would lead to a "(selection)" temporary group in the hierarchical list.
From there, you simply drag the icon "(selection)" and drop it onto the
door icon.

By clicking on the icon of group, all the associated polyhedrons and
entities are shown highlighter, which is a good way to check which
polyhedrons are in with which groups. You can also know where a
particular polyhedron is by clicking on it and looking what "Owner by"
says.


 * Conclusion *

This documentation could be much longer, but I prefer stopping here !
Discover by yourself everything that QuakeMap allows. And don't forget
to have a look at the QuakeMap Explorer, in file EXPLORER.TXT !


Thanks to Mike Melzer who wrote and updated many parts of this
documentation.


NO WARRANTIES, either expressed or implied. This software is
provided "as is". Use at your own risk. The author cannot be held
responsible for any damage caused to your computer or its data.
Quake and all associated logo's and textures are the property of
id Software.


Author : Armin Rigo, armin.rigo@p22.gnothi.fn.alphanet.ch
Comments/bug reports are welcome and encouraged.