space: Simplify the code and its goals

Originally this was supposed to be a sort of mini game, but that would
have probably made it too complex for newcomers. Thus, let's just keep
it to subpixel movement and shooting bullets, which is already a big
step from the `basics/sprite.s` example.

Signed-off-by: Miquel Sabaté Solà <msabate@suse.com>

2 files changed, 286 insertions, 83 deletions

diff --git a/space/src/states/bullets.s b/space/src/states/bullets.s
new file mode 100644
index 0000000..af74ce7
--- /dev/null
+++ b/space/src/states/bullets.s
@@ -0,0 +1,181 @@
+;;;
+;; Implements the pool of bullets available when pressing B. The main code
+;; should just want to call `init` for initializing the memory space, and then
+;; `update` on each main game loop iteration. The following addresses are
+;; reserved:
+;;      -> $40-$41: internal data.
+;;      -> $0208-$0213: OAM data (this is a pool of three sprites).
+;;
+;; NOTE: the code in here touch the addresses on OAM directly, instead of
+;; keeping them in some internal addresses on zero page. This is usually not a
+;; good idea, and more so if we were to do collision checking and stuff like
+;; that. That being said, because of its simplicity, it's not that big of a
+;; deal.
+.scope Bullets
+    ;; The number of bullets shown on screen for the current frame.
+    m_bullets_screen = $40
+
+    ;; Frame counter. See `FRAMES` below.
+    m_frames = $41
+
+    ;; How many frames have to pass to allow the user to shoot another bullet
+    ;; after the previous one.
+    FRAMES = 15
+
+    ;; Initializes the pool of bullets.
+    .proc init
+        ;; Initializing variables.
+
+        lda #0
+        sta m_bullets_screen
+
+        lda #FRAMES
+        sta m_frames
+
+        ;; Set X and Y positions off-screen for the three available slots.
+
+        lda #$ff
+        sta $208
+        sta $20C
+        sta $210
+        sta $20B
+        sta $20F
+        sta $213
+
+        ;; All three sprites are instances of the same tile.
+
+        lda #4
+        sta $209
+        sta $20D
+        sta $210
+
+        ;; Nothing special for these sprites, set attributes to 0.
+
+        lda #0
+        sta $20A
+        sta $20E
+        sta $212
+
+        rts
+    .endproc
+
+    ;; Update bullets on screen, check if a new one has to be shown, etc.
+    .proc update
+        ;; If the frame counter has the same value as our allowed one, we can go
+        ;; into the `bullets_pressed` subroutine, otherwise we will skip it
+        ;; altogether.
+        lda m_frames
+        cmp #FRAMES
+        beq @check
+        inc m_frames
+        jmp @position
+    @check:
+        jsr bullets_pressed
+    @position:
+        jsr update_positions
+
+        rts
+    .endproc
+
+    ;; Shows a new bullet right in front of the ship if the player requested it
+    ;; and it is possible.
+    .proc bullets_pressed
+        ;; If we reached the maximum of bullets on screen, return early.
+        lda m_bullets_screen
+        cmp #3
+        bne :+
+        rts
+    :
+        ;; If the B button is not pressed, return early.
+        lda #Joypad::BUTTON_B
+        and Joypad::m_buttons1
+        bne :+
+        rts
+    :
+        ;; The following code will loop through the three bullet sprites and
+        ;; find one that is free (off-screen). If one could be found, it will
+        ;; assign it to the ship's position.
+        ldx #0
+    @loop:
+        ;; Is the Y position on this sprite $FF? If so then it's free and we can
+        ;; jump into @set so we re-initialize the position for this bullet.
+        lda $208, x
+        cmp #$FF
+        beq @set
+
+        ;; Oops, that was not the case. At this point, is this the last bullet?
+        ;; If so, we can go to the @end, otherwise we increase the index and try
+        ;; again.
+        cpx #8
+        beq @end
+        inx
+        inx
+        inx
+        inx
+        jmp @loop
+    @set:
+        ;; At the current index we have a bullet to initialize. Hence, give it
+        ;; the Y value from the player and the X one (+4 so it's at the center
+        ;; of the ship on the X axis).
+        lda Player::m_screen_y
+        sta $208, x
+        lda Player::m_screen_x
+        clc
+        adc #4
+        inx
+        inx
+        inx
+        sta $208, x
+
+        ;; Reset the `m_frames` so to disallow too many bullets being shot at
+        ;; once, and increate the `m_bullets_screen` variable.
+        lda #0
+        sta m_frames
+        inc m_bullets_screen
+    @end:
+        rts
+    .endproc
+
+    ;; Updates the positions from the bullets being shown on screen. If one
+    ;; bullet goes off screen, then it's properly freed so it can be picked up
+    ;; by another B press.
+    .proc update_positions
+        ldx #0
+    @loop:
+        ;; Do nothing if the bullet is free.
+        lda $208, x
+        cmp #$FF
+        beq @next
+
+        ;; The indexed bullet is shown on screen, and we should make it move
+        ;; upward by 10 units. That being said, if its Y position is lesser or
+        ;; equal than 10, we can directly free it now. Otherwise, just update
+        ;; the Y value by performing this subtraction.
+        cmp #10
+        bcc @free
+        beq @free
+        sec
+        sbc #10
+        jmp @save
+    @free:
+        ;; This bullet should be freed, decrease `m_bullets_screen` and set `a`
+        ;; to an off-screen value.
+        dec m_bullets_screen
+        lda #$FF
+    @save:
+        ;; Either way you reach this, in `a` we have the Y value to be stored.
+        sta $208, x
+    @next:
+        ;; If we are already at the last bullet, jump to the @end. Otherwise
+        ;; increase the index and loop again.
+        cpx #8
+        beq @end
+        inx
+        inx
+        inx
+        inx
+        jmp @loop
+    @end:
+        rts
+    .endproc
+.endscope
diff --git a/space/src/states/player.s b/space/src/states/player.s
index a43f61e..29c1585 100644
--- a/space/src/states/player.s
+++ b/space/src/states/player.s
@@ -5,28 +5,48 @@
 ;;   -> $0200-$0207: OAM data.
 ;;;
 .scope Player
-    ;; TODO: change names of pos_x and signed_x et al
-    m_pos_x             = $30
-    m_pos_y             = $31
-    m_velocity_x        = $32
-    m_velocity_y        = $33
+    ;; Unsigned screen coordinates on the X axis.
+    m_screen_x = $30
+
+    ;; Unsigned screen coordinates on the Y axis.
+    m_screen_y = $31
+
+    ;; The actual velocity on the X coordinates. This is a signed fixed point
+    ;; 4.4 (high nibble: pixels; low: subpixels).
+    m_velocity_x = $32
+
+    ;; The actual velocity on the Y coordinates. This is a signed fixed point
+    ;; 4.4 (high nibble: pixels; low: subpixels).
+    m_velocity_y = $33
+
+    ;; The target velocity on the X coordinates. This is a signed fixed point
+    ;; 4.4 (high nibble: pixels; low: subpixels).
     m_target_velocity_x = $34
+
+    ;; The target velocity on the Y coordinates. This is a signed fixed point
+    ;; 4.4 (high nibble: pixels; low: subpixels).
     m_target_velocity_y = $35
-    m_signed_x          = $36   ; NOTE !
-    m_signed_y          = $38   ; NOTE !
+
+    ;; Computed position on the X coordinates at the subpixel level. This is a
+    ;; signed fixed point 12.4. NOTE: two bytes!
+    m_position_x = $36
+
+    ;; Computed position on the X coordinates at the subpixel level. This is a
+    ;; signed fixed point 12.4. NOTE: two bytes!
+    m_position_y = $38
 
     ;; Initializes the player by initializing its internal data and loading some
     ;; values of the sprite itself.
     .proc init
         ;; Initialize position + subpixel.
         lda #$B0
-        sta m_signed_y
+        sta m_position_y
         lda #$00
-        sta m_signed_y + 1
+        sta m_position_y + 1
         lda #$7A
-        sta m_signed_x
+        sta m_position_x
         lda #$F0
-        sta m_signed_x + 1
+        sta m_position_x + 1
 
         ;; Initialize velocity.
         lda #0
@@ -35,21 +55,6 @@
         sta m_target_velocity_x
         sta m_target_velocity_y
 
-        ;; The player itself is built with two identical sprites placed side by
-        ;; side, where the second one is flipped horizontally. Thus, the player
-        ;; takes up the first two slots on OAM data ($0200-$0207). Here we only
-        ;; need to select the sprite and the attributes, since the position will
-        ;; be updated on each game loop. Hence, here we select the sprite
-        ;; located at #0 on the pattern table, and then we set for the second
-        ;; one the horizontal flip bit for the attributes.
-        lda #0
-        sta $0201               ; First sprite select.
-        sta $0205               ; Second sprite select.
-        lda #%00000000
-        sta $0202               ; First sprite attributes.
-        lda #%01000000
-        sta $0206               ; Second sprite attributes.
-
         rts
     .endproc
 
@@ -87,7 +92,6 @@
             lda positive_velocity, x
             sta m_target_velocity_x
             jmp @target_check_up
-
         @target_check_left:
             ;; Similar to before: if it was not pressed, then set the target
             ;; velocity to 0, otherwise set the proper value and jump to the up
@@ -98,14 +102,11 @@
             lda negative_velocity, x
             sta m_target_velocity_x
             jmp @target_check_up
-
         @target_no_x:
             ;; None of the buttons on the X-axis were pressed. Set the target
             ;; velocity to 0.
             lda #0
             sta m_target_velocity_x
-            ;; NOTE: walkthrough
-
         @target_check_up:
             ;; Same as before but we return early if it was pressed, otherwise
             ;; we go into the arrow-down check.
@@ -115,7 +116,6 @@
             lda negative_velocity, x
             sta m_target_velocity_y
             rts
-
         @target_check_down:
             ;; If down was not pressed, go to the "no_y" case, otherwise return
             ;; early after setting the proper Y target velocity.
@@ -125,26 +125,21 @@
             lda positive_velocity, x
             sta m_target_velocity_y
             rts
-
         @target_no_y:
             ;; None of the buttons on the Y-axis were pressed. Set the target
             ;; velocity to 0.
             lda #0
             sta m_target_velocity_y
             rts
-
-        ;; TODO
         positive_velocity:
-    ;; $18: 0001 | 1000
-    ;; $28: 0010 | 1000
             .byte $18, $28
         negative_velocity:
-    ;; $E8: 1110 | 1000
-    ;; $D8: 1101 | 1000
             .byte $E8, $D8
         .endproc
 
-    ;; TODO: give it a closer look
+        ;; Increase the current velocity on each axis so to match the target
+        ;; velocity on each case. Note that the velocity is simply increased by
+        ;; one. A more detailed code could be more nuanced than this.
         .proc accelerate
             lda m_velocity_x
             sec
@@ -173,72 +168,70 @@
             rts
         .endproc
 
-    ;; TODO: give it a closer look
+        ;; Apply the currently computed velocity to the position at subpixel
+        ;; level.
         .proc apply_velocity
             lda m_velocity_x
             bmi @apply_negative_velocity_x
 
             clc
-            adc m_signed_x
-            sta m_signed_x
+            adc m_position_x
+            sta m_position_x
             lda #0              ;NOTE: adding possible carry!
-            adc m_signed_x + 1
-            sta m_signed_x + 1
+            adc m_position_x + 1
+            sta m_position_x + 1
             jmp @apply_velocity_y
-
         @apply_negative_velocity_x:
             lda #0
             sec
             sbc m_velocity_x
             sta $00
-            lda m_signed_x
+            lda m_position_x
             sec
             sbc $00
-            sta m_signed_x
-            lda m_signed_x + 1
+            sta m_position_x
+            lda m_position_x + 1
             sbc #0
-            sta m_signed_x + 1
-            ;; NOTE: walkthrough
-
+            sta m_position_x + 1
         @apply_velocity_y:
             lda m_velocity_y
             bmi @apply_negative_velocity_y
 
             clc
-            adc m_signed_y
-            sta m_signed_y
+            adc m_position_y
+            sta m_position_y
             lda #0
-            adc m_signed_y + 1
-            sta m_signed_y + 1
+            adc m_position_y + 1
+            sta m_position_y + 1
             rts
-
         @apply_negative_velocity_y:
             lda #0
             sec
             sbc m_velocity_y
             sta $00
-            lda m_signed_y
+            lda m_position_y
             sec
             sbc $00
-            sta m_signed_y
-            lda m_signed_y + 1
+            sta m_position_y
+            lda m_position_y + 1
             sbc #0
-            sta m_signed_y + 1
+            sta m_position_y + 1
             rts
         .endproc
 
+        ;; Translate the position at subpixel level to actual screen coordinates.
         .proc position_to_coordinates
             jsr position_to_coordinates_x
             jsr position_to_coordinates_y
-
             rts
         .endproc
 
+        ;; Translate the X position at subpixel level to actual screen coordinates.
         .proc position_to_coordinates_x
             ;; Convert the fixed point position coordinate into screen coordinates
-            lda m_signed_x
+            lda m_position_x
             sta $00
-            lda m_signed_x + 1
+            lda m_position_x + 1
             sta $01
             lsr $01
             ror $00
@@ -250,7 +243,7 @@
             ror $00
             ; Assume that everything is fine and save the sprite position
             lda $00
-            sta m_pos_x
+            sta m_screen_x
 
             lda m_velocity_x
             bmi @position_from_negative_velocity
@@ -263,32 +256,33 @@
             rts
         @bound_upper_x:
             lda #$EF
-            sta m_pos_x
+            sta m_screen_x
             lda #$0E
-            sta m_signed_x + 1
+            sta m_position_x + 1
             lda #$F0
-            sta m_signed_x
+            sta m_position_x
             lda #0
             sta m_velocity_x
             rts
         @position_from_negative_velocity:
-            lda m_signed_x + 1
+            lda m_position_x + 1
             bmi @bound_lower_x
             rts
         @bound_lower_x:
             lda #0
-            sta m_signed_x
-            sta m_signed_x + 1
-            sta m_pos_x
+            sta m_position_x
+            sta m_position_x + 1
+            sta m_screen_x
             sta m_velocity_x
             rts
         .endproc
 
+        ;; Translate the Y position at subpixel level to actual screen coordinates.
         .proc position_to_coordinates_y
             ;; Convert the fixed point position coordinate into screen coordinates
-            lda m_signed_y
+            lda m_position_y
             sta $00
-            lda m_signed_y + 1
+            lda m_position_y + 1
             sta $01
             lsr $01
             ror $00
@@ -300,7 +294,7 @@
             ror $00
             ; Assume that everything is fine and save the sprite position
             lda $00
-            sta m_pos_y
+            sta m_screen_y
 
             lda m_velocity_y
             bmi @position_from_negative_velocity_y
@@ -313,23 +307,23 @@
             rts
         @bound_upper_y:
             lda #$EF
-            sta m_pos_y
+            sta m_screen_y
             lda #$0E
-            sta m_signed_y + 1
+            sta m_position_y + 1
             lda #$F0
-            sta m_signed_y
+            sta m_position_y
             lda #0
             sta m_velocity_y
             rts
         @position_from_negative_velocity_y:
-            lda m_signed_y + 1
+            lda m_position_y + 1
             bmi @bound_lower_y
             rts
         @bound_lower_y:
             lda #0
-            sta m_signed_y
-            sta m_signed_y + 1
-            sta m_pos_y
+            sta m_position_y
+            sta m_position_y + 1
+            sta m_screen_y
             sta m_velocity_y
             rts
         .endproc
@@ -340,16 +334,44 @@
         ;; Update the sprite on OAM memory according to what we have in the
         ;; internal data stored in $30-$3F.
         .proc update
-            lda m_pos_y
+            ;; Update Y position.
+            lda m_screen_y
             sta $200
             sta $204
 
-            lda m_pos_x
+            ;; Update X position.
+            lda m_screen_x
             sta $203
             clc
             adc #8
             sta $207
 
+            ;; If we have a target velocity, then we will show some fire,
+            ;; otherwise we keep the basic ship.
+            lda m_target_velocity_x
+            bne @fire
+            lda m_target_velocity_y
+            bne @fire
+            lda #0
+            jmp @sprite_set
+        @fire:
+            lda #2
+        @sprite_set:
+            ;; The player itself is built with two identical sprites placed side
+            ;; by side, where the second one is flipped horizontally. Thus, the
+            ;; player takes up the first two slots on OAM data ($0200-$0207).
+            ;; Here we only need to select the sprite and the attributes, since
+            ;; the position will be updated on each game loop. Hence, here we
+            ;; select the sprite as indexed by the value set on the `a` register
+            ;; on the pattern table, and then we set for the second one the
+            ;; horizontal flip bit for the attributes.
+            sta $0201               ; First sprite select.
+            sta $0205               ; Second sprite select.
+            lda #%00000000
+            sta $0202               ; First sprite attributes.
+            lda #%01000000
+            sta $0206               ; Second sprite attributes.
+
             rts
         .endproc
     .endscope