The Build Engine

- Main Page
- Classes
- Files

- File List
- File Members

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

  dasect | The sector to modify.
  x | The X coordinate to intersect.
  y | The Y coordinate to intersect.
  z | The 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

  dasect | The sector to modify.
  x | The X coordinate to intersect.
  y | The Y coordinate to intersect.
  z | The 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

  tilenume | The tile number to associate with the memory.
  xsiz | The width to allocate.
  ysiz | The 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

  x1 | X coordinate of point 1.
  y1 | Y coordinate of point 1.
  z1 | Z coordinate of point 1.
  sect1 | Point 1's sector.
  x2 | X coordinate of point 2.
  y2 | Y coordinate of point 2.
  z2 | Z coordinate of point 2.
  sect2 | Point 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

  dacol | The 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

  dacol | The 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

  x | Center of box X.
  y | Center of box Y.
  wallnum | Wall to test against.
  walldist | Radius 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

  *x | A pointer to the object's X coordinate.
  *y | A pointer to the object's Y coordinate.
  *z | A pointer to the object's Z coordinate.
  *sectnum | A pointer to the object's current sector.
  xvect | The desired X velocity of movement.
  yvect | The desired Y velocity of movement.
  walldist | The distance the object should stay away from walls.
  ceildist | The distance the object should stay away from the ceiling.
  flordist | The distance the object should stay away from the floor.
  cliptype | See 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

  tilenume1 | The source tile
  sx1 | X coordinate to start the copy from
  sy1 | Y coordinate to start the copy from.
  xsiz | The width to copy from the source.
  ysiz | The height to copy from the source.
  tilenume2 | The destination tile.
  sx2 | The X coordinate to paste at.
  sy2 | The Y coordinate to paste at.

int deletesprite | ( | short | spritenum | ) |

Delete a sprite from the map.

This function will delete a sprite.

Parameters

  spritenum | The 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

  pointhighlight | The wall to drag.
  dax | The X coordinate to drag to.
  day | The 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

  posxe | Left side of visible grid.
  posye | Top side of visible grid.
  ange | Not used.
  zoome | Zoom factor of grid.
  gride | The 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

  x1 | X coordinate of starting point.
  y1 | Y coordinate of starting point.
  x2 | X coordinate of ending point.
  y2 | Y coordinate of ending point.
  col | Color 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

  dax | The x coordinate to center on the map.
  day | The y coordinate to center on the map.
  zoome | The zoom to apply to the map.
  ang | The 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

  daposx | X position of the camera.
  daposy | Y position of the camera.
  daposz | Z position of the camera.
  daang | Viewing angle of the camera.
  dahoriz | ??? fixme
  dacursectnum | Sector 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

  pictopleft | The first tile to show.
  picbox | The 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

  xvect | The x component.
  yvect | The 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

  sectnum | The sector to look in.
  dax | The x coordinate to look in.
  day | The 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

  sectnum | The sector to look in.
  dax | The x coordinate to look in.
  day | The 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

  mousx | A pointer to write the X position of the mouse to.
  mousy | A pointer to write the Y position of the mouse to.
  bstatus | A 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

  x | The x cordinate of the pixel.
  y | The 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

  x | X coordinate of location.
  y | Y coordinate of location.
  z | Z coordinate of location.
  sectnum | Current sector.
  *ceilz | Pointer to store Z extent of ceiling.
  *florz | Pointer to store Z extent of floor.
  *ceilhit | First object hit in the up direction.
  *florhit | First object hit in the down direction.
  walldist | Size of your clipping box.
  cliptype | See 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

  sectnum | The sector to look in.
  dax | The x coordinate to look in.
  day | The y coordinate to look in.
  *ceilz | A pointer to write the ceiling z value to.
  *florz | A 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

  xs | Starting X position.
  ys | Starting Y position.
  zs | Starting Z position.
  sectnum | Starting sector.
  vx | X component of 3D vector.
  vy | Y component of 3D vector.
  vz | Z component of 3D vector.
  *hitsect | The sector that the intersection occured in.
  *hitwall | The wall that got hit.
  *hitsprite | The sprite that got hit.
  *hitx | The X coordinate of the point that the intersection occured.
  *hity | The Y coordinate of the point that the intersection occured.
  *hitz | The Z coordinate of the point that the intersection occured.
  cliptype | See 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

  sectnum | The sector number to place the sprite into.
  statnum | The 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

  x | X coordinate of point.
  y | Y coordinate of point.
  sectnum | The 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

  num | The 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

  point | The 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

  filename | The filename to load.
  *daposx | A pointer for the starting X coordinate.
  *daposy | A pointer for the starting Y coordinate.
  *daposz | A pointer for the starting Z coordinate.
  *daang | A pointer for the starting angle.
  *dacursectnum | A 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

  *filename | The 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

  tilenume | The 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

  sectnum | The sector to work on.
  wallnum | The 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

  xs | X coordinate to search from.
  ys | Y coordinate to search from.
  zs | Z coordinate to search from.
  sectnum | Sector number to search from.
  ange | Angle to search from.
  *neartagsector | The nearest tagged sector.
  *neartagwall | The nearest tagged wall.
  *neartagsprite | The nearest tagged sprite.
  *neartaghitdist | Distance to the found object.
  neartagrange | Maximum distance to search.
  tagsearch | What 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

  sectnum | The sector to test with
  thez | The z coordinate to start the search from.
  topbottom | Search ceilings/floors only.
  direction | Search 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

  x | The x coordinate of the pixel.
  y | The y coordinate of the pixel.
  col | The 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

  xpos | X position of text.
  ypos | Y position of text.
  col | Color of text.
  backcol | Background color of text, or -1 for transparency.
  name | The text to draw.
  fontsize | The 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

  xpos | X position of text.
  ypos | Y position of text.
  col | Color of text.
  backcol | Background color of text, or -1 for transparency.
  name | The text to draw.
  fontsize | The 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

  *x | Object's X coordinate.
  *y | Object's Y coordinate.
  *z | Object's Z coordinate.
  *sectnum | Object's sector.
  walldist | Distance to avoid walls by.
  ceildist | Distance to avoid ceilings by.
  flordist | Distane to avoid floors by.
  cliptype | See 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

  voxindex | The voxel number to use.
  *filename | The 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

  xpivot | X coordinate of point to pivot about.
  ypivot | Y coordinate of point to pivot about.
  x | X coordinate of point to translate.
  y | Y coordinate of point to translate.
  daang | Angle to rotate (CW, relative)
  *x2 | X coordinate of the translated point.
  *y2 | Y 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

  sx | X center of sprite to draw.
  sy | Y center of sprite to draw.
  z | Zoom to draw with.
  a | Angle to draw at.
  picnum | The tile to draw.
  dashade | The shade to draw with.
  dapalnum | The palette to draw with.
  dastat | Drawing options.
  cx1 | Upper left of screen clipping box X.
  cy1 | Upper left of screen clipping box Y.
  cx2 | Lower right of screen clipping box X.
  cy2 | Lower 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

  filename | The filename to save.
  *daposx | A pointer containing the starting X coordinate.
  *daposy | A pointer containing the starting Y coordinate.
  *daposz | A pointer containing the starting Z coordinate.
  *daang | A pointer containing the starting angle.
  *dacursectnum | A 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

  *filename | The filename to write to.
  inverseit | Set 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

  theline | The 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

  daxrange | Sets the viewing range angle.
  daaspect | Sets 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

  dabrightness | The gamma level. Accepted range of 0-15, where 0 is the darkest and 15 is the lightest.
  *dapal | A 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

  sectnum | The sector to modify.
  newfirstwall | The 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

  davidoption | The video modeset to use (0-6). Allowed options: `0` – `1` – VESA mode. Any VESA resolution is allowed. `2` – `3` – `4` – `5` – `6` –
  daxdim | The x resolution. (must be 320 if param 1 != 1.)
  daydim | The 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

  spritenum | The sprite to move.
  newx | The X coordinate to move to.
  newy | The Y coordinate to move to.
  newz | The 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

  x1 | upper left X coordinate.
  y1 | upper left Y coordinate.
  x2 | lower right X coordinate.
  y2 | lower 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

  tilenume | Tile to show.
  xsiz | X size to draw.
  ysiz | Y 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

  tilenume | The 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

  x | The x coordinate to look up.
  y | The y coordinate to look up.
  *sectnum | A 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.