basics: Add a flickering example

Add an example on how to flicker sprites so to not surpass the scanline
limit for them.

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

4 files changed, 435 insertions, 4 deletions

diff --git a/Makefile b/Makefile
index fd12927..bb5c572 100644
--- a/Makefile
+++ b/Makefile
@@ -1,7 +1,7 @@
 CC65   ?= cl65
 CA65   ?= ca65
 LD65   ?= ld65
-CCOPTS ?= --verbose --target nes
+CCOPTS ?= --target nes
 
 .PHONY: all
 all: clean deps build
@@ -11,7 +11,7 @@ clean:
 	@rm -rf out
 	@find . -type f -name "*.o" -delete
 	@find . -type f -name "*.nes" -delete
-	@mkdir -p out/basics out/scroll
+	@mkdir -p out/basics out/scroll out/space
 
 .PHONY: deps
 deps:
@@ -25,6 +25,7 @@ basics:
 	$(CC65) $(CCOPTS) basics/sprite.s -o out/basics/sprite.nes
 	$(CC65) $(CCOPTS) basics/input.s -o out/basics/input.nes
 	$(CC65) $(CCOPTS) basics/persist.s -o out/basics/persist.nes
+	$(CC65) $(CCOPTS) basics/flicker.s -o out/basics/flicker.nes
 
 	$(CA65) $(CCOPTS) basics/unrom.s -o basics/unrom.o
 	$(LD65) basics/unrom.o -C config/unrom.cfg -o out/basics/unrom.nes
@@ -37,7 +38,7 @@ basics:
 .PHONY: space
 space:
 	@cd space && CC65=$(CC65) CCOPTS="$(CCOPTS)" $(MAKE)
-	@mv space/space.nes out/
+	@mv space/space.nes out/space/
 
 .PHONY: scroll
 scroll:
diff --git a/basics/flicker.s b/basics/flicker.s
index d6c08a7..b170d5e 100644
--- a/basics/flicker.s
+++ b/basics/flicker.s
@@ -1 +1,280 @@
-;; TODO
+;;;
+;; This is a simple example of sprite cycling, so sprites don't disappear on a
+;; scanline overflow. This example is extremely simple, and on a real game you'd
+;; take into account lots of things that would make this process less tedious
+;; and less cycle consuming.
+
+.segment "HEADER"
+    .byte 'N', 'E', 'S', $1A
+
+    .byte $02, $01
+
+    .byte $00
+    .byte $00
+
+.segment "VECTORS"
+    .addr nmi, reset, irq
+
+.segment "CHARS"
+.incbin "../assets/diskun.chr"
+
+.segment "STARTUP"
+.segment "CODE"
+
+.include "../shared/diskun.s"
+
+.proc main
+    jsr Diskun::init_palettes
+    jsr init_sprites
+
+    cli
+    lda #%10010000
+    sta $2000                   ; PPUCTRL
+    lda #%00011110
+    sta $2001                   ; PPUMASK
+
+@main_game_loop:
+    ;; NOTE: the logic is pretty simply: read the pad, move the player
+    ;; accordingly, and apply the flickering effect.
+    jsr Joypad::read
+    jsr Diskun::update
+
+    ;; NOTE: comment this `jsr` out if you want to see what happens if no
+    ;; flickering effect is applied (spoiler alert: the last character will
+    ;; suddenly disappear :P).
+    ;;
+    ;; NOTE: this function is called mindlessly. In a real game you'd try to
+    ;; detect scanline overflows, or you will try to be more careful with sprite
+    ;; priorities and apply the flickering more carefully. Here it's applied for
+    ;; (almost) every sprite on each frame and we roll with it.
+    jsr apply_flicker
+
+    lda #%10000000
+    ora $20
+    sta $20
+@wait_for_render:
+    bit $20
+    bmi @wait_for_render
+
+    jmp @main_game_loop
+.endproc
+
+
+;;;
+;; NOTE: this is the actual meat of the example :D
+.proc apply_flicker
+    ;; We will store a 16-bit pointer to the first sprite that can be flickered.
+    ;; In this case, we will point to the first sprite from the first NPC. That
+    ;; is, we suppose that, for whatever reason, we don't want to apply the
+    ;; flickering effect for the player.
+    lda #$10
+    sta $40
+    lda #$02
+    sta $41
+
+    ;;;
+    ;; The algorithm is really straight-forward here: we will simply cycle the
+    ;; sprites starting from the one being pointed at $40-$41 until the last
+    ;; sprite. The main idea is that the OAM will show sprites on a scanline in
+    ;; order. Hence, those sprites that are left beyond the eigth on a scanline
+    ;; will suddenly disappear. Flickering is a technique by which sprites are
+    ;; rotated from OAM priority, and hence they won't disappear always, but
+    ;; just for a small amount of time: just enough to see them, creating a
+    ;; flickering effect.
+    ;;
+    ;; For this, we will reserve four bytes (1 sprite) for auxiliary temporary
+    ;; values ($42-$45) which will then be used in order to carry values along
+    ;; the cycle.
+
+    ;; We initialize the auxiliary bytes with the data from the last sprite to
+    ;; be iterated since these are the values to be stored for the first sprite
+    ;; now (that is, the last element is now the first one).
+    lda $24C
+    sta $42
+    lda $24D
+    sta $43
+    lda $24E
+    sta $44
+    lda $24F
+    sta $45
+
+@loop:
+    ;; For each of the four bytes from a sprite, pick the value stored on its
+    ;; auxiliary byte and save the old value into the auxiliary byte afterwards.
+    ;; This way the current byte holds the value from the previous sprite, but
+    ;; its value will be carry on into the next sprite.
+    .repeat 4, I
+        ldy #I
+        lda $42, y
+        pha
+        lda ($40), y
+        sta $42, y
+        pla
+        sta ($40), y
+    .endrepeat
+
+    ;; And move the sprite pointer 4 bytes (1 sprite). Note that we only need to
+    ;; move the low byte since we know beforehand that everything will be inside
+    ;; of the $2xx range.
+    lda $40
+    clc
+    adc #4
+    sta $40
+
+    ;; We know that that last byte from the last sprite is held at $24F. Thus,
+    ;; if the sprite pointer is already passed this point, we can break the
+    ;; loop. Otherwise just carry on.
+    cmp #$50
+    bne @loop
+
+    rts
+.endproc
+
+;;;
+;; NOTE: and from here on stuff that is not relevant for sprite flickering.
+
+nmi:
+    bit $20
+    bpl @next
+
+    pha
+    txa
+    pha
+    tya
+    pha
+
+    jsr Diskun::nmi_update
+
+    lda #$00
+    sta $2003                   ; OAMADDR
+    lda #$02
+    sta $4014                   ; OAMDMA
+
+    bit $2002                   ; PPUSTATUS
+    lda #$00
+    sta $2005                   ; PPUSCROLL
+    sta $2005                   ; PPUSCROLL
+
+    lda #%01111111
+    and $20
+    sta $20
+
+    pla
+    tay
+    pla
+    tax
+    pla
+@next:
+    rti
+
+reset:
+    sei
+    cld
+
+    ldx #$40
+    stx $4017                   ; APU Frame Counter
+
+    ldx #$ff
+    txs
+
+    inx
+    stx $2000                   ; PPUCTRL
+    stx $2001                   ; PPUMASK
+    stx $4010                   ; APU DMC
+
+@vblankwait1:
+    bit $2002                   ; PPUSTATUS
+    bpl @vblankwait1
+
+    ldx #0
+    lda #0
+@ram_reset_loop:
+    sta $000, x
+    sta $100, x
+    sta $300, x
+    sta $400, x
+    sta $500, x
+    sta $600, x
+    sta $700, x
+    inx
+    bne @ram_reset_loop         ; if x overflows back to #00, then we are done.
+
+    lda #$ef
+@sprite_reset_loop:
+    sta $200, x
+    inx
+    bne @sprite_reset_loop
+
+    lda #$00
+    sta $2003                   ; OAMADDR
+    lda #$02
+    sta $4014                   ; OAMDMA
+
+@vblankwait2:
+    bit $2002                   ; PPUSTATUS
+    bpl @vblankwait2
+
+    lda #$3F
+    sta $2006                   ; PPUADDR
+    lda #$00
+    sta $2006                   ; PPUADDR
+
+    lda #$0F
+    ldx #$20
+@palettes_reset_loop:
+    sta $2007                   ; PPUDATA
+    dex
+    bne @palettes_reset_loop
+
+    jmp main
+
+irq:
+    rti
+
+.proc init_sprites
+    NUM_SPRITES = 20
+
+    lda #$40
+    sta Diskun::m_screen_y
+    lda #$46
+    sta Diskun::m_screen_x
+
+    ldx #$00
+@load_sprites_loop:
+    lda initial_sprite_data, x
+    sta $0200, x
+    inx
+    cpx #(4 * NUM_SPRITES)
+    bne @load_sprites_loop
+    rts
+initial_sprite_data:
+    ;; $200-$20F
+    .byte $40, $01, %00000000, $46
+    .byte $40, $01, %01000000, $4E
+    .byte $48, $11, %00000000, $46
+    .byte $48, $11, %01000000, $4E
+
+    ;; $210-$21F
+    .byte $60, $01, %00000000, $68
+    .byte $60, $01, %01000000, $70
+    .byte $68, $11, %00000000, $68
+    .byte $68, $11, %01000000, $70
+
+    ;; $220-$22F
+    .byte $60, $01, %00000000, $7A
+    .byte $60, $01, %01000000, $82
+    .byte $68, $11, %00000000, $7A
+    .byte $68, $11, %01000000, $82
+
+    ;; $230-$23F
+    .byte $60, $01, %00000000, $8C
+    .byte $60, $01, %01000000, $94
+    .byte $68, $11, %00000000, $8C
+    .byte $68, $11, %01000000, $94
+
+    ;; $240-$24F
+    .byte $60, $01, %00000000, $9E
+    .byte $60, $01, %01000000, $A6
+    .byte $68, $11, %00000000, $9E
+    .byte $68, $11, %01000000, $A6
+.endproc
diff --git a/shared/diskun.s b/shared/diskun.s
new file mode 100644
index 0000000..d8bab90
--- /dev/null
+++ b/shared/diskun.s
@@ -0,0 +1,95 @@
+;;; Simple sprite that can be moved with the dpad easily. Use it to have
+;;; something funny moving.
+
+.include "joypad.s"
+
+.scope Diskun
+    m_screen_x = $30
+    m_screen_y = $31
+
+    .proc init_palettes
+        lda #$3F
+        sta $2006                   ; PPUADDR
+        lda #$00
+        sta $2006                   ; PPUADDR
+
+        ldx #0
+    @load_palettes_loop:
+        lda palettes, x
+        sta $2007                   ; PPUDATA
+        inx
+        cpx #$20
+        bne @load_palettes_loop
+        rts
+    palettes:
+        DEFAULT_COLOR = $11
+
+        ;; Background
+        .byte DEFAULT_COLOR, $36, $17, $0F
+        .byte DEFAULT_COLOR, $00, $00, $00
+        .byte DEFAULT_COLOR, $00, $00, $00
+        .byte DEFAULT_COLOR, $00, $00, $00
+
+        ;; Foreground
+        .byte DEFAULT_COLOR, $28, $0F, $30
+        .byte DEFAULT_COLOR, $00, $00, $00
+        .byte DEFAULT_COLOR, $00, $00, $00
+        .byte DEFAULT_COLOR, $00, $00, $00
+
+        rts
+    .endproc
+
+    .proc update
+        lda #Joypad::BUTTON_UP
+        and Joypad::m_buttons1
+        beq @check_down
+
+        dec Diskun::m_screen_y
+        dec Diskun::m_screen_y
+        jmp @check_left
+    @check_down:
+        lda #Joypad::BUTTON_DOWN
+        and Joypad::m_buttons1
+        beq @check_left
+
+        inc Diskun::m_screen_y
+        inc Diskun::m_screen_y
+    @check_left:
+        lda #Joypad::BUTTON_LEFT
+        and Joypad::m_buttons1
+        beq @check_right
+
+        dec Diskun::m_screen_x
+        dec Diskun::m_screen_x
+    @check_right:
+        lda #Joypad::BUTTON_RIGHT
+        and Joypad::m_buttons1
+        beq @end
+
+        inc Diskun::m_screen_x
+        inc Diskun::m_screen_x
+    @end:
+        rts
+    .endproc
+
+    .proc nmi_update
+        lda Diskun::m_screen_x
+        sta $203
+        sta $20B
+        clc
+        adc #8
+        sta $207
+        sta $20F
+
+        lda Diskun::m_screen_y
+        sta $200
+        sta $204
+        clc
+        adc #8
+        sta $208
+        sta $20C
+
+        rts
+    .endproc
+.endscope
+
diff --git a/shared/joypad.s b/shared/joypad.s
new file mode 100644
index 0000000..2abf959
--- /dev/null
+++ b/shared/joypad.s
@@ -0,0 +1,56 @@
+;;; TODO: safe read
+
+.scope Joypad
+    ;; Button masks.
+    BUTTON_A      = 1 << 7
+    BUTTON_B      = 1 << 6
+    BUTTON_SELECT = 1 << 5
+    BUTTON_START  = 1 << 4
+    BUTTON_UP     = 1 << 3
+    BUTTON_DOWN   = 1 << 2
+    BUTTON_LEFT   = 1 << 1
+    BUTTON_RIGHT  = 1 << 0
+
+    ;; Port addresses for controllers.
+    JOYPAD1 = $4016
+    JOYPAD2 = $4017
+
+    ;; We keep all the information from controller from mainly two variables:
+    ;; m_buttons1 and m_buttons2; containing respectively the buttons pressed
+    ;; for this frame for both controllers. The m_inv_buttons ($21) is an
+    ;; internal variable and should not be used for anything outside of this
+    ;; usage.
+    m_inv_buttons = $21
+    m_buttons1    = $22
+    m_buttons2    = $23
+
+    ;; READ_CONTROLLER reads the input from the controller mapped into the given
+    ;; port, and saves the state into the given `buttons` address.
+    ;; Implementation taken from NESHacker's example of smb3-like movement.
+    .macro READ_CONTROLLER port, buttons
+        lda m_inv_buttons
+        tay
+        lda #1
+        sta port
+        sta m_inv_buttons
+        lsr
+        sta port
+    :
+        lda port
+        lsr
+        rol m_inv_buttons
+        bcc :-
+        tya
+        eor m_inv_buttons
+        and m_inv_buttons
+        sta buttons
+    .endmacro
+
+    ;; read sets the values for m_buttons1 and m_buttons2 as read from both
+    ;; controllers.
+    .proc read
+        READ_CONTROLLER JOYPAD1, m_buttons1
+        READ_CONTROLLER JOYPAD2, m_buttons2
+        rts
+    .endproc
+.endscope