Function Index

Between the game code and the C library routines used by the game code, there are 271 functions defined and documented in this project. This is a centralized, alphabetical (A–Z, a–z) index of all of these functions, their definitions, a brief description of their purpose, and a link to the page section that describes each in greater detail.

Note: Due to the extraction technique used, symbols with non-external visibility will not show address or size information. Each symbol’s size is a best-effort guess based on the distance to the next known symbol, and in some cases this may overestimate the size due to either non-visible symbols or padding inserted by the compiler/linker.

ActBarrel() »

void ActBarrel(word index);

The tick function for every barrel and basket actor. It takes the index of the current actor in the actors array.

ActFootSwitch() »

void ActFootSwitch(word index);

The tick function for every foot switch actor. It takes the index of the current actor in the actors array.

AdLibService() »

void AdLibService(void);

Streams chunks of music data to the AdLib hardware at the appropriate time.

AddScore() »

void AddScore(dword points);

Wraps DrawStatusBarScore() with the correct X,Y position for display on the screen. It adds points to the player’s score and updates the status bar with the new value.

AddScoreForSprite() »

void AddScoreForSprite(word sprite_type);

Determines how many points should be added to the player’s score for defeating an actor of a given sprite_type, and adds that amount.

AdjustActorMove() »

void AdjustActorMove(word index, word dir);

Verifies the legality of a map position that the actor (identified by slot index) has just moved into and reverts/adjusts their position accordingly. dir should be either DIR4_WEST or DIR4_EAST to match the direction of movement.

AnimatePalette() »

void AnimatePalette(void);

Cycles through any palette animations that have been requested by the map.

CanExplode() »

bool CanExplode(word sprite_type, word frame, word x_origin, word y_origin);

Returns true if a sprite (consisting of a sprite_type and a frame) is able to be destroyed by any explosion. If so, destruction shards and effects are inserted at (x_origin, y_origin) and points are awarded to the score, but the target actor is not destroyed.

CheckHighScoreAndShow() »

void CheckHighScoreAndShow(void);

Scans the high score table for a position where the current gameScore could be sorted. If a position is located, a prompt is presented asking for a name to be associated with the score at that position, and all inferior scores are shifted one position lower. The tenth score falls off the bottom of the list. Calls ShowHighScoreTable() unconditionally before returning.

ClearGameScreen() »

void ClearGameScreen(void);

Clears all content from both draw pages of the EGA’s memory and redraws a fresh status bar.

ClearPlayerDizzy() »

void ClearPlayerDizzy(void);

Resets all the global variables related to the player’s “dizziness” immobilization, immediately returning the player to normal state.

ClearPlayerPush() »

void ClearPlayerPush(void);

Immediately cancels any push the player may be experiencing, and returns the game state back to regular player control.

ClearScreen() »

void ClearScreen(void);

Overwrites the EGA memory for the current draw page with solid black tiles.

ConstructActor() »

void ConstructActor(word sprite_type, word x_origin, word y_origin, bool force_active, bool stay_active, bool weighted, bool acrophile, ActorTickFunction tick_func, word data1, word data2, word data3, word data4, word data5);

Called by NewActorAtIndex() as a helper to initialize each member of an Actor structure. The actor slot position is provided in the pass-by-global nextActorIndex variable, and the structure at that position is initialized according to the values passed in the arguments.

CopyTilesToEGA() »

void CopyTilesToEGA(byte *source, word dest_length, word dest_offset);

Reads solid tile image data from the memory pointed to by source, and installs it into a block of dest_length bytes of the EGA’s memory starting at dest_offset. Because the destination memory is planar, each byte of address space covered by dest_length consumes four bytes from source.

DRAW_SOLID_TILE_XY() »

#define DRAW_SOLID_TILE_XY(src, x, y) { \
    DrawSolidTile((src), (x) + ((y) * 320)); \
}

Wraps a call to DrawSolidTile(), converting x and y tile coordinates into the linear offset form expected by that function.

DestroyBarrel() »

void DestroyBarrel(word index);

Handles the animation, sound effects, and lifecycle management at the instant a barrel or basket is destroyed.

DetectAdLib() »

bool DetectAdLib(void);

Interrogates the default AdLib I/O address to check if one is installed, and initializes the hardware if it is there. Returns true if an AdLib is installed, and false otherwise.

DrawCartoon() »

void DrawCartoon(byte frame, word x_origin, word y_origin);

Draws a cartoon having the provided frame number, with the lower-left tile at coordinates (x_origin, y_origin).

DrawExplosions() »

void DrawExplosions(void);

Draws the animation sequence for each active explosion, along with the starting/ending decorations and the flashing palette effect if enabled. This function will cause the player to become hurt if they are in close proximity to any active explosions.

DrawFountains() »

void DrawFountains(void);

Iterates through every fountain active on the map and draws the sprites that they are built from. If the player is touching any part of the stream beneath the spray at the top of the fountain, damage is inflicted on the player.

DrawFullscreenImage() »

void DrawFullscreenImage(word image_num);

Loads and displays the full-screen image identified by image_num, fading the screen contents between what has already been drawn and the new image. If the requested image_num is anything other than IMAGE_TITLE or IMAGE_CREDITS, any playing music is stopped.

DrawFullscreenText() »

void DrawFullscreenText(char *entry_name);

Draws a page of B800 text to the screen and clears space for the DOS prompt.

DrawLights() »

void DrawLights(void);

Iterates through all the lights present on the current map and draws any that are currently scrolled into view. If areLightsActive is false, this function does nothing.

DrawMainMenu() »

void DrawMainMenu(void);

A small helper that draws the main menu frame and text, but does not do any input handling. It is only called from TitleLoop().

DrawMapRegion() »

void DrawMapRegion(void);

Draws one complete frame of the static game world to the current draw page. This includes the solid and masked tiles read from the map data and the scrolling backdrop.

DrawMaskedTile() »

void DrawMaskedTile(byte *src, word x, word y);

Copies an 8×8 pixel masked tile from the byte pointer src minus 16,000 to the video memory tile location identified by column x and row y.

DrawNumberFlushRight() »

void DrawNumberFlushRight(word x_origin, word y_origin, dword value);

Draws a numeric value with the rightmost (least significant) digit anchored at screen coordinates (x_origin, y_origin). value is interpreted as an unsigned long integer.

DrawPlayer() »

void DrawPlayer(byte frame, word x_origin, word y_origin, word mode);

Draws a player sprite having the provided frame number, with the lower-left tile at coordinates (x_origin, y_origin). mode is a DRAW_MODE_* that influences the drawing behavior.

DrawRandomEffects() »

void DrawRandomEffects(void);

Adds random decorative effects to the game world based on what is currently visible on the screen. It randomly applies a sparkling effect to map tiles that have the “slippery” attribute, and adds raindrops (if rain is enabled on the map) in any unoccupied areas at the top edge of the screen.

DrawSBarHealthHelper() »

void DrawSBarHealthHelper(void);

Wraps DrawStatusBarHealth() with the correct X,Y position for display on the screen.

DrawScancodeCharacter() »

void DrawScancodeCharacter(word x, word y, byte scancode);

Draws a single-character representation of scancode at screen tile position (x, y).

DrawSolidTile() »

void DrawSolidTile(word src_offset, word dst_offset);

Copies an 8×8 pixel solid tile from the tile storage area byte offset src_offset to the video memory byte offset dst_offset. Both offsets refer to locations within the EGA’s memory space. The EGA hardware must be in “latched write” mode for this function to work correctly.

DrawSprite() »

void DrawSprite(
    word sprite_type, word frame, word x_origin, word y_origin, word mode
);

Draws a sprite of the provided sprite_type and frame, with the lower-left tile at coordinates (x_origin, y_origin). The mode influences the origin calculations and visual appearance.

DrawSpriteTile() »

void DrawSpriteTile(byte *src, word x, word y);

Copies an 8×8 pixel masked tile from the byte pointer src to the video memory tile location identified by column x and row y.

DrawSpriteTileFlipped() »

void DrawSpriteTileFlipped(byte *src, word x, word y);

Copies a vertically-flipped 8×8 pixel masked tile from the byte pointer src to the video memory tile location identified by column x and row y.

DrawSpriteTileTranslucent() »

void DrawSpriteTileTranslucent(byte *src, word x, word y);

Copies a translucent outline of an 8×8 pixel masked tile from the byte pointer src to the video memory tile location identified by column x and row y.

DrawSpriteTileWhite() »

void DrawSpriteTileWhite(byte *src, word x, word y);

Copies a solid white outline of an 8×8 pixel masked tile from the byte pointer src to the video memory tile location identified by column x and row y.

DrawStaticGameScreen() »

void DrawStaticGameScreen(void);

Initializes the static components of the game screen by clearing everything from the current draw page and redrawing the status bar on the freshly-cleared screen. The current score, health, bombs, and stars values are drawn onto the status bar in the process.

DrawStatusBarBombs() »

void DrawStatusBarBombs(word x_origin, word y_origin);

Updates the “bombs” counter in the status bar. Requires x_origin and y_origin for positioning, which anchors the single digit at an absolute tile position on the screen.

DrawStatusBarHealth() »

void DrawStatusBarHealth(word x_origin, word y_origin);

Updates the health bars in the status bar. Requires x_origin and y_origin for positioning, which anchors the top of the rightmost bar at an absolute tile position on the screen.

DrawStatusBarScore() »

void DrawStatusBarScore(dword add_points, word x_origin, word y_origin);

Increments the player’s score by add_points then updates the score counter in the status bar. Requires x_origin and y_origin for positioning, which anchors the rightmost (least significant) digit at an absolute tile position on the screen.

DrawStatusBarStars() »

void DrawStatusBarStars(word x_origin, word y_origin);

Updates the “stars” counter in the status bar. Requires x_origin and y_origin for positioning, which anchors the rightmost (least significant) digit at an absolute tile position on the screen.

DrawTextFrame() »

word DrawTextFrame(
    word left, word top, int height, int width, char *top_text,
    char *bottom_text, bbool centered
);

Draws an empty text frame to the current draw page with the upper-left corner at tile position (left, top) and a total size of width×height tiles. The top and bottom edges of the frame are prefilled with top_text and bottom_text respectively, aligned according to the centered flag. Returns the X tile coordinate of the inside-left edge of the frame.

DrawTextLine() »

void DrawTextLine(word x_origin, word y_origin, char *text);

Draws a single line of text with the first character anchored at screen coordinates (x_origin, y_origin). A limited form of markup is supported to allow insertion of cartoon images, player/actor sprites, and text animation effects.

EGA_BIT_MASK_DEFAULT() »

#define EGA_BIT_MASK_DEFAULT() { outport(0x03ce, (0xff << 8) | 0x08); }

Resets the EGA’s bit mask to its default state.

EGA_MODE_DEFAULT() »

#define EGA_MODE_DEFAULT() { outport(0x03ce, (0x00 << 8) | 0x05); }

Resets the EGA’s read and write modes to their default state.

EGA_MODE_LATCHED_WRITE() »

#define EGA_MODE_LATCHED_WRITE() { \
    outport(0x03c4, (0x0f << 8) | 0x02); \
    outport(0x03ce, (0x01 << 8) | 0x05); \
}

Resets the EGA’s map mask to its default state and enables latched writes from the CPU.

EraseWaitSpinner() »

void EraseWaitSpinner(word x, word y);

Erases an area previously occupied by a wait spinner by drawing a tile of solid dark gray at screen tile position (x, y).

ExitClean() »

void ExitClean(void);

Cleans up game state and exits back to DOS.

FadeIn() »

void FadeIn(void);

Calls FadeInCustom() with a fixed delay of three game ticks per palette entry.

FadeInCustom() »

void FadeInCustom(word delay);

“Fades” the screen image into view by rebuilding the EGA’s default palette, one entry at a time, pausing delay game ticks between each entry.

FadeOut() »

void FadeOut(void);

Calls FadeOutCustom() with a fixed delay of three game ticks per palette entry.

FadeOutAdLibPlayback() »

void FadeOutAdLibPlayback(void);

Nominally fades any playing music to silence over a period of time, but as implemented it simply cuts the music off immediately.

FadeOutCustom() »

void FadeOutCustom(word delay);

“Fades” the screen image away by incrementally blanking the EGA’s palette to black, one entry at a time, pausing delay game ticks between each entry.

FadeWhiteCustom() »

void FadeWhiteCustom(word delay);

“Fades” the screen image away by incrementally blanking the EGA’s palette to white, one entry at a time, pausing delay game ticks between each entry.

GameLoop() »

void GameLoop(byte demo_state);

Runs once for each frame of gameplay and is responsible for running the appropriate sub-functions for timing, input, player/actor movement, world drawing, and level exit conditions. This function takes a demo_state argument which should be one of the DEMO_STATE_* constants – this controls the presence of the “DEMO” overlay sprite and is passed through to the input handling functions.

GameRand() »

word GameRand(void);

Returns a pseudorandom number based on a fixed table of randomness combined with influence from the player and scrolling game window positions. The output sequence from this function is deterministic for a given sequence of player and scroll positions.

GetMapTile() »

word GetMapTile(word x, word y);

Returns the data for a single map tile positioned at horizontal position x and vertical position y.

GetProcessorType() »

word GetProcessorType(void);

Tests the system processor and returns a value indicating its model. Returns CPU_TYPE_*.

GroupEntryFp() »

FILE *GroupEntryFp(char *entry_name);

Returns a file stream pointer to the data that a group file’s entry_name refers to.

GroupEntryLength() »

dword GroupEntryLength(char *entry_name);

Locates a group file entry_name and returns the size of its data in bytes.

HurtPlayer() »

void HurtPlayer(void);

Deducts a bar of health from the player, and kills them if they have lost enough health.

InitializeBackdropTable() »

void InitializeBackdropTable(void);

Fills the backdropTable[] array with four identical copies of backdrop tile offset data.

InitializeDecorations() »

void InitializeDecorations(void);

Clears all of the memory slots used to store decoration state, immediately terminating all incomplete decoration animations and making each slot available for use.

InitializeEpisode() »

void InitializeEpisode(void);

Sets up the initial values for a few of the episode-related global variables tracked by the game. This sets up the initial score, health, level number, etc. when a new game is started.

InitializeExplosions() »

void InitializeExplosions(void);

Clears all of the memory slots used to store explosion state, immediately terminating all incomplete explosion animations and making each slot available for use.

InitializeInterruptRate() »

void InitializeInterruptRate(void);

Sets up the system timer interrupt rate depending on whether or not the AdLib hardware is enabled.

InitializeLevel() »

void InitializeLevel(word level_num);

Initializes all of the global variables and related subsystems for the start (or restart) of the level identified by level_num.

InitializeMapGlobals() »

void InitializeMapGlobals();

Resets many of the global variables pertaining to player movement and map/actor interactivity.

InitializeShards() »

void InitializeShards(void);

Clears all of the memory slots used to store shard state, immediately terminating all incomplete shard animations and making each slot available for use.

InitializeSpawners() »

void InitializeSpawners(void);

Clears all of the memory slots used to store spawner state, immediately terminating all incomplete spawner animations and making each slot available for use.

InnerMain() »

void InnerMain(int argc, char *argv[]);

Main game function, once CPU testing has passed.

InteractPlayer() »

bool InteractPlayer(word index, word sprite_type, word frame, word x, word y);

Tests for a potential interaction between an actor located at position index in the actors array and the player. The actor’s sprite_type, frame, x, and y must all be passed, and should agree with the values currently held in the actor’s memory structure. Returns true if the actor should not be drawn due to being hidden, destroyed, or picked up.

IsAdLibAbsent() »

bbool IsAdLibAbsent(void);

Returns true if an AdLib or compatible card was NOT detected in the system.

IsAnyKeyDown() »

bbool IsAnyKeyDown(void);

Returns true if any key is currently pressed, without regard to which key it is.

IsIntersecting() »

bool IsIntersecting(
    word sprite1, word frame1, word x1, word y1,
    word sprite2, word frame2, word x2, word y2
);

Returns true if one sprite (consisting of a sprite type and a frame) located at an x/y position on the map is intersecting any part of a second sprite passed in the same form.

IsNearExplosion() »

bool IsNearExplosion(
    word sprite_type, word frame, word x_origin, word y_origin
);

Returns true if a sprite (consisting of a sprite_type and a frame) located at (x_origin, y_origin) is intersecting any active explosion.

IsNewBackdrop() »

bbool IsNewBackdrop(word backdrop_num);

Tracks the most recently used backdrop number and horizontal/vertical scroll flags. The scroll flags are read from global variables, but the backdrop number being tested must be passed in backdrop_num. Returns true if these have changed since the previous call, or false if none of the tracked variables have changed.

IsSpriteVisible() »

bool IsSpriteVisible(
    word sprite_type, word frame, word x_origin, word y_origin
);

Returns true if the provided sprite_type and frame located at x_origin and y_origin is at least partially visible within the scrolling game window.

IsTouchingPlayer() »

IsTouchingPlayer(word sprite_type, word frame, word x_origin, word y_origin);

Returns true if the passed sprite_type and frame located at x_origin and y_origin is touching any part of the player sprite at its current position.

JoinPath() »

char *JoinPath(char *dir, char *file);

Combines a string dir with a string file, creating and returning an absolute pathname.

KeyboardInterruptService() »

void interrupt KeyboardInterruptService(void);

Maintains the state of the keyboard variables. Called in response to the keyboard interrupt event.

LightenScreenTile() »

void LightenScreenTile(word x, word y);

Lightens the entire area at the video memory tile location identified by column x and row y.

LightenScreenTileEast() »

void LightenScreenTileEast(word x, word y);

Lightens the lower-left half of an 8×8 tile at the video memory tile location identified by column x and row y.

LightenScreenTileWest() »

void LightenScreenTileWest(word x, word y);

Lightens the lower-right half of an 8×8 tile at the video memory tile location identified by column x and row y.

LoadActorTileData() »

void LoadActorTileData(char *entry_name);

Loads actor tile data into system memory.

LoadBackdropData() »

void LoadBackdropData(char *entry_name, byte *scratch);

Reads backdrop data from the passed group file entry_name and installs it into the appropriate location in the EGA memory. If horizontal and/or vertical scrolling is enabled in the map variables, additional copies are loaded into the EGA memory to facilitate sub-tile parallax scrolling. A scratch buffer is required, which must be large enough to hold two complete copies of backdrop data plus an additional 640 bytes.

LoadCartoonData() »

void LoadCartoonData(char *entry_name);

Loads the cartoon masked tile image data from the group file entry_name.

LoadConfigurationData() »

void LoadConfigurationData(char *filename);

Loads and parses the contents of the configuration file named filename into several global variables.

LoadDemoData() »

void LoadDemoData(void);

Copies the data from the PREVDEMO.MNI group file entry into system memory.

LoadFontTileData() »

void LoadFontTileData(char *entry_name, byte *dest, word length);

Loads font data into system memory.

LoadGameState() »

bbool LoadGameState(char slot_char);

Reads the current state of the most important player variables from a file on disk, whose filename extension is influenced by the character provided in slot_char. If the file cannot be loaded, returns false. If the file’s internal anti-tampering checksum does not match, an error message is displayed and the program exits. Otherwise, returns true.

LoadGroupEntryData() »

void LoadGroupEntryData(char *entry_name, byte *dest, word length);

Reads data from an entry_name inside a group file and stores it in the memory block pointed to by dest. length controls how much data is copied.

LoadInfoData() »

void LoadInfoData(char *entry_name, word *dest, word length);

Reads a group file entry_name containing “info” data into the memory block pointed to by dest.

LoadMapData() »

void LoadMapData(word level_num);

Reads the map file associated with the passed level_num and initializes the global variables that are most affected by a map file’s contents.

LoadMaskedTileData() »

void LoadMaskedTileData(char *entry_name);

Loads data from the group file entry named entry_name and stores it in the masked tile data block.

LoadMusicData() »

Music *LoadMusicData(word music_num, Music *dest);

Opens music data from a group file entry (whose name is indexed by a numerical music_num), loads the data into the Music structure pointed to by dest, and prepares the AdLib service to receive new music data. Returns a pointer to dest.

LoadSoundData() »

void LoadSoundData(char *entry_name, word *dest, int skip);

Reads data from the group file entry named by entry_name and stores it in the dest memory block along with index structures.

LoadTileAttributeData() »

void LoadTileAttributeData(char *entry_name);

Loads data from the group file entry named entry_name and stores it in the tile attribute data block.

MAP_CELL_ADDR() »

#define MAP_CELL_ADDR(x, y) (mapData.w + ((y) << mapYPower) + x)

Converts an x and y position, measured in zero-based tiles, into a pointer to the map data in memory.

MAP_CELL_DATA() »

#define MAP_CELL_DATA(x, y) (*(mapData.w + (x) + ((y) << mapYPower)))

Looks up the value of a tile at an x and y position, measured in zero-based tiles, from the map data in memory.

MAP_CELL_DATA_SHIFTED() »

#define MAP_CELL_DATA_SHIFTED(x, y, shift_expr) \
    (*(mapData.w + (x) + ((y) << mapYPower) + shift_expr))

Looks up the value of a tile at an x and y position plus an arbitrary shift expression shift_expr, all measured in zero-based tiles, from the map data in memory.

MK_FP() »

#define MK_FP(seg, ofs) \
    ((void far *) (((unsigned long)(seg) << 16) | (unsigned)(ofs)))

Makes a far pointer from its component segment (seg) and offset (ofs) parts.

MoveAndDrawActors() »

void MoveAndDrawActors(void);

Iterates over each actor currently active in the game and calls the per-actor processing function.

MoveAndDrawDecorations() »

void MoveAndDrawDecorations(void);

Draws, advances the animation step, and moves each decoration currently running, and handles looping and ending conditions.

MoveAndDrawShards() »

void MoveAndDrawShards(void);

Moves and draws the sprites for all shards that are currently active. When a shard animation ends its slot is marked inactive.

MoveAndDrawSpawners() »

void MoveAndDrawSpawners(void);

Moves and draws the sprites for all spawners that are currently active. When a spawner animation ends (either due to finishing the animation or hitting a solid map tile) its slot is marked inactive and a new actor is created in the spawner’s final position.

MoveFountains() »

void MoveFountains(void);

Iterates through each fountain defined on the current map and adjusts their position by one tile.

MovePlatforms() »

void MovePlatforms(void);

Iterates through each platform defined on the current map and adjusts their position by one tile.

MovePlayerPlatform() »

void MovePlayerPlatform(word x_west, word x_east, word x_dir, word y_dir);

Determines if a platform covering X positions x_west to x_east is interacting with the player, and if so, modifies the player’s position to keep them attached to the platform as it moves. The current movement direction of the platform is passed in horizontal/vertical arguments x_dir and y_dir.

MovePlayerPush() »

void MovePlayerPush(void);

Handles one game tick of player push movement.

NewActor() »

void NewActor(word actor_type, word x_origin, word y_origin);

Dynamically inserts a new actor having the specified actor_type into the game world at the location specified by x_origin and y_origin.

NewActorAtIndex() »

bbool NewActorAtIndex(word index, word actor_type, word x, word y);

Inserts an actor of the specified actor_type into the actors[] array at the specified index position. The initial origin position is provided in x and y, and X/Y shifts are applied here. Returns true as long as actor_type referred to a defined actor type.

NewDecoration() »

void NewDecoration(
    word sprite_type, word num_frames, word x_origin, word y_origin,
    word dir, word num_times
);

Creates a new decoration at x_origin and y_origin consisting of the passed sprite_type with an animation duration of num_frames. dir controls the straight-line direction the decoration will move in, and num_times controls how many times the animation sequence will play before ending.

NewExplosion() »

void NewExplosion(word x_origin, word y_origin);

Creates a new instance of an explosion at the passed x_origin and y_origin map tile coordinates, sets the animation up to run, and plays the explosion sound. The actual location of the explosion sprite will be two tiles lower on the screen than y_origin requests.

NewMapActorAtIndex() »

void NewMapActorAtIndex(word index, word map_actor_type, word x_origin, word y_origin);

Creates actors and special actors based on the passed map_actor_type. For regular actors, index controls the position in the actors array where the new actor will be created; for special actors it does nothing. For both actor kinds, x_origin and y_origin control the actor’s initial position within the map.

NewPounceDecoration() »

void NewPounceDecoration(word x, word y);

Inserts six decorations representing pieces of pounce debris into the game world, radiating away from the origin point specified in x and y.

NewShard() »

void NewShard(word sprite_type, word frame, word x_origin, word y_origin);

Creates a new shard at x_origin and y_origin consisting of the passed sprite_type and frame.

NewSpawner() »

void NewSpawner(word actor_type, word x_origin, word y_origin);

Creates a new instance of a spawner at the passed x_origin and y_origin map tile coordinates and sets the animation up to run. actor_type controls both the type of actor that will be created when the spawner completes, and the sprite type that will be drawn while the spawner is running.

NextLevel() »

void NextLevel(void);

Selects the next level to be played in the progression. Depending on the number of stars collected, it conditionally takes the player to or from one of the bonus levels at regular intervals. If a demo is being recorded or played back, a fixed (and discontinuous) progression of levels is selected instead.

PCSpeakerService() »

void PCSpeakerService(void);

Sends a new fragment of sound effect data to the PC speaker.

ProcessActor() »

void ProcessActor(word index);

Handles the overall per-tick movement for one actor, identified by its index position in the actors array. If the actor is marked as dead, this function is a no-op.

ProcessAndDrawPlayer() »

bbool ProcessAndDrawPlayer(void);

Determines the player’s reaction to pain or death and draws the player sprite accordingly. If the player has died and completed the relevant death animation sequence, this function reloads the game state to the way it was when the level was last started and returns true. If the level has not been restarted, this function returns false.

ProcessGameInput() »

byte ProcessGameInput(byte demo_state);

Handles all keyboard and joystick input while the game is being played. Depending on the value passed in demo_state (which should be one of the DEMO_STATE_* values), this behavior is modified to record or play back demo data. Returns one of the GAME_INPUT_* values to control the game loop’s flow.

ProcessGameInputHelper() »

byte ProcessGameInputHelper(word active_page, byte demo_state);

Prepares the video hardware for the possibility of showing a menu or dialog during the game loop. active_page should contain the “active” (i.e. currently displayed) video page number, and demo_state should hold one of the DEMO_STATE_* values.

ProcessPlayerDizzy() »

void ProcessPlayerDizzy(void);

Determines when a queued bout of dizziness should become effective, and handles the cases where dizziness wears off naturally or is abruptly canceled.

ProfileCPU() »

void ProfileCPU(void);

Measures the execution speed of the CPU relative to the system’s Programmable Interval Timer, and records the number of busy loop iterations the CPU requires to generate various delay times.

ProfileCPUService() »

void interrupt ProfileCPUService(void);

Benchmarks the timing characteristics of the CPU relative to the system’s Programmable Interval Timer.

PromptKeyBind() »

bbool PromptKeyBind(byte *target_var, word x, char *message);

Displays message text at the provided x position (and a fixed Y position) on the screen and reads a single scancode into the memory pointed to by target_var. Returns true if the user pressed the Esc key and false for all other keys.

PromptLevelWarp() »

bbool PromptLevelWarp(void);

Prompts the user to select a map number from 1 to 12 (or 13, depending on the episode) and jumps to the start of the chosen map. Returns true if the map changed, or false if the user entered a non-numeric or out-of-range value.

PromptQuitConfirm() »

bbool PromptQuitConfirm(void);

Displays a window prompting the user to confirm their intention to quit, and blocks until a key is pressed. The return value is true if the Y key was pressed, or false in the case of any other key.

PromptRestoreGame() »

byte PromptRestoreGame(void);

Displays a menu that prompts the user to pick a save game slot (1-9) to load from, and gameplay jumps to that state. The user may cancel this prompt without loading by pressing Esc, Space, or Enter. The return value is one of the RESTORE_GAME_* constants.

PromptSaveGame() »

void PromptSaveGame(void);

Displays a menu that prompts the user to pick a save game slot (1-9) to save the state of their game into, then the save is carried out. The user may cancel this prompt without saving by pressing Esc, Space, or Enter.

ReadAndEchoText() »

void ReadAndEchoText(
    word x_origin, word y_origin, char *dest, word max_length
);

Presents a wait spinner near (x_origin, y_origin) that accepts at most max_length characters of keyboard input. The typed characters are echoed to the screen and stored in the memory pointed to by dest, which should be large enough to hold max_length + 1 bytes of data.

ReadDemoFrame() »

bbool ReadDemoFrame(void);

Reads the next byte from the demo data and updates the global input command state. Returns true on end of data.

ReadJoystickState() »

JoystickState ReadJoystickState(word stick_num);

Polls the joystick identified by stick_num for its current position and button state, and updates the player control variables accordingly.

ReadJoystickTimes() »

void ReadJoystickTimes(word stick_num, int *x_time, int *y_time);

Triggers a timing interval on the joystick hardware and returns the raw interval lengths for the one joystick, identified by stick_num, in x_time and y_time.

SET_PLAYER_DIZZY() »

#define SET_PLAYER_DIZZY() { queuePlayerDizzy = true; }

Puts the player into a “dizzy” state, which will begin to take effect the next time they are standing on solid ground.

SaveConfigurationData() »

void SaveConfigurationData(char *filename);

Saves the state of the global game configuration variables to the configuration file named filename.

SaveDemoData() »

void SaveDemoData(void);

Flushes all of the in-memory demo data to the PREVDEMO.MNI file on disk – it does not modify any group file contents.

SaveGameState() »

void SaveGameState(char slot_char);

Writes the current state of the most important player variables to a file on disk, whose filename extension is influenced by the character provided in slot_char.

SelectActivePage() »

void SelectActivePage(word page_num);

Switches the actively-displayed video memory page to page_num, causing its contents to appear on the screen, using a BIOS interrupt call.

SelectDrawPage() »

void SelectDrawPage(word page_num);

Changes the draw page to page_num and updates the memory address that subsequent drawing procedures should operate on.

SetAdLibRegister() »

void SetAdLibRegister(byte addr, byte data);

Writes one data byte to the AdLib register at address addr, assuming the hardware is present at the standard I/O ports.

SetBorderColorRegister() »

void SetBorderColorRegister(word color_value);

Configures the display adapter to use color_value to fill the overscan area at the edges of the screen, using a BIOS interrupt call.

SetInterruptRate() »

void SetInterruptRate(word ints_second);

Configures channel 0 of the system’s Programmable Interval Timer with an interrupts-per-second value specified by ints_second.

SetMapTile() »

void SetMapTile(word value, word x, word y);

Sets one map tile at horizontal position x and vertical position y to the value passed in value.

SetMapTile4() »

void SetMapTile4(
    word val1, word val2, word val3, word val4, word x_origin, word y_origin
);

Sets a horizontal span of four map tiles, starting at horizontal position x_origin and vertical position y_origin, to the values passed in val1 through val4.

SetMapTileRepeat() »

void SetMapTileRepeat(word value, word count, word x_origin, word y_origin);

Sets a horizontal span of count map tiles, starting at horizontal position x_origin and vertical position y_origin, to the value passed in value.

SetMusicState() »

bool SetMusicState(bool state);

Enables or disables AdLib output based on the value of state.

SetPIT0Value() »

void SetPIT0Value(word value);

Configures channel 0 of the system’s Programmable Interval Timer with the provided counter value.

SetPaletteRegister() »

void SetPaletteRegister(word palette_index, word color_value);

Configures the display adapter to use color_value as the screen display color at positions where the video memory contains palette_index, using a BIOS interrupt call.

SetPlayerPush() »

void SetPlayerPush(
    word dir, word max_time, word speed, word force_frame, bool abortable,
    bool blockable
);

Configures the global game state to cause the player to be pushed in a direction dir at speed tiles per game tick for a total duration of max_time game ticks. During this time, the player sprite will be drawn using force_frame as the frame number. If the abortable flag is set, the player can cancel the effect of the push by jumping. If the blockable flag is set, the push will consider and stop at any solid map tiles encountered along the way.

SetVideoMode() »

void SetVideoMode(word mode_num);

Changes the system’s video mode to the mode number specified by mode_num, using a BIOS interrupt call.

ShowAlteredFileError() »

void ShowAlteredFileError(void);

Shows when the user tries to load a manipulated save file whose checksum does not match the expected value.

ShowBombHint() »

void ShowBombHint(void);

Displays a hint dialog that informs the player that they can’t use the bomb key until they have picked up a bomb.

ShowCheatMessage() »

void ShowCheatMessage(void);

Displays a static dialog informing the user that they have entered the cheat code successfully and explaining the effect.

ShowCongratulations() »

void ShowCongratulations(void);

Shows a brief page of post-ending story and a pitch for another upcoming game.

ShowCopyright() »

void ShowCopyright(void);

Shows an abbreviated list of credits, the copyright year, and the game version.

ShowE1CliffhangerMessage() »

void ShowE1CliffhangerMessage(word actor_type);

Presents a sequence of two dialogs introducing the “cliffhanger” ending sequence of episode one, followed by ending the game by setting winGame to true. During each call, the passed actor_type value is used to determine which text to show, or if the game should end.

ShowEnding() »

void ShowEnding(void);

Presents a sequence of dialogs when an episode of the game has been played to completion.

ShowForeignOrders() »

void ShowForeignOrders(void);

Displays five consecutive pages of ordering information for international customers.

ShowGameRedefineMenu() »

void ShowGameRedefineMenu(void);

Shows a menu labeled “Game Redefine” in response to the user selecting the G option in either the main menu or the in-game help menu. This function simply dispatches one of the submenu functions in response to the user’s input.

ShowHealthHint() »

void ShowHealthHint(void);

Displays a hint dialog that teaches the player what Power-Up Modules are and how they affect gameplay.

ShowHelpMenu() »

byte ShowHelpMenu(void);

Shows a menu labeled “Help Menu” in response to the user pressing F1 during the game. It gives access to save/restore functions and a subset of options offered by the main menu. Returns one of the HELP_MENU_* variables.

ShowHighScoreTable() »

void ShowHighScoreTable(void);

Shows the top ten scores that have been reached and the name of the player who earned each spot. The table can optionally be erased by pressing the F10 key and confirming with the Y key.

ShowHintGlobeMessage() »

void ShowHintGlobeMessage(word hint_num);

Displays a dialog containing an animated context-appropriate hint message. The message is selected via the numeric hint_num argument.

ShowHintsAndKeys() »

void ShowHintsAndKeys(word top);

Displays a page of helpful hints, followed by two pages of keyboard help. The top parameter influences the vertical position of the frames, to allow the dialogs to be placed higher on the screen while the game is being played.

ShowInstructions() »

void ShowInstructions(void);

Shows a progression of five pages of dialog frames that teach the user how to play the game.

ShowJoystickConfiguration() »

void ShowJoystickConfiguration(word stick_num);

Prompts the user to calibrate the joystick timings and button configuration for the joystick identified by stick_num.

ShowKeyboardConfiguration() »

void ShowKeyboardConfiguration(void);

Shows and handles the keyboard configuration (sometimes called keyboard redefine) menu.

ShowLevelIntro() »

void ShowLevelIntro(word level_num);

Presents the animated message “Now entering level…” followed by the map number of the passed level_num.

ShowMemoryUsage() »

void ShowMemoryUsage(void);

Displays a debug dialog with a few live statistics about available system memory and the current number of actors.

ShowOrderingInformation() »

void ShowOrderingInformation(void);

Displays five sequential pages of ordering information in the shareware episode of the game, or a single page thanking the user for purchasing one of the registered episodes in other cases.

ShowPauseMessage() »

void ShowPauseMessage(void);

Presents a “game paused” dialog, stops music playback, and stops all execution until a key is pressed. Once that happens, the music is restarted and the function returns to its caller.

ShowPounceHint() »

void ShowPounceHint(void);

Displays a sequence of two hint dialogs that teach the player how to pounce on enemies for defense.

ShowPublisherBBS() »

void ShowPublisherBBS(void);

Displays two consecutive pages of information on how to access Apogee’s official channels on popular bulletin board systems (BBSes) of the day.

ShowRescuedDNMessage() »

void ShowRescuedDNMessage(void);

Displays a dialog sequence between the player and Duke Nukem (here using the short-lived but canonical spelling “Nukum”).

ShowRestoreGameError() »

void ShowRestoreGameError(void);

Shows when the user tries to restore a saved game whose file does not exist.

ShowSectionIntermission() »

void ShowSectionIntermission(char *top_text, char *bottom_text);

Ties different “sections” of the level progression together by showing a completion dialog and presenting the star bonus. Sections are two levels long, followed by a conditional bonus level. Depending on the context (section complete, or bonus level complete) different values may be passed in top_text and bottom_text.

ShowSoundTest() »

void ShowSoundTest(void);

Presents a menu that allows the user to seek through and preview each sound effect available in the game.

ShowStarBonus() »

void ShowStarBonus(void);

Presents a dialog that tallies up the number of stars collected by the player during the previous section. As a side effect, this function zeroes gameStars and increases gameScore accordingly.

ShowStory() »

void ShowStory(void);

Shows a progression of six pages of dialog frames that explain the basic premise of the game.

StartAdLib() »

void StartAdLib(void);

Detects and initializes the AdLib hardware if it is present, installs the interrupt handler necessary to run the AdLib and PC speaker services, and measures values for CPU-based time delays.

StartAdLibPlayback() »

void StartAdLibPlayback(void);

Sets the enableAdLib variable to true, permitting the AdLib service to play music.

StartGameMusic() »

void StartGameMusic(word music_num);

Starts playing the music identified by the numeric music_num if the AdLib hardware is available. This function is only safe to use while gameplay is occurring.

StartMenuMusic() »

void StartMenuMusic(word music_num);

Starts playing the music identified by the numeric music_num if the AdLib hardware is available. This function is only safe to use on the title screens, main menu, and its submenus.

StartSound() »

void StartSound(word sound_num);

Queues the new sound effect identified by sound_num for playback and immediately returns.

Startup() »

void Startup(void);

Initializes the game environment and shows pre-title/copyright screens.

StepPalette() »

void StepPalette(byte *pal_table);

During each frame of gameplay, steps through each element of the passed palette table pal_table and sets the palette key color accordingly, repeating once the END_ANIMATION marker has been reached.

StepWaitSpinner() »

byte StepWaitSpinner(word x, word y);

Draws one frame of the wait spinner, immediately returning the most recent scancode seen by the keyboard hardware (even if that scancode is stale).

StopAdLib() »

void StopAdLib(void);

Stops all playback from the AdLib card and restores the original system timer interrupt handler.

StopAdLibPlayback() »

void StopAdLibPlayback(void);

Clears all the AdLib parameter values that could produce note sounds.

StopMusic() »

void StopMusic(void);

Silences any active music and prevents the AdLib service from processing any new chunks of music.

SwitchMusic() »

void SwitchMusic(Music *music);

Stops any currently playing music and starts playing the music specified by music.

TILE_BLOCK_EAST() »

#define TILE_BLOCK_EAST(val) (*(tileAttributeData + ((val) / 8)) & 0x08)

Evaluates to a nonzero value if the tile value passed in val has its “block east movement” attribute flag set.

TILE_BLOCK_NORTH() »

#define TILE_BLOCK_NORTH(val) (*(tileAttributeData + ((val) / 8)) & 0x02)

Evaluates to a nonzero value if the tile value passed in val has its “block north movement” attribute flag set.

TILE_BLOCK_SOUTH() »

#define TILE_BLOCK_SOUTH(val) (*(tileAttributeData + ((val) / 8)) & 0x01)

Evaluates to a nonzero value if the tile value passed in val has its “block south movement” attribute flag set.

TILE_BLOCK_WEST() »

#define TILE_BLOCK_WEST(val) (*(tileAttributeData + ((val) / 8)) & 0x04)

Evaluates to a nonzero value if the tile value passed in val has its “block west movement” attribute flag set.

TILE_CAN_CLING() »

#define TILE_CAN_CLING(val) (*(tileAttributeData + ((val) / 8)) & 0x80)

Evaluates to a nonzero value if the tile value passed in val has its “player can cling” attribute flag set.

TILE_IN_FRONT() »

#define TILE_IN_FRONT(val) (*(tileAttributeData + ((val) / 8)) & 0x20)

Evaluates to a nonzero value if the tile value passed in val has its “draw in front” attribute flag set.

TILE_SLIPPERY() »

#define TILE_SLIPPERY(val) (*(tileAttributeData + ((val) / 8)) & 0x10)

Evaluates to a nonzero value if the tile value passed in val has its “is slippery” attribute flag set.

TILE_SLOPED() »

#define TILE_SLOPED(val) (*(tileAttributeData + ((val) / 8)) & 0x40)

Evaluates to a nonzero value if the tile value passed in val has its “is sloped” attribute flag set.

TestPlayerMove() »

word TestPlayerMove(word dir, word x_origin, word y_origin);

Tests if the player sprite is permitted to move in the direction specified by dir and enter the map tiles around x_origin and y_origin. Depending on the result of the test, one of the MOVE_* constants is returned.

TestSpriteMove() »

word TestSpriteMove(word dir, word sprite_type, word frame, word x_origin, word y_origin);

Tests if the sprite identified by sprite_type and frame is permitted to move in the direction specified by dir and enter the map tiles around x_origin and y_origin. Depending on the result of the test, one of the MOVE_* constants is returned.

TimerInterruptService() »

void interrupt TimerInterruptService(void);

Handles interrupts that occur on interrupt vector 8 (IRQ 0), which is wired to channel 0 of the system’s Programmable Interval Timer. Each time the timer ticks, this function updates the sounds being played by the PC speaker and/or the AdLib.

TitleLoop() »

byte TitleLoop(void);

Runs at the start of the program and is responsible for showing the title screen, credits, demo, and main menu. Additionally, this function reads the keyboard input for the main menu selection and calls the appropriate function in response. Returns one of the DEMO_STATE_* variables.

ToggleGodMode() »

void ToggleGodMode(void);

Inverts the state of the global isGodMode debug variable and presents a dialog informing the user of the current setting.

ToggleMusic() »

void ToggleMusic(void);

Inverts the setting of the global isMusicEnabled variable then presents a dialog confirming the resulting state. If the system does not have an AdLib compatible card installed, this function is a no-op.

ToggleSound() »

void ToggleSound(void);

Inverts the setting of the global isSoundEnabled variable then presents a dialog confirming the resulting state.

TryPounce() »

bool TryPounce(int recoil);

Checks if all necessary player variables are in the correct state to perform a pounce on an enemy actor. If this state is correct, a caller-provided recoil amount is imparted to the player and true is returned.

UnfoldDNFrame() »

word UnfoldDNFrame(void);

Draws the dialog frame that is used when Duke Nukem is speaking to the player. It contains no inner content aside from a Duke sprite image on the left side. Returns the X coordinate where text should be placed to appear within the frame.

UnfoldPlayerFrame() »

word UnfoldPlayerFrame(void);

Draws the dialog frame that is used when the player is speaking with Duke Nukem. It contains no inner content aside from a player sprite image on the right side. Returns the X coordinate where text should be placed to appear within the frame.

UnfoldTextFrame() »

word UnfoldTextFrame(
    int top, int height, int width, char *top_text, char *bottom_text
);

Draws an animated, empty text frame to the current draw page with the top edge at tile position top and a total size of width×height tiles. The top and bottom edges of the frame are prefilled with top_text and bottom_text respectively. The frame and its top/bottom texts are always centered horizontally on the screen. The return value is the X tile coordinate of the left edge of the inner text area.

UpdateBombs() »

void UpdateBombs(void);

Wraps DrawStatusBarBombs() with the correct X,Y position for display on the screen. It refreshes the bomb count on the status bar with the current global value.

UpdateDrawPageSegment() »

void UpdateDrawPageSegment(void);

Recalculates the segment address of the video memory where drawing should occur.

UpdateHealth() »

void UpdateHealth(void);

Wraps DrawSBarHealthHelper() and handles draw page selection. It redraws all of the health cells with either filled or empty bars to represent the player’s current health.

UpdateStars() »

void UpdateStars(void);

Wraps DrawStatusBarStars() with the correct X,Y position for display on the screen. It refreshes the star count on the status bar with the current global value.

ValidateSystem() »

void ValidateSystem(void);

Ensures the system has an EGA adapter, and verifies there is enough free memory. If either are not true, exits back to DOS.

WaitForAnyKey() »

byte WaitForAnyKey(void);

Waits indefinitely for any key to be pressed and released, then returns the scancode of that key.

WaitHard() »

void WaitHard(word delay);

Pauses execution for delay game ticks with no provision for the user to skip the wait.

WaitSoft() »

void WaitSoft(word delay);

Pauses execution for delay game ticks, returning early if the user presses a key.

WaitSpinner() »

byte WaitSpinner(word x, word y);

Draws a rotating green icon at tile position (x, y) on the screen, blocking until a key is pressed. Once that occurs, the scancode of the pressed key is returned.

WaitWallclock() »

void WaitWallclock(word loops);

Creates an artificial delay using a CPU busy loop, controlled by the iteration count specified in loops.

WrapBackdropHorizontal() »

void WrapBackdropHorizontal(byte *src, byte *dest);

Creates a modified copy of the backdrop image pointed to by src and stores it in the location pointed to by dest. The new copy of the image is shifted horizontally toward the left by four pixels, and the four columns of pixels that shift off the left edge are wrapped into the empty space created at the right edge.

WrapBackdropVertical() »

void WrapBackdropVertical(byte *src, byte *dest, byte *scratch);

Creates a modified copy of the backdrop image pointed to by src and stores it in the location pointed to by dest using a scratch buffer of at least 640 bytes. The new copy of the image is shifted vertically toward the top by four pixels, and the four rows of pixels that shift off the top edge are wrapped into the empty space created at the bottom edge.

WriteDemoFrame() »

bbool WriteDemoFrame(void);

Captures a snapshot of the global input command state (from the keyboard or joystick) and encodes it into a stream of demo data bytes. Returns true on error.