home *** CD-ROM | disk | FTP | other *** search
- QuakeDef Tools
- by Chris Johnson
- Email: demstar@fn.net
-
-
- -*- OVERVIEW -*-
-
- QuakeDef Tools is a package of simple utilities intended to simplify
- the hacking of certain Quake files. At this time, there are three main
- tools provided in this package: QDEXPORT, QDIMPORT, and the (almost) Ansi C
- source code. Each program will be explained individually later in this
- documentation. Until then, I shall commence ass covering....
-
-
- -*- LEGAL STUFF -*-
-
- The author of the QuakeDef Tools package, Christopher Johnson, specifically
- disclaims any warranty, expressed or implied, including but not limited to,
- any implied warranty of merchantability or fitness for a particular purpose.
- The programs and source code within the QuakeDef Tools package are provided
- 'as is.' The entire risk as to the quality and performance of each entity
- within the QuakeDef package is with you.
-
- In no event unless required by applicable law will the the author of the
- QuakeDef Tools package be liable for any damages, including any general,
- special, incidental or consequential damages arising out of the use or
- misuse of the programs or source code (including but not limited to loss of
- data, or data being rendered inaccurate) or losses sustained by you or
- third parties or a failure of the program to operate with any other program,
- even if such holder has been advised of the possibility of such damages.
-
-
- -*- THE SOURCE CODE -*-
- * About *
-
- I've manipulated the source code to the point where it's suitable
- for public usage, and have included it as an aid to other programmers and
- Quake hackers. The programs have only been successfully compiled under
- Borland's Turbo C++ v3.0 for DOS. With the exception of the C++ style
- comments, the code is strictly Ansi C, with an attempt to adhere to the
- standard Ansi C library functions. I had no problem compiling the source
- using the C++ compiler, and I don't assume you will either. But if you do,
- and you're not using a Borland compiler, there's not much I can do to help
- you, as I'm unfamiliar with any other DOS C compilers, and am only vaguely
- familiar with gcc and CC for Unix.
- I've included the PRJ and DSK files for Borland's IDE, where I
- compiled all of this. If you can't get those to work, or are using a
- different compiler, here are the source dependencies:
-
-
- * Dependencies *
-
- QDIMPORT.EXE -[ QDIMPORT.OBJ -[ QDIMPORT.C
- [ QDIMPORT.H
- [ FILEUTIL.H
- [ QDFUNCT.H
-
- -[ FILEUTIL.OBJ -[ FILEUTIL.C
- [ FILEUTIL.H
-
- -[ QDFUNCT.OBJ -[ QDFUNCT.C
- [ QDFUNCT.H
-
-
- QDEXPORT.EXE -[ QDEXPORT.OBJ -[ QDEXPORT.C
- [ QDEXPORT.H
- [ FILEUTIL.H
- [ QDFUNCT.H
-
- -[ FILEUTIL.OBJ -[ FILEUTIL.C
- [ FILEUTIL.H
-
- -[ QDFUNCT.OBJ -[ QDFUNCT.C
- [ QDFUNCT.H
-
-
- * Notes *
-
- QDIMPORT.C and QDEXPORT.C include the main and help functions for
- the respective programs. FILEUTIL.C is a collection of useful file
- functions, including a block copy function. QDFUNCT.C is a collection of
- functions specific to hacking out certain pieces of Quake's BSP files,
- relative to the QuakeDef portion.
-
-
- -*- BEFORE WE START... -*-
-
- Before we start, here are a few caveats. First, I'm assuming you've
- already unpak'd your id1.pak file using one of the many unpak'ing utilities
- out. If you haven't, then do it, otherwise this package is of no use to
- you unless you have an inordinate desire to read OPC (other people's code).
- Central to this package is, obviously, QuakeDef hacking. Inside of the BSP
- files in the maps/ directory after unpak'ing id1.pak are QuakeDef files.
- They look much like a cross between C code blocks and a proprietary
- scripting language (because that's basically what they are). The QuakeDef
- file basically DEFines all of the entities specific to the BSP file. An
- entity in a QuakeDef file looks like this:
-
- {
- "classname" "monster_ogre"
- "origin" "380 800 50"
- "angle" "180"
- }
-
- Each entity within a QuakeDef file is surrounded by brackets, and
- each key word is surrounded by quotes. The keywords here are "classname",
- "origin", and "angle". The data here are "monster_ogre", "380 800 50", and
- "180". In this example, the entity defined is an ogre. It starts at
- coordinates x:380 y:800 z:50, and at angle:180. Yes, it's that easy. :)
-
- An explanation of all keywords and tokens (monster_ogre can be
- construed as a token) is beyond the scope of this documentation at this time
- (read: I don't know them all :). A wealth of keywords and tokens
- (monster_ogre can be construed as a token) can be found in the file PROGS.DAT,
- which should be in your main Quake directory. Try some stuff out of there --
- some of it looks really interesting (including some AI tidbits)!
-
- Don't be afraid to experiment! The worst that should happen is
- Quake will reject your entity, and you'll have to try something else. The
- purpose of this is TO try stuff out, experiment, make some "new" levels,
- share your findings with others, etc. That's what it's all about, baby!
-
-
- -*- QDEXPORT -*-
- * About *
-
- QDEXPORT is a program that rips the QuakeDef portion from a BSP
- file and stores it, slightly formatted, into an ASCII file. It is designed
- for version 23 of the BSP file structure (the first four bytes of the file
- should be 17 00 00 00 in a hex editor), and may not work on different
- versions. Usage is as follows:
-
- qdexport <drive:><\path\><mapfile.bsp> <drive:><\path\><deffile.def>
-
- The <drive:> and <\path\> fields are optional, necessary only if
- the desired files are not in the current directory. The file <mapfile.bsp>
- is the filename of the .BSP file to extract from the QuakeDef portion of data
- from. The file <deffile.def> is the filename for the ASCII dump of QuakeDef.
- Of course, the < and > symbols should not be included in the input.
-
-
- * Example *
-
- qdexport test1.bsp test1.def
-
- This would extract the QuakeDef portion of test1.bsp and
- write it to the ASCII file test1.def.
-
- qdexport c:\quake\maps\b_shell1.bsp c:\quake\maps\defs\b_shell1.def
-
- This would extract the QuakeDef portion from the file
- b_shell1.bsp in the directory c:\quake\maps\, and write it
- to the file b_shell1.def in the directory c:\quake\maps\defs\.
- The directory is assumed to exist, and if it does not exist, a
- file creation error will occur.
-
-
- * Notes *
-
- The resulting ASCII file can, obviously, be loaded into a text
- editor and manipulated to your heart's content. If you don't already know,
- if you edit this file in a word processor, and don't save the resulting file
- as ASCII, then that resulting file will be filled with jibberish characters,
- and likely be unusable by Quake.
-
-
- -*- QDIMPORT -*-
- * About *
-
- Literally, QDIMPORT just takes an ASCII file and puts it in the
- middle of a BSP file. In typical usage, that ASCII file will be a QuakeDef
- file, likely extracted with QDEXPORT. QDIMPORT removes only the formatting
- QDEXPORT places in the QuakeDef file, which at this point includes single
- line indentation for all text between braces, and all extraneous <CR>'s.
- Any other formatting, including tabs, extraneous spaces and extended ASCII
- characters, is left in. If you experience problems with formatting
- characters you've put into the QuakeDef file, just don't use those
- characters. Usage is as follows:
-
- qdimport <drive:><\\path\\><deffile.def> <drive:><\\path\\><old_map.bsp>
- <drive:><\\path\\><new_map.bsp>
-
- The <drive:> and <\path\> fields are optional, necessary only if
- the desired files are not in the current directory. The file <old_map.bsp>
- is the filename of the old .BSP from which the data before and after the
- QuakeDef portion will be taken. The file <deffile.def> is the ASCII
- QuakeDef file that will be used in place of the QuakeDef portion of
- <old_map.bsp>. The file <new_map.bsp> is the recipient file to which
- the aforementioned data will be written. It is very important to note that
- <old_map.bsp> and <new_map.bsp> cannot have the same name if they are to
- reside in the same directory. Doing this will almost guarantee Quake will
- puke when you try to use <new_map.bsp>.
-
-
- * Example *
-
- qdimport test2.def test2.bsp test4.bsp
-
- This would integrate test2.def and test2.bsp into the new
- BSP file test4.bsp. Test4.bsp would be identical to
- test2.bsp, except the QuakeDef portion of test4.bsp would
- be test2.def.
-
- qdimport c:\quake\maps\defs\b_shell1.def b_shell1.bsp c:\qnew\b_shell1.bsp
-
- This would integrate the file b_shell1.def in the directory
- c:\quake\maps\defs\, and the file b_shell1.bsp in the current
- directory, into the new BSP file b_shell1.bsp in the directory
- c:\qnew\. Remember, the old and new BSP files must only have
- different names if they reside in the same directory. The
- directory c:\qnew\ is assumed to exist, and if it does not exist,
- a file creation error will occur.
-
-
- * Notes *
-
- As mentioned previously, QDIMPORT will only remove the formatting
- placed in QuakeDef files by QDEXPORT. If you have introduced extraneous
- formatting characters into the QuakeDef file, they may not be removed by
- QDIMPORT, and this may lead to problems if you use the resulting BSP file
- with Quake. The QuakeDef file you choose to integrate into a BSP file
- may be longer or shorter than the QuakeDef file already within that BSP file.
- You may have changed, added, or deleted entities since extracting the QuakeDef
- file. Although not recommended, you can even integrate a QuakeDef file from
- one BSP into an entirely different BSP (you're likely to find everything
- either stuck in a wall or floating out in space if you do this). And, as
- mentioned at the onset of this section, all QDIMPORT really does is stick an
- ASCII file in the middle of a BSP file and make a new BSP file out of that, so
- the ASCII file you integrate doesn't even have to be a QuakeDef file at all
- for QDIMPORT to work (this is strongly discouraged, however, since Quake will
- obviously throw a fit over such a thing).
-
-
- -*- History -*-
-
- QuakeDef v0.01 -
- Was in a hurry to get the package out. Only included
- QDIMPORT.EXE, QDEXPORT.EXE, and very cheesy Q&A docs
- for each of those. Accidentally put in a development
- stage version of QDIMPORT.EXE which printed hex
- characters upon completion. Told you I was in a hurry. ;)
-
- QuakeDef v1.0 -
- Totally restructured and improved the source code, such
- that it is presentable to the public. Included the
- DOS executables and (almost) Ansi C source code for
- QDIMPORT and QDEXPORT. Included (almost) real
- documentation. The package overall is more robust and
- usable than in v0.01.
-