Finished doc'ing functions & routines...

... with source code comments

CHANGES.txt

@@ -9,6 +9,7 @@ http://www.newbreedsoftware.com/firefighter/
    them if using one joystick (where you cannot walk while spraying).
    (h/t phigan & JLsoft on AtariAge forums for reporting)
  * Stick setting & latest level saved as config file on disk (ATR) version
+ * Finished doc'ing functions & routines with source code comments
 
 0.1-beta-1 (2023-08-22):
  * First public beta release

src/config.c

@@ -1,4 +1,6 @@
 /*
+  Firefighter Config File (disk version) routines
+
   Firefighting game for the Atari 8-bit
   Bill Kendrick <bill@newbreedsoftware.com>
   http://www.newbreedsoftware.com/firefighter/
@@ -14,7 +16,7 @@
 extern char level;
 extern char main_stick;
 
-/* FIXME */
+/* (Attempt to) load config from disk */
 void load_config() {
   FILE * fi;
 
@@ -26,7 +28,7 @@ void load_config() {
   }
 }
 
-/* FIXME */
+/* (Attempt to) save config to disk */
 void save_config() {
   FILE * fi;
 

src/config.h

@@ -1,4 +1,6 @@
 /*
+  Firefighter Config File (disk version) routines
+
   Firefighting game for the Atari 8-bit
   Bill Kendrick <bill@newbreedsoftware.com>
   http://www.newbreedsoftware.com/firefighter/

src/dli.c

@@ -1,4 +1,6 @@
 /*
+  Firefighter Display List Interrupt routines
+
   Firefighting game for the Atari 8-bit
   Bill Kendrick <bill@newbreedsoftware.com>
   http://www.newbreedsoftware.com/firefighter/
@@ -9,7 +11,6 @@
 #include "dli.h"
 
 extern unsigned char font1_data[];
-// extern unsigned char font2_data[]; /* Not actually referenced */
 
 void dli(void) {
   asm("pha");

src/dli.h

@@ -1,4 +1,6 @@
 /*
+  Firefighter Display List Interrupt routines
+
   Firefighting game for the Atari 8-bit
   Bill Kendrick <bill@newbreedsoftware.com>
   http://www.newbreedsoftware.com/firefighter/

src/draw_text.c

@@ -1,4 +1,6 @@
 /*
+  Firefighter text drawing routines
+
   Firefighting game for the Atari 8-bit
   Bill Kendrick <bill@newbreedsoftware.com>
   http://www.newbreedsoftware.com/firefighter/
@@ -13,6 +15,12 @@
 
 extern unsigned char scr_mem[];
 
+/* Draw some text on the screen.
+
+   @param char * str - The NUL-terminated ('\0') string to write
+   @unsigned char * dest - The destination in memory
+     (expected to within src_mem[]!!!)
+*/
 void draw_text(char * str, unsigned char * dest) {
   unsigned char ch;
   unsigned int i;
@@ -30,6 +38,13 @@ void draw_text(char * str, unsigned char * dest) {
   }
 }
 
+/* Draw a zero-padded decimal number on the screen.
+
+   @param unsigned long int n - The number to draw
+   @param int digits - How many digits to show (will be zero-padded)
+   @unsigned char * dest - The destination in memory
+     (expected to within src_mem[]!!!)
+*/
 void draw_number(unsigned long int n, int digits, unsigned char * dest) {
   do {
     POKE(dest + digits - 1, (n % 10) + 16);

src/draw_text.h

@@ -1,4 +1,6 @@
 /*
+  Firefighter text drawing routines
+
   Firefighting game for the Atari 8-bit
   Bill Kendrick <bill@newbreedsoftware.com>
   http://www.newbreedsoftware.com/firefighter/

src/firefite.c

@@ -1,4 +1,7 @@
 /*
+  Firefighter core `main()` loop that calls other loops
+  (title screen, help screen, and the game).
+
   Firefighting game for the Atari 8-bit
   Bill Kendrick <bill@newbreedsoftware.com>
   http://www.newbreedsoftware.com/firefighter/
@@ -24,27 +27,37 @@ char high_score_name[4];
 char main_stick;
 char level;
 
+/* Main loop! */
 void main(void) {
   char want_help;
 
+  /* Set default high score */
   high_score = 1031;
   strcpy(high_score_name, "BJK");
+
+  /* Set default config */
   main_stick = STICK_LEFT;
   level = 1;
 
 #ifdef DISK
+  /* Load saved config from disk */
   load_config();
 #endif
 
   do {
     do {
+      /* Show title screen */
       want_help = show_title();
+
 #ifdef DISK
       if (want_help) {
+        /* Show help screen */
         show_help();
       }
 #endif
     } while (want_help);
+
+    /* Play the game! */
     start_game();
   } while(1);
 }

src/game.c

@@ -1,4 +1,6 @@
 /*
+  Firefighter game loop and its helper functions.
+
   Firefighting game for the Atari 8-bit
   Bill Kendrick <bill@newbreedsoftware.com>
   http://www.newbreedsoftware.com/firefighter/
@@ -14,7 +16,7 @@
 #include "draw_text.h"
 #include "dli.h"
 
-/* FIXME: Shove in a "score.h" header? */
+/* FIXME: Shove in a "score.h" header? -bjk 2023.08.22 */
 #define SCORE_AX_COLLECT 15
 #define SCORE_CIVILIAN_RESCUE 100
 #define SCORE_CRATE_BREAK_DEDUCTION 1
@@ -469,7 +471,13 @@ void start_game(void) {
    tip shape near the player, and three other shapes
    beyond that; we'll avoid drawing those other three
    if the first part failed to draw, to avoid being
-   able to spray through solid objects! */
+   able to spray through solid objects!i
+
+   @param unsigned char x - X position to [attempt to] draw
+   @param unsigned char y - Y position to [attempt to] draw
+   @param unsigned char want_shape - water shape to [attempt to] draw
+   @return boolean 1 if it was drawn, 0 otherwise (e.g., obstacle, fire, etc.)
+*/
 unsigned char spray(unsigned char x, unsigned char y, unsigned char want_shape) {
   unsigned char shape;
 
@@ -545,7 +553,9 @@ void setup_game_screen(void) {
   OS.sdmctl = (DMACTL_PLAYFIELD_NORMAL | DMACTL_DMA_FETCH);
 }
 
-/* FIXME */
+/* Draw the current level, including drawing the
+   level/score/bonus status bar at the top.
+   Flashes a "GET READY!" message, before proceeding. */
 void draw_level(void) {
   int l;
 
@@ -571,7 +581,7 @@ void draw_level(void) {
   memcpy(scr_mem + 60, levels_data + l * LEVEL_TOT_SIZE + 1, LEVEL_SPAN);
 }
 
-/* FIXME */
+/* Draws the level/score/bonus in the status bar */
 void draw_score(void) {
   draw_number(level, 2, scr_mem + 28);
   draw_number(score, 6, scr_mem + 39);
@@ -657,6 +667,7 @@ void cellular_automata(void) {
             if (valid_dir(x, y, dir) &&
                 shape_at(x + dir_x[dir], y + dir_y[dir]) == 0) {
               set_shape(x, y, 0);
+
               if ((dir_x[dir] == 1 && dir_y[dir] >= 0) || dir_y[dir] == 1) {
                 set_shape(x + dir_x[dir], y + dir_y[dir], CIVILIAN_MOVED);
               } else {
@@ -665,7 +676,12 @@ void cellular_automata(void) {
             }
           }
         } else if (shape == CIVILIAN_MOVED) {
-          /* FIXME */
+          /* Turn a previously-moved worker back into a regular worker.
+
+             (Since cellular automaton goes from top-to-bottom, left-to-right,
+             we use an interim 'shape' to avoid processing the same worker
+             multiple times per frame (causing them to 'fly' across or down
+             the screen) if they move down or right) */
           set_shape(x, y, CIVILIAN);
         } else if (shape == PIPE_BROKEN_UP_DOWN && rand < 128) {
           /* Draw (or erase) gas leak on left/right of a broken vertical pipe */
@@ -682,21 +698,8 @@ void cellular_automata(void) {
     }
   }
 
-  /* FIXME */
-/*
-  for (y = 0; y < LEVEL_H; y++) {
-    for (x = 0; x < LEVEL_W; x++) {
-      shape = shape_at(x, y);
-      if (shape == CIVILIAN_MOVED) {
-        set_shape(x, y, CIVILIAN);
-      } else if (shape == FIRE_SM || shape == FIRE_MD || shape == FIRE_LG) {
-        any_fire++;
-      }
-    }
-  }
-*/
-
-  /* FIXME */
+  /* Play crackling fire sound effect
+     (the more fire, the higher the volume) */
   if (any_fire) {
     POKEY_WRITE.audf1 = ((POKEY_READ.random) >> 4) + 128;
     POKEY_WRITE.audc1 = (any_fire >> 4) + 1;
@@ -705,7 +708,14 @@ void cellular_automata(void) {
   }
 }
 
-/* FIXME */
+/* Given a broken pipe at a position on the screen,
+   [attempt to] draw a gas leak shape, or a blank,
+   depending on the state of all valves on the screen.
+
+   @param int x - X position to [attempt to] draw/erase gas leak
+   @param int y - Y position to [attempt to] draw/erase gas leak
+   @param char shape - gas leak shape to [attempt to] draw there
+*/
 void broken_pipe(int x, int y, char shape) {
   char c;
 
@@ -752,7 +762,11 @@ char pipe_corner[16] = {
 
 
 /* Create an explosion of fire at the given position
-   (occurs when fire touches oil barrels or gas leaks) */
+   (occurs when fire touches oil barrels or gas leaks)
+
+   @param char x - X position for explosion
+   @param char y - Y position for explosion
+*/
 void explode(char x, char y) {
   char shape, flam;
 
@@ -801,7 +815,13 @@ void explode(char x, char y) {
 }
 
 /* Determines whether moving a given direction from
-   a particular position is still in-bounds */
+   a particular position is still in-bounds
+
+   @param unsigned char x - X position from which to test
+   @param unsigned char y - Y position from which to test
+   @param unsigned char dir - direction (0-7; see dir_x[] & dir_y[]) to test
+   @return unsigned char boolean whether the new position is in bounds
+*/
 unsigned char valid_dir(unsigned char x, unsigned char y, unsigned char dir) {
   int dx, dy;
 
@@ -814,7 +834,14 @@ unsigned char valid_dir(unsigned char x, unsigned char y, unsigned char dir) {
 };
 
 /* Return the flammability of an object; used to determine
-   how (and if) fire spreads */
+   how (and if) fire spreads
+
+   @param unsigned char c - Object shape to test for flammability
+   @param unsigned char - Fire shape to draw on the screen
+     (FIRE_SM, FIRE_MD, or FIRE_LG),
+     or FIRE_INFLAM if the shape is not flammable (don't spread fire),
+     or FIRE_XLG if the shape is explosive
+*/
 unsigned char flammable(unsigned char c) {
   if (c == OIL || c == GASLEAK_RIGHT || c == GASLEAK_LEFT || c == GASLEAK_UP || c == GASLEAK_DOWN) {
     /* Oil barrel and gas leaks cause an explosion */
@@ -841,7 +868,16 @@ unsigned char flammable(unsigned char c) {
   }
 }
 
-/* FIXME */
+/* Set sound parameters
+   @param char p - Starting pitch (0-255)
+   @param char pch - Pitch delta
+     (negative for higher, positive for lower, zero for no change)
+   @param char dist - Distortion (as high nybble)
+     (e.g., (10<<4) aka 160 aka 0xA0 for 'pure' tone (square wave)
+   @param char vol - Starting volume (0-15)
+   @param char volch - Volume change; how fast to decrease volume
+     (note: always _positive_)
+*/
 void set_sound(char p, char pch, char dist, char vol, char volch) {
   hit_pitch = p;
   hit_pitch_change = pch;
@@ -850,7 +886,11 @@ void set_sound(char p, char pch, char dist, char vol, char volch) {
   hit_vol_decrease = volch;
 }
 
-/* FIXME */
+/* End-of-level bonus sequence:
+   + Show "Level Complete!"
+   + Show and tally Time Bonus
+   + Show and tally Safety Bonus
+*/
 void level_end_bonus(void) {
   int i;
   char c, any_fire;
@@ -908,7 +948,7 @@ void level_end_bonus(void) {
   }
 }
 
-/* FIXME */
+/* Briefly flash the background color (of the entire screen) */
 void flash(void) {
   char i, j;
 
@@ -924,6 +964,7 @@ void flash(void) {
   }
 }
 
+/* Pause for a few seconds */
 void pause(void) {
   int i;
 
@@ -932,7 +973,10 @@ void pause(void) {
   }
 }
 
-/* FIXME */
+/* Bonus score tally sequence (used by end-of-level bonus sequence)
+   @param int x - X position to draw bonus score for countdown
+   @param int deduct - How quickly to deduct points from bonus during tally
+*/
 void bonus_tally(int x, int deduct) {
   while (bonus >= deduct) {
     bonus = bonus - deduct;
@@ -966,4 +1010,3 @@ void quiet(void) {
   POKEY_WRITE.audf4 = 0;
   POKEY_WRITE.audc4 = 0;
 }
-

src/game.h

@@ -1,4 +1,6 @@
 /*
+  Firefighter game loop and its helper functions.
+
   Firefighting game for the Atari 8-bit
   Bill Kendrick <bill@newbreedsoftware.com>
   http://www.newbreedsoftware.com/firefighter/

src/help.c

@@ -1,4 +1,6 @@
 /*
+  Firefighter Help Text display
+
   Firefighting game for the Atari 8-bit
   Bill Kendrick <bill@newbreedsoftware.com>
   http://www.newbreedsoftware.com/firefighter/
@@ -16,7 +18,7 @@
 extern unsigned char scr_mem[];
 extern unsigned char * dlist;
 
-/* FIXME */
+/* Routine to load and show help text on a fullscreen text display */
 void show_help(void) {
   int i;
   unsigned char y, last;
@@ -88,3 +90,4 @@ void show_help(void) {
   do {
   } while (OS.strig0 == 0 || OS.strig1 == 0 || CONSOL_START(GTIA_READ.consol) == 1);
 }
+