Introduction | define | definequote | definelevelname | music | definesound | Sound Table

The following information pertains to any BUILD game using Todd Replogle's CON Scripts. Individual differences may be indicated.

The USER.CON is used by novice hackers, its a great place to start. It contains most of the variables and parameters that define the characteristics of the weapons, player health, strengths of actors, sound fFX and system messages,  thus 'USER CONtrol'

There are 5 major types of lines(primitives) in the USER.CON:  define,  definequote,   definelevelname,  music  and  definesound.

"define" <name> to be <num>.  Basically it allows you to use the supplied name instead of handling digits all the time, they provide substitution. Defines are ubiquitous; almost everything in the .CON files are really a number, but is DEFINEd as a common name, simply because coding in numbers can become a hassle. Either way the game will compile the code into numbers regardless. Changing one value is allot easier than replacing many.

The format of a definequote line is:

define #NAME #NUM

  The following example sets the string MAXPLAYERHEALTH to the value of 100.

Ex: define MAXPLAYERHEALTH 100

2nd Ex:  If you have a line somewhere in your USER.CON that said:

define STARTARMORHEALTH 30

Then anytime after that, if the word "STARTARMORHEALTH" appears in the code, the value 30 is substituted in its place. This method of subsition makes it helpful later on, when your writing actor code(A.I.) or other large coding projects.

Most of the 'variables' you can define are very usefull for the beginner to tinker with.  Such as defining new values for Dukes/Player starting and maximum health, armor amount, ammo per clip picked up, how much ammo is allowed for each weapon, how much damage each weapon does per hit, etc, etc... In Dukev1.5, NAM, WWIIGI there are additional variables that can be change to even allow further control of the game. You can even define a define with an exsisting define.

define MAXPLAYERATOMICHEALTH 200 // doubles as maxarmor.
define DOUBLEMAXPLAYERHEALTH MAXPLAYERATOMICHEALTH

Don't get to cocky, you can't change these values and then go play your friend online and kick his arse, you both must have the same CONs or the game will eventual become corrupted, out of sync.  Also changing values for the shotgun and pistol also effect the pigcops and any enemy that has a pistol(SHOTSPARK1.)

Some of the unusual, complicated and new defines explained:

• define YELLHURTSOUNDSTRENGTH 40 // This means at 40 Health playback a specific sound.
• define YELLHURTSOUNDSTRENGTHMP 50 // This means at 50 Health during a multiplayer game playback a specific sound.
• define MAXXSTRETCH 70 // added in v1.4 - Stretch dimensions when using the new Expander Weapon.
• define MAXYSTRETCH 70 // added in v1.4
• define MINXSTRETCH 9 // added in v1.4
• define MINYSTRETCH 8 // added in v1.4
• define RETRIEVEDISTANCE 844 // All Distances are measured by BUILD Editor Units.
• define SQUISHABLEDISTANCE 1024 // For actors only!
• define DEFAULTVISIBILITY 512  // How far away the game will start to remove light / increase darkness.
• define FROZENQUICKKICKDIST 980 // This distance is for the automatic kick, how close you have to be in order for autoquickkick to engage.
• define GENERICIMPACTDAMAGE 10  // not a clue as to its precise results, still testing.
• define TRIPBOMBLASERMODE 0 // New to v1.4; most of these new settings could be simulated with editart, But Flag #2 is the key feature.
  // 0 = always visible
  // 1 = translucence
  // 2 = invisible w/o IR goggles
  // 3 = totally invisible
• define QSIZE 64 // New to v1.4; total number of active, bullet holes, blood, footprints, money, essentially any sprites that use the 'Minor Particle Engine'(max 1024)
• define RUNNINGSPEED 53200 // ?need to review scale?
• define GRAVITATIONALCONSTANT 176  // The amount of gravity that is pulling, the strength of motion pulling down. ?need to review scale?
• ...add more...

Want even more information, See the DEF.CONs and Primitives Documents.

"definequote" lines define the different phrases 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 some ammo or an inventory item, what words will appear when you adjust game options etc.. etc...

The format of a definequote line is:

definequote #NUM $QUOTE

"definequote" lines have two arguments: a <num> and a <quote>. The number is what you use to refer to the quote by later on when called(externally), instead of typing the same string again and again. For an example, the line:

Ex: definequote 101 NIGHT  I.R. GOGGLES!

// Defines quote number 101 as "NIGHT  I.R. GOGGLES!" You can use upto 64 characters for each assigned phrase.

This method of calling quotes by number is ideal for similiar reasons mentioned in 'define' above. It is possibly how ever to actual type a phrase into the code that your scripting, without calling upon one of the defined quotes.

The two arguments: <quotenum> and <quote> are defined to be equal. 

Note: In Duke v1.5 you can have a maxium of 192 slots.

"definelevelname" Is used to define the episode, level number, map file name, level par, record times and level names for each level. This is typicaly handled in the user.con for organization.  This is called externally within the cons.

The format of a definelevelname line is:

definelevelname #EPISODE #LEVEL $MAPNAME #LEVELPAR #RECORD $LEVELNAME

<episode> is the episode number that the map<level> is in (0 for the first episode, 1 for the second and 2 for the third...)
The episode numbers starts off at zero. Episode 1 in the game is actually #0 in the CON file. Thus episode 7 in the game is actualy #6 in the CON file.

<level> is the level number that the map<mapname> should take (0 for the first level, 1 for the second and so on).
The level numbers starts off at zero. Level 1 in the game is actually #0 in the CON file. Thus Level 5 in the game is actualy #4 in the CON file.

<mapname> is the file name of the map that you wish to use. The map file name cannot exceed 13 characters(?128 in DN3D v1.5) - ie;  xxxxxxxx.xxx eight characters for the name, one for the period, and the three character file extension.

<levelpar> is the general par time for the level. Level par cannot exceed 5 characters including the ' : '
(mn:sc) mn is minutes and sc is seconds. For good practice always pad the par times with a leading 0 if your using single digits.

<record> is the goal par time for the level. The goal par cannot exceed 5 characters including the ' : '
(mn:sc) mn is minutes and sc is seconds. For good practice always pad the record times with a leading 0 if your using single digits.

<levelname> is a null(no value, but present) terminated string  that contains the name of the level that you wish to use. Typicaly something that relates to the filename. The string cannot exceed 32 characters in length.

Take this example, Episode 1, Level 5 is "The Abyss." The map of this level is in the file E1L5.map(which is contained in the master .grp file.)  The par time is 9 minutes, 10 seconds, and the record time is 5 minutes flat. Its definelevelname entry looks like this:

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

As you see, you must subtract one from the actual episode and level numbers. Very important.

"music" lines define which .MID (midi) file to play for each level. There are two formats of a music line:

Please note the following information are basic steps,

The format of a music line for the Title Song and the Ending Song. (Yes, GRABBAG.MID is the Duke3D Theme)

music 0 $TITLEFILE $ENDINGFILE

Ex: music 0 GRABBAG.MID ITSGREEN.MID

The example below indicates the format used to provide separate songs to each of the individual levels.

music #EPISODE $LEVEL1FILE $LEVEL2FILE ...

Ex: music 1 stalker.mid dethtoll.mid streets.mid watrwld1.mid ...

The <episode> can be 1, 2, 3 and etc if there are additional episodes in a particular game. Duke3D v1.5 includes a 4th. I'm not sure if the music lines need to be stacked in order as they are in the original cons, but then again why would you want to change it.

As for the <level#file>, I don't recall if you can use the .midi extension over the .mid I don't see why not.

Two Available Methods to replace songs:

1. Copy and Paste -Lets say you want to change the music for the Toxic Dump, which is E1L3. Goto line music 1 and count over to the third file. See the name streets.mid, rename your new song to streets.mid and place it into your games directory. Ex: If I wanted my new midi file, rtcmsong.mid to play when street.mid is called, I would rename it to street.mid. make notice that some songs are used more than once in the game, there for if you replaced the original street.mid song, then all levels that use it are effected. Note: Any resource file in your games directory that matches the name in the cons will automatically override the default file in the .grp
2. Edit the CON -The second method(advanced), and the best method is to rename the filename within the cons to match your new song. Ensure to retain the spacing between each song. Ex: If I wanted my new midi file, rtcmsong.mid to play, I would type over the old file name street.mid, with the new. Make sure your new song is placed in the game directory as the list does not accept directory paths.

Midi Format Notes:

You will find that not all midi files work well with Duke3D, and some will not work at all. You will get weird effects from files in the wrong format! The midi's need to be in General Midi Format, with the percussion track(s) on channel 10 and the file should not exceed the maximum file size of approximately 48k. Otherwise you will only get silence. (con indicates Music will not play if the .MID file exceeds 72000 bytes.) Echo/Reverb and fast tempos may lag as they are played or crash the game entirely. The volume settings of the midi file will also have to be fairly loud, because Duke3D plays them back rather quietly.
 

dethtoll Midi:

When you start up Duke3D, it checks to see if a file is present within its directory called "dethtoll.mid". If it is not there, it will go on to play the customary music contained within the program itself. But if it does find a dethtoll.mid file in the game's directory, then it will play that music file instead of the default tunes. All you have to do is take your midi and rename that to "dethtoll.mid" then move it into your main Duke directory. Load Duke3D and it will play your midi.

Composed Midi:

The key points of your composition should be concerned with looping. Your music shouldn't really start but sort of slip into existence. For an example, the last bar must lead into the first. Unfortunately the Duke3D playback engine doesn't always join the end to the beginning seamlessly - there may be a hiccup and there may be a jump in the rhythm. It is best, therefore, if the beginning and end are rather beat less, not starting out an insistent rhythm. It is also best to begin and end with a beat or two of silence. Ensure that all channels (except for the percussion and any dummy tracks) have a patch specifically assigned to them. If you don't, you will get whatever last used that channel in the soundcard playing, with bizarre results. Obviously you do not use any fadeout at the end of the file, as it has to be looped endlessly when played back.

"definesound" lines define various names that correspond to a VOC or WAV file that can be called with. You will notice that the other sounds contain a SOUNDNAME, the FILENAME and a set of numbers like: 
"STEPNIT LIZSHIT3.VOC  0  0  254  12  0"  

The format of a definesound line is:

definesound SOUNDNAME filename #1 #2 #3 #4 #5

• #1 and #2 defines a random pitch range. This value can be positive or negative. Min/Max frequency adjustment. A random value between these two limits is chosen each time the sound is played. This will also slow the sound down as its randomly changing pitch.
• #3 is the priority flag. 0-255, the higher the number the more important the sound is to the game. This value has a Max of 255. Priority 0 sounds are played "in back" of all others, and priority 255 ones are in the very front. If there are too many sounds to be played at once the higher priority sounds get played. Maximum snds that will play is determined by the Number of voices you have set in your config file (See RTCMs related document on the configuration file.)
• #4 is a bit parsed variable identifying the type of sound it is in the game, attributes.(ex: ambient or bad guy etc.)...add the values below together for desired effects.

• [3]=
• [12]=
• [20]=
• [128]=(?) True Global (heard in the entire map by all players)

• #5 is the 'volume' adjustment. It seems only extreme values will have any effect, In the high hundreds and thousands. These values can be positive or negative. It also depends on how many decibels you mixed your sound at. Also duke phrases (duke talk) tend to be set internally hardcoded to playback at the highest volume (Like .RTS playback)

You can add your own sounds to the game by following these steps:

1. Copy your sound file (.VOC or .WAV format) into the games directory.
2. Open the USER.CON file and scroll down to the last "definedsound" and then go down one more.
3. Add your new line at the very end of the "definesound" table. After the last slot.
4. New line:  definesound SOUNDNAME filename 0 0 255 0 to the sound list of the USER.CON
5. You must define your new SOUNDNAME in the DEF.CON Just open it up and scroll to the very bottom of the list.
6. Place this statement line:  define SOUNDNAME ### where SOUNDNAME would be replaced with the new name you are calling your new sound. The ### is the next highest number of the sound list in the DEFS.CON file.
7. You can also use the ### to tag sounds in a map you maybe making.
   

Here's a quick and simple way to add your own sounds to the game. You can either change the  filename.voc  given to match your new sounds file name, or you can rename your file to match the name given in the user.con. The secound method is preferred, following these steps:

1. Copy your sound file (.VOC or .WAV format) into the games directory.
2. Open the USER.CON file and locate the name of the sound you want to replace.
3. Scroll over to the right and locate the filesname.voc you want to replace.
4. Now go back to the games directory and rename your sound to match the name in the user.con (for design sake, do not rename the filename.voc in the user.con) All sound files shipped with the game are included inside the .GRP file, however when a sound file with the same name as the one in the user.con is placed in the games directory, the game will use them instead.
5. Next time you run the game the new sound will be used instead of the one supplied with the game.

Special Note: Replacing some original game sounds does have limitations, There are a few that are internally hardcoded to playback at there default parameters, if you change the values they will not effect the outcome. This includes Sounds 9, 14, & 17 as they are built in custom global sounds. (rpg explode, pipe explode, & laser trip explode), they do not require a bit variable.

Some may have a limitation of the length (seconds) they can be. An example of some files they contain these limitations are the  barmusic.voc  file and  wind54.voc  file. These snds loop internally controlled by game.exe about every 20sec. The sounds themself are not looped and should not be looped if replaced.

Ambience and parameters: When testing your ambience loops it becomes slightly difficult to find the right parameters for the sound, Try these values "0 0 0 2 0"  They seem to work well, generally.

Maximum Sounds For Duke3D

Duke1.3D Total different sounds are 254 and you have a maximum of 348 sounds. Values: are (0-348)
Duke1.4/1.5 Total different sounds are 398 and you have a maximum of 450 sounds. Values: are (0-449)

The sound fx list follows this explanation.

1. The table below list all the snds.
   The numbers from the left margin is the
   • Sound Number (Used in BUILD.)
   • Sound Name (This is the name that Duke Nukem uses internally to reference the sound.)
   • Sound file name (stored in duke3d.grp)
   • Descriptions of a soundname is located under most of the snds.
   • A + in any section denotes that the section is not defined, hence following sections are also not defined

    

2. The numbers that are to the right of the sound file name are technical parameters which are explained here, These make for a valid sound.
   • 1 and 2 - The first two numbers define a random pitch variation range. They can be positive or negative numbers.
   • 3 - The 3rd number is a priority flag.
   • 4 - The 4th number is a bit parsed set of technical variables; See table in previous section above.
   • 5 - The 5th number is volume adjustment. Used to make the sound louder or softer.
   • 6 - The 6th number is the sample rate (Khz) Multi means the .voc file has multiple blocks.
   • 7 - The 7th number is the bit format used 8-bit or 16-bit (only four 16-bit exists)

If you use the table below you will see what sampling rate the snds have been recorded at, and if there 8-bit or 16-bit. An alterative is to load one of the games snd files into your Sound Creation Tool to determine the formats of the sound. You'll notice many of the sounds are low quality, this was by design so the computer systems back in 1996 could run the game at higher FPS. It is however something 3DR said that they wanted to have much higher quality sound mixed for the game. The game can handle a sample rate of 44,100 easily now on modern systems.

Note: When 3DR where making the Plutonium Pak they changed some of the values in the USER.CON from v1.3D. These changes are in contained in ().

Sound Table

Duke3D v1.3D Table

Plutonium Pak (Atomic Edition) Added Table

The following list shows sounds that where modified for v1.4 from v1.3D.

FACE01
INHELL01
EATSHIT01
BLOWIT01
GOTHRT01
HOLYCW01
HOLYSH02
IMGOOD12
PIECE02
BITCHN04
AMESS06
KICKHEAD (removed in v1.5 GRP) (remarked out in v1.5 USER.CON)
WHIPYU01