/**************************************************************************\
*                        Con Editing Information v1.2                      *
\**************************************************************************/


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 possible, use the WYSIWYG version (RTF).



James Ferry, 6th February 1999

http://members.xoom.com/HCAD
(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.

//, /* and */   ends                    ifhitweapon     mikesnd
{ and }         fall                    ifinouterspace  money
action          gamestartup             ifinspace       move
actor           getlastpal              ifinwater       music
addammo         globalsound             ifmove          operate
addinventory    guts                    ifmultiplayer   palfrom
addkill         hitradius               ifnotmoving     pkick
addphealth      ifaction                ifonwater       pstomp
addweapon       ifactioncount           ifoutside       quote
ai              ifactor                 ifp             resetactioncount
betaname	ifactornotstayput	ifpdistg	resetcount
break           ifai                    ifpdistl        resetplayer
cactor          ifawayfromwall          ifphealthl      respawnhitag
count           ifbulletnear            ifpinventory    shoot
cstat           ifcansee                ifrespawn       sizeto
debris          ifcanseetarget          ifrnd           sound
debug           ifcanshoottarget        ifspawnedby     soundonce
define          ifceilingdistl          ifspritepal     spawn
definelevelname ifcount                 ifsquished      spritepal
definequote     ifdead                  ifstrength      state
definesound     iffloordistl            ifwasweapon     stopsound
else            ifgapzl                 include         strength
enda            ifgotweaponce           killit          tip
endofgame       ifhitspace              lotsofglass     wackplayer



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.
Unfortunatly, this was designed to make use of WYSIWYG text, so there is no
distinguishing between the function names and parametres and the
descriptions.
Sorry.
The function names are between the two dashed lines (77 hyphens).


-----------------------------------------------------------------------------
//, /* 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)

Value	Description
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
        last/fifth value is looking from the rear.  The second, third an
        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 instead of 45 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 degrees from the front to the right.


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

Value   Common name     Description
0       GET_STEROIDS    Steroids - will set the inventory level to amount.
                        If the amount is not set to the maximum value, then
                        the steroids will automatically start running.
1       GET_SHIELD      Armour - will add amount to the current inventory
                        level
2       GET_SCUBA       Airtank/scuba gear - will set the inventory level to
                        amount.
3       GET_HOLODUKE    Holoduke - will set the inventory level to amount.
4       GET_JETPACK     Jet pack - will set the inventory level to amount.
6       GET_ACCESS      Access cards - bit status (on/off) of which cards the
                        player has.  The actor giving the player the card's
                        palette determines which card to give the player.
7       GET_HEATS       Night vision goggles - will set the inventory level
                        to amount.
9       GET_FIRSTAID    First aid - will set the inventory level to amount.
10      GET_BOOTS       Boots - will set the inventory level to amount.


-----------------------------------------------------------------------------
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.


Value	Description
1       blocking sprite (used for distances from other actors)
2	translucent
4	x-flipped
8	y-flipped
16      wall sprite (vertical)
32      floor sprite (horizontal, I think it will ignore16|wall if this one
        is set)
64      1-sided sprite
128     real centering
256     blocking sprite (use with hitscan / cliptype 1)
512     translucence reversing (more translucent than 2|translucent, I think
        2|translucent is ignored if this is set)
1,024	reserved
2,048	reserved
4,096	reserved
8,192	reserved
16,384	reserved
32,768  invisible (I think it will also make it unable to be hit)


-----------------------------------------------------------------------------
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.

Value   Common name
2,390	SCRAP6
2,400	SCRAP1
2,404	SCRAP2
2,408	SCRAP3
2,412	SCRAP4
2,416	SCRAP5


-----------------------------------------------------------------------------
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,
                                        the original vale was 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.

Value   Common name     Brief Description
1,520   DUKETORSO       flying body part (Duke's upper torso)
1,528   DUKEGUN         flying body part (Duke's forearm and gun)
1,536   DUKELEG         flying body part (Duke's leg)
1,768   HEADJIB1        flying body part (Liztroop's head)
1,772   ARMJIB1         flying body part (Liztroop's arm)
1,776   LEGJIB1         flying body part (Liztroop's leg)
1,860   INNERJAW        no image, causes damage to player if close enough
2,201   LIZMANHEAD1     flying body part (Lizman's head)
2,205   LIZMANARM1      flying body part (Lizman's arm)
2,209   LIZMANLEG1      flying body part (Lizman's leg)
2,245   JIBS1           flying internal body part
2,250   JIBS2           flying internal body part
2,255   JIBS3           flying internal body part
2,260   JIBS4           flying internal body part
2,265   JIBS5           flying internal body part
2,286   JIBS6           flying internal body part


-----------------------------------------------------------------------------
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.

Value   Common name     Brief description
1	pstanding	standing
2	pwalking	walking
4       prunning        running (needs the run key, auto run will not work)
8	pducking	ducking
16	pfalling	falling
32	pjumping	jumping
64      phigher         higher than current actor
128     pwalkingback    walking backwards
256     prunningback    running backwards
512     pkicking        kicking (needs to be weapon one, not quick kick)
1,024   pshrunk         smaller than the normal size by a certain amount
2,048   pjetpack        using a jetpack
4,096   ponsteroids     using steroids
8,192   ponground       on the ground/surface (this includes anything that
                        can be stood on, including solid sprites)
16,384  palive          alive (not dead)
32,568  pdead           dead (not alive anymore)
65,536  pfacing         looking at the current actor


-----------------------------------------------------------------------------
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.

Value   Common name     Description
1       faceplayer      faces the player.
2       geth            travels in a horizontal direction.
4       getv            travels in a vertical direction.
8       randomangle     faces a random angle when ever it touches a wall or
                        is shot at.  This seems to only face random angles
                        when the actor is an actor such as a monster, not an
                        item or object.
16      faceplayerslow  faces the player a bit slower than 1 (faceplayer)
32      spin            spins in circles
64      faceplayersmart faces slightly towards where the player is heading
128     fleeenemy       faces directly away from the player
257     jumptoplayer    attempts to jump
512     seekplayer      trys to find the player
1,024   furthestdir     faces the furthest distance from the closest player
2,048                   similar to 8 (randomangle), except that once it is
                        called, if it spins or faces another angle and
                        returns to using this value, it will go back to using
                        the angle that this value last used, unless the cause
                        for the change in angle was bumping into a wall or
                        being shot at.  This seems to only face random angles
                        when the actor is an actor such as a monster, not an
                        item or object.
4,096   dodgebullet     attempts to avoid a projectile nearby




=============================================================================
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.

Number  Name           Shoot    Hit    Strength        Notes
26      HEAVYHBOMB      no      no      yes     *creates 1670 damage
916     FIREEXT         no      yes     yes*    *preset strength
940     BOUNCEMINE      yes     no      yes     *creates 1670 damage
1,360	COOLEXPLOSION1	yes	yes	yes	
1,625	FIRELASER	yes	yes	yes	
1,636   SPIT            yes     yes     yes 
1,641	FREEZEBLAST	yes	yes	yes	
1,642   DEVISTATORBLAST yes     no      yes     uses 2605 code, *creates 2605
                                                damage
1,646	SHRINKSPARK	yes	yes	yes	
1,650   MORTER          yes     no      yes     *creates 1670 damage
1,670   RADIUSEXPLOSION no*     yes     yes*    *use hitradius or other
                                                weapon
2,296	BLOODSPLAT1	yes	no	no	
2,297	BLOODSPLAT2	yes	no	no	
2,298	BLOODSPLAT3	yes	no	no	
2,299	BLOODSPLAT4	yes	no	no	
2,521   KNEE            yes     yes     yes*    *adds rnd(5)+1
2,536   CHAINGUN        yes     no      yes*    uses 2595 code, *adds
                                                rnd(5)+1
2,566   TRIPBOMB        no      no*     yes     *creates 1670 damage
2,595   SHOTSPARK1      yes     yes     yes*    code can be modified, *adds
                                                rnd(5)+1
2,605   RPG             yes     yes     yes*    *doubles damage for direct
                                                hits
2,613   SHOTGUN         yes     no      yes*    uses 2595 code, adds rnd(5)+1


Number  Common Name
0	KNEE_WEAPON
1	PISTOL_WEAPON
2	SHOTGUN_WEAPON
3	CHAINGUN_WEAPON
4	RPG_WEAPON
5	HANDBOMB_WEAPON
6	SHRINKER_WEAPON
7	DEVISTATOR_WEAPON
8	TRIPBOMB_WEAPON
9	FREEZE_WEAPON




=============================================================================
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.
