home *** CD-ROM | disk | FTP | other *** search
/ Quake 'em / QUAKEEM.BIN / quake / programs / qdtool10 / qdtools.doc < prev   
Encoding:
Text File  |  1996-03-03  |  11.6 KB  |  250 lines
  1.                                QuakeDef Tools
  2.                               by Chris Johnson
  3.                            Email: demstar@fn.net
  4.  
  5.  
  6.                               -*- OVERVIEW -*-
  7.  
  8.         QuakeDef Tools is a package of simple utilities intended to simplify
  9. the hacking of certain Quake files.  At this time, there are three main
  10. tools provided in this package: QDEXPORT, QDIMPORT, and the (almost) Ansi C
  11. source code.  Each program will be explained individually later in this
  12. documentation.  Until then, I shall commence ass covering....
  13.  
  14.  
  15.                             -*- LEGAL STUFF -*-
  16.  
  17. The author of the QuakeDef Tools package, Christopher Johnson, specifically
  18. disclaims any warranty, expressed or implied, including but not limited to,
  19. any implied warranty of merchantability or fitness for a particular purpose.
  20. The programs and source code within the QuakeDef Tools package are provided
  21. 'as is.'  The entire risk as to the quality and performance of each entity
  22. within the QuakeDef package is with you.
  23.  
  24. In no event unless required by applicable law will the the author of the
  25. QuakeDef Tools package be liable for any damages, including any general,
  26. special, incidental or consequential damages arising out of the use or
  27. misuse of the programs or source code (including but not limited to loss of
  28. data, or data being rendered inaccurate) or losses sustained by you or
  29. third parties or a failure of the program to operate with any other program,
  30. even if such holder has been advised of the possibility of such damages.
  31.  
  32.  
  33.                           -*- THE SOURCE CODE -*-
  34.                                  * About *
  35.  
  36.         I've manipulated the source code to the point where it's suitable
  37. for public usage, and have included it as an aid to other programmers and
  38. Quake hackers.  The programs have only been successfully compiled under
  39. Borland's Turbo C++ v3.0 for DOS.  With the exception of the C++ style
  40. comments, the code is strictly Ansi C, with an attempt to adhere to the
  41. standard Ansi C library functions.  I had no problem compiling the source
  42. using the C++ compiler, and I don't assume you will either.  But if you do,
  43. and you're not using a Borland compiler, there's not much I can do to help
  44. you, as I'm unfamiliar with any other DOS C compilers, and am only vaguely
  45. familiar with gcc and CC for Unix.
  46.         I've included the PRJ and DSK files for Borland's IDE, where I
  47. compiled all of this.  If you can't get those to work, or are using a
  48. different compiler, here are the source dependencies:
  49.  
  50.  
  51.                               * Dependencies *
  52.  
  53. QDIMPORT.EXE -[ QDIMPORT.OBJ -[ QDIMPORT.C
  54.                               [ QDIMPORT.H
  55.                               [ FILEUTIL.H
  56.                               [ QDFUNCT.H
  57.  
  58.              -[ FILEUTIL.OBJ -[ FILEUTIL.C
  59.                               [ FILEUTIL.H
  60.  
  61.              -[ QDFUNCT.OBJ  -[ QDFUNCT.C
  62.                               [ QDFUNCT.H
  63.  
  64.  
  65. QDEXPORT.EXE -[ QDEXPORT.OBJ -[ QDEXPORT.C
  66.                               [ QDEXPORT.H
  67.                               [ FILEUTIL.H
  68.                               [ QDFUNCT.H
  69.  
  70.              -[ FILEUTIL.OBJ -[ FILEUTIL.C
  71.                               [ FILEUTIL.H
  72.  
  73.              -[ QDFUNCT.OBJ  -[ QDFUNCT.C
  74.                               [ QDFUNCT.H
  75.  
  76.  
  77.                                  * Notes *
  78.  
  79.         QDIMPORT.C and QDEXPORT.C include the main and help functions for
  80. the respective programs.  FILEUTIL.C is a collection of useful file
  81. functions, including a block copy function.  QDFUNCT.C is a collection of
  82. functions specific to hacking out certain pieces of Quake's BSP files,
  83. relative to the QuakeDef portion.
  84.  
  85.  
  86.                          -*- BEFORE WE START... -*-
  87.  
  88.         Before we start, here are a few caveats.  First, I'm assuming you've
  89. already unpak'd your id1.pak file using one of the many unpak'ing utilities
  90. out.  If you haven't, then do it, otherwise this package is of no use to
  91. you unless you have an inordinate desire to read OPC (other people's code).
  92. Central to this package is, obviously, QuakeDef hacking.  Inside of the BSP
  93. files in the maps/ directory after unpak'ing id1.pak are QuakeDef files.
  94. They look much like a cross between C code blocks and a proprietary
  95. scripting language (because that's basically what they are).  The QuakeDef
  96. file basically DEFines all of the entities specific to the BSP file.  An
  97. entity in a QuakeDef file looks like this:
  98.  
  99. {
  100.  "classname" "monster_ogre"
  101.  "origin" "380 800 50"
  102.  "angle" "180"
  103. }
  104.  
  105.         Each entity within a QuakeDef file is surrounded by brackets, and
  106. each key word is surrounded by quotes.  The keywords here are "classname",
  107. "origin", and "angle".  The data here are "monster_ogre", "380 800 50", and
  108. "180".  In this example, the entity defined is an ogre.  It starts at
  109. coordinates x:380 y:800 z:50, and at angle:180.  Yes, it's that easy.  :)
  110.  
  111.         An explanation of all keywords and tokens (monster_ogre can be
  112. construed as a token) is beyond the scope of this documentation at this time
  113. (read: I don't know them all :).  A wealth of keywords and tokens
  114. (monster_ogre can be construed as a token) can be found in the file PROGS.DAT,
  115. which should be in your main Quake directory.  Try some stuff out of there --
  116. some of it looks really interesting (including some AI tidbits)!
  117.  
  118.         Don't be afraid to experiment!  The worst that should happen is
  119. Quake will reject your entity, and you'll have to try something else.  The
  120. purpose of this is TO try stuff out, experiment, make some "new" levels,
  121. share your findings with others, etc.  That's what it's all about, baby!
  122.  
  123.  
  124.                               -*- QDEXPORT -*-
  125.                                  * About *
  126.  
  127.         QDEXPORT is a program that rips the QuakeDef portion from a BSP
  128. file and stores it, slightly formatted, into an ASCII file.  It is designed
  129. for version 23 of the BSP file structure (the first four bytes of the file
  130. should be 17 00 00 00 in a hex editor), and may not work on different
  131. versions.  Usage is as follows:
  132.  
  133. qdexport <drive:><\path\><mapfile.bsp> <drive:><\path\><deffile.def>
  134.  
  135.         The <drive:> and <\path\> fields are optional, necessary only if
  136. the desired files are not in the current directory.  The file <mapfile.bsp>
  137. is the filename of the .BSP file to extract from the QuakeDef portion of data
  138. from.  The file <deffile.def> is the filename for the ASCII dump of QuakeDef.
  139. Of course, the < and > symbols should not be included in the input.
  140.  
  141.  
  142.                                 * Example *
  143.  
  144. qdexport test1.bsp test1.def
  145.  
  146.         This would extract the QuakeDef portion of test1.bsp and
  147.         write it to the ASCII file test1.def.
  148.  
  149. qdexport c:\quake\maps\b_shell1.bsp c:\quake\maps\defs\b_shell1.def
  150.  
  151.         This would extract the QuakeDef portion from the file
  152.         b_shell1.bsp in the directory c:\quake\maps\, and write it
  153.         to the file b_shell1.def in the directory c:\quake\maps\defs\.
  154.         The directory is assumed to exist, and if it does not exist, a
  155.         file creation error will occur.
  156.  
  157.  
  158.                                  * Notes *
  159.  
  160.         The resulting ASCII file can, obviously, be loaded into a text
  161. editor and manipulated to your heart's content.  If you don't already know,
  162. if you edit this file in a word processor, and don't save the resulting file
  163. as ASCII, then that resulting file will be filled with jibberish characters,
  164. and likely be unusable by Quake.
  165.  
  166.  
  167.                               -*- QDIMPORT -*-
  168.                                  * About *
  169.  
  170.         Literally, QDIMPORT just takes an ASCII file and puts it in the
  171. middle of a BSP file.  In typical usage, that ASCII file will be a QuakeDef
  172. file, likely extracted with QDEXPORT.  QDIMPORT removes only the formatting
  173. QDEXPORT places in the QuakeDef file, which at this point includes single
  174. line indentation for all text between braces, and all extraneous <CR>'s.
  175. Any other formatting, including tabs, extraneous spaces and extended ASCII
  176. characters, is left in.  If you experience problems with formatting
  177. characters you've put into the QuakeDef file, just don't use those
  178. characters.  Usage is as follows:
  179.  
  180. qdimport <drive:><\\path\\><deffile.def> <drive:><\\path\\><old_map.bsp>
  181.          <drive:><\\path\\><new_map.bsp>
  182.  
  183.         The <drive:> and <\path\> fields are optional, necessary only if
  184. the desired files are not in the current directory.  The file <old_map.bsp>
  185. is the filename of the old .BSP from which the data before and after the
  186. QuakeDef portion will be taken.  The file <deffile.def> is the ASCII
  187. QuakeDef file that will be used in place of the QuakeDef portion of
  188. <old_map.bsp>.  The file <new_map.bsp> is the recipient file to which
  189. the aforementioned data will be written.  It is very important to note that
  190. <old_map.bsp> and <new_map.bsp> cannot have the same name if they are to
  191. reside in the same directory.  Doing this will almost guarantee Quake will
  192. puke when you try to use <new_map.bsp>.
  193.  
  194.  
  195.                                 * Example *
  196.  
  197. qdimport test2.def test2.bsp test4.bsp
  198.  
  199.         This would integrate test2.def and test2.bsp into the new
  200.         BSP file test4.bsp.  Test4.bsp would be identical to
  201.         test2.bsp, except the QuakeDef portion of test4.bsp would
  202.         be test2.def.
  203.  
  204. qdimport c:\quake\maps\defs\b_shell1.def b_shell1.bsp c:\qnew\b_shell1.bsp
  205.  
  206.         This would integrate the file b_shell1.def in the directory
  207.         c:\quake\maps\defs\, and the file b_shell1.bsp in the current
  208.         directory, into the new BSP file b_shell1.bsp in the directory
  209.         c:\qnew\.  Remember, the old and new BSP files must only have
  210.         different names if they reside in the same directory.  The
  211.         directory c:\qnew\ is assumed to exist, and if it does not exist,
  212.         a file creation error will occur.
  213.  
  214.  
  215.                                  * Notes *
  216.  
  217.         As mentioned previously, QDIMPORT will only remove the formatting
  218. placed in QuakeDef files by QDEXPORT.  If you have introduced extraneous
  219. formatting characters into the QuakeDef file, they may not be removed by
  220. QDIMPORT, and this may lead to problems if you use the resulting BSP file
  221. with Quake.  The QuakeDef file you choose to integrate into a BSP file
  222. may be longer or shorter than the QuakeDef file already within that BSP file.
  223. You may have changed, added, or deleted entities since extracting the QuakeDef
  224. file.  Although not recommended, you can even integrate a QuakeDef file from
  225. one BSP into an entirely different BSP (you're likely to find everything
  226. either stuck in a wall or floating out in space if you do this).  And, as
  227. mentioned at the onset of this section, all QDIMPORT really does is stick an
  228. ASCII file in the middle of a BSP file and make a new BSP file out of that, so
  229. the ASCII file you integrate doesn't even have to be a QuakeDef file at all
  230. for QDIMPORT to work (this is strongly discouraged, however, since Quake will
  231. obviously throw a fit over such a thing).
  232.  
  233.  
  234.                               -*- History -*-
  235.  
  236. QuakeDef v0.01 -
  237.         Was in a hurry to get the package out.  Only included
  238.         QDIMPORT.EXE, QDEXPORT.EXE, and very cheesy Q&A docs
  239.         for each of those.  Accidentally put in a development
  240.         stage version of QDIMPORT.EXE which printed hex
  241.         characters upon completion.  Told you I was in a hurry.  ;)
  242.  
  243. QuakeDef v1.0 -
  244.         Totally restructured and improved the source code, such
  245.         that it is presentable to the public.  Included the
  246.         DOS executables and (almost) Ansi C source code for
  247.         QDIMPORT and QDEXPORT.  Included (almost) real
  248.         documentation.  The package overall is more robust and
  249.         usable than in v0.01.
  250.