CD Ware Multimedia 1997 June/CDW0697.iso/Quake/NIVELES/QMAP25.ZIP/EXPLORER.TXT

Text File | 1996-11-20 | 29.6 KB | 562 lines

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

Version 2.3

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 distribute a light-weight DOS run-time, easily distributable
  and configurable, which can 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. With this, you are able to distribute .qme files without
  having to worry about whether the other people have QuakeMap or not. This
  utility also lets anyone extract .map files out of .qme files. Source code
  available.


******** 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.

There is a Wizard to help you to import external files into QuakeMap, in order
to use them with QuakeMap. For example, if you found a cool new monster on the
Internet, it will probably come with an .mdl file (the monster's model), a .qc
file (the monster's AI), and maybe .wav files (sounds).  This wizard will help
you to put all this in a QuakeMap file (.qme), so that you can put this new
monster in your maps. Choose 'New' 'Import Wizard' to open the wizard.


******** Entry types **********************************************************


 ** 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", rebuilt by
QBSP/VIS/LIGHT into "MyTest.bsp", 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.

Entries of type "map" may also be used as models for new entities, or to define
the shape of new entities that don't move, like health boxes, but that you made
yourself, along with their behavior. See the example discussion below.


 ** New entities **

Well, this is not a real entity type ; it is in fact just a special Map entity.
See below, in º Examples, for more informations about it.


 ** 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, if you used personal textures you made yourself or you got from elsewhere,
QuakeMap will also import them in another entry of type "New textures". When it
must rebuild the .bsp, not only will it look for textures in id's .bsp's, but
also in the "New textures" entry. This way, you can distribute your .qme files
without trouble - non-standard textures are systematically be stored in the
file. The only problems are caused from different textures having the same name.
During the operation of importing and exporting back the .bsp, QuakeMap could
use the wrong texture. Try to avoid this case.


 ** New textures **

Entries of this type contain your personal textures. If you are already using
your own textures with other map editors, you have your texture set in .wad
files. QuakeMap allows you to import textures from .wad files as well as .bmp's
or even compiled .bsp's.

Click on the "View/Edit" button to open the texture browser. There, with the
help of the right mouse button, you can import and export textures from/to
.wad's, .bsp's or .bmp's, as well as the clipboard. If you make your own new
textures with a picture editor, save them as .bmp's and import them back in
QuakeMap - or use copy and paste. Width and height must be a multiple of 16.
The colors will be converted to fit the color palette of Quake.

You probably know that Quake uses 4 images for each texture : besides the
normal one, there is a another image, twice as small as the first one, a 3rd,
1/4 of the original size, and a 4th, 1/8 of the original size. This helps
prevent aliasing effects. QuakeMap will automatically compute these scaled-down
images, by computing means for each pixel. However, you can also import and
export .bmp's which contains all 4 images. Such images must be disposed as
follow in the bitmap :

 +---------------+-------+---+-+ 1/8
 |               |       |1/4+-+
 |               |  1/2  +---+ |
 |  normal       |       |     |
 |  image        +-------+     |
 |               |             |
 |               |             |
 |               |    black    |
 +---------------+-------------+

If QuakeMap detects that your .bmp contains a single image, it computes the
scaled-down ones; if it detects that the scaled-down textures are present, they
are directly used.

The process of color conversion consists in assigning for each pixel the nearest
color available in the Quake palette. Be careful of some color effets : some
colors, like light green, can't be rendered, because the palette of Quake
doesn't contain any light green entry. Also note that some colors look strange
in fully lighted Quake maps, because Quake laks lighter colors. The navy blue,
for example, will be light gray in too light maps. You can see this effect in
the original levels of Quake, in the Well of Wishes, for example : the blue
Dopefish background becomes light gray if you come near with a powerup that make
you shine. Don't blame QuakeMap as I first did.

In the texture browser, your textures are displayed in a new 'tab' whose name
is the name you gave to the entry in QuakeMap Explorer. This new 'tab' is
available for you to use your new textures in your maps.

Textures are stored in the .qme file itself, so they can make it grow a lot.
The textures you imported are only available for maps in the same .qme file, so
you would have to duplicate this entry for each .qme file. File Links can help
to solve this problem; see below.


 ** 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, unless you like big text lists. See by yourself.


 ** File Links **

This type of entry allows you to reuse your preffered entries from several
.qme's. File Links are just a logical link to another file, whose entries will
be processed as if they really where in the current file. You can put your own
textures, code patches, motionless entities (like health boxes), and so on, in
a .qme file used as model, and link your other .qme's to it. See examples below.

Be careful that the linked file is NOT physically included in the .qme file -
it is the only thing that is not when you make a new entry. So you have to
distribute the linked .qme files together when you plan to distribute one.


******** Examples *************************************************************

In this section, I will describe the examples distributed with QuakeMap, as well
as have a look at the particular Models.qme file.


 ** Radar.qme **

This is a QuakeC patch for 1.01 Quake from Id Software, made by Francesco
Ferrara. It simply signal vicinity of enemy with a dark sound. The sound is a
standard wave file (.wav), 11 KHz, 8 bits, mono. It is extracted to the
"QMapExec\sounds\" sub-directory when you run Quake, where it can be found by
Quake's "precache_sound" routine.

The QuakeC code is in the "Radar code" entry. W_Precache() is called at the
start of a map, to allow precaching of sounds and other things. I show there
how to add a behavior to a function without loosing the original behavior :
simply call "inherited();". Binding keys to the activation and deactivation of
the radar is easy : all you have to write is a "bind" command, followed by
the default key name, the description, and the function to call when the key
is pressed. If the function is defined as "void()", it will be called whenever
you press the key; if it is defined as "void(float xxx)", it will also be called
when you release the key. In the latter case, the float parameter will be 1 when
the key is pressed and 0 when it is released. You can also write a string
instead of a function name after the "bind" command : this will bind the key to
a Quake's console command. Try this :

  bind "F", "Full ammo", "impulse 9"

There is another special command : "autoexec". It just writes something in the
.cfg file that will be executed at Quake start-up. Try this :

  bind "F", "Flash screen when pressed and call MyFunc() when released", "+flash"
  autoexec "alias +flash bf"
  autoexec "alias -flash \q", MyFunc, "\q"     //      \q means quote


 ** Rockets.qme **

This file contains two QuakeC examples, heavily commented. Look by yourself.


 ** ExploWal.qme **

Explodable wall, to be reused in your maps. See explanations below about
BspItems.qme and use the sample ExpWTest.qme to see how to add
explodable walls in your own levels.


 ** BspItems.qme **

This demonstrates how to create new fixed entities, like health boxes. The file
BspItems.qme itself is not supposed to be run. It only contains the definitions
for these new boxes, with I called MyCrates. The file to run is
BspTest.qme, which contains only a File Link to BspItems.qme and a test
map to show the result. Try running BspTest to see how it looks. If you
want to use MyCrates in your levels, just make a File Link to BspItems.qme from
your .qme file.

Here is how MyCrates are made. The first entry in BspItems.qme is the 3D shape
of MyCrates. As you can see, it is no real map, but instead only a single
polyhedron with a Duplicator. I needed to put the polyhedron and the Duplicator
in a group, named "Crate", because if I don't, the Duplicator duplicates
"worldspawn" itself, and you get three worldspawns ! This is not allowed, and
if you try to, QuakeMap will protest. Let's come back to MyCrate. The crate
itself uses personal textures. They are stored in entry "Textures for MyCrate".

The QuakeC code is the link between the entities, found in maps as
"item_mycrate", and the .bsp produced by "MyCrate 3D model", as well as the
behavior for MyCrate.

The last entry is, once more, not a real map, but stores the "item_mycrate"
definition so that QuakeMap knows that it can let the user insert such entities
in maps. As you can see when you click on this entry, "This stores models for
new entities". To tell QuakeMap that a pseudo-map stores models for new
entities, check "Stores models" in the "Map" menu or in the entry's
context-menu.

The map itself only contains a group named "My Crate" and an "item_mycrate"
entity. The group is in fact "worldspawn", but has been renamed to something
else and its icon has been changed. The "item_mycrate" is also special because
its classname is, in fact, "item_mycrate             A new crate". This long
name is only the description of the item. The real classname has been set in
the "_new" Specific. More about this two paragraphs later.


 ** 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.

Note that you can't directly open this file. If you try to, only a copy will be
opened, so that the original file is always accessible for QuakeMap. You can,
however, make changes to the copy and then save back over the previous
Models.qme (of course, if you don't have QuakeMap's .zip file any more, I
recommend making a backup of the original Models.qme first).

The "Model" entries are used whenever you make a new entry with the "New" menu
or with the "New map" command. There is one "Model" entry for each entry type,
expected "Texture Links", because you can't create new texture links. You can
change them to change, for example, what your new maps look like, or to
automatically include your name in the "author" field of Descriptions.

This file contains a lot of entries besides the "Model" ones. They are three
map that are designated as "Stores models for new entities", which contains
exactly what appear in the "New..." window when you want to add something to
your map. More about this in next paragraph.

The last 17 entries are the links to id's original textures. They are stored in
the text format you see when you click on one of them. You can modify them, but
be careful to respect the format (texturename=filename) and not enter filenames
that doesn't exist.


 ** Models for new entities **

The list you see in the "New..." window, when you want to add a new entity or
polyhedron to your level, is build by putting together every map that has been
tagged "Stores models". You can put this tag by choosing "Stores models" in the
"Map" menu. Such maps are no real maps - QuakeMap will never try to extract them
for being built and played in. Try opening entry "New entities" in file
Models.qme.

The top group, which is usually "worldspawn", has been renamed to something more
appropriated, and its icon has been changed. I recommend that you always change
the icon of the top group to this "New folder" icon. If you created the list
with the menu command 'New' 'New entities', this change has already been made
for you. You can change an icon by picking another one in the list that appears
below the Specifics. You can add your own icons.

Now, open the sub-groups and note that the classname, along with the entity
description, is a single text - just try to adjust spaces so that it looks good.
To be exact, you can put whatever you like as a classname : it won't be used at
all when you will choose an entity to add it to one of your map. Everything that
is "addable" - i.e. everything that can be copied into your map by double-
clicking on it in the "New..." window - must have a "_new" Specific. This
Specific not only tells QuakeMap that the entity is "addable", but also specifies
the real classname to give to it. I know this sounds strange, but it allowed me
to make whole groups addable, like the teleporters. There is a Wizard to help you
set the various Specifics for addable things; click on 'New entity Wizard'.

Finally, have a look at entry "New polyhedrons". As you know, polyhedrons don't
appear in the entity list - at least not individually. This means that I had to
use a trick to allow you to see and select the simpler polyhedrons, like the
cube, wall 1, etc. In fact, what you see are just groups with a special icons,
like the top group itself. Try clicking on "Cube". You will see its Specifics :
"_icon 3" to give it the icon of a cube; there is a "_new" Specific, like
everything addable, but it is a bit special - it says "*". This is a trick to
tell QuakeMap to remove the group when you try to add it to your map, and keep
only its sub-items. The "Cube" group has a single sub-item, the cubic polyhedron.
This is how it works. There is also another Specific, "_texture". It tells
QuakeMap that this group holds polyhedrons with user-definable texture. The
Specific "_texture" tells "clip" : it means that every time QuakeMap finds a
texture named "clip" in the sub-items of the group, it will change it with the
texture choosen at the bottom of the "New..." window. If you have a look at the
map, you will see that all the cube's sides use the texture "clip".

The ability to set a particular texture name to replace has been used to make
teleporters. Their frame has a user-definable texture, so their groups hold
the Specific "_texture" with the name of the texture that where originally used
for the frame of the teleporter. But the interior of the teleporter must always
has texture "*teleport", and so won't be replaced.

All this is a bit complicated but powerful. It allows you to make your own
"New..." lists, as shown in BspItems.qme. If you open BspTest.qme, and
then its single map, you will see that the "New..." window has two more lines,
holding the new "item_mycrate". This is taken from the last entry of the linked
file BspItems.qme, and will be available in every .qme file that makes a link
to BspItems.qme. Using the same technic, you can build your own new items and
use them in all your maps.


******** Conclusion ***********************************************************

I hope this 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 now released 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, [e-mail]
Comments/bug reports are welcome and encouraged.