--- title: writing an nes game, part 2 date: "2014-10-14 15:30" tags: [hacker school, nes] --- # Writing an NES game - code layout So before we get into the code itself, there are a couple more concepts that will be important to understand, in order to understand why the code is laid out the way it is. First, we need to understand how the PPU handles drawing. The NES was designed to work on CRT screens, which work by drawing a horizontal line at a time from the top of the screen to the bottom, at which point it starts again at the top. This is done by a device called an [electron gun](https://en.wikipedia.org/wiki/Electron_gun), which fires electrons at a screen of pixels. The key point here is that drawing is done sequentially, one pixel at a time, and the mechanism requires some amount of time to move from one line to the next, and to move from the bottom of the screen back to the top. The period of time when the electron gun is moving from the end of one line to the beginning of the next is called the "HBlank" time, and the period of time when the electron gun is moving from the bottom of the screen back to the top is called the "VBlank" time. Except during HBlank and VBlank, the PPU is busy controlling what actually needs to be drawn, and manipulating it at all can cause all kinds of weird graphical glitches, so we need to make sure we only communicate with the PPU during HBlank or VBlank. The way the NES handles this is to provide an interrupt (called NMI) which fires at the beginning of every VBlank, which allows you to do all of your drawing during a safe period of time. HBlank is harder to detect and not as useful (since it occurs in the middle of drawing a frame), and so it is not typically used except for some visual effects. NTSC television screens refresh at 60 frames per second, and the CPU clock speed in the NES is approximately 1.79MHz, and so we get approximately 30,000 CPU cycles per frame, which translates into roughly 5,000-10,000 opcodes. VBlank, though, only lasts around 2273 cycles (roughly 400-800 opcodes), so drawing code needs to be especially efficient. In particular, we don't want to do any game logic at all during VBlank time, since that time is so limited. The other aspect that needs to be handled is system initialization. When the CPU starts up, it's in an undefined state, so we need to set things up to ensure that the game executes in a repeatable way. Emulators tend to be consistent in how they initialize the system state at startup, but this isn't true of the real hardware, so it's important to do this explicitly. Also, the PPU requires initialization, but that is handled automatically. It does take a bit over 30,000 CPU cycles though (a little over one frame), so we wait for two frames before starting our main game code. Two frames is plenty of time to do any initialization we might need to do. To illustrate these concepts, here is an example program which modifies the background color every second. The details about how the background color is set isn't particularly important (it's not really a feature you're likely to use very often), but this should illustrate the basic structure of an NES game. This isn't intended to be a lesson on 6502 assembly (there are plenty of much better tutorials and references out there for that - see below), but just to show how games for the NES specifically are structured. ```asm .ROMBANKMAP BANKSTOTAL 2 BANKSIZE $4000 BANKS 1 BANKSIZE $2000 BANKS 1 .ENDRO .MEMORYMAP DEFAULTSLOT 0 SLOTSIZE $4000 SLOT 0 $C000 SLOTSIZE $2000 SLOT 1 $0000 .ENDME .ENUM $00 ; declare the label 'sleeping' to refer to the byte at memory location $0000 sleeping DB ; 'color' will then be at $0001 color DB ; and 'frame_count' will be at $0002 frame_count DB .ENDE .bank 0 slot 0 .org $0000 RESET: ; First, we disable pretty much everything while we try to get the system ; into a consistent state. In particular, we really don't want any ; interrupts to fire until the stack pointer is set up (because interrupt ; calls use the stack), and we don't want any drawing to be done until the ; PPU is initialized. SEI ; disable all IRQs CLD ; disable decimal mode LDX #$FF TXS ; Set up stack (grows down from $FF to $00, at $0100-$01FF) INX ; now X = 0 STX $2000.w ; disable NMI (we'll enable it later once the ppu is ready) STX $2001.w ; disable rendering (we're not using it in this example) STX $4010.w ; disable DMC IRQs LDX #$40 STX $4017.w ; disable APU frame IRQ ; First wait for vblank to make sure PPU is ready. The processor sets a ; status bit when vblank ends, so we just loop until we notice it. vblankwait1: BIT $2002 ; bit 7 of $2002 is reset once vblank ends BPL vblankwait1 ; and bit 7 is what is checked by BPL ; set everything in ram ($0000-$07FF) to $00, except for $0200-$02FF which ; is conventionally used to hold sprite attribute data. we set that range ; to $FE, since that value as a position moves the sprites offscreen, and ; when the sprites are offscreen, it doesn't matter which sprites are ; selected or what their attributes are clrmem: LDA #$00 STA $0000, x STA $0100, x STA $0300, x STA $0400, x STA $0500, x STA $0600, x STA $0700, x LDA #$FE STA $0200, x INX BNE clrmem ; initialize variables in ram LDA #%10000001 STA color ; no need to initialize frame_count or sleeping, since we just set them to ; $00 in the clrmem loop ; Second wait for vblank, PPU is ready after this vblankwait2: BIT $2002 BPL vblankwait2 LDA #%10000000 ; enable NMI interrupts now that the PPU is ready STA $2000 loop: ; sleep while vblank is happening. this serializes the code flow a bit ; (the NMI interrupt will almost certainly occur while we are in this loop ; unless we do a significant amount of processing in the main codepath, so ; it won't interrupt anything important). it also ensures that our game ; logic only executes once per frame. INC sleeping wait_for_vblank_end: LDA sleeping BNE wait_for_vblank_end ; change color every 60 frames LDX frame_count CPX #60 BCS change_color INX STX frame_count JMP loop_end change_color: LDA #$00 STA frame_count LDX color CPX #%10000001 BEQ turn_green CPX #%01000001 BEQ turn_red turn_blue: LDA #%10000001 STA color JMP loop_end turn_green: LDA #%01000001 STA color JMP loop_end turn_red: LDA #%00100001 STA color loop_end: JMP loop NMI: ; save the contents of the registers on the stack, since the interrupt can ; be called at any point in our main loop PHA TXA PHA TYA PHA LDA color STA $2001 ; indicate that we're done drawing for this frame LDA #$00 STA sleeping ; and restore the register contents before returning PLA TAY PLA TAX PLA RTI .orga $FFFA .dw NMI .dw RESET .dw 0 .bank 1 slot 1 .org $0000 .incbin "sprites.chr" ``` The first thing we do when the system turns on is disable IRQ interrupts. Calling and returning from interrupts uses the system stack, but the stack pointer could be pointing anywhere at this point, and so interrupts would be confuse things quite a bit. We never reenable IRQ interrupts here because we don't use them at all (they would be reenabled by the `CLI` instruction). Next we disable decimal mode (this shouldn't actually do anything, since the NES doesn't have a BCD chip, but no real reason not to do this, to avoid confusion) and set the stack pointer to `$FF`. The stack pointer is stored in the register named S, and it is a one-byte offset from the RAM address `$0100`. The stack grows downward, so the stack pointer should start out pointing to `$01FF`, and then it will be decremented by `PHA` instructions and incremented by `PLA` instructions as necessary. Finally, we disable a bunch of other functionality on the PPU and APU, since we don't want them to be active until we have finished initializing. We need to wait for a total of two frames to ensure that the PPU is entirely initialized, so we next wait for the first frame to end, and then clear out the entire RAM space, and then wait for the second frame to end. At this point, the PPU is initialized, so we can enable NMI interrupts (by setting a bit in the PPU control register at `$2000`) and begin our main loop. The main loop is where all of the logic goes. In this example, we just increment the frame count every frame, and change the background color (via some magic) every 60 frames. This allows the NMI interrupt to do nothing more than write a single value to the PPU, without requiring any logic at all. This illustrates the basic principle of using the main game loop to set up values in memory, which the code in the NMI interrupt can just read and act on directly, without requiring any calculations. Here are some more useful links discussing the topics in this post: * [NES ASM Tutorial](http://nixw0rm.altervista.org/files/nesasm.pdf) * [The frame and NMIs](http://wiki.nesdev.com/w/index.php/The_frame_and_NMIs) * [6502 instruction set overview](http://www.dwheeler.com/6502/oneelkruns/asm1step.html) * [6502 instruction set reference](http://e-tradition.net/bytes/6502/6502_instruction_set.html) * [NES technical documentation](http://emu-docs.org/NES/nestech.txt)