raze/polymer/eduke32/build/doc/buildinf.txt

// "Build Engine & Tools" Copyright (c) 1993-1997 Ken Silverman
// Ken Silverman's official web site: "http://www.advsys.net/ken"
// See the included license file "BUILDLIC.TXT" for license info.

Build information to get you started:

The first half of this file explains the .ART, .MAP, and PALETTE.DAT formats.
The second half has documentation about every BUILD engine function, what it
   does, and what the parameters are.

-Ken S.

------------------------------------------------------------------------------
Documentation on Ken's .ART file format                     by Ken Silverman

   I am documenting my ART format to allow you to program your own custom
art utilites if you so desire.  I am still planning on writing the script
system.

   All art files must have xxxxx###.ART.  When loading an art file you
should keep trying to open new xxxxx###'s, incrementing the number, until
an art file is not found.


1. long artversion;

      The first 4 bytes in the art format are the version number.  The current
   current art version is now 1.  If artversion is not 1 then either it's the
   wrong art version or something is wrong.

2. long numtiles;

      Numtiles is not really used anymore.  I wouldn't trust it.  Actually
   when I originally planning art version 1 many months ago, I thought I
   would need this variable, but it turned it is was unnecessary.  To get
   the number of tiles, you should search all art files, and check the
   localtilestart and localtileend values for each file.

3. long localtilestart;

      Localtilestart is the tile number of the first tile in this art file.

4. long localtileend;

      Localtileend is the tile number of the last tile in this art file.
      Note:  Localtileend CAN be higher than the last used slot in an art
      file.

         Example:  If you chose 256 tiles per art file:
      TILES000.ART -> localtilestart = 0,   localtileend = 255
      TILES001.ART -> localtilestart = 256, localtileend = 511
      TILES002.ART -> localtilestart = 512, localtileend = 767
      TILES003.ART -> localtilestart = 768, localtileend = 1023

5. short tilesizx[localtileend-localtilestart+1];

      This is an array of shorts of all the x dimensions of the tiles
   in this art file.  If you chose 256 tiles per art file then
   [localtileend-localtilestart+1] should equal 256.

6. short tilesizy[localtileend-localtilestart+1];

      This is an array of shorts of all the y dimensions.

7. long picanm[localtileend-localtilestart+1];

      This array of longs stores a few attributes for each tile that you
   can set inside EDITART.  You probably won't be touching this array, but
   I'll document it anyway.

   Bit:  |31           24|23           16|15            8|7             0|
         -----------------------------------------------------------------
         | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
         -----------------------------------------------------------------
                 | Anim. |  Signed char  |  Signed char  |   |  Animate  |
                 | Speed |   Y-center    |   X-center    |   |   number  |
                 --------|    offset     |    offset     |   |------------
                         --------------------------------|   ------------
                                                         | Animate type:|
                                                         | 00 - NoAnm   |
                                                         | 01 - Oscil   |
                                                         | 10 - AnmFd   |
                                                         | 11 - AnmBk   |
                                                         ----------------
          You probably recognize these:
       Animate speed -            EDITART key: 'A', + and - to adjust
       Signed char x&y offset -   EDITART key: '`', Arrows to adjust
       Animate number&type -      EDITART key: +/- on keypad

8. After the picanm's, the rest of the file is straight-forward rectangular
      art data.  You must go through the tilesizx and tilesizy arrays to find
      where the artwork is actually stored in this file.

      Note:  The tiles are stored in the opposite coordinate system than
         the screen memory is stored.  Example on a 4*4 file:

         Offsets:
         -----------------
         | 0 | 4 | 8 |12 |
         -----------------
         | 1 | 5 | 9 |13 |
         -----------------
         | 2 | 6 |10 |14 |
         -----------------
         | 3 | 7 |11 |15 |
         -----------------



----------------------------------------------------------------------------
   If you wish to display the artwork, you will also need to load your
palette.  To load the palette, simply read the first 768 bytes of your
palette.dat and write it directly to the video card - like this:

   Example:
      long i, fil;

      fil = open("palette.dat",O_BINARY|O_RDWR,S_IREAD);
      read(fil,&palette[0],768);
      close(fil);

      outp(0x3c8,0);
      for(i=0;i<768;i++)
         outp(0x3c9,palette[i]);
------------------------------------------------------------------------------

Packet format for DUKE3D (specifically for network mode 1, n(n-1) mode):

Example bunch of packets:
A  B  C   D  E  F     G      H      I   J  K  L  M   N...       O
---------------------------------------------------------------------
d9 00 d9  11 01 00  -  -   -  -   -  -   -  -  -  -  4f       16 31
da 00 da  11 01 00  -  -   -  -   -  -   -  -  -  -  b2       b7 9d
db 00 db  11 01 00  -  -   -  -   -  -   -  -  -  -  b1       24 62
dc 00 dc  11 01 00  -  -   -  -   -  -   -  -  -  -  ca       1d 58
dd 00 dd  11 01 00  -  -   -  -   -  -   -  -  -  -  a9       94 14
de 00 de  11 01 05  00 00  -  -   03 00  -  -  -  -  c5       50 b9
df 00 df  11 01 0f  a1 ff  fe 09  00 00  26 -  -  -  e2       88 6f
e0 00 e0  11 01 04  -  -   -  -   fd ff  -  -  -  -  77       51 d7
e1 00 e1  11 01 03  1f 00  ff 09  -  -   -  -  -  -  ac       14 b7
e2 00 e2  11 01 0b  9c 00  fb 09  -  -   24 -  -  -  f8       6c 22

GAME sends fields D-N
MMULTI adds fields A-C and O for error correction.

A: Packet count sending modulo 256
B: Error state.  Usually 0.  To request a resend, bit 0 is set.  In order
      to catch up on networks, sending many packets is bad, so 2 packets
      are sent in 1 IPX packet.  To send 2 packets in 1 packet, bit 1 is set.
      In special cases, this value may be different.
C: Packet count receiving modulo 256

D: Message header byte.  These are all the possible values currently.  You
      are probably only interested in case 17.  Note that fields E-N apply
      to case 17 only.
     0: send movement info from master to slave (network mode 0 only)
     1: send movement info from slave to master (network mode 0 only)
     4: user-typed messages
     5: Re-start level with given parameters
     6: Send player name
     7: Play Remote Ridicule sound
     8: Re-start level with given parameters for a user map
    17: send movement info to everybody else (network mode 1 only)
   250: Wait for Everybody (Don't start until everybody's done loading)
   255: Player quit to DOS

E: Timing byte used to calculate lag time.  This prevents the 2 computer's
      timers from drifting apart.

F: Bits field byte.  Fields G-M are sent only when certain bits
      in this byte are set.

G: X momentum update (2 bytes).  Sent only if ((F&1) != 0)

H: Y momentum update (2 bytes).  Sent only if ((F&2) != 0)

I: Angle momentum update (2 bytes).  Sent only if ((F&4) != 0)

J: The states of 8 different keys (1 byte).  Sent only if ((F&8) != 0)
K: The states of 8 different keys (1 byte).  Sent only if ((F&16) != 0)
L: The states of 8 different keys (1 byte).  Sent only if ((F&32) != 0)
M: The states of 8 different keys (1 byte).  Sent only if ((F&64) != 0)

N: Sync checking byte.  Useful for debugging programming errors.  Can be a
   variable number of bytes.  Actual number of sync checking bytes is
   calculated by length of the whole packet minus the rest of the bytes sent.

O: CRC-16

------------------------------------------------------------------------------
|   @@@@@@@@@@@     @@@       @@@  @@@@@@@@@  @@@           @@@@@@@@@        |
|   @@@@@@@@@@@@@   @@@       @@@  @@@@@@@@@  @@@           @@@@@@@@@@@      |
|   @@@       @@@@  @@@       @@@     @@@     @@@           @@@    @@@@@     |
|   @@@        @@@  @@@       @@@     @@@     @@@           @@@      @@@@    |
|   @@@       @@@@  @@@       @@@     @@@     @@@           @@@       @@@    |
|   @@@@@@@@@@@@@   @@@       @@@     @@@     @@@           @@@       @@@    |
|   @@@@@@@@@@@@@   @@@       @@@     @@@     @@@           @@@       @@@    |
|   @@@       @@@@  @@@       @@@     @@@     @@@           @@@       @@@    |
|   @@@        @@@  @@@       @@@     @@@     @@@           @@@      @@@@    |
|   @@@       @@@@  @@@@     @@@@     @@@     @@@           @@@    @@@@@     |
|   @@@@@@@@@@@@@    @@@@@@@@@@@   @@@@@@@@@  @@@@@@@@@@@@  @@@@@@@@@@@      |
|   @@@@@@@@@@@        @@@@@@@     @@@@@@@@@  @@@@@@@@@@@@  @@@@@@@@@        |
|                                                                            |
|                          M A P   F O R M A T !                             |
------------------------------------------------------------------------------

Here is Ken's documentation on the COMPLETE BUILD map format:
BUILD engine and editor programmed completely by Ken Silverman

Here's how you should read a BUILD map file:
{
   fil = open(???);

      //Load map version number (current version is 7L)
   read(fil,&mapversion,4);

      //Load starting position
   read(fil,posx,4);
   read(fil,posy,4);
   read(fil,posz,4);          //Note: Z coordinates are all shifted up 4
   read(fil,ang,2);           //All angles are from 0-2047, clockwise
   read(fil,cursectnum,2);    //Sector of starting point

      //Load all sectors (see sector structure described below)
   read(fil,&numsectors,2);
   read(fil,&sector[0],sizeof(sectortype)*numsectors);

      //Load all walls (see wall structure described below)
   read(fil,&numwalls,2);
   read(fil,&wall[0],sizeof(walltype)*numwalls);

      //Load all sprites (see sprite structure described below)
   read(fil,&numsprites,2);
   read(fil,&sprite[0],sizeof(spritetype)*numsprites);

   close(fil);
}

      -------------------------------------------------------------
      | @@@@@@@ @@@@@@@ @@@@@@@ @@@@@@@@ @@@@@@@ @@@@@@@  @@@@@@@ |
      | @@      @@      @@         @@    @@   @@ @@   @@@ @@      |
      | @@@@@@@ @@@@@   @@         @@    @@   @@ @@@@@@@  @@@@@@@ |
      |      @@ @@      @@         @@    @@   @@ @@   @@@      @@ |
      | @@@@@@@ @@@@@@@ @@@@@@@    @@    @@@@@@@ @@    @@ @@@@@@@ |
      -------------------------------------------------------------

   //sizeof(sectortype) = 40
typedef struct
{
   short wallptr, wallnum;
   long ceilingz, floorz;
   short ceilingstat, floorstat;
   short ceilingpicnum, ceilingheinum;
   signed char ceilingshade;
   char ceilingpal, ceilingxpanning, ceilingypanning;
   short floorpicnum, floorheinum;
   signed char floorshade;
   char floorpal, floorxpanning, floorypanning;
   char visibility, filler;
   short lotag, hitag, extra;
} sectortype;
sectortype sector[1024];

wallptr - index to first wall of sector
wallnum - number of walls in sector
z's - z coordinate (height) of ceiling / floor at first point of sector
stat's
   bit 0: 1 = parallaxing, 0 = not                                 "P"
   bit 1: 1 = sloped, 0 = not
   bit 2: 1 = swap x&y, 0 = not                                    "F"
   bit 3: 1 = double smooshiness                                   "E"
   bit 4: 1 = x-flip                                               "F"
   bit 5: 1 = y-flip                                               "F"
   bit 6: 1 = Align texture to first wall of sector                "R"
   bits 7-15: reserved
picnum's - texture index into art file
heinum's - slope value (rise/run) (0-parallel to floor, 4096-45 degrees)
shade's - shade offset of ceiling/floor
pal's - palette lookup table number (0 - use standard colors)
panning's - used to align textures or to do texture panning
visibility - determines how fast an area changes shade relative to distance
filler - useless byte to make structure aligned
lotag, hitag, extra - These variables used by the game programmer only


          -----------------------------------------------
          | @@      @@ @@@@@@@@ @@      @@      @@@@@@@ |
          | @@      @@ @@    @@ @@      @@      @@      |
          | @@  @@  @@ @@@@@@@@ @@      @@      @@@@@@@ |
          | @@ @@@@ @@ @@    @@ @@      @@           @@ |
          |  @@@ @@@@  @@    @@ @@@@@@@ @@@@@@@ @@@@@@@ |
          ----------------------------------------------|

   //sizeof(walltype) = 32
typedef struct
{
   long x, y;
   short point2, nextwall, nextsector, cstat;
   short picnum, overpicnum;
   signed char shade;
   char pal, xrepeat, yrepeat, xpanning, ypanning;
   short lotag, hitag, extra;
} walltype;
walltype wall[8192];

x, y: Coordinate of left side of wall, get right side from next wall's left side
point2: Index to next wall on the right (always in the same sector)
nextwall: Index to wall on other side of wall (-1 if there is no sector)
nextsector: Index to sector on other side of wall (-1 if there is no sector)
cstat:
   bit 0: 1 = Blocking wall (use with clipmove, getzrange)         "B"
   bit 1: 1 = bottoms of invisible walls swapped, 0 = not          "2"
   bit 2: 1 = align picture on bottom (for doors), 0 = top         "O"
   bit 3: 1 = x-flipped, 0 = normal                                "F"
   bit 4: 1 = masking wall, 0 = not                                "M"
   bit 5: 1 = 1-way wall, 0 = not                                  "1"
   bit 6: 1 = Blocking wall (use with hitscan / cliptype 1)        "H"
   bit 7: 1 = Transluscence, 0 = not                               "T"
   bit 8: 1 = y-flipped, 0 = normal                                "F"
   bit 9: 1 = Transluscence reversing, 0 = normal                  "T"
   bits 10-15: reserved
picnum - texture index into art file
overpicnum - texture index into art file for masked walls / 1-way walls
shade - shade offset of wall
pal - palette lookup table number (0 - use standard colors)
repeat's - used to change the size of pixels (stretch textures)
pannings - used to align textures or to do texture panning
lotag, hitag, extra - These variables used by the game programmer only

      -------------------------------------------------------------
      | @@@@@@@ @@@@@@@ @@@@@@@   @@@@@@ @@@@@@@@ @@@@@@@ @@@@@@@ |
      | @@      @@   @@ @@   @@@    @@      @@    @@      @@      |
      | @@@@@@@ @@@@@@@ @@@@@@@     @@      @@    @@@@@   @@@@@@@ |
      |      @@ @@      @@    @@    @@      @@    @@           @@ |
      | @@@@@@@ @@      @@    @@  @@@@@@    @@    @@@@@@@ @@@@@@@ |
      -------------------------------------------------------------

   //sizeof(spritetype) = 44
typedef struct
{
   long x, y, z;
   short cstat, picnum;
   signed char shade;
   char pal, clipdist, filler;
   unsigned char xrepeat, yrepeat;
   signed char xoffset, yoffset;
   short sectnum, statnum;
   short ang, owner, xvel, yvel, zvel;
   short lotag, hitag, extra;
} spritetype;
spritetype sprite[4096];
x, y, z - position of sprite - can be defined at center bottom or center
cstat:
   bit 0: 1 = Blocking sprite (use with clipmove, getzrange)       "B"
   bit 1: 1 = transluscence, 0 = normal                            "T"
   bit 2: 1 = x-flipped, 0 = normal                                "F"
   bit 3: 1 = y-flipped, 0 = normal                                "F"
   bits 5-4: 00 = FACE sprite (default)                            "R"
             01 = WALL sprite (like masked walls)
             10 = FLOOR sprite (parallel to ceilings&floors)
   bit 6: 1 = 1-sided sprite, 0 = normal                           "1"
   bit 7: 1 = Real centered centering, 0 = foot center             "C"
   bit 8: 1 = Blocking sprite (use with hitscan / cliptype 1)      "H"
   bit 9: 1 = Transluscence reversing, 0 = normal                  "T"
   bits 10-14: reserved
   bit 15: 1 = Invisible sprite, 0 = not invisible
picnum - texture index into art file
shade - shade offset of sprite
pal - palette lookup table number (0 - use standard colors)
clipdist - the size of the movement clipping square (face sprites only)
filler - useless byte to make structure aligned
repeat's - used to change the size of pixels (stretch textures)
offset's - used to center the animation of sprites
sectnum - current sector of sprite
statnum - current status of sprite (inactive/monster/bullet, etc.)

ang - angle the sprite is facing
owner, xvel, yvel, zvel, lotag, hitag, extra - These variables used by the
                                               game programmer only
------------------------------------------------------------------------------




-----------------------------------------------------------------------------
|                        IMPORTANT ENGINE FUNCTIONS:                        |
-----------------------------------------------------------------------------

initengine()
   Initializes many variables for the BUILD engine.  You should call this
   once before any other functions of the BUILD engine are used.

uninitengine();
   Frees buffers.  You should call this once at the end of the program
   before quitting to dos.

loadboard(char *filename, long *posx, long *posy, long *posz, short *ang, short *cursectnum)
saveboard(char *filename, long *posx, long *posy, long *posz, short *ang, short *cursectnum)
   Loads/saves the given board file from memory.  Returns -1 if file not
   found.  If no extension is given, .MAP will be appended to the filename.

loadpics(char *filename);
   Loads the given artwork file into memory for the BUILD engine.
   Returns -1 if file not found.  If no extension is given, .ART will
   be appended to the filename.

loadtile(short tilenum)
   Loads a given tile number from disk into memory if it is not already in
   memory.  This function calls allocache internally.  A tile is not in the
   cache if (waloff[tilenum] == 0)

-----------------------------------------------------------------------------
|                          SCREEN STATUS FUNCTIONS:                         |
-----------------------------------------------------------------------------

setgamemode(char vidoption, long xdim, long ydim);
   This function sets the video mode to 320*200*256color graphics.
   Since BUILD supports several different modes including mode x,
   mode 13h, and other special modes, I don't expect you to write
   any graphics output functions.  (Soon I have all the necessary
   functions)  If for some reason, you use your own graphics mode,
   you must call this function again before using the BUILD drawing
   functions.

   vidoption can be anywhere from 0-6
   xdim,ydim can be any vesa resolution if vidoption = 1
   xdim,ydim must be 320*200 for any other mode.
      (see graphics mode selection in my setup program)

setview(long x1, long y1, long x2, long y2)
   Sets the viewing window to a given rectangle of the screen.
   Example: For full screen 320*200, call like this: setview(0L,0L,319L,199L);

nextpage();
   This function flips to the next video page.  After a screen is prepared,
   use this function to view the screen.

-----------------------------------------------------------------------------
|                             DRAWING FUNCTIONS:                            |
-----------------------------------------------------------------------------

drawrooms(long posx, long posy, long posz, short ang, long horiz, short cursectnum)
   This function draws the 3D screen to the current drawing page,
   which is not yet shown.  This way, you can overwrite some things
   over the 3D screen such as a gun.  Be sure to call the drawmasks()
   function soon after you call the drawrooms() function.  To view
   the screen, use the nextpage() function.  The nextpage() function
   should always be called sometime after each draw3dscreen()
   function.

drawmasks();
   This function draws all the sprites and masked walls to the current
   drawing page which is not yet shown.  The reason I have the drawing
   split up into these 2 routines is so you can animate just the
   sprites that are about to be drawn instead of having to animate
   all the sprites on the whole board.  Drawrooms() prepares these
   variables:  spritex[], spritey[], spritepicnum[], thesprite[],
   and spritesortcnt.  Spritesortcnt is the number of sprites about
   to be drawn to the page.  To change the sprite's picnum, simply
   modify the spritepicnum array  If you want to change other parts
   of the sprite structure, then you can use the thesprite array to
   get an index to the actual sprite number.

clearview(long col)
   Clears the current video page to the given color

clearallviews(long col)
   Clears all video pages to the given color

drawmapview (long x, long y, long zoom, short ang)
   Draws the 2-D texturized map at the given position into the viewing window.

rotatesprite (long sx, long sy, long z, short a, short picnum,
              signed char dashade, char dapalnum, char dastat,
              long cx1, long cy1, long cx2, long cy2)
   (sx, sy) is the center of the sprite to draw defined as
       screen coordinates shifted up by 16.
   (z) is the zoom.  Normal zoom is 65536.
       Ex: 131072 is zoomed in 2X and 32768 is zoomed out 2X.
   (a) is the angle (0 is straight up)
   (picnum) is the tile number
   (dashade) is 0 normally but can be any standard shade up to 31 or 63.
   (dapalnum) can be from 0-255.
   if ((dastat&1) == 0) - no transluscence
   if ((dastat&1) != 0) - transluscence
   if ((dastat&2) == 0) - don't scale to setview's viewing window
   if ((dastat&2) != 0) - scale to setview's viewing window (windowx1,etc.)
   if ((dastat&4) == 0) - nuttin' special
   if ((dastat&4) != 0) - y-flip image
   if ((dastat&8) == 0) - clip to startumost/startdmost
   if ((dastat&8) != 0) - don't clip to startumost/startdmost
   if ((dastat&16) == 0) - use Editart center as point passed
   if ((dastat&16) != 0) - force point passed to be top-left corner
   if ((dastat&32) == 0) - nuttin' special
   if ((dastat&32) != 0) - use reverse transluscence
   if ((dastat&64) == 0) - masked drawing (check 255's) (slower)
   if ((dastat&64) != 0) - draw everything (don't check 255's) (faster)
   if ((dastat&128) == 0) - nuttin' special
   if ((dastat&128) != 0) - automatically draw to all video pages

   Note:  As a special case, if both ((dastat&2) != 0) and ((dastat&8) != 0)
      then rotatesprite will scale to the full screen (0,0,xdim-1,ydim-1)
      rather than setview's viewing window. (windowx1,windowy1,etc.)  This
      case is useful for status bars, etc.

      Ex: rotatesprite(160L<<16,100L<<16,65536,totalclock<<4,
                       DEMOSIGN,2,50L,50L,270L,150L);
          This example will draw the DEMOSIGN tile in the center of the
          screen and rotate about once per second.  The sprite will only
          get drawn inside the rectangle from (50,50) to (270,150)

drawline256(long x1, long y1, long x2, long y2, char col)
   Draws a solid line from (x1,y1) to (x2,y2) with color (col)
   For this function, screen coordinates are all shifted up 16 for precision.

printext256(long xpos, long ypos, short col, short backcol,
            char *message, char fontsize)
   Draws a text message to the screen.
   (xpos,ypos) - position of top left corner
   col - color of text
   backcol - background color, if -1, then background is transparent
   message - text message
   fontsize - 0 - 8*8 font
              1 - 4*6 font

-----------------------------------------------------------------------------
|                         MOVEMENT COLLISION FUNCTIONS:                     |
-----------------------------------------------------------------------------

clipmove(long *x, long *y, long *z, short *sectnum, long xvect, long yvect,
         long walldist, long ceildist, long flordist, unsigned long cliptype)
      Moves any object (x, y, z) in any direction at any velocity and will
   make sure the object will stay a certain distance from walls (walldist)
       Pass the pointers of the starting position (x, y, z).  Then
   pass the starting position's sector number as a pointer also.
   Also these values will be modified accordingly.  Pass the
   direction and velocity by using a vector (xvect, yvect).
   If you don't fully understand these equations, please call me.
         xvect = velocity * cos(angle)
         yvect = velocity * sin(angle)
      Walldist tells how close the object can get to a wall.  I use
    128L as my default.  If you increase walldist all of a sudden
    for a certain object, the object might leak through a wall, so
    don't do that!
       Cliptype is a mask that tells whether the object should be clipped
    to or not.  The lower 16 bits are anded with wall[].cstat and the higher
    16 bits are anded with sprite[].cstat.

     Clipmove can either return 0 (touched nothing)
                                32768+wallnum (wall first touched)
                                49152+spritenum (sprite first touched)

pushmove (long *x, long *y, long *z, short *sectnum,
          long walldist, long ceildist, long flordist, unsigned long cliptype)
      This function makes sure a player or monster (defined by x, y, z, sectnum)
   is not too close to a wall.  If it is, then it attempts to push it away.
   If after 256 tries, it is unable to push it away, it returns -1, in which
   case the thing should gib.

getzrange(long x, long y, long z, short sectnum,
                  long *ceilz, long *ceilhit,
                  long *florz, long *florhit,
                  long walldist, unsigned long cliptype)

      Use this in conjunction with clipmove.  This function will keep the
   player from falling off cliffs when you're too close to the edge.  This
   function finds the highest and lowest z coordinates that your clipping
   BOX can get to.  It must search for all sectors (and sprites) that go
   into your clipping box.  This method is better than using
   sector[cursectnum].ceilingz and sector[cursectnum].floorz because this
   searches the whole clipping box for objects, not just 1 point.
      Pass x, y, z, sector normally.  Walldist can be 128.  Cliptype is
   defined the same way as it is for clipmove.  This function returns the
   z extents in ceilz and florz. It will return the object hit in ceilhit
   and florhit.  Ceilhit and florhit will also be either:
                                 16384+sector (sector first touched) or
                                 49152+spritenum (sprite first touched)

hitscan(long xstart, long ystart, long zstart, short startsectnum,
        long vectorx, long vectory, long vectorz,
        short *hitsect, short *hitwall, short *hitsprite,
        long *hitx, long *hity, long *hitz);

   Pass the starting 3D position:
        (xstart, ystart, zstart, startsectnum)
   Then pass the 3D angle to shoot (defined as a 3D vector):
        (vectorx, vectory, vectorz)
   Then set up the return values for the object hit:
        (hitsect, hitwall, hitsprite)
   and the exact 3D point where the ray hits:
        (hitx, hity, hitz)

   How to determine what was hit:
      * Hitsect is always equal to the sector that was hit (always >= 0).

      * If the ray hits a sprite then:
           hitsect = thesectornumber
           hitsprite = thespritenumber
           hitwall = -1

       * If the ray hits a wall then:
           hitsect = thesectornumber
           hitsprite = -1
           hitwall = thewallnumber

       * If the ray hits the ceiling of a sector then:
           hitsect = thesectornumber
           hitsprite = -1
           hitwall = -1
           vectorz < 0
           (If vectorz < 0 then you're shooting upward which means
              that you couldn't have hit a floor)

       * If the ray hits the floor of a sector then:
           hitsect = thesectornumber
           hitsprite = -1
           hitwall = -1
           vectorz > 0
           (If vectorz > 0 then you're shooting downard which means
              that you couldn't have hit a ceiling)

neartag(long x, long y, long z, short sectnum, short ang,  //Starting position & angle
        short *neartagsector,   //Returns near sector if sector[].tag != 0
        short *neartagwall,     //Returns near wall if wall[].tag != 0
        short *neartagsprite,   //Returns near sprite if sprite[].tag != 0
        long *neartaghitdist,   //Returns actual distance to object (scale: 1024=largest grid size)
        long neartagrange,      //Choose maximum distance to scan (scale: 1024=largest grid size)
        char tagsearch)         //1-lotag only, 2-hitag only, 3-lotag&hitag
      Neartag works sort of like hitscan, but is optimized to
   scan only close objects and scan only objects with
   tags != 0.  Neartag is perfect for the first line of your space bar code.
   It will tell you what door you want to open or what switch you want to
   flip.

cansee(long x1, long y1, long z1, short sectnum1,
       long x2, long y2, long z2, short sectnum2);  returns 0 or 1
   This function determines whether or not two 3D points can "see" each
   other or not.  All you do is pass it the coordinates of a 3D line defined
   by two 3D points (with their respective sectors)  The function will return
   a 1 if the points can see each other or a 0 if there is something blocking
   the two points from seeing each other.  This is how I determine whether a
   monster can see you or not. Try playing DOOM1.DAT to fully enjoy this
   great function!

updatesector(long x, long y, &sectnum);
   This function updates the sector number according to the x and y values
   passed to it.  Be careful when you use this function with sprites because
   remember that the sprite's sector number should not be modified directly.
   If you want to update a sprite's sector, I recomment using the setsprite
   function described below.

inside(long x, long y, short sectnum);
   Tests to see whether the overhead point (x, y) is inside sector (sectnum)
   Returns either 0 or 1, where 1 means it is inside, and 0 means it is not.

clipinsidebox(long x, long y, short wallnum, long walldist)
   Returns TRUE only if the given line (wallnum) intersects the square with
   center (x,y) and radius, walldist.

dragpoint(short wallnum, long newx, long newy);
   This function will drag a point in the exact same way a point is dragged
   in 2D EDIT MODE using the left mouse button.  Simply pass it which wall
   to drag and then pass the new x and y coordinates for that point.
   Please use this function because if you don't and try to drag points
   yourself, I can guarantee that it won't work as well as mine and you
   will get confused.  Note:  Every wall of course has 2 points.  When you
   pass a wall number to this function, you are actually passing 1 point,
   the left side of the wall (given that you are in the sector of that wall)
   Got it?

-----------------------------------------------------------------------------
|                           MATH HELPER FUNCTIONS:                          |
-----------------------------------------------------------------------------

krand()
   Random number function - returns numbers from 0-65535

ksqrt(long num)
   Returns the integer square root of the number.

getangle(long xvect, long yvect)
   Gets the angle of a vector (xvect,yvect)
   These are 2048 possible angles starting from the right, going clockwise

rotatepoint(long xpivot, long ypivot, long x, long y,
            short daang, long *x2, long *y2);
      This function is a very convenient and fast math helper function.
   Rotate points easily with this function without having to juggle your
   cosines and sines.  Simply pass it:

       Input:   1. Pivot point     (xpivot,ypivot)
                2. Original point  (x,y)
                3. Angle to rotate (0 = nothing, 512 = 90<39> CW, etc.)
       Output:  4. Rotated point   (*x2,*y2)

lastwall(short point);
      Use this function as a reverse function of wall[].point2.  In order
   to save memory, my walls are only on a single linked list.

nextsectorneighborz(short sectnum, long thez, short topbottom, short direction)
   This function is used to tell where elevators should stop.  It searches
   nearby sectors for the next closest ceilingz or floorz it should stop at.
   sectnum - elevator sector
   thez - current z to start search from
   topbottom - search ceilingz's/floorz's only
   direction - search upwards/downwards

getceilzofslope(short sectnum, long x, long y)
getflorzofslope(short sectnum, long x, long y)
getzsofslope(short sectnum, long x, long y, long *ceilz, long *florz)
   These 3 functions get the height of a ceiling and/or floor in a sector
   at any (x,y) location.  Use getzsofslope only if you need both the ceiling
   and floor.

alignceilslope(short sectnum, long x, long y, long z)
alignflorslope(short sectnum, long x, long y, long z)
   Given a sector and assuming it's first wall is the pivot wall of the slope,
   this function makes the slope pass through the x,y,z point.  One use of
   this function is used for sin-wave floors.

-----------------------------------------------------------------------------
|                             SPRITE FUNCTIONS:                             |
-----------------------------------------------------------------------------

insertsprite(short sectnum, short statnum);   //returns (short)spritenum;
   Whenever you insert a sprite, you must pass it the sector
   number, and a status number (statnum).  The status number can be any
   number from 0 to MAXSTATUS-1.  Insertsprite works like a memory
   allocation function and returns the sprite number.

deletesprite(short spritenum);
   Deletes the sprite.

changespritesect(short spritenum, short newsectnum);
   Changes the sector of sprite (spritenum) to the
   newsector (newsectnum).  This function may become
   internal to the engine in the movesprite function.  But
   this function is necessary since all the sectors have
   their own doubly-linked lists of sprites.

changespritestat(short spritenum, short newstatnum);
   Changes the status of sprite (spritenum) to status
   (newstatus).  Newstatus can be any number from 0 to MAXSTATUS-1.
   You can use this function to put a monster on a list of active sprites
   when it first sees you.

setsprite(short spritenum, long newx, long newy, long newz);
      This function simply sets the sprite's position to a specified
   coordinate (newx, newy, newz) without any checking to see
   whether the position is valid or not.  You could directly
   modify the sprite[].x, sprite[].y, and sprite[].z values, but
   if you use my function, the sprite is guaranteed to be in the
   right sector.

-----------------------------------------------------------------------------
|                             CACHE FUNCTIONS:                              |
-----------------------------------------------------------------------------
initcache(long dacachestart, long dacachesize)
   First allocate a really large buffer (as large as possible), then pass off
   the memory bufer the initcache
   dacachestart: 32-bit offset in memory of start of cache
   dacachesize: number of bytes that were allocated for the cache to use

allocache (long *bufptr, long bufsiz, char *lockptr)
   *bufptr = pointer to 4-byte pointer to buffer.  This
      allows allocache to remove previously allocated things
      from the cache safely by setting the 4-byte pointer to 0.
   bufsiz = number of bytes to allocate
   *lockptr = pointer to locking char which tells whether
      the region can be removed or not.  If *lockptr = 0 then
      the region is not locked else its locked.

-----------------------------------------------------------------------------
|                          GROUP FILE FUNCTIONS:                            |
-----------------------------------------------------------------------------
initgroupfile(char *filename)
   Tells the engine what the group file name is.
   You should call this before any of the following group file functions.
uninitgroupfile()
   Frees buffers.  You should call this once at the end of the program
   before quitting to dos.

kopen4load(char *filename, char searchfirst)
   Open a file.  First tries to open a stand alone file.  Then searches for
   it in the group file.  If searchfirst is nonzero, it will check the group
   file only.

kread(long handle, void *buffer, long leng)
klseek(long handle, long offset, long whence)
kfilelength(long handle)
kclose(long handle)
   These 4 functions simply shadow the dos file functions - they
   can do file I/O on the group file in addition to stand-along files.

-----------------------------------------------------------------------------
|                          COMMUNICATIONS FUNCTIONS:                        |
-----------------------------------------------------------------------------
   Much of the following code is to keep compatibity with older network code:

initmultiplayers(char damultioption, char dacomrateoption, char dapriority)
   The parameters are ignored - just pass 3 0's
uninitmultiplayers()    Does nothing

sendpacket(long other, char *bufptr, long messleng)
   other - who to send the packet to
   bufptr - pointer to message to send
   messleng - length of message
short getpacket (short *other, char *bufptr)
   returns the number of bytes of the packet received, 0 if no packet
   other - who the packet was received from
   bufptr - pointer to message that was received

sendlogon()             Does nothing
sendlogoff()
   Sends a packet to everyone else where the
   first byte is 255, and the
   second byte is myconnectindex

getoutputcirclesize()  Does nothing - just a stub function, returns 0
setsocket(short newsocket) Does nothing

flushpackets()
   Clears all packet buffers
genericmultifunction(long other, char *bufptr, long messleng, long command)
   Passes a buffer to the commit driver.  This command provides a gateway
   for game programmer to access COMMIT directly.

-----------------------------------------------------------------------------
|                             PALETTE FUNCTIONS:                            |
-----------------------------------------------------------------------------
VBE_setPalette(long start, long num, char *palettebuffer)
VBE_getPalette(long start, long num, char *palettebuffer)
   Set (num) palette palette entries starting at (start)
   palette entries are in a 4-byte format in this order:
      0: Blue (0-63)
      1: Green (0-63)
      2: Red (0-63)
      3: Reserved

makepalookup(long palnum, char *remapbuf,
             signed char r, signed char g, signed char b,
             char dastat)
   This function allows different shirt colors for sprites.  First prepare
   remapbuf, which is a 256 byte buffer of chars which the colors to remap.
   Palnum can be anywhere from 1-15.  Since 0 is where the normal palette is
   stored, it is a bad idea to call this function with palnum=0.
   In BUILD.H notice I added a new variable, spritepal[MAXSPRITES].
   Usually the value of this is 0 for the default palette.  But if you
   change it to the palnum in the code between drawrooms() and drawmasks
   then the sprite will be drawn with that remapped palette.  The last 3
   parameters are the color that the palette fades to as you get further
   away.  This color is normally black (0,0,0).  White would be (63,63,63).
   if ((dastat&1) == 0) then makepalookup will allocate & deallocate
   the memory block for use but will not waste the time creating a palookup
   table (assuming you will create one yourself)

setbrightness(char gammalevel, char *dapal)
   Use this function to adjust for gamma correction.
   Gammalevel - ranges from 0-15, 0 is darkest, 15 brightest. Default: 0
   dapal: standard VGA palette (768 bytes)

------------------------------------------------------------------------------
|                     This document brought to you by:                       |
|                                                                            |
|          @@@@@@        @@@@@@  @@@@@@@@@@@@@@@@@@  @@@@@@@@         @@@@@@ |
|          @@@@@@       @@@@@@   @@@@@@@@@@@@@@@@@@  @@@@@@@@@        @@@@@@ |
|          @@@@@@     @@@@@@@    @@@@@@@@@@@@@@@@@@  @@@@@@@@@@       @@@@@@ |
|          @@@@@@    @@@@@@@     @@@@@@              @@@@@@@@@@@      @@@@@@ |
|          @@@@@@  @@@@@@@       @@@@@@              @@@@@@@@@@@@     @@@@@@ |
|          @@@@@@ @@@@@@@        @@@@@@              @@@@@@@@@@@@@    @@@@@@ |
|          @@@@@@@@@@@@          @@@@@@@@@@@@@@@     @@@@@@ @@@@@@@   @@@@@@ |
| @@@@@@@  @@@@@@@@@@@           @@@@@@@@@@@@@@@     @@@@@@  @@@@@@@  @@@@@@ |
|          @@@@@@@@@@@@          @@@@@@@@@@@@@@@     @@@@@@   @@@@@@@ @@@@@@ |
|          @@@@@@ @@@@@@@        @@@@@@              @@@@@@    @@@@@@@@@@@@@ |
|          @@@@@@  @@@@@@@       @@@@@@              @@@@@@     @@@@@@@@@@@@ |
|          @@@@@@    @@@@@@@     @@@@@@              @@@@@@      @@@@@@@@@@@ |
|          @@@@@@     @@@@@@@    @@@@@@@@@@@@@@@@@@  @@@@@@       @@@@@@@@@@ |
|          @@@@@@       @@@@@@   @@@@@@@@@@@@@@@@@@  @@@@@@        @@@@@@@@@ |
|          @@@@@@        @@@@@@  @@@@@@@@@@@@@@@@@@  @@@@@@         @@@@@@@@ |
|                                                                            |
|                   Ken Silverman of East Greenwich, RI USA                  |
------------------------------------------------------------------------------