---=== 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" 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, armin.rigo@p22.gnothi.fn.alphanet.ch Comments/bug reports are welcome and encouraged.