The Build Engine
Macros | Functions
engine.h File Reference

Main engine include file. More...

Go to the source code of this file.

Macros

#define SUPERBUILD   /* don't touch this. */
 

Functions

void faketimerhandler (void)
 
int initmouse (void)
 
int setgamemode (char davidoption, long daxdim, long daydim)
 Set the video mode. More...
 
int getceilzofslope (short sectnum, long dax, long day)
 Get the ceiling z value for a point in a sector. More...
 
int getflorzofslope (short sectnum, long dax, long day)
 Get the floor z value for a point in a sector. More...
 
void getzsofslope (short sectnum, long dax, long day, long *ceilz, long *florz)
 Get the floor and ceiling z values for a point. More...
 
void setaspect (long daxrange, long daaspect)
 Set aspect ratio and viewing range angle. More...
 
int insertsprite (short sectnum, short statnum)
 Insert a sprite into a sector. More...
 
void updatesector (long x, long y, short *sectnum)
 Update a sector pointer, given x and y values. More...
 
int lastwall (short point)
 Find the wall to the left of another wall. More...
 
void initspritelists (void)
 Set up the sprite lists. More...
 
int deletesprite (short spritenum)
 Delete a sprite from the map. More...
 
int insertspritesect (short sectnum)
 
int deletespritesect (short deleteme)
 
int deletespritestat (short deleteme)
 
int insertspritestat (short statnum)
 
int changespritesect (short spritenum, short newsectnum)
 
int changespritestat (short spritenum, short newstatnum)
 
void loadtile (short tilenume)
 Loads a tile into memory. More...
 
void setmmxoverlay (int isenabled)
 
int getmmxoverlay (void)
 
void nextpage (void)
 Flip to next drawing page. More...
 
void drawrooms (long daposx, long daposy, long daposz, short daang, long dahoriz, short dacursectnum)
 Draw the 3D screen to the current drawing page. More...
 
int loadboard (char *filename, long *daposx, long *daposy, long *daposz, short *daang, short *dacursectnum)
 Loads a map from disk. More...
 
void drawmasks (void)
 Draw the sprites and maskwalls to the current drawing page. More...
 
void printext256 (long xpos, long ypos, short col, short backcol, char name[82], char fontsize)
 Draws a text message to the screen. More...
 
void printext256_noupdate (long xpos, long ypos, short col, short backcol, char name[82], char fontsize)
 Draws a text message to the screen without refreshing. More...
 
void initengine (void)
 Initialize the Build Engine. More...
 
void uninitengine (void)
 Uninitialize the Build Engine. More...
 
int loadpics (char *filename)
 Loads an artwork file into the engine. More...
 
int saveboard (char *filename, long *daposx, long *daposy, long *daposz, short *daang, short *dacursectnum)
 Saves a map to disk. More...
 
void plotpixel (long x, long y, char col)
 Plots a pixel to the screen. More...
 
unsigned char getpixel (long x, long y)
 Returns the color of a pixel on screen. More...
 
void setbrightness (char dabrightness, unsigned char *dapal)
 Adjust the gamma of a VGA palette. More...
 
int screencapture (char *filename, char inverseit)
 Take a screenshot. More...
 
void getmousevalues (short *mousx, short *mousy, short *bstatus)
 Get the current mouse location and button state. More...
 
int clipmove (long *x, long *y, long *z, short *sectnum, long xvect, long yvect, long walldist, long ceildist, long flordist, unsigned long cliptype)
 Move an object using collision detection. More...
 
void getzrange (long x, long y, long z, short sectnum, long *ceilz, long *ceilhit, long *florz, long *florhit, long walldist, unsigned long cliptype)
 Find the highest and lowest z coordinates your clipping box can get to. More...
 
int getangle (long xvect, long yvect)
 Gets the angle of a vector. More...
 
void alignceilslope (short dasect, long x, long y, long z)
 Adjust the slope of a sector's ceiling to pass through a point. More...
 
void alignflorslope (short dasect, long x, long y, long z)
 Adjust the slope of a sector's floor to pass through a point. More...
 
int hitscan (long xs, long ys, long zs, short sectnum, long vx, long vy, long vz, short *hitsect, short *hitwall, short *hitsprite, long *hitx, long *hity, long *hitz, unsigned long cliptype)
 Project a ray and report what it hit. More...
 
int inside (long x, long y, short sectnum)
 Tests to see if a 2d point is in a sector. More...
 
void setfirstwall (short sectnum, short newfirstwall)
 Sets the first wall of a sector. More...
 
void rotatepoint (long xpivot, long ypivot, long x, long y, short daang, long *x2, long *y2)
 Rotate / translate a point. More...
 
int drawtilescreen (long pictopleft, long picbox)
 Draw the tile screen. More...
 
void clearview (long dacol)
 Clear the current video page to a given color. More...
 
void clearallviews (long dacol)
 Clear all video pages to a given color. More...
 
void draw2dgrid (long posxe, long posye, short ange, long zoome, short gride)
 Draw a 2D grid. More...
 
void draw2dscreen (long posxe, long posye, short ange, long zoome, short gride)
 Draw the 2D screen. More...
 
int sectorofwall (short theline)
 A fast routine to find the sector that owns a certain wall. More...
 
int setsprite (short spritenum, long newx, long newy, long newz)
 Puts a sprite somewhere, without checking for validity. More...
 
void dragpoint (short pointhighlight, long dax, long day)
 Drag a wall to a new point. More...
 
int ksqrt (long num)
 Integer Square Root Function. More...
 
int loopnumofsector (short sectnum, short wallnum)
 Find number of walls in sector, up to a known wall. More...
 
int cansee (long x1, long y1, long z1, short sect1, long x2, long y2, long z2, short sect2)
 Check if two points can see each other. More...
 
int lintersect (long x1, long y1, long z1, long x2, long y2, long z2, long x3, long y3, long x4, long y4, long *intx, long *inty, long *intz)
 
int rintersect (long x1, long y1, long z1, long vx, long vy, long vz, long x3, long y3, long x4, long y4, long *intx, long *inty, long *intz)
 
int allocatepermanenttile (short tilenume, long xsiz, long ysiz)
 Allocate a tile permanently. More...
 
void drawline256 (long x1, long y1, long x2, long y2, unsigned char col)
 Draw a line. More...
 
void copytilepiece (long tilenume1, long sx1, long sy1, long xsiz, long ysiz, long tilenume2, long sx2, long sy2)
 Copy a piece of a tile to another tile, skipping transparent pixels. More...
 
int nextsectorneighborz (short sectnum, long thez, short topbottom, short direction)
 Find the next closest ceiling or floor in surrounding sectors. More...
 
int neartag (long xs, long ys, long zs, short sectnum, short ange, short *neartagsector, short *neartagwall, short *neartagsprite, long *neartaghitdist, long neartagrange, char tagsearch)
 Find the closest objects with tags the player is pointing at. More...
 
int pushmove (long *x, long *y, long *z, short *sectnum, long walldist, long ceildist, long flordist, unsigned long cliptype)
 Try to keep object away from wall. More...
 
int krand (void)
 Returns a random number. More...
 
void flushperms (void)
 
void 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)
 Rotate and draw a sprite on the screen. More...
 
void makepalookup (long palnum, char *remapbuf, signed char r, signed char g, signed char b, char dastat)
 Make a lookup table for remapping. More...
 
void drawmapview (long dax, long day, long zoome, short ang)
 Draw the overhead textured map view. More...
 
void setview (long x1, long y1, long x2, long y2)
 Sets the viewing window for 3D mode. More...
 
void setviewtotile (short tilenume, long xsiz, long ysiz)
 Shows a tile on screen, saving the previous view. More...
 
void setviewback (void)
 Shows the screen as it was previous to the last setviewtotile. More...
 
void squarerotatetile (short tilenume)
 Rotates a tile's image. More...
 
void preparemirror (long dax, long day, long daz, short daang, long dahoriz, short dawall, short dasector, long *tposx, long *tposy, short *tang)
 
void completemirror (void)
 
int clipinsidebox (long x, long y, short wallnum, long walldist)
 Check if a clipping box intersects a wall. More...
 
void qloadkvx (long voxindex, char *filename)
 Load a voxel. More...
 

Detailed Description

Main engine include file.

A list of all symbols exported from engine.c for a game's use.

Function Documentation

void alignceilslope ( short  dasect,
long  x,
long  y,
long  z 
)

Adjust the slope of a sector's ceiling to pass through a point.

This function will cause the slope of a sector to change and the sector plane to pass through the point specified.

Parameters
dasectThe sector to modify.
xThe X coordinate to intersect.
yThe Y coordinate to intersect.
zThe Z coordinate to intersect.
Remarks
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.
void alignflorslope ( short  dasect,
long  x,
long  y,
long  z 
)

Adjust the slope of a sector's floor to pass through a point.

This function will cause the slope of a sector to change and the sector plane to pass through the point specified.

Parameters
dasectThe sector to modify.
xThe X coordinate to intersect.
yThe Y coordinate to intersect.
zThe Z coordinate to intersect.
Remarks
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 sine-wave floors.
int allocatepermanenttile ( short  tilenume,
long  xsiz,
long  ysiz 
)

Allocate a tile permanently.

This function allocates a place on the cache as permanent.

Parameters
tilenumeThe tile number to associate with the memory.
xsizThe width to allocate.
ysizThe height to allocate.
Remarks
Ken's Notes on this function:
Right now, I reset the cache every time you call this function so I would recommend calling this function right after loadpics.
int cansee ( long  x1,
long  y1,
long  z1,
short  sect1,
long  x2,
long  y2,
long  z2,
short  sect2 
)

Check if two points can see each other.

This function will determine whether there is a line of sight between two points.

Parameters
x1X coordinate of point 1.
y1Y coordinate of point 1.
z1Z coordinate of point 1.
sect1Point 1's sector.
x2X coordinate of point 2.
y2Y coordinate of point 2.
z2Z coordinate of point 2.
sect2Point 2's sector.
void clearallviews ( long  dacol)

Clear all video pages to a given color.

This function clears all the video pages to the color dacol.

Parameters
dacolThe color to clear to.
void clearview ( long  dacol)

Clear the current video page to a given color.

This function clears the current video page to the color dacol.

Parameters
dacolThe color to clear to.
int clipinsidebox ( long  x,
long  y,
short  wallnum,
long  walldist 
)

Check if a clipping box intersects a wall.

This function will test if a box intersects a wall.
It returns TRUE if an intersection ocurrs.

Parameters
xCenter of box X.
yCenter of box Y.
wallnumWall to test against.
walldistRadius of clipping box.
Returns
TRUE if an intersection ocurred.
int clipmove ( long *  x,
long *  y,
long *  z,
short *  sectnum,
long  xvect,
long  yvect,
long  walldist,
long  ceildist,
long  flordist,
unsigned long  cliptype 
)

Move an object using collision detection.

This function will move any object at any velocity and make sure the object stays a certain distance from walls.

Parameters
*xA pointer to the object's X coordinate.
*yA pointer to the object's Y coordinate.
*zA pointer to the object's Z coordinate.
*sectnumA pointer to the object's current sector.
xvectThe desired X velocity of movement.
yvectThe desired Y velocity of movement.
walldistThe distance the object should stay away from walls.
ceildistThe distance the object should stay away from the ceiling.
flordistThe distance the object should stay away from the floor.
cliptypeSee description below.
Returns
Status of clipping:
  • 0 – Nothing was touched.
  • 32768+wallnum – Wall first touched.
  • 49152+wallnum – Sprite first touched.
Remarks
Notes on this function:
xvect and yvect are calculated with the following equations:
  • xvect = velocity * cos(angle)
  • yvect = velocity * sin(angle)
Ken uses 128 for walldist as his default.
Don't suddenly increase walldist – it may cause an object to go throught the wall!
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.
void copytilepiece ( long  tilenume1,
long  sx1,
long  sy1,
long  xsiz,
long  ysiz,
long  tilenume2,
long  sx2,
long  sy2 
)

Copy a piece of a tile to another tile, skipping transparent pixels.

This function will copy a piece of tilenume1 into tilenume2, skipping transparent parts. If the source coordinates are larger than the source tile, the texture will automatically wrap around.
NOTE: IF THE MODIFIED TILE GETS REMOVED FROM THE CACHE, tilenume2 WILL BE RESET TO ITS ORIGINAL FORM.
IF YOU NEED TO KEEP THE TILE CREATED BY THIS FUNCTION, CALL allocatepermanenttile ON IT FIRST!

Parameters
tilenume1The source tile
sx1X coordinate to start the copy from
sy1Y coordinate to start the copy from.
xsizThe width to copy from the source.
ysizThe height to copy from the source.
tilenume2The destination tile.
sx2The X coordinate to paste at.
sy2The Y coordinate to paste at.
int deletesprite ( short  spritenum)

Delete a sprite from the map.

This function will delete a sprite.

Parameters
spritenumThe sprite number to delete.
void dragpoint ( short  pointhighlight,
long  dax,
long  day 
)

Drag a wall to a new point.

This function will reliabaly drag a point to a new location on the map, using a method identical to dragging the point in 2D edit mode.

Parameters
pointhighlightThe wall to drag.
daxThe X coordinate to drag to.
dayThe Y coordinate to drag to.
Remarks
Ken's Notes about this function: 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?
void draw2dgrid ( long  posxe,
long  posye,
short  ange,
long  zoome,
short  gride 
)

Draw a 2D grid.

This function is used by Build to draw the grid in 2D.
NOTE: This function works only in two graphics modes:
640*350*16col, 640*480*16col.

Parameters
posxeLeft side of visible grid.
posyeTop side of visible grid.
angeNot used.
zoomeZoom factor of grid.
grideThe grid's scale.
Remarks
Please do not use this function. It is only public because the build editor needs it.
void draw2dscreen ( long  posxe,
long  posye,
short  ange,
long  zoome,
short  gride 
)

Draw the 2D screen.

Thus function is used by build to draw the 2d screen.
See draw2dgrid for explanation.

Remarks
Please do not use this function. It is only public because the build editor needs it.
void drawline256 ( long  x1,
long  y1,
long  x2,
long  y2,
unsigned char  col 
)

Draw a line.

This function draws a colored, solid line.

Parameters
x1X coordinate of starting point.
y1Y coordinate of starting point.
x2X coordinate of ending point.
y2Y coordinate of ending point.
colColor to use.
void drawmapview ( long  dax,
long  day,
long  zoome,
short  ang 
)

Draw the overhead textured map view.

This function is used to draw the overhead textured map view.

Parameters
daxThe x coordinate to center on the map.
dayThe y coordinate to center on the map.
zoomeThe zoom to apply to the map.
angThe angle to rotate the map by.
void drawmasks ( void  )

Draw the sprites and maskwalls to the current drawing page.

This function will draw the visible sprites and masked walls to the current drawing page.

Remarks
Ken's Notes on this function:
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.
void drawrooms ( long  daposx,
long  daposy,
long  daposz,
short  daang,
long  dahoriz,
short  dacursectnum 
)

Draw the 3D screen to the current drawing page.

This function draws the current 3D screen to the current drawing page. Remember to call nextpage() to actually show the page on the screen!

Parameters
daposxX position of the camera.
daposyY position of the camera.
daposzZ position of the camera.
daangViewing angle of the camera.
dahoriz??? fixme
dacursectnumSector camera is currently in.
int drawtilescreen ( long  pictopleft,
long  picbox 
)

Draw the tile screen.

This function draws the tile chooser in Build. (what you get when you press "v".)

Parameters
pictopleftThe first tile to show.
picboxThe tile to highlight.
int getangle ( long  xvect,
long  yvect 
)

Gets the angle of a vector.

This function will return the angle closest to the vector you specify.
There are 2048 possible angles, starting from the right (3 o'clock), going clockwise.

Parameters
xvectThe x component.
yvectThe y component.
int getceilzofslope ( short  sectnum,
long  dax,
long  day 
)

Get the ceiling z value for a point in a sector.

This function returns the Z value of a ceiling at a point in the sector.

Parameters
sectnumThe sector to look in.
daxThe x coordinate to look in.
dayThe y coordinate to look in.
Returns
The z coordinate at that point.
int getflorzofslope ( short  sectnum,
long  dax,
long  day 
)

Get the floor z value for a point in a sector.

This function returns the Z value of a floor at a point in the sector.

Parameters
sectnumThe sector to look in.
daxThe x coordinate to look in.
dayThe y coordinate to look in.
Returns
The z coordinate.
void getmousevalues ( short *  mousx,
short *  mousy,
short *  bstatus 
)

Get the current mouse location and button state.

This function will store the current mouse position and the state of the mouse buttons in the pointers you give it.

Parameters
mousxA pointer to write the X position of the mouse to.
mousyA pointer to write the Y position of the mouse to.
bstatusA pointer to write the current state of the mouse buttons to.
Remarks
bstatus is a bitmask of the mouse states:
  • 1 – Left button is down.
  • 2 – Right button is down.
  • 4 – Middle button is down.
unsigned char getpixel ( long  x,
long  y 
)

Returns the color of a pixel on screen.

This function will find the color of a pixel in any graphics mode.
NOTE: This function is not designed to be fast! – Use it in moderation.

Parameters
xThe x cordinate of the pixel.
yThe y coordinate of the pixel.
Returns
The color of the pixel.
void getzrange ( long  x,
long  y,
long  z,
short  sectnum,
long *  ceilz,
long *  ceilhit,
long *  florz,
long *  florhit,
long  walldist,
unsigned long  cliptype 
)

Find the highest and lowest z coordinates your clipping box can get to.

This function finds the highest and lowest z coordinates your clipping box can get to.

Parameters
xX coordinate of location.
yY coordinate of location.
zZ coordinate of location.
sectnumCurrent sector.
*ceilzPointer to store Z extent of ceiling.
*florzPointer to store Z extent of floor.
*ceilhitFirst object hit in the up direction.
*florhitFirst object hit in the down direction.
walldistSize of your clipping box.
cliptypeSee description below.
Remarks
Notes on this function:
walldist is suggested to be 128.
ceilhit and florhit will be the following after the function call:
16384+sector (sector first touched) or
49152+spritenum (sprite first touched)
void getzsofslope ( short  sectnum,
long  dax,
long  day,
long *  ceilz,
long *  florz 
)

Get the floor and ceiling z values for a point.

This function finds the Z value of a floor and ceiling, and stores the values in two pointers.

Parameters
sectnumThe sector to look in.
daxThe x coordinate to look in.
dayThe y coordinate to look in.
*ceilzA pointer to write the ceiling z value to.
*florzA pointer to write the floor z value to.
int hitscan ( long  xs,
long  ys,
long  zs,
short  sectnum,
long  vx,
long  vy,
long  vz,
short *  hitsect,
short *  hitwall,
short *  hitsprite,
long *  hitx,
long *  hity,
long *  hitz,
unsigned long  cliptype 
)

Project a ray and report what it hit.

This function will project a ray in the direction specified by a 3D vector and report where and what the ray hit.

Parameters
xsStarting X position.
ysStarting Y position.
zsStarting Z position.
sectnumStarting sector.
vxX component of 3D vector.
vyY component of 3D vector.
vzZ component of 3D vector.
*hitsectThe sector that the intersection occured in.
*hitwallThe wall that got hit.
*hitspriteThe sprite that got hit.
*hitxThe X coordinate of the point that the intersection occured.
*hityThe Y coordinate of the point that the intersection occured.
*hitzThe Z coordinate of the point that the intersection occured.
cliptypeSee description below.
Remarks
Notes on this function:
HOW TO DETERMINE WHAT WAS HIT:
If the ray hits a sprite, then
  • hitsprite = thespritenumber.
  • hitwall = -1.
If the ray hits a wall, then
  • hitsprite = -1
  • hitwall = thewallnumber
If the ray hits the ceiling of a sector, then
  • 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
  • hitsprite = -1
  • hitwall = -1
  • vectorz > 0
  • (If vectorz > 0 then you're shooting downard which means that you couldn't have hit a ceiling)
void initengine ( void  )

Initialize the Build Engine.

This function initializes many variables for the Build Engine. You should call this function before using any other Build functions.

void initspritelists ( void  )

Set up the sprite lists.

This function will initialize the doubly-linked sprite sector and sprite status lists.

int insertsprite ( short  sectnum,
short  statnum 
)

Insert a sprite into a sector.

This function is used to insert a sprite into a sector.

Parameters
sectnumThe sector number to place the sprite into.
statnumThe sprite's status. (cstat)
Returns
The number assigned to the new sprite.
int inside ( long  x,
long  y,
short  sectnum 
)

Tests to see if a 2d point is in a sector.

This function will check if a 2d point is inside a sector.

Parameters
xX coordinate of point.
yY coordinate of point.
sectnumThe sector to test against.
int krand ( void  )

Returns a random number.

This function returns a pseudorandom number in the range 0-65535.

Returns
A random number.
int ksqrt ( long  num)

Integer Square Root Function.

This function will return an integer approximating the square root of a number.

Parameters
numThe number to work on.
Returns
The square root of num.
int lastwall ( short  point)

Find the wall to the left of another wall.

Use this function as a reverse function of wall[].point2.

Parameters
pointThe wall to search with.
Returns
The wall to the left of point.
int loadboard ( char *  filename,
long *  daposx,
long *  daposy,
long *  daposz,
short *  daang,
short *  dacursectnum 
)

Loads a map from disk.

This function loads a map from disk and stores the starting location in the pointers you pass. If no extention is given to filename, .MAP is assumed.

Parameters
filenameThe filename to load.
*daposxA pointer for the starting X coordinate.
*daposyA pointer for the starting Y coordinate.
*daposzA pointer for the starting Z coordinate.
*daangA pointer for the starting angle.
*dacursectnumA pointer for the starting sector.
Returns
-1 if the map is not found.
int loadpics ( char *  filename)

Loads an artwork file into the engine.

This function is used to load an artwork file into memory so the engine knows where to find the tiles referenced by the artwork file. If no extention is given to filename, .ART is assumed.

Parameters
*filenameThe name of the artwork file.
Returns
-1 if the file was not found.
void loadtile ( short  tilenume)

Loads a tile into memory.

This function will ensure tilenume is in memory.

Parameters
tilenumeThe tile to load.
Remarks
Ken's Notes on this function:
A tile is not in the cache if (waloff[tilenum] == 0)
int loopnumofsector ( short  sectnum,
short  wallnum 
)

Find number of walls in sector, up to a known wall.

This function will find the number of walls in a sector, up to the specified wall.

Parameters
sectnumThe sector to work on.
wallnumThe wall to stop on.
Returns
The number of walls in sectnum before wallnum, or -1 if wallnum does not occur in sectnum.
void makepalookup ( long  palnum,
char *  remapbuf,
signed char  r,
signed char  g,
signed char  b,
char  dastat 
)

Make a lookup table for remapping.

Ken's description of this function: This function allows different shirt colors for sprites. First prepare remapbuf, which is a 256 byte buffer of chars with 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 (it assumes you will create one yourself).

int neartag ( long  xs,
long  ys,
long  zs,
short  sectnum,
short  ange,
short *  neartagsector,
short *  neartagwall,
short *  neartagsprite,
long *  neartaghitdist,
long  neartagrange,
char  tagsearch 
)

Find the closest objects with tags the player is pointing at.

This function will get the nearest tagged objects. It is useful for door and switch activation code, among other things.

Parameters
xsX coordinate to search from.
ysY coordinate to search from.
zsZ coordinate to search from.
sectnumSector number to search from.
angeAngle to search from.
*neartagsectorThe nearest tagged sector.
*neartagwallThe nearest tagged wall.
*neartagspriteThe nearest tagged sprite.
*neartaghitdistDistance to the found object.
neartagrangeMaximum distance to search.
tagsearchWhat to search for.
Remarks
Notes on this function:
For tagsearch:
  • 1 = search lotag only.
  • 2 = search hitag only.
  • 3 = search both lotag and hitag.
void nextpage ( void  )

Flip to next drawing page.

This function flips to the next drawing page. After a page is prepared, use this function to show the it on the screen and set up the next one for drawing.

int nextsectorneighborz ( short  sectnum,
long  thez,
short  topbottom,
short  direction 
)

Find the next closest ceiling or floor in surrounding sectors.

This function will find the next closest ceiling or floor in the sectors surrounding the given sector. It is useful for calculating where elevators should stop.

Parameters
sectnumThe sector to test with
thezThe z coordinate to start the search from.
topbottomSearch ceilings/floors only.
directionSearch up/down.
Remarks
Notes:
topbottom: pass -1 to search ceilings, 1 to search floors.
direction: pass -1 to search upwards, 1 to search downwards.
void plotpixel ( long  x,
long  y,
char  col 
)

Plots a pixel to the screen.

This function can plot a pixel to the screen in any graphics mode.
NOTE: This function is not designed to be fast! Use it in moderation.

Parameters
xThe x coordinate of the pixel.
yThe y coordinate of the pixel.
colThe color of the pixel.
void printext256 ( long  xpos,
long  ypos,
short  col,
short  backcol,
char  name[82],
char  fontsize 
)

Draws a text message to the screen.

This function will draw a message to the screen using one of the built in fonts.

Parameters
xposX position of text.
yposY position of text.
colColor of text.
backcolBackground color of text, or -1 for transparency.
nameThe text to draw.
fontsizeThe font size. Legal values: 0 – 8x8 font. 1 – 4x6 font.
void printext256_noupdate ( long  xpos,
long  ypos,
short  col,
short  backcol,
char  name[82],
char  fontsize 
)

Draws a text message to the screen without refreshing.

This function will draw a message to the screen using one of the built in fonts. It will also avoid refreshing the screen. See Ryan's notes below.

Parameters
xposX position of text.
yposY position of text.
colColor of text.
backcolBackground color of text, or -1 for transparency.
nameThe text to draw.
fontsizeThe font size. Legal values: 0 – 8x8 font. 1 – 4x6 font.
Remarks
Ryan's notes on this function:
This is ryan's change. SDL requires me to call SDL_UpdateRect() to force vid updates without a SDL_Flip() call, but there's no such thing in the DOS version of this program, so text won't show up sometimes without my update call in Linux.
However, to get a nice shadow effect on some text, Ken draws a string at an offset and darker, and then on top of it draws the actual string.
Two SDL_UpdateRect() calls in over top of each other cause flicker, so I have this function here so the shadow can be drawn with _noupdate, and the actual string is draw with an update.
int pushmove ( long *  x,
long *  y,
long *  z,
short *  sectnum,
long  walldist,
long  ceildist,
long  flordist,
unsigned long  cliptype 
)

Try to keep object away from wall.

This function checks if an object is too close to a wall. If it is, it attempts to push it away. If it tries to push 256 times, and the object is still too close, it returns -1.

Parameters
*xObject's X coordinate.
*yObject's Y coordinate.
*zObject's Z coordinate.
*sectnumObject's sector.
walldistDistance to avoid walls by.
ceildistDistance to avoid ceilings by.
flordistDistane to avoid floors by.
cliptypeSee below.
Remarks
Notes on this function:
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.
void qloadkvx ( long  voxindex,
char *  filename 
)

Load a voxel.

This function will load a voxel that can be used to replace a sprite.
See notes below.

Parameters
voxindexThe voxel number to use.
*filenameThe voxel file to load.
Remarks
Ken's Notes on Using Voxels:
To actually display the voxel, you need to set the (sprite[?].cstat&48) to equal 48 like this:
sprite[?].cstat |= 48;
I have no special collision code for voxels. They are simply treated as face sprites.

You should set the sprite[?].picnum to equal the VOXEL index of the voxel that you passed to qloadkvx. If you don't do this you will see nothing. To handle this index remapping it is a good idea to make some array like this:
short picnumtovox[MAXTILES];
and save the array in some file (or in the .GRP file)
Many other fields of the sprite structure also affect voxels, such as: ang, shade, pal, xrepeat, yrepeat.

Note: To view voxels in the Build editor, you will need to do the same qloadkvx calls in your BSTUB.C.
And now a warning: Voxels tend to draw the fastest when they are tall and thin.
For example, a telephone pole would work just great.
They slow down very quickly as you add detail.
This is why you don't see any large voxels in SW and Blood.
void rotatepoint ( long  xpivot,
long  ypivot,
long  x,
long  y,
short  daang,
long *  x2,
long *  y2 
)

Rotate / translate a point.

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.

Parameters
xpivotX coordinate of point to pivot about.
ypivotY coordinate of point to pivot about.
xX coordinate of point to translate.
yY coordinate of point to translate.
daangAngle to rotate (CW, relative)
*x2X coordinate of the translated point.
*y2Y coordinate of the translated point.
void 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 
)

Rotate and draw a sprite on the screen.

This function will rotate and draw a sprite onto the screen. See notes for proper usage.

Parameters
sxX center of sprite to draw.
syY center of sprite to draw.
zZoom to draw with.
aAngle to draw at.
picnumThe tile to draw.
dashadeThe shade to draw with.
dapalnumThe palette to draw with.
dastatDrawing options.
cx1Upper left of screen clipping box X.
cy1Upper left of screen clipping box Y.
cx2Lower right of screen clipping box X.
cy2Lower right of screen clipping box Y.
Remarks
Ken's Notes on this function.
  • (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).
int saveboard ( char *  filename,
long *  daposx,
long *  daposy,
long *  daposz,
short *  daang,
short *  dacursectnum 
)

Saves a map to disk.

This function dumps the working map to disk, using the pointers you pass as the starting location. If no extention is given to filename, .MAP is assumed.

Parameters
filenameThe filename to save.
*daposxA pointer containing the starting X coordinate.
*daposyA pointer containing the starting Y coordinate.
*daposzA pointer containing the starting Z coordinate.
*daangA pointer containing the starting angle.
*dacursectnumA pointer containing the starting sector.
int screencapture ( char *  filename,
char  inverseit 
)

Take a screenshot.

This function will dump a picture of the current screen to a file.
Set inverseit to 1 if you want the colors inverted.

Parameters
*filenameThe filename to write to.
inverseitSet to 1 if you want the colors inverted.
Remarks
Notes on filename:
If you use "captxxxx.pcx" as your filename, Build will automatically replace the x's with an automatically incrementing number, starting from 0000.
int sectorofwall ( short  theline)

A fast routine to find the sector that owns a certain wall.

This function will find the sector that owns the wall theline.

Parameters
thelineThe wall to lookup.
Returns
The sector the wall belongs to.
void setaspect ( long  daxrange,
long  daaspect 
)

Set aspect ratio and viewing range angle.

This function sets the aspect ratio and viewing range angle of the engine. Used for weird video modes or special effects.

Parameters
daxrangeSets the viewing range angle.
daaspectSets the aspect ratio.
Remarks
Ken's Notes on this function:
------------------—
For a standard 90ø 320*200 screen, daxrange and daaspect are
  1. For square aspect ratio at 320*400, set daaspect to 131072. Since daxrange is actually zoom, you must modify the aspect ratio inversely if you only want to change the viewing angle.
    ------------------—
    [for daaspect] you pass the Y/X aspect ratio scaled up 16 bits, so 65536 would be normal. You don't need to call this if you don't want to. By default, in setview, I call setaspect with these parameters: setaspect(divscale16(ydim*320,xdim*200)); (also written as:) setaspect(((ydim*320)<<16)/(xdim*200)); Note that in 320*200 mode the value passed would be 65536 which is a 1:1 aspect ratio.
    ------------------—
    Since drawmapview is also affect by the aspect ratio, you will need to make sure drawoverheadmap is affected so the map modes match up. Please look at and copy my updated drawoverheadmap function into your GAME.C if you use it.
void setbrightness ( char  dabrightness,
unsigned char *  dapal 
)

Adjust the gamma of a VGA palette.

This function will adjust the brightness of colors in dapal.

Parameters
dabrightnessThe gamma level. Accepted range of 0-15, where 0 is the darkest and 15 is the lightest.
*dapalA pointer to a standard 768 byte VGA palette.
void setfirstwall ( short  sectnum,
short  newfirstwall 
)

Sets the first wall of a sector.

This function sets the first wall of a sector. It can be used to change the hinge wall of a slope, among other things.

Parameters
sectnumThe sector to modify.
newfirstwallThe wall to set as the first wall.
int setgamemode ( char  davidoption,
long  daxdim,
long  daydim 
)

Set the video mode.

This function sets the video mode. If you change the mode in your program, you must call this again to reset the mode before using the build drawing functions.

Parameters
davidoptionThe video modeset to use (0-6). Allowed options:
  • 0
  • 1 – VESA mode. Any VESA resolution is allowed.
  • 2
  • 3
  • 4
  • 5
  • 6
daxdimThe x resolution. (must be 320 if param 1 != 1.)
daydimThe y resolution. (must be 200 if param 1 != 1.)
int setsprite ( short  spritenum,
long  newx,
long  newy,
long  newz 
)

Puts a sprite somewhere, without checking for validity.

This function will move a sprite to anywhere on the map, regardless of whether the new place is valid.

Parameters
spritenumThe sprite to move.
newxThe X coordinate to move to.
newyThe Y coordinate to move to.
newzThe Z coordinate to move to.
void setview ( long  x1,
long  y1,
long  x2,
long  y2 
)

Sets the viewing window for 3D mode.

This function will cause the engine to draw the 3D view in a specified portion of the screen.

Parameters
x1upper left X coordinate.
y1upper left Y coordinate.
x2lower right X coordinate.
y2lower right Y coordinate.
Remarks
Example: For full screen 320*200, call like this: setview(0L,0L,319L,199L);
void setviewback ( void  )

Shows the screen as it was previous to the last setviewtotile.

This function will show the screen as it was before the last call to setviewtotile.

void setviewtotile ( short  tilenume,
long  xsiz,
long  ysiz 
)

Shows a tile on screen, saving the previous view.

This function will show a tile on screen, saving the previous view. You can call this multiple times, and calling setviewback will go to the last view. If you keep calling setback, you will eventually get back to your original screen. All drawing starts in the top left corner.

Parameters
tilenumeTile to show.
xsizX size to draw.
ysizY size to draw.
void squarerotatetile ( short  tilenume)

Rotates a tile's image.

This function will rotate the graphic of a tile. It only works with square tiles.

Parameters
tilenumeThe tile to perform the rotation on.
void uninitengine ( void  )

Uninitialize the Build Engine.

This function frees the buffers used by the build engine. You should call this function once before you end your program.

void updatesector ( long  x,
long  y,
short *  sectnum 
)

Update a sector pointer, given x and y values.

This function updates a pointer with the sector number occupied by an x and y value.

Parameters
xThe x coordinate to look up.
yThe y coordinate to look up.
*sectnumA pointer to the variable you want to write the result into.
Remarks
Ken's Notes on this function:
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 recommend using the setsprite function.