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

Version 2.0  (beta 4)

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


 *** What is QuakeMap Explorer ? ***

  QuakeMap is centered on a proprietary file format, near than PAK files,
  which allows me to store some information about maps that couldn't be
  stored in a standard MAP file, like grouped polyhedrons.

  More interestingly, we can now regroup several other datas than maps
  in this proprietary file format. For example : new textures, or new
  files to replace or complete ID standard files, like sound and model
  files.

  Consider this : large maps often require A LOT of computing power, a
  lot of time, and a lot of RAM to compile (I've "only" 16Mb - and I'm
  having trouble compiling some large maps). That's why it would be
  useful to distribute BSPs instead of (or with) MAPs. But BSPs are
  large files, and it is illegal to distribute them, anyway, because it
  usually contains some of ID's original textures. So I added the
  ability to import BSP files, textures removed, in QuakeMap's files.
  Not only does this reduce size, it makes the distribution of BSPs
  legal. Then, on another computer, QuakeMap reconstructs the original
  BSP, using textures from the local computer's PAK (or unPAKed) files.

  I have even included parts of the REACC program I made and distributed
  (see DEACC & REACC). REACC is a compiler like QCC, which I wrote
  without knowing that ID would release QCC. The purpose of
  including REACC into QuakeMap is double.
                                                First, it will provide
  another way to distribute QuakeC patches - a better way, because you
  will distribute only portions of files that changed, not full files
  like now. The interest of it is to allow you to use several patches at
  once. This is usually not easy with the current method of distributing
  complete modified files : to play with several of the patches,
  you have to figure out what really changed in which file, and regroup
  yourself the changes. QuakeMap's integrated patch compiler should be
  able to deal with multiple patches from multiple sources.

  Second, it will allow us to associate QuakeC patches with particular
  levels. We'll then be able to build level-specific programs, like we
  did in Hexen. For example, we could do something like Hexen's first
  level, where there are walls that make a half turn, fire a few fireballs
  on you, and then rotate back in place. This could be done in a standard
  QuakeC patch, but associating this patch with the level make it far
  easier to use, and prevent oneself from playing the level without the
  patch or vice-versa.
                
  It also provides a consistent way of assigning actions with new keys -
  you know, "impulse" commands. You'll be shown a list of new actions the
  installed patches provides, and you'll have to choose a key for each
  of them. QuakeMap will then automatically remap impulse numbers as
  needed (useful for several patches from serveral sources) and
  write the "autoexec.cfg" to bind them with the keys you choosen.

  I also plans to make a light-weight DOS run-time, easily distributable
  and configurable, which would expand files of the proprietary file
  format into playable files, with the correct directory structure, add
  textures to BSPs, as well as compiling QC patches and prompting for
  key assignment. Except this to come out in the final 2.0 version. With
  this, you will be able to distribute .qme files without having to worry
  about whether the other people have QuakeMap or not. This utility will
  also let anyone extract .map files out of .qme files.


 *** 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 entries (such as text descriptions,
patches, etc.) that are included.

When you click on an entry, you see its contents in the right portion
of the screen. The exact contents of each entry depends on which type
the entry is : map, code patch, etc. Each entry type has an associated
icon to help distinguish between them. You can add, remove, rename, cut
and paste entries. To add a new entry, choose the entry type in the
"New" menu. If no entry is selected, the right portion of the screen
displays a big, fat "GO!" button. If you click on it, you tell
QuakeMap that you want to play Quake with the opened file. It will
process each entry, i.e. extract maps, compile code, etc, and launch
Quake. It is the easier way to try playing with a .qme file.

The .qme file actually contains *everything* included in it : the description,
the map (not stored like a standard ".map", but in a binary format that allows
hierarchy and that is much faster to load in the editor than a .map file), etc.
Even the QuakeC patches are stored in the .qme. To distribute your creations,
you only have to distribute the .qme file.

So this explorer can also be a Quake front-end, for loading desired
patches and maps. If you make a .qme file and give it to somebody else, this
person *must* have QuakeMap in order to use it. But if he loads your .qme in
QuakeMap, the first thing he will see is the big "GO !" button. By just pressing
this button, he tolds QuakeMap that he would like to play with this .qme. So
QuakeMap extracts each map as a separate ".map" file, looks for the textures
that are used in these maps, extract them in the temporary "gfx/quakemap.wad"
from the .pak files; QuakeMap then regroups the QuakeC patches and compile them
in a single pass (regrouped because the compiler is slow at loading and
analysing the original "progs.dat" file, which will be modified). When all this
is done, QuakeMap launches QBSP, VIS and LIGHT on the extracted .map files, and
launches Quake, with a command-line parameter that makes Quake automatically
load the first map in the .qme !

Other people need to have QuakeMap in order to use your .qme files, but that
will change soon, with the introduction of the DOS run-time. You will then only
have to distribute the .qme file and, if necessary, the small DOS-based program
that allows anyone to run Quake with your .qme, as well as extract entries
(extract maps as standard .map files, for example).

QuakeMap works by creating a parallel directory structure in the Quake
directory, named QMapExec. When it runs Quake, it gives it the "-game QMapExec"
parameter, and so Quake looks in the QMapExec directory and sub-directories
first. If you want to play with a .qme, every files are extracted in the
appropriate subdirectories : maps are stored in the directory "QMapExec\maps",
for example. You should consider this QMapExec directory as temporary only,
and never put anything by yourself there. It is totally cleared every time you
click on the "GO!" button.


 ** Descriptions **

The first type of entry that may be put in a .qme file is "description". It is
used to write down standard description texts, like the ones you find on the
Internet, associated with maps, and telling you who is the author, giving you
a description of the map, etc.

You enter text in a "description" entry by using the forms you see in the right
portion of the screen. Note that you can enter text formatting for the
description. Of course, text attributes will not be used while producting the
.txt file, but QuakeMap stores them and other people having QuakeMap will see
them.

To build a .txt file out of a description, choose "export as .txt" in the
"Description" menu.

Descriptions are not extracted automatically when you click on the "GO!"
button.


 ** Maps **

Entries of type "map" are... well, maps. They contains maps, but not stored in
.map file format; instead, they are stored as a binary format that allows to
save information like the hierarchy of groups and sub-groups. When you click on
a "map" entry, you see a preview of the map at the right. To edit the map, you
have to open the QuakeMap Editor by clicking on the corresponding button.

You can give every map a DOS filename (8 caracters maximum). Type it under
"File name after extraction". This filename does not depend on the name of the
entry itself (remember, you can give any entry any name). The DOS filename will
be used when extracting the map as a .map file, and so it is the name you must
type in the Quake console if you want to play with it later. For example, if
you give a map the name "MyTest", it will be extracted as "MyTest.map" and you
will be able to play with it by typing, in the Quake console, "MAP MYTEST".

Note that once the QuakeMap Editor is opened, you can choose, in the File menu,
either "export as map" to save your map in a standard .map file, or "Save in
new entry" to save your map in a new entry of the .qme file. To store the map
in a new entry of another .qme file, you have to save it in a new entry in the
current .qme file and use cut and paste to move it in the other .qme file.

Maps are extracted automatically when you click on the "GO!" button, and
QBSP, VIS and LIGHT are launched. Quake is run by using a "+map xxx"
command-line parameter to automatically load and play the first map found
in the .qme file.


 ** QuakeC **

These entities holds QuakeC code patches. You can write patches in standard
QuakeC. However, they are a few things you must be aware of :

  - The integrated QC compiler is a patch compiler - that is, it takes the
    original Progs.dat file, modifies it, and writes a new one. You don't
    have to recompile all the .qc files released by id Software. Anyway,
    you couldn't, because this compiler does not support some operations
    that are essential to produce a Progs.dat but that make no sense for
    patches, like modifying the system variables.

  - Unlike what you do usually with the .qc files, you should not distribute
    a whole, modified .qc file as a patch. You should only write a modified
    version of one or a few functions - only the ones that needs changes,
    and not a whole .qc file !

  - To let the user play with multiple patches from multiple sources, you
    should, whenever possible, modify functions by only adding something
    at its begin or at its end. This is done trough the special "inherited"
    variable, which contains the address of the original function when you
    are overwriting one. See Rockets.qme for examples of this.

  - A few keywords have been added to easily bind actions with keys. You
    can bind the execution of a function to a key. In standard ways, you
    would have to modify the W_WeaponFrame function to add support for your
    new function, through an IMPULSE command. This is automated with
    QuakeMap : IMPULSE numbers are choosen automatically, and W_WeaponFrame
    is modified in the background. See Radar.qme and BindTest.qme for
    examples of this.

  - When you run a QuakeC patch that contains "bind" commands, you will be
    asked to choose which key you want to bind to the actions. This lets
    the user of your .qme files know which special actions your patch
    provides, and see and if he wants change the keys.


 ** Compiled BSP **

You can include a compiled map into your .qme file. This enlarge its size,
of course, but it lets other users play your maps without having to run
QBSP/VIS/LIGHT first. For large maps, this may be a great time saving for
them, especially if their computer is not too powerful or has not enough RAM
to compile large maps.

Like maps, you must give every included .bsp a DOS filename that will be used
for extraction. Note that you can distribute both the map and the
corresponding, precomputed .bsp file in the same .qme file. As long as their
DOS filenames are the same, the -bsp file is considered to be the compiled
version of the map, and the map is not extracted and recompiled when you click
on the "GO!" button - only the .bsp is.

For room saving as well as for legal concerns, textures will be removed from
the included .bsp files, and restored when the .bsp needs to be extracted.
Here are some explanations about this process.

In fact, if you remove textures from a standard .bsp file, then it is no longer
a standard .bsp file. What QuakeMap does, is allowing you to store into .qme
files a copy of parts of a .bsp. A standard .bsp file holds a predefined number
of entries - you may think of them like .pak files, but with no explicit
filename. The first entry is the Entities data, the second entry is Planes data,
the third one is Textures, and so on. So what QuakeMap does is reading each of
the .bsp entries, and storing them in the .qme, except the Textures entry, which
is only stored in the .qme as a list of texture names, instead of actual texture
images. When you use QuakeMap to extract the integrated .bsp, it does the
opposite job and uses texture names - and the original textures found in the
.pak files - to rebuild a standard .bsp.

Q: Could there be a problem if a level is created with some textures removed
   from a .bsp/.pak that the new user does not have ?

The textures you used from a .bsp from ID Software is supposed to be available
on every machine running Quake. The only problem would be if you used textures
that are not available in the Shareware version of Quake, but you are not
supposed to do a Quake editor that works well with the Shareware version, are
you ?  ,-)   Anyway, ID removed support for modified Quake in the Shareware
version.

Now, with the current version of QuakeMap, you can't use - at all - personal
textures you made yourself or you got from elsewhere. But I plan to add support
for this. You would have to make a new entry in the .qme file, which physically
holds your textures. This way, you could distribute your .qme files without
trouble - non-standard textures would systematically be stored in the file. See
"New textures" in the "New" menu.


 ** New textures **

Not implemented yet !


 ** Imported file **

Imported files are files that are stored directly in the .qme file, ready to
be extracted in a particular sub-directory. For example, to include a new
sound in your .qme, all you have to do is to make a new entry and importing
the .wav file in it. Like for maps and compiled BSPs, you have to give the
DOS filename for this file, but this time with the path. For example, sounds
must be stored in the "sounds/" subdirectory, so you would give your file the
DOS filename : "sounds\mysound.wav". See Radar.qme for this example.

Imported files are automatically extracted when you click on the "GO!" button.


 ** Links to id's textures **

This type of entry is not available to you. I used it in file Models.qme to
make links to id's original textures and organize them into groups. You can't
change this group organization - at least for now.


 *** The standard Models.qme file ***

This file is required for QuakeMap to run. It contains several important
informations, like models for making new entries, the list of the new
entities that you may put in your maps, the links to id's textures, etc.

I will extend the documentation concerning this file in a future release of
QuakeMap. For now, look by yourself.



 *** Conclusion ***

I hope this short documentation, with the examples, should be enough for you
to experiment the QuakeMap Explorer, and realize how useful it may be to
work with .qme files. As I said, I hope that this file format will prove to
be good for distribution also, and that it will generalize itself with the
introduction of the DOS run-time.


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.