Con Editing Information v1.3

This document includes D3D v1.3D information, which is relevent to later versions, it does not however contain material relevent only to v1.4 and/or v1.5.

If at all possible, use the WYSIWYG version (RTF), that is if you download it.

This file has been tested using:

MSIE 4.0

Netscape 4.1

© James Ferry, 10th February 1999

http://

(mind the capitals at the end, it is case sensitive)

Contents

Introduction


Part One: Con files

Part Two: Printing

Part Three: Internal functions

1 Listing

2 Details

• 
  

  Part Four: Directions
  

  Part Five: Weapons
  

  Part Six: Interesting notes
  

  Part Seven: The if structure

^ Introduction

This document was written to clear up any misinformation from other sources regarding this subject. No diagrams were included, as they display differently in different programs.

The topics may not be ordered very well, but it suffices, and it will provide you with all the information that you need to edit the con files in Duke Nukem 3D v1.3D. These commands should still be in v1.4/v1.5, although there are also newer commands included in v1.4/v1.5. I am not sure what version, and how compatible the Macintosh versions are.

^ 1 Con files

The con files are files that can be modified by the user to change the way the program behaves. These don't have to be con files, they can be any name that you want them to be, it is just that the default name is game.con, which is where the name came from.

You may be wondering why you would want to modify/rewrite the con files, the answer might be you don't want to, another would be don't bother, and one more would be why not?.

Con editing can be useful just to change some of the values in D3D to make it a bit more fun, or just when you get bored, or if you need a few modifications to make some map you made just that bit more like how you wanted it to be. The other reason is when for larger projects such as total conversions (TC from here on). Many people/groups try to pass off a bunch of maps with some new graphics and some minor changes to the original con files as a TC, but all it is just a map package. A proper TC should consist of major overhauls to the game. Even if there are no new maps, and barely any or graphics changes at all, as long as there is major changes in the game play, done via the con editing, it will become a TC. On the other hand, a package containing many maps and lots of new graphics, while using no or barely any con editing, would not really be a TC, it would be more of a patch for D3D.

^ 2 Printing

In case you want to print this document out, you might want to remove the page breaks, and make the margins smaller, and maybe remove/shrink the header/footer so that you don't use as much paper. Double sided printing helps. If you are using a laser printer or some other large/heated printer, don't feed the paper back into the machine, as they may jam if a fresh print is feed back into it, similar to photocopiers, because the paper can curl, and will not feed correctly through the machine.

Unfortunately, because different viewers/editors may have different page sizes, pagination is very difficult, so some of the tables and information will cross over to the next page.

^ 3 Internal functions

Listing 3.1

Details 3.2

^ 3.1 Listing

This list of functions is directly extracted from duke3d.exe.

^ 3.2 Details

Firstly, the format for the parameters of some of these functions, is as follows.

Square brackets ( [ ] ) represent optional parameters.

Braces represent ( { } ) optionally repeated parameters.

The pipe ( | ) represents an or between the previous and next set of parameters.

Some explanations on structures are written in pseudo code and C code.

I have tried to make the function names bold and the function parameters italic.

^ //, /* and */

Standard C style comments.

These commenting symbols can not be adjacent to other letters, otherwise they will be considered names of handles and functions.

ie; resetplayer // Return player to starting point

will work, but

resetplayer //Return player to starting point

will fail.

^ { and }

Standard C style function operators.

Separate different objects in a function. Similar to C/C++ and Pascal. It pretty much makes whatever is between them get treated like one function by anything outside the braces.

These are restricted to the same problems that the comments are.

^ action

External

action name [ relative [ frame face increment delay ]]

Defines the action/animation/image to the handle name.

With no parameters, it will create a still image of the current actors first frame. This is the equivalent of action name 0. If relative is given a number, it will set the first frame/still image to a relative tile from the current actor. e.g.; if the current actor is 1405, and the action's relative parameter is, let's say, -100, when called, the animation/image will start from tile 1305.

The parameter frame defines the number of frames are in the animation (set it to 0 if there are none).

The parameter face sets the number of directions that the images appear from when not a wall or floor sprite

Valid values are: (all angles are viewed from above)

The images for the faces must be consecutive tiles following the first image of each frame.

The parameter increment is the value that is added to the current image in an animation that will move it to the next image.

The parameter delay is the amount of time that each image will pause/wait for before incrementing.

I am not sure about the timing, it could be a value of 128 is one second, or a value of 64, or a value of 100. Trial and error.

Internal

action name

Starts the action/animation/image identified by a predefined handle name.

^ actor name [ strength [ action [ movement | speedxy [ speedz ] [ { directions } ] ] ] ]

Creates the code for an actor.

Parameter name is a handle/number for the actor. If a handle is used, it is a definition of a number (or the number is it's definition, either way).

Parameter strength defines the strength that the actor will start at, unless it is created with cactor, where this parameter and the following are ignored.

The parameter action sets the actor's initial action to the predefined action given by the handle.

The parameter movement | speedxy [ speedz ] [ { directions } ] sets the actor's initial movement to either the predefined handle movement, or to a velocity of speedxy along the ground (horizontal plane/x-y vector), with the optional speedz for velocity in the vertical direction (up and down/z vector) and the optional directions (see the Directions section)

This should be ended with an enda function.

^ addammo weapon amount

Add the value of amount to the current player's, or the closest player's, ammunition level for the weapon given by weapon. This will call a break if the ammunition level is full.

^ addinventory item amount

Either sets or adds the value of amount to the current player's, or the closest player's, inventory level for the item given by item. See the following for details

^ addkill

Adds 1 to the nearest players kill count..

^ addphealth param

Adds the value of param to the current player's, or the closest player's, health level.

^ addweapon weapon amount

Add the weapon given by weapon with the ammunition of amount to the current player's, or the closest player's, ammunition level. This will call a break if the ammunition level is full.

Look at the weapon section for more details.

^ ai

External

ai name action movement directions { directions }

Creates a new AI called name which uses the animation/action called action. The AI uses the parameter movement for its velocity, and its direction is set by the parameters directions (see the Directions section).

Internal

ai name

Makes the AI name the current actor's current AI.

^ betaname

I have no idea.

^ break

Stops processing code in the current actor or state.

^ cactor name

Change the current actor to the actor defined by name. This will use the current strength, movement, palette, size, action, and AI of the original actor, and ignore any of the initialization values of the new actor.

^ count param

Sets the current actors count to param.

^ cstat param

Changes the current status of the actor to that of param. This uses a 16 bit, unsigned integer value for param. To select multiple values, just add the values together. Look at the following for details.

^ debris actor amount

Creates amount pieces of flying debris in the form of actor. The actors that I know that can be used are as follows.

^ debug param

Prints the value of param to the output buffer.

If a standard game is loaded, with the default output buffer being used, it will print the value to the screen.

If output buffer is changed, e.g.; the command line of

"duke3d.exe -map test.map /q8 > test.log"

will change the output buffer to test.log, then the standard output will be sent to the new output buffer. If this is a file, then the file can be opened and read later, if it is a printer, it will be printed out etc..

^ define handle value

Defines the handle with the definition of the number given by value. This is a useful way of referencing the actor and values s by a descriptive name instead of by their number.

This is called externally.

^ definelevelname episode level map time1 time2 name

Parameter episode is the episode number that the map should be in (0 for the first episode, 1 for the second and 2 for the third).

Parameter level is the level number that the map should take (0 for the first level, 1 for the second and so on).

Parameter map is the file name of the map that you wish to use. This can not be more than thirteen characters - ie; eight characters for the name, a full stop, and the three character extension.

Parameter time1 is the par time. This can not exceed five characters (it uses the format of mm:ss, where mm is minutes and ss is seconds).

Parameter time2 is 3D Realms time. This can not exceed five characters (it uses the format of mm:ss, where mm is minutes and ss is seconds).

Parameter name is a null terminated string that contains the name of the level that you wish to use. This can not be greater than 32 characters in length.

This is called externally.

^ definequote value string

Changes the definition of the string referenced by value to that of the null terminated string given by string. This can be later called with the quote function to display the text on the players screen if they have messages enabled.

This is called externally.

^ definesound value file pitch1 pitch2 priority type volume

Defines the sound value with the following parameters.

file is a VOC (voice) or WAV (wave) file that the program will attempt to find to use for the sound.

I found that 8bit, 8000hz MONO sounds will work happily.

pitch1 and pitch2 are random pitch variations. These are signed (negative and positive).

priority sets the importance (the preferance of sounds if to many are available). It seems to be the higher the number the more important the sound. It also seems to be a 1 byte, unsigned number (0 to 255 inclusive).

type is the type of sound it is in the game - I can't be sure what the value mean, but they follow a pattern. Trial and error.

volume is the adjustment on the sound leve/volume/loudness that the sound should use. A negative number means louder, a positive number means softer. This seems to be a signed integer (-32767 to 32767 inclusive).

This is called externally.

^ else

Returns true if the last function returned false.

^ enda

Closes an actor function.

^ endofgame param

Ends the current volume. I am not sure what param should be, but the original con files use 52, and I use 51. Trial and error.

^ ends

Closes a state function

^ fall

Accelerates the actor downwards.

^ gamestartup

default_visibility - visibility of the game

generic_impact_damage - I have no idea

maximum_player_health_and_armour_level - maximum level of health and armour

start_armour_health - initial armour level

respawn_actor_time - time for an actor to respawn

respawn_item_time - time for an item to respawn

running_speed - speed that the player will run at, default is 53200, too high a value will cause the player to keep on sliding

rpg_blast_radius - blast radius of the RPG

pipebomb_blast_radius - blast radius of the pipebomb

shrinker_blast_radius - blast radius of the shrinker

tripbomb_blast_radius - blast radius of the tripbomb

morter_blast_radius - blast radius of the morters

bounce_mine_blast_radius - blast radius of the magnetic mine (sea mine)

seenine_blast_radius - blast radius of the C9 canisters

pistol_ammo - maximum ammunition of the pistol

shotgun_ammo - maximum ammunition of the shotgun

chaingun_ammo - maximum ammunition of the chaingun

rpg_ammo - maximum ammunition of the rpg

handbomb_ammo - maximum amount of pipebombs

shrinker_ammo - maximum ammunition of the shrinker

devistator_ammo - maximum ammunition of the devistator

tripbomb_ammo - maximum amount of tripbombs

freezer_ammo - maximum ammunition of the freezer

destructable_cameras - set to 1 if you wish security cameras to be destructable, or 0 if not

number_of_freeze_bounces - a value of 0 to 255 inclusive. This defines how many paths a blast from a freezer can follow. 0 means it doesn't go anywhere, 1 means it will last until it hits a wall or object, 2 means it will bounce once, 3 (default) will bounce twice, and so on.

freezer_hurt_owner - set to 1 if the freezer can hurt it's owner/thing that fired it, 0 if not

This function sets the initial values for the game, they can not be changed after they have been set.

This is called externally.

^ getlastpal

Changes the current actors palette back to its previous palette

^ globalsound param

Plays the sound param so that it can be heard at the same volume everywhere on the map.

^ guts param value

The current actor will create value amount of the actor param. It will normally spawn an actor, but in certain cases, they will use special effects instead. The actors that I know of are as follows.

^ hitradius rad max third half first

Makes the actor/weapon 1670 (RADIUSEXPLOSION) with a maximum radius of rad, using strength defined by the following four parameters.

The parameter max is the strength that will be used in the outermost quater (area) of the circle, ie; between the radius of 3*rad/4 and rad.

The parameter third is the strength that will be used in the second outermost quater (area) of the circle, ie; between the radius of rad/2 and 3*rad/4.

The parameter half is the strength that will be used in the second quater (area) of the circle, ie; between the radius of rad/4 and rad/2.

The parameter first is the strength that will be used in the first quater (area) of the circle, ie; between the centre/origin of the circle and rad/2.

^ ifaction name

Returns true if the current actor is using the action defined as name.

^ ifactioncount value

Returns true if the current animation has reached the frame number value.

^ ifactor value

Returns true if the current actor is the actor value.

^ ifactornotstayput

Returns true if the current actor has been activated. To activate an actor, it either activates immediately (such as 487 and 489) or it waits until it is spotted by, or has spotted the player.

^ ifai name

Returns true if the current actor is using the ai defined as name.

^ ifawayfromwall

Seems to return true when ever the current actor exists in two sectors at once, such as the boundary between two sectors, like the shore of a water sector, and a dry sector, or on the boundary of a two sectors joining at a ceiling and floor, such as the surface of two water sectors, one sector being above the surface, and the other below.

^ ifbulletnear

Seems to return true if there is a bullet or other projectile (that uses impact damage) near the current actor.

^ ifcansee

Seems to returns true if the current actor can see its target.

^ ifcanseetarget

Seems to returns true if the current actor can see its target. The target seems to be the player.

^ ifcanshoottarget

Seem to returns true if the current actor can shoot its target. The target seems to be the player.

^ ifceilingdistl param

Returns true if the distance between the current actor's centre and the ceiling is less than param.

^ ifcount param

Returns true if the current actor's local counter has reached param counts.

^ ifdead

Returns true if the current actor is dead. As far as I remember, the actor must have started with some strength to become dead. It sometimes seemed to also need to have ifhitweapon called before this function was called to work.

^ iffloordistl param

Returns true if the distance between the current actor's centre and the floor is less than param.

^ ifgapzl param

Returns true if the distance between the floor and ceiling of the current actor's location is less than param.

^ ifgotweaponce param

If param is set to 0, in multiplayer settings of cooperative and dukematch with no spawn, it will only let the player retrieve the weapon if they don't already have it.

If param is set to 1, in multiplayer settings of cooperative and dukematch with no spawn, the player may not retrieve it.

^ ifhitspace

Tests if the player (if it is the player actor (1405|APLAYER)) or the nearest player (if it is any other actor) is pressing the use key. The default key is the space bar.

^ ifhitweapon

Returns true if the current actor has been hit by some weapon. This does not check which weapon it was.

Look at the weapon section for more details.

^ ifinouterspace

Returns true if the actor is in a sector with a parallaxed, outer space (84-89 inclusive) texture surface. Not quite sure. Trial and error.

^ ifinspace

Returns true if the actor is in a sector with a parallaxed, space (80-89 inclusive) texture surface. Not quite sure. Trial and error.

^ ifinwater

Returns true if the actor is in a sector with a lotag of 2.

^ ifmove param

Returns true if the current actor is using the movement defined by param or was set with the same value as param.

^ ifmultiplayer

Returns true if it is a cooperative game.

^ ifnotmoving

Returns true if the current actor has stopped moving.

^ ifonwater

Returns true if the actor is in a sector with a lotag of 1 and is on/near the surface.

^ ifoutside

Returns true if the actor is in a sector with a parallaxed surface.

^ ifp { param }

Returns true if any of the parameters param are true.

^ ifpdistl value

Returns true if the closest player's distance to the current actor is less than value.

^ ifpdistg value

Returns true if the closest player's distance to the current actor is greater than value.

^ ifphealthl value

Returns true if the current player's, or the closest player's health is less than or equal to value.

^ ifpinventory param value

This is a function that is commonly misdiscribed, where it is thought of as "return true if inventory param is less than value. This is incorrect.

This real use of this function is as follows.

param is the inventory item that is to be tested. To test the access cards, the current actor has to be the same palette as the access card that you wish to test. 0 for blue, 21 for red, and 23 for yellow, the same as giving the player a coloured access card.

value is the amount to test.

The function will return true when the inventory param is not equal to the amount value.

It does not test a less than, it tests a not equal to.

In the original con files, you can't tell this as it appears to be a test if it is less than, but it is really testing a not equal to.

If you want to test if the player has a given amount of inventory, then you can use the following code.

ifpinventory param value { } else { Enter the code if that you want here }

The following is an example, that was pulled out of NW3TC v1.3. The TC also contains many other longer example of this type of function (about 1000 lines or so), to control the flame-thrower's fuel, the credit clips, and the buying/purchasing, as well as the persuading. This is the code for the blue flag in capture the flag games, that checks whether the player is the other team (gives them the red flag) or its own team (takes the red flag away). The sections that are not necessary have been removed.

ifpdistl FLAG_CAPTURE_DIST ifhitspace // close enough and hitting space

{

ifpinventory GET_FIRSTAID 2 { } else // is the team red

{ addinventory GET_FIRSTAID 4 quote 163 } // if so, give flag

ifpinventory GET_FIRSTAID 3 { } else // is the team blue and has flag

{

addinventory GET_FIRSTAID 1 // take the red flag away

quote 164 // and tell them they have scored

}

}

^ ifrespawn

Seems to test that if the actor calling the function is an item, and the item respawning is enabled, it will return true, r if it is an AI actor, and monster respawn is enabled, it will also return true, otherwise it will return false.

^ ifrnd param

Has a param in 256 (param/256) chance of returning true. Use this for random events.

^ ifspawnedby value

Returns true if the current actor was spawned by an actor of type value.

^ ifspritepal value

Returns true if the actor's current palette is that of value.

^ ifsquished

Returns true if the actor has been squished by being shrunken in size and too close to another actor, by being in a space to small exist in, teleporting to a killer shaped sector, or in a squishing sector.

^ ifstrength value

Returns true if the current actor has value amount or less strength left.

^ ifwasweapon param

Returns true if the current actor has been hit by the weapon param. It is best to call this after ifhitweapon, to let it function properly

Look at the weapon section for more details.

^ include file

Includes the contents of the file file into the location where this function is called when it is being compiled.

^ killit

"Kills" the current actor. Removes the actor from the game.

^ lotsofglass value

The actor creates value amount of glass pieces, like that of a shattered glass pane.

^ mikesnd

"Plays the sound assigned to the microphone sprite in Build (the microphone sprite's hitag is the sound number to be played)."

This was from The Duke Nukem 3D Con Editing FAQ. I haven't used this yet.

^ money number

The actor will drop number amount of notes (money), which will float to the ground.

^ move

External

move movement [ speedxy [ speedz ] ]

Assignes the handle movement the horizontal velocity speedxy and the vertical velocity speedz.

Internal

move movement | [ speedxy [ speedz ] ] [ { directions } ]

Activates either the the handle movement or the the horizontal velocity speedxy with the vertical velocity speedz, using the optional directions if available. (see the Directions section)

^ music param { file }

Sets the MIDI music for the game.

param sets the location of the file (into/ending/volume number).

file sets the MID (MIDI) file that is to be used.

If param is 0, then the first file it comes across will be the introduction music, the second file will be the ending/closing music.

If param is 1, then it will define the music for volume 1, if it is 2, then for volume 2, and if it is 3, it will set the music for volume 3.

if param is 1,2 or 3, then the parameters of file that it comes across will be used for each level starting from level 1 of the current volume and increase with each new file.

^ operate

When this function is called, if a door is close enough to the current actor, it will open. This seems to work on swinging doors only.

^ palfrom [ intensity [ red [ green [ blue ] ] ] ]

The current screen palette of the current player, or closest player, will start from the palette with the parameters of red, green, and blue mixed in with an intensity of parameter intensity, and drop one level of intensity per count. The default values of each parameter is 0. For maximum colour or intensity, use 64. Using a negative number is treated as 0, using a number greater than 64 can be used for special effects as the palette spills into another region.

^ pkick

The current player, or the closest player, will do a quick kick.

^ pstomp

The current players, or the nearest player view will swing down, and the nearest actor will be squished. The player's view will then swing back to normal again.

^ quote value

The function will output the quote already defined by value on the players view. definequote is used to define the string to the value.

^ resetactioncount

Sets the action counter to 0.

^ resetcount

Sets the actor's local counter to 0.

^ resetplayer

In multiplayer games, it will return the player to a starting location, give them the default weaponry, the starting amour level, and the starting health level, and then lets them run around again.

In single player games, it will restart the map.

^ respawnhitag

This function will activate any 9 (RESPAWN) actors who have the same lotag as the current actor's hitag.

^ shoot param

Shoots/fires/ejects the projectile/shootable item given by param.

Look at the weapon information at the top of this file for more details.

^ sizeto x y

Change the size to x,y over a period of time. I think it changes it to x,y, it may be relative though. Trial and error.

^ sound param

Plays the sound param as a local sound.

^ soundonce param

Plays the sound param as a local sound, but it will can be played again until it has finished.

^ spawn value

Creates the actor with number value.

^ spritepal value

Changes the current actors image palette to that of the palette value.

^ state handle

External

Creates a function called handle, that can contain more information. This has to be closed with the ends function.

Internal

Calls the predifined state called handle, it is just treated as a function.

^ stopsound param

Stops the sound param from playing.

^ strength value

Changes the current actors strength to that of value.

^ tip

Starts the current player's, or the closest player's, animation routine.

^ wackplayer

Tilts the players viewpoint (tilts their head).

^ 4 Directions

The actor seems to see if it will end in a water sector at the end of its movement, and if so, it will treat the boundry of the water and the dry sector as a wall. It can be useful to stop them from walking into the water. It might also stop them from jumping into the water, but I am not sure.

^ 5 Weapons

number is the tile/actor number, name is the original name assigned to the actor, shoot refers to if the actor is able to be created using the shoot funtion, hit refers to if the weapon can be tested with ifwasweapon, strength refers to if the actor has a strength value or not. The actors strength is the amount of damage that it will cause. Asterixes mean that the note should be used, otherwise the note is a general note about the actor.

The second table is the listing for the players weapon inventory.

^ 6 Interesting notes

Actor 1890 (EXPLOSION2) has a very interesting effect. When it is created, on it's very first count it will produce light. This can be used to create lighting effects. This is just one of the actors that has a very useful effect that is worth pointing out.

If actor 3400 (BLIMP) uses the debris funtion, it will through out the weaponry, ammunition and inventory actors instead of the debris actors.

If actor 100 (ATOMICHEALTH) uses the addphealth function, it is able to raise the health above the players normal health limit.

When actor 3999 (FRAMEEFFECT1) is spawned, it will take the image of the actor that spawned hit, and then disappear. This can be used to make a blurred image.

If you remove an actors image from the art file, they can not be spawned, and BUILD will replace them with actor 0 (the brick wall). I am not sure what happens if you remove the brick wall though.

Removing the defines from your confiles and replacing all the names with their corresponding numbers will increase the loading time of D3D. The pauses during loading are from either loading the multimedia drivers, reading the definitions, and any external factor such as pressing pause, or the hard drive/cdrom/modem working over time in the background.

^ 7 The if structure

This is a discription of the structure of the if statments. This derived from what was is commonly thought to be a big bug, but proves that if you had any idea of programming or simple logic (what women say we men have none of) you could clearly see that it is correct.

The misconception is that people think a statement such as

ifcansee

ifai AIDUKEWANTTOSTOMP { }

else ai AIDUKEWANTTOSTOMP

is a bug because they think that it should be equal to

ifcansee

{

ifai AIDUKEWANTTOSTOMP { }

else ai AIDUKEWANTTOSTOMP

}

The misconception in this is that these are two different structures. These are not the same because if you no how these functions work in conjunction with each other, you will find that two consequetive if statements are equal to an if-and-if statement,

ie: "if this is true and if that is true"

In pseudo code the first structure is

IF cansee AND IF ai is AIDUKEWANTTOSTOMP

do nothing

ELSE

ai AIDUKEWANTTOSTOMP

ENDIF

and in C it would be

if(!cansee||ai!=AIDUKEWANTTOSTOMP)

ai=AIDUKEWANTTOSTOMP;

When writing the con files, it would be better to write the first structure as follows

ifcansee ifai AIDUKEWANTTOSTOMP { }

else ai AIDUKEWANTTOSTOMP

The second structure in pseudo code is actually

IF cansee

IF ai is AIDUKEWANTTOSTOMP

do nothing

ELSE

ai AIDUKEWANTTOSTOMP

ENDIF

ENDIF

and in C it is

if(cansee)

if(ai!=AIDUKEWANTTOSTOMP)

ai=AIDUKEWANTTOSTOMP;

This structuring of the if statement is not incorrect.