Beginning commenting before public release

debug.s

@@ -7,7 +7,7 @@ debugtext nop
     bne ?1
     rts
 
-
+; print one byte as two hex digits on current drawing screen
 debughex ; A = hex byte, X = column, Y = row; A is clobbered, X&Y are not
     pha
     stx param_x
@@ -30,6 +30,7 @@ debughex ; A = hex byte, X = column, Y = row; A is clobbered, X&Y are not
 
 hexdigit .byte "0123456789ABCDEF"
 
+; copy string to the current drawing screen
 printstr ; X = column, Y = row, scratch_ptr is text (null terminated)
     sty param_y
     ldy #0

main.s

@@ -160,10 +160,10 @@ check_restart ldx #34
     sta scratch_ptr
     lda #>over_text
     sta scratch_ptr+1
-    jsr printstr
+    jsr printstr ; prints to back page, so have to flip pages to show
     jsr pageflip
 
-    lda KBDSTROBE
+    lda KBDSTROBE ; any key restarts
 ?1  lda KEYBOARD
     bpl ?1
     lda KBDSTROBE
@@ -244,6 +244,9 @@ game_loop nop
     lda config_quit
     beq ?2
     rts
+
+    ; loop through enemies first so we can check collisions with the
+    ; players as the players are moved
 ?2  lda #FIRST_AMIDAR-1
     sta current_actor
 ?enemy inc current_actor
@@ -268,16 +271,18 @@ game_loop nop
     jsr handle_player
     jmp ?p1
 
+; if any player is still alive, the game continues. Once the last player
+; dies, the countdown timer allows the enemies to continue to move a
+; little while before the game ends
 ?alive lda still_alive
     bne ?draw
     dec countdown_time
     bne ?draw
     rts
 
-;        erase_sprites()
-;        update_background()
-;        draw_actors()
-;        show_screen()
+; main draw loop. Restoring background will overwrite the softsprites
+; so there's no need to erase the sprites some other way. Text damage
+; is also restored before any changes for the upcoming frame are drawn.
 ?draw jsr restorebg_driver
     jsr restoretext
     jsr paint_boxes

vars.s

@@ -1,9 +1,9 @@
     *= $800
 
 actor_col .ds MAX_ACTORS  ; #  current tile column
-actor_x .ds MAX_ACTORS
+actor_x .ds MAX_ACTORS  ; pixel position (calculated from col & xpixel)
 actor_row .ds MAX_ACTORS  ; #  current tile row
-actor_y .ds MAX_ACTORS
+actor_y .ds MAX_ACTORS  ; pixel position (calculated from row & ypixel)
 actor_xpixel .ds MAX_ACTORS  ; #  current pixel offset in col
 actor_xfrac .ds MAX_ACTORS  ; #  current fractional pixel
 actor_xspeed_l .ds MAX_ACTORS  ; #  current speed (affects fractional)
@@ -19,18 +19,21 @@ actor_status .ds MAX_ACTORS  ; #  alive, exploding, dead, regenerating, invulner
 actor_frame_counter .ds MAX_ACTORS  ; #  frame counter for sprite changes
 actor_input_dir .ds MAX_ACTORS  ; #  current joystick input direction
 actor_active .ds MAX_ACTORS ; 1 = active, 0 = skip, $ff = end
-actor_l .ds MAX_ACTORS
-actor_h .ds MAX_ACTORS
+actor_l .ds MAX_ACTORS  ; address (low byte) of compiled sprite
+actor_h .ds MAX_ACTORS  ; address (high byte)
 actor_turn_zone .ds MAX_ACTORS ; debugging; is player in turn zone:
 
-player_score  .ds 4
-player_next_target_score  .ds 4
-player_lives  .ds 4  ; # lives remaining
+player_score  .ds MAX_PLAYERS
+player_next_target_score  .ds MAX_PLAYERS
+player_lives  .ds MAX_PLAYERS  ; # lives remaining
 
 amidar_start_col .ds VPATH_NUM
 round_robin_up  .ds VPATH_NUM
 round_robin_down  .ds VPATH_NUM
 
+; after player completes a box, this data is used to fill it in subsequent
+; frames. This list tracks the left column (right is always a fixed distance
+; away) and starting and ending rows
 box_painting_c .ds MAX_BOX_PAINTING
 box_painting_r1 .ds MAX_BOX_PAINTING
 box_painting_r2 .ds MAX_BOX_PAINTING