Confaq42

Con File Editing - An Introduction

Con file editing is one of the coolest aspects of Duke Nukem 3D, and can be very productive in making Total Conversions and other game add-ons. Although it can look very difficult at first, editing con files is very easy and a fun way to make one of the coolest games in history even cooler.

How does one edit con files you ask? Any text editor will do. I personally use Microsoft Wordpad (not Word) to edit con files (this program comes with Windows 95), but you can use any text editor you wish. The Microsoft Notepad program is not large enough to edit con files (the files are too big for notepad to handle), but the DOS editing program works quite well. Simply open up your favorite text editor and open the con file that you wish to edit.

OK - You've opened a con file, but what do I do now? Well, if you're really serious about con file programming, you need to read through this FAQ. Even if you're not so serious about editing con files, quickly skim through this FAQ to find out how to edit some of the easiest parameters and settings in Duke Nukem 3D. You can do some very cool stuff with con files, so stick with it if you don't get it right away. If you have ever done any programming, you will instantly be able to edit con files.

The most important instruction, however, for editing con files is simply - Have fun! This stuff shouldn't make you frustrated - if you aren't getting something, take a look through this FAQ, or visit the editing and hacking forum at Dukeworld. I personally hope you enjoy your con editing experience.

CON BUILDING BLOCKS

What is an action?

An action is used to give a group of sprites, usually which are animated (as in an enemy movement or other such animated examples), a name. The structure for this primitive is:

action <name> <startframe> <frames> <viewtype> <incvalue> <delay>

<name>

This is the name of the action. This is simply a string which can be up to 64 characters in length.

<startframe>

This is the relative starting frame number (relative to the main sprite of the action that is). For example, if you want the Pigcop to look like the atomic health, you need to give the starting frame a number of -1900 since the Pigcop sprite is located at 2000 and the atomic health sprite is located at 100 (100 minus 2000, is -1900).

<frames>

This value is the total number of frames in the action.

<viewtype>

This value determines whether the sprite is one sided (it looks the same no matter what angle you see it from) or 3-Dimensional. Legal values for this parameter are:

• 0: Single image - It always faces the player no matter where they look from.

• 5: Five images - The first image is looking from the front, the second is 45 degrees from the front, the third is from the side, the fourth is 45 degrees from the rear (135 degrees from the front), and the fifth value is looking from the rear. The second, third, and fourth are used for either side of the image.

• 7: Seven images - Same as 5, except there are seven images, with images 2, 3, 4, 5 and 6 are on both sides. Image 4 is the side images, 1 and 7 are the front and rear respectively. These increment every 30 degrees.

• 8: Eight images - The first image is looking from the front, the second is 45 degrees from the front to the left, the third is from the left side, the fourth is 135 degrees from the front to the left, the last/fifth value is looking from the rear, the sixth is 135 degrees from the front to the right, the third is from the right side and the fourth is 45 from the front to the right.

<incvalue>

This parameter specifies the "direction" of the animated frames. A value of 1 causes the animation to go forwards (Example: The animation starts at tile #20, goes to #21, then to #22, etc.). A value of -1 causes the animation to go backwards (Example: The animation starts at tile #20, goes to #19, then to #18, etc.).

<delay>

This determines how long each frame of the animation lasts. Bigger values allow each frame to last longer.

What is an actor?

An actor is a sprite that will perform some function (spawn another sprite, give the player ammo, etc.) by performing several lines of code.

The structure for this primitive is:

actor <name> <strength> <action> <speed> <aifunction> {actor code} enda

<name>

This parameter is usually a string (such as PIGCOP) that is used to set the initial sprite of the actor. If you look in DEFS.CON, you will see that PIGCOP is defined to be 2000, meaning that the initial sprite for the PIGCOP actor is sprite #2000.

<strength>

This is the "health" value of the actor. If a value of 0 is used, the actor cannot be destroyed.

<action>

This parameter is the action that the actor is to use initially.

<speed>

This is the rate of movement of the current actor. A value of 0 means that the actor cannot move.

<aifunction>

The actor's initial ai routine. This is really only used with monsters.

{actor code}

Now that we have defined our actor, we have to write its code. Each time the actor being referenced is called (and this happens every frame for most animated actors), the code here is executed. This can be many lines of code, since you are grouping them together with the curly braces.

enda

This parameter signals the end of the actor definition.

Notes:

In version 1.3D of Duke Nukem 3D, new actors cannot be added. The name of an existing actor, its corresponding code, and the artwork itself can be changed to add new actors (if you want to go to all of this trouble).

In versions 1.4 or 1.5, however, you can create your own actors (without having to replace existing ones). See the section on "useractor" for more information on this.

What is an ai?

An ai is an "artificial intelligence" routine. This is basically a set of code that an actor follows when said actor is instructed to do so. The structure for this primitive is:

ai <name> <action> <speed> <type>

<name>

This is a name to identify this ai routine later on.

<action>

This value is the name of the action that the actor will cycle through when he uses this ai function (i.e. - the animation it will use).

<speed>

The rate of movement of the character when using this ai function. Negative values are allowed in this parameter.

<type>

Determines the type of ai routine. The ai types are already programmed into the game so you can't change these. Some of the legal types are:

• faceplayer: Actor faces the player's current position.

• geth: Actor travels in a horizontal direction.

• getv: Actor travels in a vertical direction.

• randomangle: Actor will change to a random angle when it touches a wall or when the actor is currently being shot at by the player. Only seems to work when the actor is a monster.

• faceplayerslow: Actor faces the player's current position but slower than the regular faceplayer command.

• spin: Actor spins in circles.

• faceplayersmart: The actor will face slightly ahead of the player's current position, making it possible for monsters to "lead" you a little bit.

• fleeenemy: Actor faces directly away from the player.

• jumptoplayer: Actor attempts to jump.

• seekplayer: Actor tries to find and move to the nearest player.

• furthestdir: Actor faces the furthest distance from the closest player.

• dodgebullet: Actor attempts to avoid all shots directed at him.

You can use more than one ai at the same time by listing them in order in the code that you write. For example: randomangle dodgebullet fleeenemy

What is a state?

A state is a set of code that you will use several times (this is very useful in that you don't have to write the same code over and over). The usage for this primitive is as follows:

state <name> {code} ends

<name>

This is the name of your state function. Can be any string.

{code}

This is simply the lines of code that you want to have executed when the state is called. This can be any number of lines you want.

ends

This parameter signals the end of the state definition.

Here is an example of a state:

state findgoldenapple // Start and name the state itself.

{

 quote 150             // This is the code to execute...

 addphealth 10

}

ends // End of state. Now returns to its caller.

To call a state from your code, simply type the following:

state <name>

The <name> parameter is simply the state that you want to call.

What is a useractor?

[This function only works with versions 1.4 and 1.5]

The useractor command is a new addition to versions 1.4 and 1.5. It allows people to create their own actors without having to replace old ones. It's usage is almost exactly like regular actors.

The structure of the useractor command is as follows:

useractor <type> <name> <strength> {actor code}

<type>

This parameter is the type of actor that you want to create. The legal values are as follows:

• enemy : The actor's code will not be executed until approximately 1 second after the player has spotted the actor.

• notenemy : The actor's code will not be executed until the player has spotted the actor.

• enemystayput : The actor will not leave the current sector when the player goes out of sight (i.e. - the actor can no longer "see" the player). This is most useful in custom enemy creation.

<name>

This parameter is usually a string (such as PIGCOP) that is used to set the initial sprite of the actor. If you look in DEFS.CON, you will see that PIGCOP is defined to be 2000, meaning that the initial sprite for the PIGCOP actor is sprite #2000.

<strength>

This is the "health" value of the actor. If a value of 0 is used, the actor cannot be destroyed.

{actor code}

This is the code that the actor will run. This code includes the following items:

<action>

This parameter is the action that the actor is to use initially.

<speed>

This is the rate of movement of the current actor. A value of 0 means that the actor cannot move.

<aifunction>

The actor's initial ai routine. This is really only used with monsters.

What is an if construction?

If statements are perhaps the most powerful aspect of CON file editing. If statements evaluate the specified condition, and run code based on the returned value of the evaluation.

Here is an example:

ifphealthl MAXPLAYERHEALTH

 {

   addphealth MAXPLAYERHEALTH

 }

else

 {

   quote 999

 }

This simple example simply says this:

If the player's health is less than MAXPLAYERHEALTH (which by default is 100)

 {

   Add MAXPLAYERHEALTH to the player's current health.

 }

Else, if the player's health is not less than MAXPLAYERHEALTH

 {

   Print quote number 999

 }

A COMPLETE PRIMITIVE LISTING

The Complete Primitive List

The following is a complete listing of all the "primitives" that can be placed into Duke Nukem 3D CON files. Primitives are simply commands and syntax in code that can control and test the items in the game.

If you find any errors in this section, e-mail me at: jonahb@3dportal.com

//

This is used (just like in C\C++) to denote comments. Everything after this comment mark is ignored by the compiler. A space must follow this comment mark, or the compiler will generate an error.

/* and */

These two marks are used to create comment blocks (just like in C\C++). Place the /* at the beginning of the area you wish to ignore, and the */ at the end of the area you wish to ignore. This is a handy way to create large comments or to ignore an entire section of code.

{ and }

These symbols are used to group several lines of code into one block of code (also called a function). Used just like C\C++.

action <name> <startframe> <frames> <viewtype> <incvalue> <delay>

See section 2.1 for an in-depth look at this primitive.

action <name>

Starts the action specified by <name>.

actor <name> <strength> <action> <speed> <aifunction> {actor code} enda

See section 2.2 for an in-depth look at this primitive.

addammo <weapon> <amount>

Adds the <amount> of ammunition to the current or closest player's value for the appropriate <weapon>. Legal values for <weapon> can be found in section 4.1.

addinventory <item> <amount>

Adds <amount> to the current or closest player's value for the appropriate <item>. Legal values for <item> can be found in section 4.2.

addkill

Adds 1 to the current or closest player's kill count.

addphealth <amount>

Adds the value <amount> to the current or closest player's health. Only the atomic health actor can boost the player's health value over the MAXPLAYERHEALTH value.

addstrength <value>

Adds <value> to the strength (health) of the current actor.

addweapon <weapon> <ammo>

Gives the current or closes player the specified <weapon> with an initial amount of ammunition equal to <ammo>. Legal values for <weapon> can be found in section 4.3.

ai <name> <action> <speed> <type>

See section 2.3 for an in-depth look at this primitive.

ai <name>

Makes the ai function <name>, the current actor's current ai routine.

break

Immediately leave the current state or actor code.

cactor <actor>

Change from the code of the current actor to the code of the actor identified by <actor>. All initialization values of the specified <actor> are ignored when this primitive is used.

clipdist <value>

The <value> parameter can be any value from 0 to 255. When a sprite or actor is blocked (by setting blocking with the [B] key in Build or through the use of the cstat primitive in GAME.CON), a "force field" (for lack of a better term) is set up around the sprite. The clipdist value determines how close an actor can get to the sprite before being blocked by that invisible "force field". The lower the value, the closer the player or an actor can get. A clipdist of 255 equals the distance of the largest grid size in Build which equals 1024 Build units. The default for <value> seems to be 32. The same effect can also be achieved in Build by placing the cursor on the sprite (in 3D mode) and pressing the [ALT]+[D] key combination. Also, it would appear that this only works on a sprite that rotates with the player. If (in Build's 3D mode) you press the [R] key to align the sprite to the grid or to the floor, altering the clipdist primitive has no effect. In addition, this attribute does not work on all sprites. At this time there is no explanation for why this primitive should either work or not work.

count <number>

Sets the current actor's count to <number>.

cstat <mask>

This primitive manually sets some various flags for an actor (a sprite). All previous settings are lost when this function is used. The legal values for <mask> can be found in section 4.4.

cstator <mask> (Used in Versions 1.4 and 1.5 Only)

This primitive manually sets some various flags for an actor (a sprite). All previous settings are not lost when this function is used; they are simply added together. This is a little like the "or" in C\C++. The legal values for <mask> can be found in section 4.4.

debris <type> <amount>

This primitive causes debris to fly around the actor. The <type> parameter is the sprite group used for the debris. Legal values are: SCRAP1, SCRAP2, SCRAP3, SCRAP4, SCRAP5, and SCRAP6. The higher the <amount> value, the more debris.

debug <parameter>

Prints the value of <parameter> to the current output buffer. If a standard game is loaded, with the default output buffer being used, it will print the value to the screen. If the output buffer is changed (for example: "duke3d.exe -map test.map /q8 > test.log"), the standard output will be printed to the output buffer "test.log". You then can open this file later to look at the values that were printed out.

define <string> <value>

This primitive makes <string> equal <value>. This allows you to use the string (which is a lot easier to remember) in your coding. The following example sets the string MAXPLAYERHEALTH to the value of 100.

 EXAMPLE: define MAXPLAYERHEALTH 100

definelevelname <eps> <lvl> <mapname> <par time> <3drealms>

Defines a level name where the episode number is <eps>, the level number is <lvl>, the map name (a string) is <mapname>, the par time is <par time>, and the 3D Realms time is <3drealms>.

definequote <value> <string>

Sets <string> equal to <value>. This is used when printing quotes at the top of the screen while in the game (it saves you from having to type the quote over and over).

defineskillname <skill> <string> (Used in Versions 1.4 and 1.5 Only)

Makes <string> equal the desired difficulty level (which is <value>). Legal values for <skill> are: 0, 1, 2, and 3. The higher the number, the harder the skill level. This is only used for setting the text of the skill levels on the skill level selection screen.

definesound <value> <file> <pitch1> <pitch2> <priority> <type> <volume>

The <value> parameter is the name of the sound (you make this up). The <file> parameter is the .voc or the .wav file that the game will try to find to use for this sound. The <pitch1> and <pitch2> are random pitch variations (these can be both negative and positive). The <priority> is the importance of the sound (telling the game that this sound has priority over other sounds). Values of 0 to 255 inclusive are acceptable for <priority>, with larger numbers being more important. The <type> is the type of sound in the game. Legal values for <type> are: The <volume> is the volume of the sound, ranging from -32,767 to 32,767. Negative values are louder and positive values are softer.

definevolumename <episode> <name> (Used in Versions 1.4 and 1.5 Only)

Defines title for each episode where <episode> is the episode number and <name> is the name it will get.

else

This is used in "if-else" statements. This returns true if the last function returned false.

enda

Closes an actor or useractor function.

endofgame <number>

Ends the game after <number> counts. For example, a value of 180 would end the game after approximately 6 seconds (30 = 1 second). A value of 52 is used to end each episode. This primitive obviously appears to exist as a "sleep" function of sorts. I believe that this is used to allow the death sequence of the boss to be completely viewed by the player, but this is only one suggestion as to its proper use.

ends

Closes a state function.

fall

Let the current actor fall until it hits a surface.

gamestartup

This is the main function which "starts" the game. It gets all the hard coded values passed as parameters. The values that get passed can not be changed during gameplay. There are too many parameters for this primitive to list here, so take a look at the user.con file.

getlastpal

Sets the palette of the current actor back to the color before the last change.

globalsound <sound>

Play sound that can be heard everywhere in the map. The <sound> value is the name of the sound to play (not the filename of the sound).

guts <type> <amount>

Same as debris but then for body parts. Legal values for <type> can be found in section 4.5. The <amount> value determines the amount of guts to make fly.

hitradius <radius> <1> <2> <3> <4>

Make an explosion (not the actual animation but just the damage). The <radius> value is the radius, <4> is how much damage is done in first quarter of circle (right near the center of the circle), <3> is how much damage is done in second quarter of circle, etc.

ifaction <action>

Test if the current actor is executing the giving <action>. The <action> parameter is defined by the action primitive (see section 2.1).

ifactioncount <number>

Tests if the actor has displayed a set <number> of frames since the last call to resetactioncount.

ifactor <actorid>

Returns true if the current actor is equal to <actorid>.

ifactornotstayput

Test if the current actor already <activated>, where <activated> means spotted by a player or he has spotted the player. It seems that an actors code isn't executed at all until one of the above events occur. You can notice this in the game. If you create a map where an actor (i.e. health) is lifted into the sky, he doesn't fall down to the ground until you spot it! (I'm not 100% sure about this one).

ifai <ainame>

Tests if the current actor is using the ai function <ainame> which was defined with the ai primitive (see section 2.3).

ifangdiffl <angle> (Used in Versions 1.4 and 1.5 Only)

Returns true if the angle between the current actor and the player is less than <angle>. 360 degrees is a value of 2048.

ifangdiffg <angle> (Used in Versions 1.4 and 1.5 Only)

Returns true if the angle between the current actor and the player is greater than <angle>. 360 degrees is a value of 2048.

ifawayfromwall

Returns true when an actor is away from all walls (including sector divisions (red lines)) in the game.

ifbulletnear

Returns true if the current actor is being shot at (bullets are coming close to the actor).

ifcansee

Tests if the current actor can see the player. It also seems to have another function. It seems as if you need to call this function to give an actor a new position to walk to when using the seekenemy and some other ai functions. If you don't call this when using that ai function he will just walk up to your previous position and just stop there!

ifcanseetarget

Returns true if the current actor can see the player.

ifcanshoottarget

Returns true if the current actor can shoot the player (which seems to be the only target the actor has).

ifceilingdistl <number>

Returns true if the distance between the current actor's center and the ceiling is less than <number>.

ifcount <number>

Returns true if the current actor's local counter has reached <number> counts.

ifdead

Returns true if the current actor has no strength (health) left. The actor must have had health at some point for this to return true.

iffloordistl <number>

Returns true if the distance between the current actor's center and the floor is less than <number>.

ifgapzl <number>

Tests if the distance between the floor and the ceiling at the actor's location is less than <number>.

ifgotweaponce <number>

If <number> is set to 0, in multiplayer games of either cooperative or dukematch with the no spawn option turned on, the player can only get the weapon if they don't already have it. If <number> is set to 1, in multiplayer games of either cooperative or Dukematch with the no spawn option turned on, the player cannot get the weapon at all.

ifhitspace

Tests to see if the player is pressing the use key (which is the spacebar by default).

ifhitweapon

Returns true if the current actor has been hit by a weapon.

ifinouterspace

Returns true if the following parameters are true: "ifinspace" is true and the ceiling (or floor) palette on the BigSpace texture is 0. This primitive is basically useless, since it is called a split second before the player dies from the vacuum of space.

ifinspace

Checks if current player is in space. "Space" means when the floor or ceiling is parallaxed and the texture is one of the space textures.

ifinwater

Tests if the current actor is in a sector with a lotag of 2 (underwater sectors).

ifmove <name>

Returns true if the current actor is using the movement defined by <name>.

ifmultiplayer

Returns true if the current game is a cooperative game.

ifnosounds

Tests if the current actor is not playing any sound effects.

ifnotmoving

Returns true if the current actor has stopped moving. This is used to test if an actor is "stuck" against a wall (usually a monster stuck near a door) - at which point the "operate" primitive can be used to allow the stuck actor to try and free himself.

ifonwater

Returns true if the current actor is in a sector with a lotag of 1 (above water sector) and is on or near the surface.

ifoutside

Tests if player is outside. A player is outside when he is in a room with parallaxing on.

ifp <type>

Returns true if the current <type> is true. Legal values for the <type> parameter can be found in section 4.6.

ifpdistg <number>

Tests if the current or closest player's distance is greater than <number>. A value of 1024 is equivalent to the largest grid size in Build.

ifpdistl <number>

Tests if the current or closest player's distance is less than <number>. A value of 1024 is equivalent to the largest grid size in Build.

ifphealthl <number>

Tests if the player's health is less than <number>.

ifphealthg <number>

Tests if the player's health is greater than <number>.

ifpinventory <item> <amount>

The <item> value is the inventory item to be tested. The <amount> value is the amount to test for. This function will return true when the <item> is not equal to the <amount> value. Legal values for <item> can be found in section 4.2.

ifrespawn

For monsters, tests if monster respawn mode is turned on. For items, tests if item (weapons, ammo, etc.) respawn mode is on.

ifrnd <number>

Generates a random probability of something happening. The <number> value divided by 256 is the chance that something will happen. So a value of 256 would happen all the time (256/256 = 1 = 100%).

ifspawnedby <actor>

Checks if the current actor was spawned by <actor>.

ifspritepal <number>

Tests if the palette of the current actor is equal to <number>.

ifsquished

Tests if the current actor has been squished. This can be caused by the actor being shrunken and stepped on, or squished by a falling sector (i.e. - the ceiling height of the sector at one point or another is the same height at the floor height of the sector).

ifstrength <number>

Tests if current actor has <number> strength (health) left.

ifwasweapon <weapon>

Tests what weapon the actor has been hit by. This primitive appears only to work after the "ifhitweapon" primitive is called. The legal values for <weapon> can be found in section 4.7.

include <filename>

Includes <filename> in the compiling process.

killit

Removes the current actor from the map.

lotsofglass <amount>

Spawns glass shards, much like when a window has broken. The <amount> parameter determines the number of glass shards to spawn.

mail <number> (Used in Versions 1.4 and 1.5 Only)

This primitive spawns some envelope sprites. The <number> value is the amount of mail to spawn.

mikesnd

Plays the sound assigned to the microphone sprite in Build (the microphone sprite's hitag is the sound number to be played). This might be available for use on other sprites (other than the microphone that is). I'm not 100% sure.

money <number>

This primitive is used to spawn a specified <number> of dollar bill sprites.

move <name> <horizontal> <vertical> <directions>

Assigns <name> to a <horizontal> and <vertical> velocity, with optional <directions>. See section 4.10 for a listing of valid <directions>. Also used to tell an actor to move with the desired velocities and directions.

music <episode> <m1> <m2> ...

Defines the music used for each level in each episode. The <episode> parameter is the episode number, with the individual music files following the episode number. This is usually defined in user.con.

nullop

The nullop primitive is another way to signify empty braces - {}.

operate

This primitive is used to allow the current actor to operate, which simply means that the current actor can open a door if one is nearby. The actor should not constantly operate, because the door will close again if the actor operates immediately after operating the first time.

palfrom <intensity> <red> <green> <blue>

This primitive is used to flash a specified color (set by mixing the <red>, <green>, and <blue> parameters) on the screen with a specified <intensity> amount. The values for the any of the parameters can be anything between 0 and 64.

paper <number> (Used in Versions 1.4 and 1.5 Only)

Spawns some paper sprites, which then float down to the ground. The <number> parameter is the amount of paper to spawn.

pkick

The current or closest player will perform a "quick kick".

pstomp

The current or closest player will look down and step on the nearest actor (if one is near).

quote <number>

This primitive prints quote <number> at the top of the screen. All game quotes can be found and are defined in user.con.

resetactioncount

Sets the action counter to 0. This counter counts the number of frames of animation that the current actor has displayed.

resetcount

Set the current actor's local counter to 0.

resetplayer

In a multiplayer game, this primitive spawns the player at one of the multiplayer starting positions, with the default amount of ammo, armor, and health. In a single player game, this primitive simply restarts the current level.

respawnhitag

This primitive activates up to 9 respawn actors who have the same lotag as the current actor's hitag.

shoot <weapon>

Allows the current actor to shoot - eject - fire the specified <weapon>. Legal values for <weapon> can be found in section 4.8. The direction that the <weapon> is fired depends on the AI function of the actor.

sizeat <x> <y> (Used in Versions 1.4 and 1.5 Only)

Immediately resizes the current actor to <x> width and <y> height.

sizeto <x> <y>

Gradually resizes the current actor to <x> width and <y> height.

sleeptime

This primitive makes the current actor sleep for counts. The current actor is not "activated" again until it "sees" the player.

sound <sound>

This primitive plays a specified <sound>. The <sound> parameter is the name of the sound to be played (these can be found in user.con).

soundonce <sound>

This primitive plays a specified <sound>. The sound cannot be activated again until it has completely finished playing.

spawn <actor>

Creates a new actor (defined by <actor>) in the map. Some special actors can be spawned to create some neat effects. See section 3.4 for more information on which actors are special to the spawn primitive.

spritepal <number>

Changes the current actor's palette to <number>. Legal values for <number> can be found in section 4.9.

state <statename> {code} ends

This is used to construct a state function. See section 2.4 for a more detailed description of what this does.

state <statename>

This primitive calls a state function with <statename> being the name of the state function. The state function must be above where this line is called.

stopsound <sound>

Stops the currently playing <sound> from playing.

strength <number>

This primitive changes the strength (health) of the current actor to <number>.

tip

Starts the current or closest player's "tipping" routine.

tossweapon

This primitive spawns the player's currently selected weapon when the player dies in the game.

wackplayer

This primitive tilts the screen to one side when called.

Predefined State Functions

The following is a listing of (most) state functions that already exist in the GAME.CON file. You can alter these to your liking, but the default functions are described here. The states are listed in order of appearance (at least in the 1.4/1.5 CON files).

state jib_sounds

Plays one of those nice sounds like "What a mess" or "Let God sort em' out".

state standard_jibs

Spawns some random body parts.

state genericshrunkcode

Shrink an actor and stomp on it if you are within the correct distance.

state genericgrowcode (Versions 1.4/1.5 Only)

Make the current actor grow and then explode.

state blimphitstate

Spawn an explosion and debris, kill the actor, and some other stuff...

state rats

Spawn some rats.

state toughgalspeech (Versions 1.4/1.5 Only)

The sounds to play when the tough girl talks.

state jibfood (Versions 1.4/1.5 Only)

Make food disappear when shot and spawn some gross jibs.

state breakobject (Versions 1.4/1.5 Only)

Code that makes all the breakable objects in versions 1.4 and 1.5 break when shot by the player.

state headhitstate

Gets called when player is hurt badly. The screen tilts when the player gets hit and his health is very low.

state burningstate

Set the current actor on fire.

state steamcode

Update steam sprite, subtract health from player who is near, etc.

state random_ooz (Versions 1.4/1.5 Only)

Spawns some ooze.

state burningbarrelcode

Code for a burning barrel.

state getcode

Gets an item and prepares it for respawn (if necessary).

state randgetweapsnds

Plays a random sound when a weapon is picked up by the player. Examples are "Groovy" or "Come get some!".

state getweaponcode

Gets the current weapon and prepares it for respawn if necessary.

state respawnit

Respawn items in a multiplayer game.

state quikget

Get code for the atomic health or other items. Does not cause the sprite to respawn.

state quikweaponget

Get code for weapons.

state firestate

Updates flames, checks to see if Duke is burning himself, etc.

state drop_ammo

Drops ammo if the odds for dropping it are right.

state drop_battery

Drops chaingun ammo if the odds for dropping it are right.

state drop_sgshells

Drops shotgun ammo if the odds for dropping it are right.

state drop_shotgun

Drops shotgun if the odds for dropping it are right.

state drop_chaingun

Drops chaingun if the odds for dropping it are right.

state random_wall_jibs

Spawns blood on the walls when an enemy is shot and near a wall.

state femcode

Takes care of the female actors in the game.

state killme

Lets some women say "kill me" when the player presses the space bar near her.

state tipme

Lets Duke give some women a dollar bill and say "Wanna dance" or "Shake it baby".

state toughgaltalk (Versions 1.4/1.5 Only)

Make the tough girl talk when the player presses [SPACE].

state troop_body_jibs

Spawns some trooper body parts.

state liz_body_jibs

Spawns some lizard body parts.

state standard_pjibs

Spawns some Duke body parts.

state handle_dead_dukes

The code for making blood pools, etc. when Duke dies. Also handles the disappearing for Duke's body in multiplayer.

state check p_standard

Makes the animations of Duke walking when walking, jumping when jumping, etc.

state rf

Changes the cstat to 4 ifrnd 128, else it makes the cstat 0. This is used in flipping corpse sprites so they don't all look the same.

There are too many enemy states to put here, but they all cover the basic artificial intelligence routines for each enemy.

Known Bugs and Problems

• Bug #1: Calling an ai routine (from an actor or state) that is already running, will cancel the ai routine, leaving the actor or state frozen in its code execution. The only known workaround for this bug is to make sure that the ai routine you want to call isn't already running.

• Bug #2: Sometimes con files don't want to compile properly, especially when user code or actors is added. The fix for this is extremely simple: A blank line must appear at the end of every con file that you edit. Some problems can occur with this bug, so it is recommended to check this before compiling your con files.

Special Notes

• Note #1: There are several special actors that can be used with the spawn primitive. These special actors are as follows:

• EXPLOSION2 - When this actor is called for the first time, it will create light, which can be used to create some minor lighting effects.

• FRAMEEFFECT1 - When this actor is spawned, a blurring effect is caused on the affected actor. This is used to make the blurring effect when monsters in the game are shrunk with the shrink ray weapon.

• Note #2: It appears that the "ifhitweapon" primitive must be executed if a weapon is to damage an actor. If it is not, the actor cannot be destroyed.

• Note #3: The "move" primitive seems to cancel any running commands when called. I'm currently not 100% about this fact, but I have heard this rumor several places.

• Note #4: The BLIMP actor uses the "debris" primitive, but it spawns ammunition, inventory items, and weapons instead.

• Note #5: The ATOMICHEALTH actor is the only actor capable of raising the player's health value above MAXPLAYERHEALTH.

• Note #6: Removing an actor's image from the .art files prevents them from being spawned in the game. Tile number 0 (the ugly, brown, brick wall) will be spawned in their place.

LEGAL VALUES

Values for addammo

   KNEE_WEAPON

   PISTOL_WEAPON

   SHOTGUN_WEAPON

   CHAINGUN_WEAPON

   RPG_WEAPON

   HANDBOMB_WEAPON

   SHRINKER_WEAPON

   TRIPBOMB_WEAPON

   DEVISTATOR_WEAPON

   FREEZE_WEAPON

   HANDREMOTE_WEAPON [???]

   GROW_WEAPON [Versions 1.4 and 1.5 Only]

Values for addinventory and ifpinventory

   GET_STEROIDS

   GET_HEATS

   GET_BOOTS

   GET_SHIELD

   GET_SCUBA

   GET_HOLODUKE

   GET_JETPACK

   GET_FIRSTAID

   GET_ACCESS

Values for addweapon

   PISTOL_WEAPON

   SHOTGUN_WEAPON

   CHAINGUN_WEAPON

   RPG_WEAPON

   HANDBOMB_WEAPON

   SHRINKER_WEAPON

   TRIPBOMB_WEAPON

   DEVISTATOR_WEAPON

   FREEZE_WEAPON

   GROW_WEAPON [Versions 1.4 and 1.5 Only]

Values for cstat and cstator

   1 = Make sprite blockable ("B" in BUILD)

   2 = Make sprite 'see-through'

   4 = Flip sprite around x-axis

   8 = Flip sprite around y-axis

   16 = Draw sprite as wall texture (vertically flat)

   32 = Draw him as floor texture (horizontally flat)

   64 = Make sprite one sided

   128 = Half submerged

   256 = Make sprite solid ("H" in BUILD)

   32768 = Invisible

Note: To use more than one setting add the values together (264 = solid (256) + upside-down (8). 256 + 8 = 264).

Values for guts

   JIBS1

   JIBS2

   JIBS3

   JIBS4

   JIBS5

   JIBS6

   HEADJIB/LEGJIB/ARMJIB  (trooper parts)

   LIZMANARM1/LIZMANLEG1  (lizman parts)

   DUKETORSO/DUKELEG/DUKEGUN (duke parts)

Values for ifp

   pstanding    = Duke is standing

   pwalking     = Duke is walking

   prunning     = Duke is running

   pducking     = Duke is ducking

   pfalling     = Duke is falling

   pjumping     = Duke is jumping

   phigher      = Duke is higher than the current actor (?)

   pshrunk      = Duke is has been shrunk

   pjetpack     = Duke is flying with the jetpack

   ponsteroids  = Duke is using his steroids

   ponground    = Duke has his both feet on the ground

   palive       = Duke hasn't died yet

   pdead        = Duke has been killed

   pfacing      = Duke is facing the current actor

Values for ifwasweapon

   KNEE

   SHOTSPARK1 (Pistol, Chaingun, or Shotgun)

   RPG

   SHRINKSPARK

   FREEZEBLAST

   FIRELASER

   SPIT

   RADIUSEXPLOSION (Tripbomb)

   COOLEXPLOSION1

   FIREEXT

   GROWSPARK [Versions 1.4 and 1.5 Only]

Values for shoot

   KNEE

   SHOTSPARK1 (The Pistol)

   SHOTGUN

   CHAINGUN

   RPG

   SHRINKSPARK

   DEVISTATORBLAST

   FREEZEBLAST

   FIRELASER

   SPIT

   BOUNCEMINE

   MORTER

   COOLEXPLOSION1

   BLOODSPLAT1

   BLOODSPLAT2

   BLOODSPLAT3

   BLOODSPLAT4

   GROWSPARK [Versions 1.4 and 1.5 Only]

Values for spritepal

The following is a listing of all the legal values for the spritepal primitive. Palettes can effect 3 different 'layers' of a tile. The easiest way to understand these 3 different 'layers' is by using the stripper sprite. The 3 'layers' are: Background (her skin), Foreground (her clothes), and Minor Foreground (money, accessories, etc).

   0 = Normal

   1 = Blue

   2 = Red

   4 = Black

   5 = All red shades (on all 3 layers) become brown

   6 = Night Vision Green

   7 = Yellow-Green

   8 = Light Green

   10 = Foreground: Red

   11 = Foreground: Light green

   12 = Foreground: Light gray

   13 = Foreground: Dark gray

   14 = Foreground: Dark green

   15 = Foreground: Brown

   16 = Foreground: Dark blue

   17 = Background: Blue, Foreground: Green, Minor Foreground: Blue

   18 = Exact same as 11

   19 = Background: Red, Foreground: Gray, Minor Foreground: Red

   20 = Background: Blue, Foreground: Gray, Minor Foreground: Blue

   21 = Foreground: Red

   22 = Foreground: Light gray

   23 = Foreground: Yellow

   25 = Minor Foreground: Red

Legal Direction Values

• faceplayer: Actor faces the player's current position.

• geth: Actor travels in a horizontal direction.

• getv: Actor travels in a vertical direction.

• randomangle: Actor will change to a random angle when it touches a wall or when the actor is currently being shot at by the player. This direction value can be used with the move command to change the direction of any actor. To do this, use the following in your actor code: move 0 randomangle

• faceplayerslow: Actor faces the player's current position but slower than the regular faceplayer command.

• spin: The actor's angle changes in a clockwise fashion (i.e. - the actor spins clockwise).

• faceplayersmart: The actor will face slightly ahead of the player's current position, making it possible for monsters to "lead" you a little bit.

• fleeenemy: Actor faces directly away from the player.

• jumptoplayer: Actor attempts to jump.

• seekplayer: Actor tries to find and move to the nearest player.

• furthestdir: Actor faces the furthest distance from the closest player.

• dodgebullet: Actor attempts to avoid all shots directed at him.

EXAMPLES

Example 1: Increase Duke Nukem's Health

Difficulty Level: Easy

To start out on the CON editing path, let's do something extremely easy. We are going to increase Duke Nukem's maximum health from 100 to 200. We also need to increase his Atomic Health (we'll take it to 400) so that picking up Atomic Health actually does something!

First, open up the user.con file, and scroll down until you see the following line:

define MAXPLAYERHEALTH 100

Now change that number, so that the line looks like this:

define MAXPLAYERHEALTH 200

Now look for the line that looks like this:

define MAXPLAYERATOMICHEALTH 200

And change it to this:

define MAXPLAYERATOMICHEALTH 400

Now you are finished! Easy huh? Well, we'll now move on to something a little more difficult.

Example 2: Rubber Trash Cans Spawn Health When Destroyed

Difficulty Level: Easy

In this example, we will make the rubber trash can spawn health, but only 50% of the time, when it is destroyed by an explosion.

Open the game.con file and scroll down to these lines of code:

actor RUBBERCAN WEAK

   ifaction RUBCANDENT

   {

     ifactioncount 16

     { 

       strength 0

       action RUBCAN

       break

     }

   }

   else ifhitweapon

   {

     ifwasweapon RADIUSEXPLOSION

     {

       state rats

       ifrnd 48

         spawn BURNING

       debris SCRAP3 12

       killit

     }

     else action RUBCANDENT

   }

enda

We need to add the following lines to the code in order to make the health spawn 50% of the time (instead of the rats).

ifrnd 128 // 50% of the time...

 spawn COLA  // ... spawn the +10% health ...

 killit // ... then delete the trashcan from the map.

else

 (Here we put the rest of the code)

But where do we put this set of code? Well, we first have to find where the code checks to see if the trash can has been hit by an explosion. You see that line that says ifwasweapon? That line of code checks to see if the trashcan was hit by the weapon stated there; the RADIUSEXPLOSION. So we need to place the weapon right in that section of code. The finished product will look like this:

actor RUBBERCAN WEAK

   ifaction RUBCANDENT

   {

     ifactioncount 16

     { 

       strength 0

       action RUBCAN

       break

     }

   }

   else ifhitweapon

   {

     ifwasweapon RADIUSEXPLOSION

     {

       ifrnd 128

       {

         spawn COLA

         killit

       }

       else

       {

         state rats

         ifrnd 128  // See note #1.

           spawn BURNING

         debris SCRAP3 12

         killit

       }

     }

     else action RUBCANDENT

   }

enda

NOTE #1: Notice that we changed the ifrnd statement from 48 to 128. Why did we do that? Well, when you stack ifrnd statements up like they are, the chances of something happening are very small. For example:

ifrnd 128

 ifrnd 128

This statement tells the sub-code to happen only 25% of the time. How did I get that number? Well, the value of 256 is 100%, so the value of 128 is 50%. Then 50% of 50% is 25%. If it sounds confusing, just work through it again and you should pick it up.

Example 3: Booby-trapped Ammunition

Difficulty Level: Intermediate

In this example, we will make chaingun ammo turn deadly - but only for 25% of the time.

Let's take a look at the chaingun ammo code, which can be found in the GAME.CON file:

actor BATTERYAMMO

   fall

   ifmove RESPAWN_ACTOR_FLAG

     state respawnit

   else ifp pshrunk 

     {

     } 

   else ifp palive

     ifpdistl RETRIEVEDISTANCE

       ifcount 6

         ifcanseetarget

          {

            addammo CHAINGUN_WEAPON CHAINGUNAMMOAMOUNT

            quote 63

            ifspawnedby BATTERYAMMO

              state getcode

            else

              state quikget

          }

enda

You see all those if statements there under the second else? That is the area that we want to add our code to. We need to add the following lines to the code, so that 25% of the time, the chaingun ammo explodes.

ifrnd 64 // 25% of the time, the following code should be executed.

{

 hitradius 1024 WEAKEST WEAK MEDIUMSTRENGTH TOUGH  // define the damage

 spawn EXPLOSION2

 debris SCRAP2 2

 sound PIPEBOMB_EXPLODE

 killit

}

else // in other cases, add the ammo amount to the player.

{

 addammo CHAINGUN_WEAPON CHAINGUNAMMOAMOUNT

 quote 63

 ifspawnedby BATTERYAMMO

   state getcode

 else

   state quikget

}

So let's add our code to the ammunition. This is what the final product will look like:

actor BATTERYAMMO

   fall

   ifmove RESPAWN_ACTOR_FLAG

     state respawnit

   else ifp pshrunk 

     {

     } 

   else ifp palive

     ifpdistl RETRIEVEDISTANCE

       ifcount 6

         ifcanseetarget

           ifrnd 64

           {

             hitradius 1024 WEAKEST WEAK MEDIUMSTRENGTH TOUGH

             spawn EXPLOSION2

             debris SCRAP2 2

             sound PIPEBOMB_EXPLODE

             killit

           }

           else

           {

             addammo CHAINGUN_WEAPON CHAINGUNAMMOAMOUNT

             quote 63

             ifspawnedby BATTERYAMMO

               state getcode

             else

               state quikget

           }

enda

Now, when you go into the game, every 25% (or roughly) of the time you should get hurt by an explosion. Cool way to make booby-traps, huh?

Example 4: Break the "Unbreakable" Plate (Versions 1.4/1.5 Only)

Difficulty Level: Intermediate

If you have ever played through Duke Nukem, you should hopefully have noticed the "unbreakable" plate in the sushi bar (episode 3, level 1). There is one plate the 3D Realms forgot about coding, and so it cannot be broken like the others can. What better a mistake for us to fix!

This coding session will only work with versions 1.4 or 1.5 of Duke Nukem 3D, because we will need to make use of the "useractor" function.

The plate that is in question is in slot #851 (you can take a look at it in Build or Editart). To make this slot an actor, we first need to define it in the defs.con file. Open up the defs.con file, and place the following line somewhere in this file:

define SUSHIPLATE99 851

I prefer putting these types of lines in order of appearance by tile number, much like 3D Realms did. Scroll down to the lines that say:

define MASKWALL13 830

define HURTRAIL 859

and put our define statement between the two lines that are there (because 851 is between 830 and 859).

Now save your work and close this file.

Now open the game.con file and place the following lines of code anywhere in the file:

useractor notenemy SUSHIPLATE99 WEAK // define it as a useractor

 ifhitweapon

 {

   lotsofglass 7

   sound GLASS_BREAKING 

   killit

 }

enda

Now, when you enter into the game, you can shoot the plate and it will break! Yay! We just fixed a bug in Duke Nukem 3D!

Example 5: Make Duke eat some food (Versions 1.4/1.5 only)

Difficulty Level: Intermediate

In this example, we are going to make use of the food that appears in a few of the levels in Episode 4 (Versions 1.4 and 1.5 only). We will make Duke eat the food when he is near enough to it, and we will add 10 health points to his health when he eats it. We also will make him say "Ooh, I needed that!" when his health is below 20.

First, open up the user.con file, and scroll down to the line that says:

definequote 124 MAP HAS A DIFFERENT NUMBER OF PLAYERS

This is the last quote defined by 3D Realms, so we will make 2 new quotes to print. Add these lines right below the definequote 124:

definequote 125 YOU EAT SOME FOOD: +10 HEALTH!

definequote 126 YOU AREN'T HUNGRY NOW...

We will use these quotes when we add code to the game.con file. Save your work and close user.con.

First we need to make a state function. Open the game.con file and put the following lines of code at the top of the file:

state eatfood

 ifp pfacing

   ifpdistl 1280

     ifhitspace

     {

       ifphealthl 20

       {

         addphealth 10

         globalsound DUKE_NEED

         quote 125

         killit

       }

       else

       {

         ifphealthl MAXPLAYERHEALTH

         {

           addphealth 10

           quote 125

           globalsound DUKE_GET

           killit

         }

         else

         {

           quote 126

           break

         }

       }

     }

ends

Now we need to find where the actors are located. Scroll down to the line that says:

useractor notenemy FOODOBJECT11 WEAK state breakobject enda

and change it to look like this:

useractor notenemy FOODOBJECT11 WEAK

 state breakobject

 state eatfood

enda

This now allows our state function to work on FOODOBJECT11. But we want to change 12 through 20 as well. So just make each useractor that we want to change look just like the useractor above. Example:

useractor notenemy FOODOBJECT12 WEAK // We change # 12 now...

 state breakobject

 state eatfood

enda

Save your work, and when you go into the game, you will find that you can now press space near the food and you will gain 10 health points if you are below 100!

A GENERAL CON OVERVIEW

DEFS.CON

This con file is the file where all basic definitions are made. Definitions for sounds, actors (sprites), and some other miscellaneous items can be found in this file. This file is included by the game.con at compile time (when the game is run).

USER.CON

This con file is one of the easiest to edit. Parameters such as weapon strengths, health values, ammo values, level names, quotes, names of sounds, names of episodes (version 1.4 and 1.5 only), names of difficulty levels (version 1.4 and 1.5 only), and more exist in this con file. This is a fun con to edit, especially if you never wish to get deeply involved into con editing and hacking. This file is also included by the game.con at compile time (when the game is run).

GAME.CON

This con file is the largest and the most complicated con file to edit. This file holds all the code for most actors in the game (some of the actors are hard coded). Most of the primitives available are used in this con file, and things can get quite complicated if you don't know where to start. This file gets compiled first at compile time, and includes (#include) the other two con files provided by 3D Realms. This is the con file to work with if you seriously want to get into con editing and hacking.

FAQ INFORMATION

About the Authors and General Information

This FAQ was written by Joris Weimar, an avid Duke Nukem 3D FAQ, and a talented con file programmer. Also working on this FAQ is myself, Jonah Bishop. I also run the Map Editing FAQ for Duke Nukem 3D and Shadow Warrior. If you have any questions, tips, corrections or comments about con files or this FAQ, visit the Duke Nukem 3D Editing and Hacking forum at Dukeworld.

Dukeworld --- http://www.dukeworld.com

Credits and Contributors

This FAQ would not be what it is today without the following people (who made suggestions and pointed out various errors):

- James Tan (ctan@xtra.co.nz)

Provided most of the new and updated information for version 4.2.

- TerminX (terminx@theoffspring.net)

For providing the updated information on the "endofgame" primitive

- The Reaper (lrdmecha@yahoo.com)

For clearing up all of the version validity problems with the predefined state functions.

- Snowblind (snowblind@brasnet.org)

For letting me know about the missing palette values

- Garry Cobbum (gcobbum@sbinet.com)

For finding several errors and for giving several suggestions

- James Ferry (sweepy@playful.com)

For the tons of information he allowed me to use. Visit his site at http://members.xoom.com/HCAD

- Joe Barta (jbarta@apk.net)

For finding more errors than can be named

- Matthew Hill (gambit@proteus.globalnet.co.uk)

For donating the correct "palfrom" primitive parameters

- Gavin Lambert (uecasm@geocities.com)

For finding an error in the "mikesnd" primitive and for clearing up the usage of the "ifinouterspace" primitive

- Reptile (reptile@worldaccess.nl)

- Linkers (linkers@dds.nl)