🚀 go-pugleaf

  Here's something I ripped off in a fit of inspiration this afternoon.
Hope it helps.

-----railgun spike here-----


THE UNNOFFICIAL DUKE NUKEM 3D .CON FILE HACKER'S GUIDE
By Ben Cantrick (cant...@rintintin.colorado.edu)


(This document is perpetually under revision. Please e-mail corrections,
comments, additions, clarifications, etc... to the author! In particular, 
I'd love info and WELL COMMENTED example code for AI routines and anything
else you can think of related to .CON file hacking. Also if anybody wants
to HTMLize this document, feel free.)


- What are Duke Nukem 3D .CON files?

  .CON files are text files that "CON"trol certain aspects of the DOOM-
like game Duke Nukem 3D (DN3D). There are three of them that come with
the Shareware version of DN3D: DEFS.CON, USER.CON, and GAME.CON. (The full
version of DN3D is has not been released as of the writing of this
document, and so I can't say anything about it.) When DN3D starts up,
it loads GAME.CON, checks it for errors, and if there are none keeps the
instructions contained in it for use later on in the game. (GAME.CON is
in charge of loading up any supplemental files, like DEFS.CON and USER.CON,
that it may want to use) The instructions currently known to be usable in
GAME.CON control things as mundane as how much damage each kind of weapon
does to things as exotic as how enemies behave.


- How can I alter .CON files?

  Well, before you start playing with them, you should definitly MAKE A
BACKUP OF ALL YOUR .CON FILES!!!!! This is not only to prevent you from
having to re-install DN3D if you mess up your existing .CON files, but
also so that you can have the original .CON files as reference material
when you start altering them. Once you've got backups made, altering the
.CON files couldn't be easier: just open them up with your favorite text
editor and edit away.


- What does all this weird, C-like junk in my .CON files mean??

  A lot of things, depending on which .CON file you edited. Let's take them
from least complex to most complex:


  ***** DEFS.CON:

  Most of the lines in DEFS.CON look something like:

	define SOMETHING SOMENUMBER 

  What they do is basically simple substitution: If you have a line
somewhere in your DEFS.CON that said:

	define THEANSWER 42

  Then any time after that, if the word "THEANSWER" appears, "42" is
substituted in it's place.

  By themselves, these lines aren't very interesting. They become helpful
later on, when you're writing actor code and don't want to remember that
an enemy who is TOUGH happens to have a strength of 137. You can just:

	define TOUGH 137

  And thereafter know that an enemy's strength is TOUGH.


 ***** USER.CON:

  USER.CON is somewhat like DEFS.CON in that it mostly just defines things.
However, USER.CON usually defines things that might be interesting to the
game player, whereas DEFS.CON usually defines things that a DN3D player
could care less about. USER.CON also contains nice technical notes written
by the 3D Realms .CON programmer, Tod Replogle, that tell you all about how
to modify it. Almost all of the info below is basically a rehash of the notes
you can find in USER.CON

  There are 5 major kinds of lines in USER.CON: defines, definequotes, 
definelevelnames, musics and definesounds.

  "define" lines are no different than they were in DEFS.CON; they define
stuff. Most of the stuff you can define here is emminantly useful, tho.
Examples abound: You can define Duke's starting and maximum health and
armor values here. You can define how much ammo Duke gets per clip picked up,
how much ammo is allowed for each weapon, how much damage each weapon does
per hit, etc, etc...
 
  "definequote" lines define the different things that will pop up on the
screen in response to certain game events. You can define what words
appear on the screen when you get an some ammo or an inventory item, what
words appear on the screen when you use the various cheat codes, what
words will appear when you adjust game options, etc, etc...

 "definequote" lines have two arguments: a number and a quote. The number
is what you use to refer to the quote by later on. For example, if you

	definequote 101 	NIGHT VISION GOGGLES!

  Then quote number 101 is "NIGHT VISION GOGGLES!" (This is pretty obvious,
isn't it?)

  "definelevelname" lines are used to define the episode and level number,
floor-plan file, par and record times, and level names for each level. The
format of a definelevelname line is:

	definelevelname #LEVEL #EPSIODE MAPFILE PARTIME RECORDTIME LEVELNAME

  For example, Episode 1, Level 5 is "The Abyss." The floor-plan of this
level is in the file E1L5.map. (which is actually contained in DUKE3D.GRP)
The par time is 9 minutes, 10 seconds, and the record time is 5 minutes
flat. It's definelevelname entry looks like this:

	definelevelname 0 4 E1L5.map 09:10 05:00 THE ABYSS

  As you can see, you must subtract one from the actual episode and level
numbers before you put them on the definelevelname line. We're in Episode 1,
but the #EPISODE is 0. We're in level 5, but the #LEVEL is 4. Notice also
that you should (I don't think it's actually required) pad the par and
record times with a leading 0 if necessary. There are also some comments
from Todd Replogle, taken from USER.CON:

  - Level file names cannot excede 13 characters.
  - Level par cannot excede 5 characters (min:sec)
  - Level titles cannot excede 32 characters.

  "music" lines (as far as I can tell) define the sequence of .MID files to
play for each level. Level 1 (aka #LEVEL 0) plays GRABBAG.MID and
ITSGREEN.MID in (I think) a continuous loop. The format looks like this:

	music 0 GRABBAG.MID ITSGREEN.MID

  "definesound" lines define various names that correspond to ways to
play a VOC file. The format of a definesound line is:

	definesound SOUNDNAME VOCFILENAME.voc	#1  #2  #3  #4  #5

  Once again, Todd Replogle has provided .CON file hackers with a helpful
technical note in USER.CON:

	-----------------------------------------------------------------
	ABOUT CHANGING SOUND FX
	The sound fx section follows this explanation. 

	1. The program expects to find a .VOC file
	2. You can either change the VOC name listed below to match your new
	   sound, or you can rename your file to match the name here.
	3. New sound files should be added to the game directory.  Though
	   all sound files shipped with the game are included inside the 
	   .GRP file, the program will know if there are sound files outside
	   the .GRP file, and will use them instead.
	4. The numbers that are to the right of the sound file name are
           technical parameters which will not be explained here, except as
           follows...
	   - The first 2 numbers define a random pitch variation range.
             They can be positive or negative numbers.
	   - The 3rd number is a priority flag.
	   - The 4th number is a bit parsed set of technical variables
             that identify the type of sound it is in the game.
	   - The 5th number is a volume adjustment flag.
	-----------------------------------------------------------------

  The explanation seems pretty self-evident, so I won't go into a detailed
explanation of each field of the definesound line.


 ***** GAME.CON:

  The BIGGIE! Lots of stuff in this one, and most of it rather difficult to
explain... let's start out with the first couple of lines, which are:

	/*
	-------------------------------------------------------------------
        Duke Nukem 3D Script Code.
	Todd Replogle.
	-------------------------------------------------------------------
        */

  If you're a C programmer, this stuff is immediatly obvious: everything
between /* and */ is considered a "comment" and Duke3D will almost always
ignore it when reading in GAME.CON. There is another kind of comment also:
"//". A // comment starts at the // and extends to the end of the line.
After the end of the line, the comment ends. /* */ comments can go for
several lines, but // only "nulls out" one line. Many such // and /* */
comments can be found all over DEFS.CON, USER.CON, and GAME.CON.

  The next few lines are "include" lines which basically process the
specified file. The line:

	include defs.con

  Makes DN3D go process DEFS.CON before it moves along to the next line.


  And now, the really big, confusing ones: states, actions, and actors.

  Apogee hasn't said anything about states, actions, or actors yet, so the
things I'm about to tell you are pure conjecture based on observation and
experimentation:


  *****STATEs

  As far as I can tell, "states" can be thought of as something like
subroutines. You go into a state, do something, and then come back to
wherever you were. The first state in GAME.CON is the "rats" state, which
randomly makes some rats whenever it's called.

  The format of a state is:

state #STATENAME
 ...
ends

  STATENAME is a unique number that is usually DEFINEd to be the name of the
state. And "ends," of course, is short for "End State."


  *****ACTIONs

  As far as I can tell, an "action" specifies a sequence of sprites
(pictures) to draw onto the screen. The format of an action is still
not quite entirely known, but it seems to be something like this:

	action #SPRITEGROUP #FIRSTFRAME #LASTFRAME #?? #?? #SPEED

  Each "sprite group" is composed of several actual pictures, or "frames."
The first number is a (usually DEFINEd) number that specifies which
group of frames to use. The second and third numbers specify which
sequence of frames from the current group to step through when you're
animating this sprite. (Animation goes from the whatever-th frame in the
group, number FIRST# to the whatever-th frame in the group, number LAST#.)

 The SPEED# number determines how fast the frames are changed. That is,
how rapidly the sprite is animated on-screen. 1 = very fast, bigger
numbers = slower.

 The two remaining numbers are a mystery. If anybody knows what they mean
and how they're used, please mail me at cant...@rintintin.colorado.edu.


  *****ACTORs

  As far as I can tell, an "actor" is any (freestanding?) object in the
game that does something. Obviously, Duke and the enemies are actors. However,
the rubber-maid trash cans in the movie-theater lobby are also actors, because
they dent and then bounce back when you shoot them. The items and weapons and
clips are also actors, because they also do something when you run over them:
they give you an item, a weapon, or more ammo.

  Walls are not actors, because they don't 'do' anything except sit there.
(Bullet-holes being an exception, I guess. Perhaps the bullets themseves are
some kind of actor that effect the surface they hit.) Doors and lifts are
borderline; I supose the game might treat them as actors internally, but I
don't know if you can/how you would alter their behavior in the .CON file. 

  The format of an actor is something like:

	actor #ACTORNUMBER #ACTORSTRENGTH #ACTION #SPEED #AI_FUNCTION
	 ...
	enda

  #ACTORNUMBER is (I think?) a unique number that identifies this actor.
Usually the ACTORNUMBER# is DEFINEd to be something easier to remember
than a number.

  #ACTORSTRENGTH is a number that determines how much damage this actor
can take before it breaks, dies, etc... (I think?) Putting a value of 0
for this field makes the object invincible. Usually, #ACTORSTRENGTH is
DEFINEd to be something easier to remember. (See 'define TOUGH' above.)

  #ACTION is (I think?) the number of an action (that is, the identifying
number of a series of frames) to cycle through for this actor, if this
actor is animated. Patches of fire actors use this to maintian an image-
loop so they look like they're constantly burning. 

  #SPEED is (I think?) how fast this actor moves, if it moves. I don't know
if "move" is always interpreted in the traditional sense; it appears from
the gun-turret actor code that turrets that spin in place are considered to
be "moving." 

  #AI_FUNCTION is (I think?) a number, as defined in DEFS.CON, that specifies
what this actor's initial AI is if it has an initial AI.

  The last three parameters of actor seem to be optional. Things that aren't
animated, don't "move" and have no AI don't seem to need to include those
parameters. You can make a perfectly sensible actor without them; as a
matter of fact the majority of non-enemy actors in Duke3D (ammo and items,
basically) do not use them at all.


- You keep putting "..." inside actors as if we already know what's
  supposed to go inside there; but we don't!

  Well, this is kind of sticky; there are quite a few things inside there,
most of them vaguely reminiscent of the C programming language with a
virtual environment twist. Let me illustrate with an example. Let's make
a new actor. (We won't actually be able to put this actor in a map without
3D Realms' DN3D level editor, but what the heck...) How about a new actor
that looks just like the red and grey rubber-maid trash cans in the movie
theater lobby but when you shoot it with a bullet-type of weapon, the
bullet bounces back at you and hurts you. Additionally, any kind of non-
bullet weapon hitting it will dent it, but it bounces back. (Don't you
wish everything was made like rubber-maid?)

  First, we need to have the basic actor code:

  In DEFS.CON:

definequote 111 Ricochet!	// Quote 111 is normally unused.

define NEW_RUBBERCAN 12000	// Ensure no actor has the same number by
				// picking a number for NEW_RUBBERCAN that
				// we KNOW has not been used by any other
				// actor. 

  In GAME.CON:

actor NEW_RUBBERCAN 1		// Our new rubber-can actor.

  ifaction RUBCANDENT {		// If we're dented/dent-ing. This state is
				//  also used by the RUBBERCAN actor, but
				//  it won't mind letting us use a copy.

    ifactioncount 16 {		// If we've been dented for a while (16
				// animation cycles, presumably?)

      strength 0 		// Make us indestructable.
      action RUBCAN		// And sprite back to normal.
      break			// That's all folks! Go to end of actor.
  } }

  // Normal code: what happens if we're not already dented.
  else ifhitweapon {		// If we were hit by a weapon.

    // Shot trashcan with a pistol?
    ifwasweapon PISTOL_WEAPON {
      quote 111			// "Richochet!" 
      ifrnd 13 {		// 13/256, or about 1/20 chance per bullet.
        addphealth -PISTOL_WEAPON_STRENGTH	
        palfrom 24 16		// Screen goes red briefly.
    } }

    // Shot trashcan with the shotgun?
    ifwasweapon SHOTGUN_WEAPON {
      quote 111			// "Richochet!" 
      ifrnd 32 {		// 32/256, or about 1/8 chance per blast.
        addphealth -SHOTGUN_WEAPON_STRENGTH	
        palfrom 24 16		// Screen goes red briefly.
    } }

   // Shot trashcan with chaingun?
    ifwasweapon CHAINGUN_WEAPON {
      quote 111			// "Richochet!" 
      ifrnd 13 {		// 13/256, or about 1/20 chance per bullet.
        addphealth -CHAINGUN_WEAPON_STRENGTH	
        palfrom 24 16		// Screen goes red briefly.
    } }
    
    // No matter what weapon shot it, the can dents.
    // (And, of course, will eventually pop back.)
    action RUBCANDENT		// Dent can.
    }
  }
ends

  So what does this new actor do? Well, for the moment ignore the first
part about "ifaction RUBCANDENT." What this actor does, mainly, is to
check what weapon hit it every time it gets hit and respond appropriatly.
DN3D's engine will run this code for you when a bullet hits any can of
this actor type.

  The can checks what kind of weapon hit it: if it was a bullet weapon,
aka the pistol, shotgun, or chaingun, then the trash-can will make the
quote "Ricochet!" appear on the screen, and randomly determine if the
richochet hit the player who fired it, and if so subtracts the appropriate
amount of life from the player and flashes their screen red momentarily.

  Then, no matter what kind of weapon hit it, the can dents by going into
the RUBCANDENT state. This is where the first part of the actor comes in
again - somehow, the actor is called each time the action changes it's
frame. The actor checks if it's been dented for 16 time units (still not
sure how long a time unit is?) and if so un-dents itself.


- So now what?

  Now go start playing with the .CON files. The worst that can happen
is that DN3D will refuse to run because you made a mistake. (Forgot a
brace, or something) If so, you'll have to correct the mistake or
restore from your backup .CON file(s). (You DID make a backup, didn't
you?  Of course you did.) 

  Please do not email the author with questions; he probably doesn't know.
Even if he does, he won't help you. If he starts answering requests, where
will it all stop? ("How do I make the sound that Duke makes when he's
ducking in the ooze sound like a fart and have bubbles float around and
etc, etc...?") Also please don't e-mail Apogee or 3D Realms with questions;
they have specifically disavowed all responsibility if you mess with the
.CON files. Instead, do what comes naturally: play around until you figure
out the answer.

-----railgun spike here-----

          -Ben
-- 
         --Ben Cantrick. Email to cantrick@nyx10.nyx.net--
>"Some people think of their body as a temple. I like to think of mine as an
amusement park. S'great." -Warren's Kei, via Yuri.  >"You never know how far
a frog will jump until you punch it." -Hillary Clinton, speaking on my campus.