home *** CD-ROM | disk | FTP | other *** search
/ The Hacker's Encyclopedia 1998 / hackers_encyclopedia.iso / pc / softdox / confaq.txt < prev    next >
Encoding:
Text File  |  2003-06-11  |  30.2 KB  |  823 lines

  1. THE UNOFFICIAL DUKE NUKEM 3D .CON FILE HACKER'S GUIDE (v .021)
  2. By Ben Cantrick (cantrick@rintintin.colorado.edu)
  3.  
  4.  
  5. Obnoxious but possible important mumbo-jumbo:
  6.  
  7.   This document is perpetually under revision. Please e-mail corrections,
  8. comments, additions, clarifications, etc... to the author! In particular, 
  9. I'd love info and WELL COMMENTED example code for AI routines and anything
  10. else you can think of related to .CON file hacking. 
  11.  
  12.   All permissions are given to copy and reproduce this document provided
  13. no profit is made from such. The author disclaims all responsibility
  14. for the information contained herein and makes no express or implied
  15. warranty for it's fitness for any particular use. If playing with your
  16. .CON files makes your computer crash, it's not my fault!
  17.  
  18.  
  19. -----
  20.  
  21. What's new since version .02?
  22.  
  23.   - Another web page has been added to the list of WWW sites this
  24. CFHG is avalable from. (See Section F.)
  25.  
  26. -----
  27.  
  28.  
  29. INDEX/TABLE OF CONTENTS:
  30.  
  31.   A. What are .CON files?
  32.   B. Can I alter .CON files?
  33.   C. How do I alter .CON files?
  34.     * What is all this strange C-programming language-like junk?
  35.      ***** DEFS.CON: define
  36.      ***** USER.CON: definequote, definelevelname, music, definesound
  37.      ***** GAME.CON: comments, include, primitives
  38.       - Listing of primitives + their uses (if known)
  39.   D. Examples
  40.     * Trampoline trash cans
  41.     * Hollow-point pistol bullets    (Unfinished)
  42.     * Kamikaze enemies            (Unfinished)
  43.   E. So now what?
  44.   F. Appendix
  45.     * Where can I get this document?
  46.     * Contributors/Thank You's.
  47.  
  48. -----
  49.  
  50.  
  51. A. What are Duke Nukem 3D .CON files?
  52.  
  53.   .CON files are text files that "CON"trol certain aspects of the DOOM-
  54. like game Duke Nukem 3D (DN3D). There are three of them that come with
  55. the Shareware version of DN3D: DEFS.CON, USER.CON, and GAME.CON. (The full
  56. version of DN3D is has not been released as of the writing of this
  57. document, and so I can't say anything about it.) When DN3D starts up,
  58. it loads GAME.CON, checks it for errors, and if there are none keeps the
  59. instructions contained in it for use later on in the game. (GAME.CON is
  60. in charge of loading up any supplemental files, like DEFS.CON and USER.CON,
  61. that it may want to use) The instructions currently known to be usable in
  62. GAME.CON control things as mundane as how much damage each kind of weapon
  63. does to things as exotic as how enemies behave.
  64.  
  65.  
  66.  
  67. B. Can I alter .CON files?
  68.  
  69.   Yes, you most certanly can. This is one of the nicer features of the
  70. Build engine, or at least Duke3D's implementation of the Build Engine.
  71.  
  72.  But, before you start playing with them, you should definitly MAKE A
  73. BACKUP OF ALL YOUR .CON FILES!!!!! This is not only to prevent you from
  74. having to re-install DN3D if you mess up your existing .CON files, but
  75. also so that you can have the original .CON files as reference material
  76. when you start altering them. Once you've got backups made, altering
  77. the .CON files couldn't be easier: just open them up with your favorite
  78. text editor and edit away.
  79.  
  80.  
  81.  
  82. C. How do I alter .CON files?
  83.  
  84.   * What does all this weird, C-like junk in my .CON files mean??
  85.  
  86.   A lot of things, depending on which .CON file you edited. Let's take
  87. the .CON files from least complex to most complex:
  88.  
  89.  
  90.   ***** DEFS.CON:
  91.  
  92.   Most of the lines in DEFS.CON look something like:
  93.  
  94.     define SOMETHING SOMENUMBER 
  95.  
  96.   What they do is basically simple substitution: If you have a line
  97. somewhere in your DEFS.CON that said:
  98.  
  99.     define THEANSWER 42
  100.  
  101.   Then any time after that, if the word "THEANSWER" appears, "42" is
  102. substituted in it's place.
  103.  
  104.   By themselves, these lines aren't very interesting. They become helpful
  105. later on, when you're writing actor code and don't want to remember that
  106. an enemy who is TOUGH happens to have a strength of 137. You can just:
  107.  
  108.     define TOUGH 137
  109.  
  110.   And thereafter don't have to remember that TOUGH = 137, you just know
  111. that an enemy is TOUGH.
  112.  
  113.   Defines are ubiquitous; almost everything in the .CON files is really a
  114. number, but is DEFINEd to be a name so it makes more sense. At some point
  115. you can just stop caring whether things are DEFINEd labels or numbers, but
  116. be aware that most of the things you deal with are really numbers.
  117.  
  118.  
  119.  ***** USER.CON:
  120.  
  121.   USER.CON is somewhat like DEFS.CON in that it mostly just defines things.
  122. However, USER.CON usually defines things that might be interesting to the
  123. game player, whereas DEFS.CON usually defines things that a DN3D player
  124. could care less about. USER.CON also contains nice technical notes written
  125. by the 3D Realms .CON programmer, Tod Replogle, that tell you all about how
  126. to modify it. Almost all of the info below is basically a rehash of the notes
  127. you can find in USER.CON
  128.  
  129.   There are 5 major kinds of lines in USER.CON: defines, definequotes, 
  130. definelevelnames, musics and definesounds.
  131.  
  132.   "define" lines are no different than they were in DEFS.CON; they define
  133. stuff. Most of the stuff you can define here is emminantly useful, tho.
  134. Examples abound: You can define Duke's starting and maximum health and
  135. armor values here. You can define how much ammo Duke gets per clip picked up,
  136. how much ammo is allowed for each weapon, how much damage each weapon does
  137. per hit, etc, etc...
  138.  
  139.  
  140.   "definequote" lines define the different things that will pop up on the
  141. screen in response to certain game events. You can define what words
  142. appear on the screen when you get an some ammo or an inventory item, what
  143. words appear on the screen when you use the various cheat codes, what
  144. words will appear when you adjust game options, etc, etc...
  145.  
  146.  "definequote" lines have two arguments: a number and a quote. The number
  147. is what you use to refer to the quote by later on. For example, the line:
  148.  
  149.     definequote 101     NIGHT VISION GOGGLES!
  150.  
  151.  Defines quote number 101 is "NIGHT VISION GOGGLES!" (This is pretty
  152. obvious, isn't it?) One other thing to keep in mind while making quotes;
  153. Todd Replogle, the Duke3D .CON file programmer, cautions:
  154.  
  155. >// Maximum quote size is 64 characters.
  156.  
  157.  
  158.   "definelevelname" lines are used to define the episode and level number,
  159. floor-plan file, par and record times, and level names for each level. The
  160. format of a definelevelname line is:
  161.  
  162.     definelevelname #LEVEL #EPSIODE MAPFILE PARTIME RECORDTIME LEVELNAME
  163.  
  164.   For example, Episode 1, Level 5 is "The Abyss." The floor-plan of this
  165. level is in the file E1L5.map. (which is actually contained in DUKE3D.GRP)
  166. The par time is 9 minutes, 10 seconds, and the record time is 5 minutes
  167. flat. It's definelevelname entry looks like this:
  168.  
  169.     definelevelname 0 4 E1L5.map 09:10 05:00 THE ABYSS
  170.  
  171.   As you can see, you must subtract one from the actual episode and level
  172. numbers before you put them on the definelevelname line. We're in Episode 1,
  173. but the #EPISODE is 0. We're in level 5, but the #LEVEL is 4. Notice also
  174. that you should (I don't think it's actually required) pad the par and
  175. record times with a leading 0 if necessary. There are also some comments
  176. from Todd Replogle, taken from USER.CON:
  177.  
  178. >  - Level file names cannot excede 13 characters.
  179. >  - Level par cannot excede 5 characters (min:sec)
  180. >  - Level titles cannot excede 32 characters.
  181.  
  182.  
  183.   "music" lines (as far as I can tell) define which .MID files to play for
  184. each level. Beyond that I'm not entirely sure how "music" lines specify
  185. exactally which file to play for which level; if someone can enlighten
  186. me I'd be appreciative.
  187.  
  188.  
  189.   "definesound" lines define various names that correspond to ways to
  190. play a VOC file. The format of a definesound line is:
  191.  
  192.     definesound SOUNDNAME VOCFILENAME.voc    #1  #2  #3  #4  #5
  193.  
  194.   Once again, Todd Replogle has provided .CON file hackers with a helpful
  195. technical note in USER.CON:
  196.  
  197. >    -----------------------------------------------------------------
  198. >    ABOUT CHANGING SOUND FX
  199. >    The sound fx section follows this explanation. 
  200. >
  201. >    1. The program expects to find a .VOC file
  202. >    2. You can either change the VOC name listed below to match your new
  203. >       sound, or you can rename your file to match the name here.
  204. >    3. New sound files should be added to the game directory.  Though
  205. >       all sound files shipped with the game are included inside the 
  206. >       .GRP file, the program will know if there are sound files outside
  207. >       the .GRP file, and will use them instead.
  208. >    4. The numbers that are to the right of the sound file name are
  209. >           technical parameters which will not be explained here, except as
  210. >           follows...
  211. >       - The first 2 numbers define a random pitch variation range.
  212. >             They can be positive or negative numbers.
  213. >       - The 3rd number is a priority flag.
  214. >       - The 4th number is a bit parsed set of technical variables
  215. >             that identify the type of sound it is in the game.
  216. >       - The 5th number is a volume adjustment flag.
  217. >    -----------------------------------------------------------------
  218.  
  219.   The explanation seems pretty self-evident, so I won't go into a detailed
  220. explanation of each field of the definesound line.
  221.  
  222.  
  223.  
  224.  ***** GAME.CON:
  225.  
  226.   The BIGGIE! Lots of stuff in this one, and most of it rather difficult to
  227. explain... let's start out with the first couple of lines, which are:
  228.  
  229.     /*
  230.     -------------------------------------------------------------------
  231.         Duke Nukem 3D Script Code.
  232.     Todd Replogle.
  233.     -------------------------------------------------------------------
  234.         */
  235.  
  236.   If you're a C programmer, this stuff is immediatly obvious: everything
  237. between /* and */ is considered a "comment" and Duke3D will almost always
  238. ignore it when reading in GAME.CON. (I say "almost always" because it appears
  239. that Duke still counts the curly braces, { and }, inside comments. This can
  240. lead to some interesting effects; comment out some bad code that has non-
  241. matching curly braces and the game might refuse to load up, even though the
  242. bad code is inside a comment, and supposedly never even seen.) 
  243.  
  244.   There are two kinds of comments: the double-slash or "//" comment and the
  245. "/* */" comment. A "//" comment starts at the double-slash and extends to the
  246. end of the line. A "//" comment ends at the end of the line.
  247.  
  248.   The "/* */" comment can span several lines, but "//" comments only "null
  249. out" one line, at most. Many // and /* */ comments can be found all over
  250. DEFS.CON, USER.CON, and GAME.CON.
  251.  
  252.   Forewarned: you must put a space after "//" before typing the text of
  253. the comment. The comment: "//This is a comment" will cause Duke3D to error
  254. out. Changing the comment to "// This is a comment" will fix the problem.
  255. I assume the same holds for "/* */" comments. Things like: "/*C*/" are
  256. a no-no. Things like "/* C */" are OK.
  257.  
  258.  
  259.   The next few lines in GAME.CON are "include" lines which basically 
  260. cause Duke3D to process the specified file. The line:
  261.  
  262.     include defs.con
  263.  
  264.   Makes DN3D go process DEFS.CON before it moves along to the next line.
  265.  
  266.  
  267.   And now, the really big, confusing ones: states, actions, and actors.
  268.  
  269.   Apogee hasn't said anything about states, actions, or actors yet, so the
  270. things I'm about to tell you are pure conjecture based on observation and
  271. experimentation:
  272.  
  273.  
  274.   *****STATEs
  275.  
  276.   As far as I can tell, "states" can be thought of as something like
  277. subroutines. You go into a state, do something, and then come back to
  278. wherever you were. The first state in GAME.CON is the "rats" state, which
  279. randomly makes some rats whenever it's called.
  280.  
  281.   The format of a state is:
  282.  
  283. state #STATENAME
  284.  ...
  285. ends
  286.  
  287.   STATENAME is a unique number that is usually DEFINEd to be the name of 
  288. the state. No two states should have the same number. "ends," of course,
  289. is short for "End State." Be sure that your states are defined before you
  290. try and use them. If you try and use a state (in an actor, perhaps) that
  291. hasn't been defined earlier in the file, DN3D will error.
  292.  
  293.  
  294.   *****ACTIONs
  295.  
  296.   As far as I can tell, an "action" specifies a sequence of sprites
  297. (pictures) to draw onto the screen. The format of an action is still
  298. not quite entirely known, but it seems to be something like this:
  299.  
  300.     action #SPRITEGROUP #FIRSTFRAME #LASTFRAME #?? #?? #DELAY
  301.  
  302.   Each action has a set of pictures, or "frames" associated with it.
  303. The number first number, #SPRITEGROUP, defines this bunch of picures, or
  304. a "sprite group." #SPRITEGROUP is usually a DEFINEd number, so you can
  305. type "action BURNING_FRAMES" instead of having to remember that the fire
  306. animation frames are number 327, and typing "action 327." The second and
  307. third numbers of an action specify which sequence of frames from the 
  308. specified sprite group group to step through when you're animating this
  309. sprite. (Animation starts from the whatever-th frame in the sprite group,
  310. number #FIRST, and goes until the whatever-th frame in the group, number
  311. #LAST. Then it usually loops back to the first frame or else quits,
  312. depending on the actor code controlling it.)
  313.  
  314.  The #DELAY number determines the delay between frame changes. That is,
  315. how rapidly the frames are animated on-screen. 1 = small delay and fast
  316. animation, bigger numbers = bigger delays and slower animation. (I think?)
  317.  
  318.  The two remaining numbers are a mystery. If anybody knows what they mean
  319. and how they're used, please mail me at cantrick@rintintin.colorado.edu so
  320. I can add them to the guide.
  321.  
  322.  
  323.   *****ACTORs
  324.  
  325.   As far as I can tell, an "actor" is any (freestanding?) object in the
  326. game that does something. Obviously, Duke and the enemies are actors.
  327. However, the rubber-maid trash cans in the movie-theater lobby are also
  328. actors, because they dent and then bounce back when you shoot them. The
  329. items and weapons and clips are also actors, because they also do something
  330. when you run over them: they give you an item, a weapon, or more ammo.
  331.  
  332.   Walls are not actors, because they don't 'do' anything except sit there.
  333. (Bullet-holes being an exception, I guess. Perhaps the bullets themseves are
  334. some kind of actor that effect the surface they hit.) Doors and lifts are
  335. borderline; I suppose the game might treat them as actors internally, but I
  336. don't know if you can/how you would alter their behavior in the .CON file. 
  337.  
  338.   The format of an actor is something like:
  339.  
  340.     actor #ACTORNUMBER #ACTORSTRENGTH #ACTION #SPEED #AI_FUNCTION
  341.      ...
  342.     enda
  343.  
  344.   #ACTORNUMBER is (I think?) a unique number that identifies this actor.
  345. No two actors should have the same number. Usually #ACTORNUMBER is
  346. DEFINEd to be something easier to remember than a number.
  347.  
  348.   #ACTORSTRENGTH is a number that determines how much damage this actor
  349. can take before it breaks, dies, etc... (I think?) Putting a value of 0
  350. for this field makes the object invincible. Usually, #ACTORSTRENGTH is
  351. DEFINEd to be something easy to remember. (See 'define TOUGH' above.)
  352.  
  353.   #ACTION is (I think?) the number of an action (that is, the identifying
  354. number of a series of frames) to cycle through for this actor, if this
  355. actor is animated. Patches of fire actors use this to maintian an image-
  356. loop so they look like they're constantly burning. The HoloDuke recharge
  357. also uses an action to make the shimmer propagate across it's surface.
  358.  
  359.   #SPEED is (I think?) how fast this actor moves, if it moves. I don't know
  360. if "move" is always interpreted in the traditional sense; it appears from
  361. the gun-turret actor code that turrets that spin in place are considered to
  362. be "moving." 
  363.  
  364.   #AI_FUNCTION is (I think?) a number, as defined in DEFS.CON, that
  365. specifies what this actor's initial AI is if it has an initial AI. The AI
  366. routines are: face_player (1), geth (2), getv (4), random_angle (8),
  367. face_player_smart (64), fleeenemy (128), seekplayer (512), fleeplayer (1024),
  368. looking (2048) and dodgebullet (4096). As to what these mean or how they
  369. work, I haven't any idea.
  370.  
  371.   The last three parameters of actor seem to be optional. Things that aren't
  372. animated, don't "move" and have no AI don't seem to include those parameters.
  373. You can make a perfectly sensible actor without them; as a matter of fact
  374. the majority of non-enemy actors in Duke3D (ammo and items) do not use them
  375. at all.
  376.  
  377.  
  378. * You keep putting "..." inside states and actors as if we already know
  379.   what's supposed to go inside there; but we don't!
  380.  
  381.   Well, this is kind of sticky; there are quite a few things inside there,
  382. most of them vaguely reminiscent of the C programming language with a
  383. virtual environment twist. The things that go inside actors and actually
  384. make up the actor "code" are what I'll call "primitives." Primitives are
  385. simple operations that the Build Engine will perform for you. For instance,
  386. one primitive is "ifrnd" which will tell you if a random number between
  387. 0 and 256 was less than the number you gave it. For instance, if you
  388. wanted there to be a 1 in 2 chance of something happening, you could put:
  389.  
  390.  ifrnd 128 {
  391.   ...        // 50% chance that this stuff gets done.
  392.  }
  393.  
  394.   Since 128 is half of 256, the random number between 0 and 256 will be
  395. less than 128 about half the time. Thusly, the "..." inside that
  396. "ifrnd" block will only be executed about half the times the ifrnd is
  397. run. To take another example: if you wanted a 1/4 chance, you'd
  398. ifrnd 64 { ... }. Since a random number between 1 and 256 will be less
  399. than 64 about 25% of the time.
  400.  
  401.   There are a bunch of other primitives, too. I'll list them each here,
  402. along with their arguments and what they do. After that, I'll give some
  403. (hopefully) illustrative examples on how to use them.
  404.  
  405.   Note: Primitives marked with a "?" instead of a "-" are still mysteries
  406. to me. As usual, mail me (cantrick@rintintin.colorado.edu) if you know how
  407. they work or if I've forgotten any primitives.
  408.  
  409.   Note: Most "add" primitives are subject to some kind of limit. These
  410. limits are usually explained in the explanation of the primitive.
  411.  
  412.  Note: All (?) 'ifXXXXX' primitives can have an (optional) else clause
  413. that gets executed if the condition being tested is false. For instance:
  414.  
  415.     ifphealthl 45 {
  416.       quote OK              // Print "You're OK."
  417.     }
  418.     else {
  419.       quote BUMMER          // Print "Find some health!"
  420.     }
  421.  
  422.  
  423.  *****PRIMITIVES:
  424.  
  425. addammo #WEAPON #AMT            - Adds #AMT ammo to #WEAPON weapon,
  426.                                         Subject to max ammo constraint for
  427.                     that weapon. Does not give player
  428.                     #WEAPON, only gives them ammo.
  429.                     Ex: "addammo PISTOL_WEAPON
  430.                                         PISTOLAMMOAMOUNT"
  431.  
  432. addinventory #ITEM #AMT            - Adds #AMT of #ITEM to player's
  433.                     inventory, subject to #ITEM's max
  434.                     amount limit.
  435.  
  436. addkills #NUM                - Adds #NUM to number of kills
  437.                     player has made.
  438.  
  439. addphealth #NUM                - Adds #NUM points to player's
  440.                     health. (#NUM may be negative.)
  441.  
  442. addweapon #WEAPON #INITIALAMT        - Gives player weapon #WEAPON that
  443.                     has #INITIALAMT of ammo in it.
  444.                     Ex: "addweapon SHOTGUN_WEAPON 10"
  445.  
  446. ai AINAME #ACTION #SPEED #AITYPE    ? Defines an AI routine for enemies
  447.                     to use. AINAME is any string, 
  448.                     #ACTION is the series of frames
  449.                     to cycle through when the enemy
  450.                     is using this AI, #SPEED is how fast 
  451.                     the enemy moves when using this AI
  452.                     and #AITYPE is what the enemy does
  453.                     when it's using this AI. (For list
  454.                                         of AITYPEs, see #AI_FUNCTION under
  455.                     ACTORs.)
  456.                     
  457. break                    - Stops whatever you're doing and
  458.                     immediatly exits the currently
  459.                     running actor or state. 
  460.  
  461. cactor #ACTORNUM            ? As far as I can tell, this
  462.                     primitive "c"alls another "actor"
  463.                     to do something for you. 
  464.  
  465. cstat #NUM                ? Allows setting of the status
  466.                     flag(s) of the current actor.
  467.                     For instance, "cstat 32768" makes
  468.                     an actor invisible. There are other
  469.                     cstat flags too, but I don't know
  470.                     what they all are. (Notably 0 may
  471.                     be "visible," and 4 may be "moving.")
  472.  
  473. debris #??? #AMT            - Causes some debris to fly. (Whose
  474.                         action or spritegroup is defined
  475.                     by #??? ?). Larger values of #AMT
  476.                      make more junk fly. Acceptable
  477.                     values of #??? seem to be "SCRAP1"
  478.                      and "SCRAP2." 
  479.                      Ex. "debris SCRAP2 5  // Lots!"
  480.  
  481. define                     - Defines various things. See other
  482. definesound                sections of document.
  483. definelevelname
  484.  
  485. fall                    - Causes the current actor to "fall"
  486.                     until it hits a surface it can come
  487.                     to rest on. Good to do right after
  488.                     you "spawn" something small from
  489.                     inside something larger.
  490.  
  491. globalsound #SOUND             ? Plays the sound associated with
  492.                     #SOUND at (which?) Duke's location.
  493.  
  494. guts #??? #AMT                - Like debris, but causes different
  495.                     kinds of body parts to fly instead
  496.                     of debris. Acceptable values for
  497.                     #??? seem to be JIBS1 to JIBS5 (Misc
  498.                     body parts) as well as HEADJIB1,
  499.                     LEGJIB1, ARMJIB1 (Trooper parts),
  500.                     LIZMANARM1 and LIZMANLEG1 (Captain).
  501.                                         Also DUKETORSO, DUKELEG, DUKEGUN.
  502.                                         Ex. "guts JIBS1 1   // A spine."
  503.  
  504. hitradius #RADIUS #1 #2 #3 #4        ? Defines the effective distance and
  505.                     strenghts of area-effectors like
  506.                     explosions and fires. #RADIUS
  507.                     determines the circle of maximum
  508.                     effect, (I think?) within which damage
  509.                     done to objects is given by #4.(?)
  510.                     Objects farther away (how much
  511.                     farther?) from the center of effect
  512.                     suffer damages of #3, objects farther
  513.                     than that sustain damage #2, objects
  514.                     farther yet take damage equal to
  515.                     #1, and objects sufficiently far
  516.                     away from the area-effector suffer
  517.                     no damage at all.
  518.                     Ex: "hitradius 1024 WEAKEST WEAK
  519.                     MEDIUMSTRENGTH TOUGH"
  520.  
  521. ifactor    #NUM                ? Tells you if the currently
  522.                     executing code was called by
  523.                     the given actor?
  524.  
  525. ifactornotstayput            ?
  526.  
  527. ifaction #ACTION { ... }        - Tests if the current actor is
  528.                     executing the given action, and
  529.                     executes the appropriate code.
  530.  
  531. ifactioncount #NUM { ... }        - Tests if the current actor is
  532.                               displaying the given frame of an
  533.                     action, and exectes the appropriate
  534.                     code.
  535.                     
  536. ifbulletnear                ? Checks to see if a bullet has
  537.                     passed near the current actor?
  538.  
  539. ifcansee                - Returns true if Duke can
  540.                     see the current actor.
  541.  
  542. ifcanseetarget                ? Enemy AI routine?
  543.  
  544. ifcanshoottarget            ? Enemy AI routine?
  545.  
  546. ifceilingdistg #NUM             - Returns true if the distance to
  547. ifceilingdistl #NUM            the ceiling is greater/less than
  548.                     the given number.
  549.  
  550. ifcount                    ? Short for ifactioncount?
  551.  
  552. ifdead                    - True if the current actor has
  553.                     taken as much damage as they can
  554.                     given their strength and is should
  555.                     be pushing up daisies.
  556.  
  557. iffloordistg #NUM            - True if the distance from the
  558. iffloordistl #NUM            current actor to the floor is 
  559.                     greater/less than #NUM.
  560.  
  561. ifgapzl    #NUM                ? True if the distance between the
  562.                     floor and the ceiling at the actor's
  563.                     location is less than #NUM.
  564.  
  565. ifhitweapon                ? True if the current actor was
  566.                     hit with a weapon recently. (How
  567.                     recently? Since the last call to
  568.                     ifhitweapon?)
  569.  
  570. ifinwater                - True if the current actor is
  571. ifonwater                in/on water.
  572.                     
  573. ifmove #NUM                ? True if the value of variable
  574.                     #NUM is not false?
  575.  
  576. ifnotmoving                ? True if the current actor is
  577.                     not moving?
  578.  
  579. ifp #COND                ? True if a player (the last one
  580.                     that affected this actor?) satisfies
  581.                     #COND, when #COND can be one of
  582.                     the defined (in DEFS.CON) numbers:
  583.                     pstanding, pwalking, prunning,
  584.                     pducking, pfalling, pjumping,
  585.                     phigher, pwalkingback, prunningback,
  586.                     pkicking, pshrunk, pjetpack,
  587.                     ponsteroids, ponground, palive,
  588.                     pdead, pfacing.
  589.  
  590. ifpdistg #NUM                ? True if a(?) player's distance
  591. ifpdistl #NUM                from the current actor is greater/
  592.                     less than #NUM.
  593.  
  594. ifphealthg #NUM                ? True if (which?) player's health
  595. ifphealthl #NUM                is greater/less than #NUM.
  596.  
  597. ifpinventory #ITEM #AMT            ?
  598.  
  599. ifrespawn                - True if monsters should respawn.
  600.  
  601. ifrnd #NUM                - True if #NUM is less than a
  602.                     randomly selected number between
  603.                     0 and 256.
  604.  
  605. ifhitspace                ? True if a(?) player hit space.
  606.  
  607. ifplayersg #NUM                ? True if player has greater/less
  608. ifplayersl #NUM                thatn #NUM Dukes left.
  609.  
  610. ifspawnedby #ACTOR            - True if the current actor was
  611.                     SPAWNed by the given type of actor.
  612.  
  613. ifspritepal                ?
  614.  
  615. ifsquished                ? True if the current actor was
  616.                     hit by the shrink ray and then
  617.                     stepped on.
  618.  
  619. ifwasweapon #WEAPON            ? True if the current actor was
  620.                     recently(?) hit by a shot from
  621.                     #WEAPON.
  622.  
  623. killit                    - Removes the current actor from
  624.                     the map. Seems to need to be the
  625.                     last instruction executed in an
  626.                     actor. In particular, don't try
  627.                     to SPAWN after this.
  628.  
  629. money #NUM                - Spawns #NUM dollar bills.
  630.  
  631. move #??? [#1 #2 #3 ...    ]        ? Sets the value of #??? to
  632.                     #1, and #2, and #3,(?) or if they
  633.                     are not specified, to 0?
  634.  
  635. palfrom #1 #2 #3            ? Rotates the palette from #1
  636.                     to #2, where #1 and 2 may be
  637.                     bitflags (aka 1, 2, 4, 8, etc...)
  638.                     where 16 specifies red and 0 or 32
  639.                     specifies green? #3 is a "delay"
  640.                     parameter that controls how quickly
  641.                     the pallete change happens; larger
  642.                     values = slower changes.(?) Ex.
  643.                     palfrom 16 16  // Screenflash red. 
  644.                     
  645.  
  646. pstomp                    ? Causes the player to look down,
  647.                     and stomp the current actor?
  648.  
  649. quote #NUM                - Prints quote #NUM out on the
  650.                     screen in the usual fashion.
  651.  
  652. resetactioncount            ? Resets the counter that counts the
  653.                     number of frames that have been
  654.                     displayed by the action that the
  655.                     current actor is executing?
  656.                     
  657. resetcount                ? ??? Same as resetactioncount?
  658.  
  659. shadeto #NUM                ? ???
  660.  
  661. shoot #WEAPON                ? Makes an enemy fire it's weapon.
  662.                     (Seems to be used to trigger blood-
  663.                     splattering, too)
  664.  
  665. sizeto #1 #2                ? Scales the sprites associated
  666.                     with the current actor to 1/#1 (?)
  667.                     in the X direction and 1/#2 in the
  668.                     Y direction.
  669.  
  670. sound #SOUND                - Plays the sound associated with
  671.                     #SOUND by definesound at the current
  672.                     actor's location.
  673.  
  674. soundonce #SOUND            ? ???
  675.  
  676. spawn #ACTOR                - Spawns a copy of #ACTOR.
  677.  
  678. spritepal #NUM                ? Changes the color of the current
  679.                     actor. Each value of #NUM corresponds
  680.                     to a different color scheme, some(?)
  681.                     of which are: 1 - bright blue, 4 -
  682.                     dark, 6 - Night vision green, 7 -
  683.                     "messed up yellow", 8 - green,
  684.                     10 - somewhat red, 19 - very reddish, 
  685.                     22 - Almost normal.
  686.  
  687. wackplayer                - Boot... TO THE HEAD!
  688.                     <Thwoosh-DONK!>
  689.  
  690.  
  691.  
  692. D. Examples
  693.  
  694.  * Trampoline Trash Cans
  695.  
  696.   I love those grey and red rubber-maid trash cans in the movie theater
  697. lobby in level 1. They're simple and static, so they're fun to play with.
  698. Let's make it so that when a player shoots one, it dents, and if they're
  699. stand too "close" when the trash can bounces back, the trash can will hit
  700. them and jar their viewpoint for a second.
  701.  
  702.   First of all, we have to understand the trash can actor code:
  703.  
  704.     action RUBCANDENT 1 1 1 1 1
  705.     action RUBCAN
  706.  
  707.     actor RUBBERCAN WEAK
  708.  
  709.       ifaction RUBCANDENT {
  710.         ifactioncount 16 {
  711.           strength 0
  712.           action RUBCAN
  713.           break
  714.         }
  715.       }
  716.  
  717.       else ifhitweapon {
  718.         ...
  719.           }
  720.  
  721.     enda
  722.  
  723.   Well, first of all, we don't care about what will happen to the trash can
  724. if it's hit with a weapon, so forget about the 'else ifhitweapon' part
  725. except to keep in mind that it takes care of denting the trash can for us.
  726. (Which is really just a call to 'action RUBCANDENT')
  727.  
  728.   Now then, before we start modifying things, try and think of what's
  729. happening from the trash can's perspective. This is Zen and the art of
  730. Duke3D: you must "become one" with your actor code. ;]
  731.  
  732.   Thinking this way, the important stuff in this actor could be paraphrased
  733. in english as: "if I'm dented, and if I've been dented for a while, pop back."
  734. We'd like to modify that to: "if I'm dented, and if I've been dented for a
  735. while, pop back. And if the player's "close," then bump them."
  736.  
  737.   So how do we tell if the player's close? We can use the "ifpdistl"
  738. primitive to tell if the player is less than a certain distance away.
  739. Now, how close is "close?" Apogee (in DEFS.CON) defined a certain
  740. distance to be close enough to retrieve an item. This is a good
  741. estimate of "close." Apogee called this distance RETRIEVEDISTANCE.
  742. How do we "bump" the player? Why, we "wackplayer," of course. ;]
  743.  
  744.   Okay, the code is shaping up. We have to modify the actor right
  745. in the part where the trash can bounces back. That's the stuff
  746. inside the 'ifactioncount 16 { ... }' Okay, so we go in there.
  747. What do we want? Well, IF player_close { bump_player }, right?
  748. So:
  749.  
  750.     actor RUBBERCAN WEAK
  751.  
  752.       ifaction RUBCANDENT {
  753.         ifactioncount 16 {
  754.           strength 0
  755.           action RUBCAN
  756.  
  757. /* We added these three lines below: */
  758.           ifpdistl RETRIEVEDISTANCE {    // If player's close...
  759.         wackplayer            // Boot... TO THE HEAD!
  760.           }
  761.  
  762.           break
  763.         }
  764.           }
  765.     
  766.       ...
  767.  
  768.     enda
  769.  
  770.  
  771.  
  772.  * Hollow-point bullets.
  773.  
  774.  * Kamikaze enemies.
  775.  
  776.  
  777.  
  778. E. So now what?
  779.  
  780.   Now go start playing with the .CON files. The worst that can happen
  781. is that DN3D will refuse to run because you made a mistake. (Forgot a
  782. brace, or something) If so, you'll have to correct the mistake or
  783. restore from your backup .CON file(s). (You DID make a backup, didn't
  784. you?  Of course you did.) 
  785.  
  786.   Please do not email the author with questions; he probably doesn't know.
  787. Even if he does, he won't help you. If he starts answering requests, where
  788. will it all stop? ("How do I make the sound that Duke makes when he's
  789. ducking in the ooze sound like a fart and have bubbles float around and
  790. etc, etc...?") Also please don't e-mail Apogee or 3D Realms with questions;
  791. they have specifically disavowed all responsibility if you mess with the
  792. .CON files. Instead, do what comes naturally: play around until you figure
  793. out the answer.
  794.  
  795.  
  796.  
  797. F. Appendix
  798.  
  799.   * Where can I get this document?
  800.  
  801.    - The UDN3DCFHG has been HTMLized by Todd Greco (tgreco@ee.net). URL:
  802.  
  803.     http://users1.ee.net/tgreco/confaq.htm
  804.  
  805.    - Joe Siegler of Apogee has put a plain copy of the CFHG on Apogee's
  806. web site. The URL is:
  807.  
  808.     http://www.3drealms.com/confaq.html
  809.  
  810.    - Rich Willoughby (slacker@rat.org) has also HTMLized the CFHG. You
  811. can find links to a plain text copy as well as his HTMLization at:
  812.  
  813.     http://rat.org/duke3d/faq.html
  814.  
  815.  
  816.   * Contributors/Thank You's
  817.  
  818.    - Apogee Software/3D Realms for a truely fun game.
  819.    - Todd Greco, Joe Siegler and Rich Willoughby for the HTML versions
  820. of the CFHG.
  821.    - Chris Gallagher (jazz411@aol.com) for help on the 'globalsound'
  822. and 'spritepal' primitives.
  823.