NintendoAge

Nightman vs. Justice Incarnate

Mario's Right Nut — 2009-11-12T10:38:05 -05.0 0

Lookin' good. Don't steal it or I won't post any more as I make progress. Don't ruin it for everyone. Should work up through the neck of the ship. Still needs some debugging. Use Start or Select to open the doors.

Thanks to all the people who have been helping me along! You guys rock.

Idea for a new game

Benihana — 2009-11-10T17:09:41 -05.0 0

Think it would be possible to do on top scroller type game like these? I mean you could use a certain button/d-pad combo for each chord...With the huge music craze now aday's I think an 8 bit version would be a total blast, with 80's songs only...Espicially if it is challanging with only the D-pad and the A/B buttons...
I know the music would be pretty weak, but hey if Journey had an Atari game, then why not on the NES?
What do you think?

Nerdy Nights Sound: Part 8

MetalSlime — 2009-11-10T07:13:52 -05.0 0

Last Week: Volume Envelopes

This Week: Opcodes and Looping

Opcodes

So far our sound engine handles two type of data that it reads from music data streams: notes and note lengths. This is enough to write complex music but of course we are going to want more features. We will want control over the sound of our notes. What if we want to change duty cycles midstream? Or volume envelopes? Or keys? What if we want to loop one part of the song four times? Or loop the entire song continuously? What if we want to play a sound effect as part of a song?

All of these types of features, features where you are issuing commands to the engine, are going to be done through opcodes (also called control codes or command codes). An opcode is a value in the data stream that tells the engine to run a specific, specialized subroutine or piece of code. Most opcodes will have arguments sent along with them. For example, an opcode that changes a stream's volume envelope will come with an argument that specifies which volume envelope to change to.

We've actually been using an opcode for weeks, I just haven't mentioned it. It's the opcode that ends a sound, and we've been encoding it in our data streams as $FF. Here is the code we've been using:

se_fetch_byte:

    ;---snip--- (fetch a byte and range test)

.opcode:                     ;else it's an opcode
    ;do Opcode stuff
    cmp #$FF
    bne .end
    lda stream_status, x    ;if $FF, end of stream, so disable it and silence
    and #%11111110
    sta stream_status, x    ;clear enable flag in status byte

    lda stream_channel, x
    cmp #TRIANGLE
    beq .silence_tri        ;triangle is silenced differently from squares and noise
    lda #$30                ;squares and noise silenced with #$30
    bne .silence
.silence_tri:
    lda #$80                ;triangle silenced with #$80
.silence:
    sta stream_vol_duty, x ;store silence value in the stream's volume variable.
    jmp .update_pointer     ;done

    ;---snip--- (do note lengths and notes, update the stream's pointer)
    rts

Here we check if the byte read has a value of $FF. If so we turn the stream off and silence it. That's an opcode.

It would be pretty messy if every opcode we had was just written straight out like this. Normally we would pull this code into its own subroutine, like this:

se_fetch_byte:

    ;---snip--- (fetch a byte and range test)

.opcode:                    ;else it's an opcode
    ;do Opcode stuff
    cmp #$FF                ;end sound opcode
    bne .end
jsr se_op_endsound      ;call the endsound subroutine
    iny
    jmp .fetch              ;grab the next byte in the stream.

    ;---snip--- (do note lengths and notes, update the stream's pointer)
    rts

se_op_endsound:
    lda stream_status, x    ;end of stream, so disable it and silence
    and #%11111110
    sta stream_status, x    ;clear enable flag in status byte

    lda stream_channel, x
    cmp #TRIANGLE
    beq .silence_tri        ;triangle is silenced differently from squares and noise
    lda #$30                ;squares and noise silenced with #$30
    bne .silence
.silence_tri:
    lda #$80                ;triangle silenced with #$80
.silence:
    sta stream_vol_duty, x ;store silence value in the stream's volume variable.
    rts

The .opcode branch is much shorter now. If we wanted to add more opcodes, we could just add some more compares:

.opcode:
    ;do Opcode stuff
    cmp #$FF            ;is it the end sound opcode?
    bne .not_FF
    jsr se_op_endsound ;if so, call the end sound subroutine
    jmp .end            ;and finish
.not_FF:
    cmp #$FE            ;else is it the loop opcode?
    bne .not_FE
    jsr se_op_loop      ;if so, call the loop subroutine
    jmp .opcode_done
.not_FE:
    cmp #$FD            ;else is it the change volume envelope opcode?
    bne .not_FD
    jsr se_op_change_ve ;if so, call the change volume envelope subroutine
    jmp .opcode_done
.not_FD:
.opcode_done:
    iny                 ;update index to next byte in the data stream
    jmp .fetch          ;go fetch another byte


This will work, but it's ugly. The more opcodes we add to our engine, the more checks we need to make. What if we have 20 opcodes? Do we really want to do that many compares? It's a waste of ROM space and cycles.

Tables
Anytime you find yourself in a situation where you are doing a lot of CMPs on one value, the answer is to use a lookup table. It will simplify everything! We've done it already with notes, note lengths, song numbers and volume envelopes. Could you imagine trying to get a note's period without using the lookup table? It would look like this:

Is the note an A1? If so, use this period, else
Is the note an A#1? If so, use this period, else
Is the note a B1? If so, use this period, else
Is the note a C2? If so, use this period, else
... (about 100 more checks)
Is the note an F#9? If so, use this period, else
Is the note a rest? If so, use this period

That's just crazy. It would be hundreds of lines of unreadable code and you'd run into branch-range errors too. When we use a lookup table, the code is simplified to this:

.note:
    ;do Note stuff
    sty sound_temp1     ;save our index
    asl a
    tay
    lda note_table, y
    sta stream_note_LO, x
    lda note_table+1, y
    sta stream_note_HI, x
    ldy sound_temp1     ;restore data stream index

Much cleaner. Again, I can't stress it enough: if you find yourself doing lots of CMPs on a single value, use a table instead!

With notes and note lengths we used a straight lookup table of values. With song numbers and volume envelopes we used a special type of lookup table called a pointer table, which stored data addresses. For opcodes we have two choices. We can use something called a jump table or we can use an RTS table. They are almost the same and the difference in performance between the two methods is negligible so for most programmers it's a matter of personal preference.

I prefer RTS tables myself, but we're going to use jump tables because they are easier to explain and understand.

Jump Tables
Ok, here's our problem: Our sound engine has opcodes. A lot of them, let's say 10 or more. Each opcode has its own subroutine. When our sound engine reads an opcode byte from the data stream, we want to avoid a long list of CMP and BNE instructions to select the right subroutine. How do we do that?   We use a jump table.

A jump table is similar to a pointer table: it is a table of addresses. But whereas a pointer table holds addresses that point to the start of data, a jump table holds addresses that point to the start of code (ie, the start of subroutines). For example, suppose we have some subroutines:

sub_a:
    lda #$00
    ldx #$FF
    rts

sub_b:
    clc
    adc #$03
    rts

sub_c:
    sec
    sbc #$03
    rts

Here is how a jump table would look using these subroutines:

sub_jump_table:
    .word sub_a, sub_b, sub_c

Hey, that's pretty easy. We just use the subroutine label and the assembler will translate that into the address where the subroutine starts. Let's make a jump table for our sound opcode subroutines:

se_op_endsound:
    ;do stuff
    rts

se_op_infinite_loop:
    ;do stuff
    rts

se_op_change_ve:
    ;do stuff
    rts

;etc.. more subroutines

;this is our jump table
sound_opcodes:
    .word se_op_endsound
    .word se_op_infinite_loop
    .word se_op_change_ve
    ;etc, one entry per subroutine

Cool. We have a jump table now. So how do we use it?

Indirect Jumping
The 6502 let's us do some cool things. One of those things is called an indirect jump. An indirect jump let's you stick a destination address into a zero-page pointer variable and jump there. It works like this:

    .rsset $0000
;first declare a pointer variable somewhere in the zero-page
jmp_ptr .rs 2 ;2 bytes because an address is always a word

    lda #$00
    sta jmp_ptr
    lda #$80
    sta jmp_ptr+1
    jmp [jmp_ptr] ;will jump to $8000

Here we stick an address ($8000, lo byte first) into our jmp_ptr variable. Then we do an indirect jump by using the JMP instruction followed by a pointer variable in brackets:

    jmp [jmp_ptr] ;indirect jump

This instruction translates into English as "Jump to the address that is stored in jmp_ptr and jmp_ptr+1". It's extrememly useful. We can stick any address we want in there:

    lda #$00
    sta jmp_ptr
    lda #$C0
    sta jmp_ptr+1
    jmp [jmp_ptr] ;will jump to $C000

We could read an address from ROM and use that if we wanted to, for example our reset vector:

    lda $FFFC
    sta jmp_ptr
    lda $FFFD
    sta jmp_ptr+1
    jmp [jmp_ptr] ;will jump to our reset routine

And we can use it in combination with our jump table:

    lda sound_opcodes, y    ;read low byte of address from jump table
    sta jmp_ptr
    lda sound_opcodes+1, y ;read high byte
    sta jmp_ptr+1
    jmp [jmp_ptr]   ;will jump to whatever address we pulled from the table.

Pretty powerful. We can dynamically jump to any section of code we want!

Implementation
So we know how to build a jump table and we know how to do an indirect jump. Let's tie it all together and stick it into our sound engine. Let's start with se_fetch_byte. se_fetch_byte reads a byte from the data stream and range-checks it to see if it is a note, note length or opcode. Recall that notes have a byte range of $00-$7F. Note lengths have a range of $80-$9F. The opcode byte range is $A0-$FF:

se_fetch_byte:
    lda stream_ptr_LO, x
    sta sound_ptr
    lda stream_ptr_HI, x
    sta sound_ptr+1

    ldy #$00
    lda [sound_ptr], y
    bpl .note                ;if < #$80, it's a Note
    cmp #$A0
    bcc .note_length         ;else if < #$A0, it's a Note Length
.opcode:                     ;else ($A0-$FF) it's an opcode
    ;do Opcode stuff
.note_length:
    ;do note length stuff
.note:
    ;do note stuff

So we need to assign our opcodes to values between $A0 and $FF. Just as with notes and note lengths, the opcode byte we read from the data stream will be used as a table index (after subtracting $A0), so we will assign our opcodes in the same order as our table:

sound_opcodes:
    .word se_op_endsound            ;this should be $A0
    .word se_op_infinite_loop       ;this should be $A1
    .word se_op_change_ve           ;this should be $A2
    ;etc, 1 entry per subroutine

;these are aliases to use in the sound data.
endsound = $A0
loop = $A1              ;be careful of conflicts here. this might be too generic. maybe song_loop is better
volume_envelope = $A2

Now let's alter se_fetch_byte to take care of our opcodes:

se_fetch_byte:
    lda stream_ptr_LO, x
    sta sound_ptr
    lda stream_ptr_HI, x
    sta sound_ptr+1

    ldy #$00
.fetch:
    lda [sound_ptr], y
    bpl .note                ;if < #$80, it's a Note
    cmp #$A0
    bcc .note_length         ;else if < #$A0, it's a Note Length
.opcode:                     ;else ($A0-$FF) it's an opcode
    ;do Opcode stuff
    jsr se_opcode_launcher   ;launch our opcode!!!
    iny                      ;next position in the data stream
    lda stream_status, x
    and #%00000001
    bne .fetch               ;after our opcode is done, grab another byte unless the stream is disabled
    rts                      ; in which case we quit (explained below)
.note_length:
    ;do note length stuff
.note:
    ;do note stuff

I added a call to a subroutine called se_opcode_launcher and a little branch. Not a big change is it? But there's an important detail here. se_opcode_launcher will be a short, simple subroutine that will read from the jump table and perform an indirect jump. It looks like this:

se_opcode_launcher:
    sty sound_temp1         ;save y register, because we are about to destroy it
    sec
    sbc #$A0                ;turn our opcode byte into a table index by subtracting $A0
                            ;   $A0->$00, $A1->$01, $A2->$02, etc. Tables index from $00.
    asl a                   ;multiply by 2 because we index into a table of addresses (words)
    tay
    lda sound_opcodes, y    ;get low byte of subroutine address
    sta jmp_ptr
    lda sound_opcodes+1, y ;get high byte
    sta jmp_ptr+1
    ldy sound_temp1         ;restore our y register
    iny                     ;set to next position in data stream (assume an argument)
    jmp [jmp_ptr]           ;indirect jump to our opcode subroutine

Short and simple. So why did I wrap this code in its own subroutine? Why not just stick this code as-is in the .opcode branch of se_fetch_byte? Because we need a place to return to.

The JSR and RTS instructions work as a pair. They go hand in hand. They need each other. Without going into too much detail, this is what goes on behind the scenes:

JSR sticks a return address on the stack and jumps to a subroutine. One way to look at it is to think of JSR as a JMP that remembers where it started from.
RTS pops the return address off the stack and jumps there.

So JSR leaves a treasure map for RTS to pick up and follow later. The key point here is that RTS expects a return address to be waiting for it on the stack.

Now our opcode subroutines all end in an RTS instruction. Do you see the potential problem here?

We call our opcode subroutines using an indirect jump. This requires us to use a JMP instruction, not a JSR instruction. A JMP instruction doesn't remember where it started from. No return address is pushed onto the stack with a JMP instruction. So when we jump to our opcode subroutine and hit the RTS instruction at the end, there is no return address waiting for us! The RTS will pull whatever random values happen to be on the stack at the time and jump there. We'll end up somewhere random and our program will surely crash!

To fix this, we wrap our indirect jump in a subroutine, se_opcode_launcher. We call it with a JSR instruction, completing the JSR/RTS pair:

    jsr se_opcode_launcher ;this jsr will let us remember where we came from

This JSR instruction will stick a return address on the stack for us. Then inside se_opcode_launcher we perform our indirect jump to our desired opcode subroutine. Now when we hit that RTS instruction at the end of the opcode subroutine we have a return address waiting for us on the stack. Our program returns back to where we started. We are safe.

Opcode Subroutines
With our opcode launcher written, we are all set up to make opcodes. We already have one written: the endsound opcode. This is the opcode we will use to terminate sound effects. Sound effects don't loop continuously like songs do, so they need to be stopped. Let's take a look again:

se_op_endsound:
    lda stream_status, x    ;end of stream, so disable it and silence
    and #%11111110
    sta stream_status, x    ;clear enable flag in status byte

    lda stream_channel, x
    cmp #TRIANGLE
    beq .silence_tri        ;triangle is silenced differently from squares and noise
    lda #$30                ;squares and noise silenced with #$30
    bne .silence            ; (this will always branch. bne is cheaper than a jmp)
.silence_tri:
    lda #$80                ;triangle silenced with #$80
.silence:
    sta stream_vol_duty, x ;store silence value in the stream's volume variable.

    rts

This opcode is special. It's the reason for the check after the call to se_opcode_launcher:

se_fetch_byte:
    ;---snip---
.opcode:                     ;else ($A0-$FF) it's an opcode
    ;do Opcode stuff
    jsr se_opcode_launcher
    iny                      ;next position in the data stream
    lda stream_status, x
    and #%00000001
    bne .fetch               ;after our opcode is done, grab another byte unless the stream is disabled
    rts                      ; in which case we quit (explained below)

    ;---snip---

Normally, we want se_fetch_byte to keep fetching bytes until it hits a note. Recall that with note lengths we jumped back to .fetch after setting the new note length. This is because after setting the length of the note, we needed to know WHAT note to play. So we fetch another byte. The same thing is true of opcodes. If we change the volume envelope with an opcode, great! But we still need to know what note to play next. If we use an opcode to switch our square's duty cycle, great! But we still need to know what note to play next. If we use an opcode to loop back to the beginning of the song, that's great! But we still need to read that first note of the song. This is why we jump back to fetch a byte after we run an opcode.

The ONE exception to this rule is when we end a sound effect. We are terminating the sound effect completely, so there is no next note. We don't want to fetch something that isn't there, so we need to skip the jump. That's why we check the status byte after we run the opcode. If the stream is disabled by the endsound opcode, we are finished. Otherwise, fetch another byte.

Looping
The next opcode in our list is the loop opcode. This is the opcode that we will stick at the end of every song to tell the sound engine to play the song again, and again and again. It is actually quite easy to implement. It takes a 2-byte argument, which is the address to loop back to. The subroutine looks like this:

se_op_infinite_loop:
    lda [sound_ptr], y      ;read LO byte of the address argument from the data stream
    sta stream_ptr_LO, x    ;save as our new data stream position
    iny
    lda [sound_ptr], y      ;read HI byte of the address argument from the data stream
    sta stream_ptr_HI, x    ;save as our new data stream position data stream position

    sta sound_ptr+1         ;update the pointer to reflect the new position.
    lda stream_ptr_LO, x
    sta sound_ptr
    ldy #$FF                ;after opcodes return, we do an iny. Since we reset
                            ;the stream buffer position, we will want y to start out at 0 again.
    rts

The first thing to notice about this subroutine is that it reads two bytes from the data stream. This is the address argument that gets passed along with the opcode. To make it clear, let's look at some example sound data:

song1_square1:
    .byte eighth ;set note length to eighth notes
    .byte C5, E5, G5, C6, E6, G6, C5, Eb5, G5, C6, Eb6, half, G6 ;play some notes
    .byte loop          ;this alias evaluates to $A1, the loop opcode
    .word song1_square1 ;this evaluates to the address of the song1_square1 label
                        ;ie, the address we want to loop to.

After the "loop" opcode comes a word which is the address to loop back to. In this example I chose to loop back to the beginning of the stream data.

So what does our loop opcode do? It reads the first byte of this address argument (the low byte) and stores it in stream_ptr_LO. Then it reads the second byte of the address argument (the high byte) and stores it in stream_ptr_HI. These are the variables that keep track of our data stream position! The loop opcode just changes these values to some address that we specify. Not too complicated at all. The last step is to update the actual pointer (sound_ptr) so that the next byte we read from the data stream will be the first note we looped back to.

In the example sound data above I looped back to the beginning of the stream data, but there's nothing stopping me from looping somewhere else:

song1_square1:
;intro, don't loop this part
    .byte quarter
    .byte C4, C4, C4, C4
.loop_point:    ;this is where we will loop back to.
    .byte eighth ;set note length to eighth notes
    .byte C5, E5, G5, C6, E6, G6, C5, Eb5, G5, C6, Eb6, half, G6
    .byte loop          ;this alias evaluates to $A1, the loop opcode
    .word .loop_point ;this evaluates to the address of the .loop_point label
                        ;ie, the address we want to loop to.

Technically we can also "loop" to a forward position, in which case it's actually more like a jump than a loop. That's all a loop is really: a jump... backwards.

Changing Volume Envelopes
Let's write the opcode subroutine to change volume envelopes. This one is even easier. It takes one argument, which will be which volume envelope to switch to:

se_op_change_ve:
    lda [sound_ptr], y      ;read the argument
    sta stream_ve, x        ;store it in our volume envelope variable
    lda #$00
    sta stream_ve_index, x ;reset volume envelope index to the beginning
    rts

That's it!

Changing Duty Cycles
Now let's add an opcode that will change the duty cycle for a square stream. This one also takes one argument: which duty cycle to switch to.

se_op_duty:
    lda [sound_ptr], y      ;read the argument (which duty cycle to change to)
    sta stream_vol_duty, x ;store it.
    rts

Done! Now we have the subroutine, but we still need to add it to our jump table:

sound_opcodes:
    .word se_op_endsound            ;this should be $A0
    .word se_op_loop                ;this should be $A1
    .word se_op_change_ve           ;this should be $A2
    .word se_op_duty                ;this should be $A3
    ;etc, 1 entry per subroutine

;these are aliases to use in the sound data.
endsound = $A0
loop = $A1
volume_envelope = $A2
duty = $A3

And it's ready to use:

song0_square1:
;intro, don't loop this part
    .byte quarter
    .byte C4, C4, C4, C4
.loop_point:                            ;this is where we will loop back to.
    .byte duty, $B0                     ;change the duty cycle
    .byte volume_envelope, ve_blip_echo ;change the volume envelope
    .byte eighth                        ;set note length to eighth notes
    .byte C5, E5, G5, C6, E6, G6        ;play some notes

    .byte duty, $30                     ;change the duty cycle
    .byte volume_envelope, ve_short_staccato    ;change volume envelope
    .byte C5, Eb5, G5, C6, Eb6, half, G6    ;play some eighth notes and a half note

    .byte loop                          ;loop to .loop_point
    .word .loop_point

Readability
sound_engine.asm is getting pretty bulky with all these subroutines. It will only get bigger as we add more opcodes. It's nice to have all of our opcodes together in one place, but it's annoying to have to scroll around to find them. So let's pull all of our opcodes into their own file: sound_opcodes.asm. Then, at the bottom of sound_engine.asm, we can .include it:

    .include "sound_opcodes.asm" ;our opcode subroutines, jump table and aliases
    .include "note_table.i" ;period lookup table for notes
    .include "note_length_table.i"
    .include "vol_envelopes.i"
    .include "song0.i" ;holds the data for song 0 (header and data streams)
    .include "song1.i" ;holds the data for song 1
    .include "song2.i"
    .include "song3.i"
    .include "song4.i"
    .include "song5.i"
    .include "song6.i" ;oooh.. new song!

I gave it the extension .asm because it contains code as well as data, and I like to be able to tell at a glance what files have what in them. Now whenever we want to add new opcodes, or tweak old ones, we have them nice and compact in their own file.

Updating Sound Data
Whenever we add new things to our sound engine, we have to think about how it will affect our old sound data. This week we added opcodes, which will change our songs and sound effects terminate. Before we were terminating them with $FF. This won't work anymore because $FF doesn't do anything. For songs, we should terminate with "loop" followed by an address to loop to. With sound effects we should terminate with the opcode "endsound". See the included songs and sound effects for examples.

RTS Tables
We talked about jump tables and indirect jumping this week. Another method for doing the same thing involves something called an RTS table and the RTS Trick. I won't cover it in these tutorials, but if you are curious to know how this works you can read this nesdev wiki article I wrote about the RTS Trick.

Putting It All Together
Download and unzip the opcodes.zip sample files. Make sure the following files are in the same folder as NESASM3:

    opcodes.asm
    sound_engine.asm
    sound_opcodes.asm
    opcodes.chr
    note_table.i
    note_length_table.i
    vol_envelopes.i
    song0.i
    song1.i
    song2.i
    song3.i
    song4.i
    song5.i
    song6.i
    opcodes.bat

Double click opcodes.bat. That will run NESASM3 and should produce the opcodes.nes file. Run that NES file in FCEUXD SP.

Use the controller to select songs and play them. Controls are as follows:

Up: Play
Down: Stop
Right: Next Song/SFX
Left: Previous Song/SFX

Song0 is a silence song. Not selectable.
Song1 is a boss song from The Guardian Legend. Now it loops!
Song2 is the same short sound effect from last week. Terminated with endsound.
Song3 is a song from Dragon Warrior. Now it loops!
Song4 is the same song4 as last week, but now it loops!
Song5 is a short sound effect, terminated with the endsound opcode.
Song6 should be familiar to readers of this forum. Do you recognize it? It utilizes opcodes for changing duty cycles and volume envelopes. Plus it loops!

Try adding your own songs and sound effects in. Try to add your own opcodes too. Here's some ideas for opcodes:

1. Trigger a sound effect mid-song
2. Implement duty cycle envelopes (similar to volume envelopes). Then make an opcode that allows you to change it.
3. Finite loops

Next Week: more opcode fun. Finite Loops, Changing Keys and Automatic Chord Progressions.

Flash Action Script 3

IntrglctcNinjaPirate — 2009-11-08T11:23:35 -05.0 0

For the past few months I have been writing simple ship shooter episodes in AS3. The ships load offstage, fly in, and are removed via kill, or negative X axis.

anyone else using this method, or perhaps a better one?

http://www.intergalacticninjapirate.com

what is everyone else working on in flash?

ThAnx,
INP

NESdev wiki wants info about projects

Sivak — 2009-11-05T23:48:37 -05.0 0

I've made up some pages for my projects, but others can register and do up pages for theirs if they wish.

http://wiki.nesdev.com/w/index.php/Projects - The page where to make links.

You do need to register and you also need permission from admins if you want to post images. I posted some trivia on my games.

Another platformer by someone at nesdev

Sivak — 2009-11-05T13:29:48 -05.0 0

This was interesting-looking I thought:

http://www.youtube.com/watch?v=jFoBdeLDVc8

Also doesn't have scrolling, except for when you touch the edges of screens.

Nerdy Nights Sound: Part 7

MetalSlime — 2009-11-02T05:15:05 -05.0 0

Last Week: Tempo, Note Lengths, Buffering and Rests

This Week: Volume Envelopes

Volume Envelopes

This week we will add volume envelopes to our engine. A volume envelope is a series of volume values that are applied to a note one frame at a time. For example, if we had a volume envelope that looked like this:

F E D C 9 5 0

Then whenever we played a note, it would have a volume of F on the first frame, a volume of E on the second frame, then D, then C, then 9, then 5 until it is finally silenced with a volume of 0 on the 7th frame. Applying this volume envelope on our notes would give them a sharp, short staccato feel. Conversely, if we had a volume envelope that looked like this:

1 1 2 2 3 3 4 4 7 7 8 8 A A C C D D E E F F F

Each note would start very quietly and fade in to full volume. Look at this volume envelope:

D D D C B 0 0 0 0 0 0 0 0 6 6 6 5 4 0

Here we start at a high volume (D) and let it ring for 5 frames. Then we silence the note for 8 frames. Then the note comes back at a very low volume for 5 frames. Notes using this volume envelope would sound like they had an faint echo.

As you can see, volume envelopes are pretty cool. We can get a lot of different sounds out of them. Let's add them in.

Channels
Volume envelopes are best suited for the square and noise channels where we have full control of the volume. The triangle channel on the other hand doesn't allow much volume control. It only has two settings: full blast and off. We can still apply volume envelopes in a limited way though. Consider these two volume envelopes:

0F 0E 0D 0C 09 05 00

04 04 05 05 06 06 07 07 08 08 09 09 0A 0A 00

These two envelopes would have a vastly different sound on the square channels, but to the triangle they look like this:

On On On On On On Off
On On On On On On On On On On On On On On Off

You don't get the subtle shifts in volume, but you do get a different length. We can use volume envelopes that end in 00 to control when the triangle key-off occurs. Not as cool as full volume control, but still useful.

Defining volume envelopes
First let's define some volume envelopes so we have some data to work with. We'll use some of the examples from above:

se_ve_1:
    .byte $0F, $0E, $0D, $0C, $09, $05, $00
    .byte $FF
se_ve_2:
    .byte $01, $01, $02, $02, $03, $03, $04, $04, $07, $07
    .byte $08, $08, $0A, $0A, $0C, $0C, $0D, $0D, $0E, $0E
    .byte $0F, $0F
    .byte $FF
se_ve_3:
    .byte $0D, $0D, $0D, $0C, $0B, $00, $00, $00, $00, $00
    .byte $00, $00, $00, $00, $06, $06, $06, $05, $04, $00
    .byte $FF

Notice that I terminated each envelope with $FF. We need some terminator value so the engine will know when we've reached the end of the envelope. We could have used any value, but $FF is pretty common.

Next we will make a pointer table that holds the addresses of our volume envelopes:

volume_envelopes:
    .word se_ve_1, se_ve_2, se_ve_3

Declaring variables
In order to apply a volume envelope to a particular stream, we will need a variable that tells us which one to use. We will also need an index variable that tells us our current position within the volume envelope:

stream_ve .rs 6         ;current volume envelope
stream_ve_index .rs 6   ;current position within the volume envelope

stream_ve will tell us which volume envelope to use. Code-wise, it will act as an index into our pointer table so we know where to read from. Sound familiar? It works the same way as "song number" did for loading a song. We aren't there yet, but here's a peek at how we will use these variables to read from the volume envelopes. (x holds the stream number):

    sty sound_temp1             ;save y because we are about to destroy it.

    lda stream_ve, x            ;which volume envelope?
    asl a                       ;multiply by 2 because we are indexing into a table of addresses (words)
    tay
    lda volume_envelopes, y     ;get the low byte of the address from the pointer table
    sta sound_ptr
    lda volume_envelopes+1, y   ;get the high byte of the address
    sta sound_ptr+1

    ldy stream_ve_index, x      ;our current position within the volume envelope.
    lda [sound_ptr], y          ;grab the value.
    ;check against $FF (our termination value)
    ;set the volume
    ;increment stream_ve_index
    ;etc

Compare this code to the beginning of the sound_load routine. Are you starting to see a pattern?

Initializing
Whenever we add a new feature, we need to consider how we should initialize it. Every stream in our music data will potentially have a different volume envelope, so we should add a volume envelope field to our header. Volume envelopes will deprecate our old "initial volume" field, but we will still need to have duty cycle info, so we'll just rename that field:

main header:
--------+----------------
byte # | what it tells us
--------+----------------
00      | number of streams
01+     | stream headers (one for each stream)

stream headers:
--------+----------------
byte # | what it tells us
--------+----------------
00      | which stream (stream number)
01      | status byte
02      | which channel
03      | initial duty (for triangle, set the 7bit)
04      | volume envelope
05-06   | pointer to data stream
07      | initial tempo

To read this data from the header, we will have to insert the following code into our sound_load routine (after reading the duty):

    lda [sound_ptr], y      ;the stream's volume envelope
    sta stream_ve, x
    iny

Notes will always start from the beginning of the volume envelope, so we can just initialize stream_ve_index to 0:

    lda #$00
    sta stream_ve_index, x

Now we just need to make sure to assign volume envelopes to all the streams in our song data and we're ready to go:

song5_header:
    .byte $01           ;1 stream

    .byte SFX_1         ;which stream
    .byte $01           ;status byte (stream enabled)
    .byte SQUARE_2      ;which channel
    .byte $70           ;initial duty (01). Initial volume deprecated.
    .byte $00           ;the first volume envelope (se_ve_1)
    .word song5_square2 ;pointer to stream
    .byte $FF           ;tempo..very fast tempo

Remember that you can always create descriptive aliases for your volume envelopes if you don't want to remember which number is which:

;volume envelope aliases
ve_short_staccato = $00
ve_fade_in = $01
ve_blip_echo = $02

song5_header:
    .byte $01           ;1 stream

    .byte SFX_1         ;which stream
    .byte $01           ;status byte (stream enabled)
    .byte SQUARE_2      ;which channel
    .byte $7F           ;initial duty (01). Initial volume deprecated.
    .byte ve_short_staccato   ;the first volume envelope (se_ve_1)
    .word song5_square2 ;pointer to stream
    .byte $FF           ;tempo..very fast tempo

Using aliases is a good idea because the assembler will give you an error if you mistype your alias. If you mistype your number, and it is still a valid number, the assembler won't know there's a problem and will assemble it. This kind of bug in your data can be hard to trace.

Implementing Volume Envelopes

To implement volume envelopes, we need to modify the code where we set the volume. Instead of using a fixed value like we were doing before, we need to read from our current position in the volume envelope and use that value instead. Our volume code is starting to get a little complicated, so let's pull it out into its own subroutine. This will make our code easier to follow:

;----------------------------------------------------
; se_set_temp_ports will copy a stream's sound data to the temporary apu variables
;      input:
;           X: stream number
se_set_temp_ports:
    lda stream_channel, x
    asl a
    asl a
    tay

    jsr se_set_stream_volume    ;let's stick all of our volume code into a new subroutine
                                ;less cluttered that way

    lda #$08
    sta soft_apu_ports+1, y     ;sweep

    lda stream_note_LO, x
    sta soft_apu_ports+2, y     ;period LO

    lda stream_note_HI, x
    sta soft_apu_ports+3, y     ;period HI

    rts

What should our new subroutine se_set_stream_volume do? First it needs to read a value from our stream's volume envelope. Then it needs to modify the stream's volume using that value. Then we need to update our position within the volume envelope. Finally it needs to check to see if we are resting, and silence the stream if we are (we wrote this code last week). It looks something like this (new code in red):

se_set_stream_volume:
    sty sound_temp1             ;save our index into soft_apu_ports (we are about to destroy y)

    lda stream_ve, x            ;which volume envelope?
    asl a                       ;multiply by 2 because we are indexing into a table of addresses (words)
    tay
    lda volume_envelopes, y     ;get the low byte of the address from the pointer table
    sta sound_ptr               ;put it into our pointer variable
    lda volume_envelopes+1, y   ;get the high byte of the address
    sta sound_ptr+1

.read_ve:
    ldy stream_ve_index, x      ;our current position within the volume envelope.
    lda [sound_ptr], y          ;grab the value.
    cmp #$FF
    bne .set_vol                ;if not FF, set the volume
    dec stream_ve_index, x      ;else if FF, go back one and read again
    jmp .read_ve                ; FF essentially tells us to repeat the last
                                ; volume value for the remainder of the note
.set_vol:
    sta sound_temp2             ;save our new volume value (about to destroy A)
    lda stream_vol_duty, x      ;get current vol/duty settings
    and #$F0                    ;zero out the old volume
    ora sound_temp2             ;OR our new volume in.

    ldy sound_temp1             ;get our index into soft_apu_ports
    sta soft_apu_ports, y       ;store the volume in our temp port
    inc stream_ve_index, x      ;set our volume envelop index to the next position

.rest_check:
    ;check the rest flag. if set, overwrite volume with silence value
    lda stream_status, x
    and #%00000010
    beq .done                   ;if clear, no rest, so quit
    lda stream_channel, x
    cmp #TRIANGLE               ;if triangle, silence with #$80
    beq .tri                    ;else, silence with #$30
    lda #$30
    bne .store                  ;this always branches. bne is cheaper than a jmp
.tri:
    lda #$80
.store:
    sta soft_apu_ports, y
.done:
    rts

After we read a value from our volume envelope, we AND stream_vol_duty with #$F0. This has the nice effect of clearing the old volume while preserving our squares' duty cycle settings. But we need to be careful here. Recall that the triangle channel's on/off status is controlled by the low 7 bits of the port:

TRI_CTRL ($4008)

76543210
||||||||
|+++++++- Value
+-------- Control Flag (0: use internal counters; 1: disable internal counters)

If any of those Value bits are set, the triangle channel will be considered on. Consider what happens if bit 4, 5 or 6 happen to be set. In this case, ANDing with #$F0 won't turn the triangle channel off. If the volume we pull from the volume envelope is 0, it won't silence our triangle channel because bit 4, 5 or 6 will still be set. If we are careful not to set these bits in our song headers, the problem should never come up. But for completeness we should fix it:

se_set_stream_volume:
    sty sound_temp1             ;save our index into soft_apu_ports (we are about to destroy y)

    lda stream_ve, x            ;which volume envelope?
    asl a                       ;multiply by 2 because we are indexing into a table of addresses (words)
    tay
    lda volume_envelopes, y     ;get the low byte of the address from the pointer table
    sta sound_ptr               ;put it into our pointer variable
    lda volume_envelopes+1, y   ;get the high byte of the address
    sta sound_ptr+1

.read_ve:
    ldy stream_ve_index, x      ;our current position within the volume envelope.
    lda [sound_ptr], y          ;grab the value.
    cmp #$FF
    bne .set_vol                ;if not FF, set the volume
    dec stream_ve_index, x      ;else if FF, go back one and read again
    jmp .read_ve                ; FF essentially tells us to repeat the last
                                ; volume value for the remainder of the note
.set_vol:
    sta sound_temp2             ;save our new volume value (about to destroy A)

    cpx #TRIANGLE
    bne .squares                ;if not triangle channel, go ahead
    lda sound_temp2
    bne .squares                ;else if volume not zero, go ahead (treat same as squares)
    lda #$80
    bmi .store_vol              ;else silence the channel with #$80
.squares:
    lda stream_vol_duty, x      ;get current vol/duty settings
    and #$F0                    ;zero out the old volume
    ora sound_temp2             ;OR our new volume in.

.store_vol:
    ldy sound_temp1             ;get our index into soft_apu_ports
    sta soft_apu_ports, y       ;store the volume in our temp port
    inc stream_ve_index, x      ;set our volume envelop index to the next position

.rest_check:
    ;check the rest flag. if set, overwrite volume with silence value
    lda stream_status, x
    and #%00000010
    beq .done                   ;if clear, no rest, so quit
    lda stream_channel, x
    cmp #TRIANGLE               ;if triangle, silence with #$80
    beq .tri                    ;else, silence with #$30
    lda #$30
    bne .store                  ;this always branches. bne is cheaper than a jmp
.tri:
    lda #$80
.store:
    sta soft_apu_ports, y
.done:
    rts

New notes
The last thing we need to consider is new notes. When an old note finishes and we start playing a new note, we will want to reset the volume envelope back to the beginning. This is as easy as setting stream_ve_index to 0 when we read a new note:

se_fetch_byte:
    ;...snip... (setup pointers, read byte, test range, etc)
.note:
    ;do Note stuff
    sty sound_temp1     ;save our index into the data stream
    asl a
    tay
    lda note_table, y
    sta stream_note_LO, x
    lda note_table+1, y
    sta stream_note_HI, x
    ldy sound_temp1     ;restore data stream index

    lda #$00
    sta stream_ve_index, x ;reset the volume envelope.

    ;check if it's a rest and modify the status flag appropriately
    jsr se_check_rest

    ;...snip... (update pointer)

And now we have volume envelopes.

Putting It All Together
Download and unzip the envelopes.zip sample files. Make sure the following files are in the same folder as NESASM3:

    envelopes.asm
    sound_engine.asm
    envelopes.chr
    note_table.i
    note_length_table.i
    vol_envelopes.i
    song0.i
    song1.i
    song2.i
    song3.i
    song4.i
    song5.i
    envelopes.bat

Double click envelopes.bat. That will run NESASM3 and should produce the envelopes.nes file. Run that NES file in FCEUXD SP.

Use the controller to select songs and play them. Controls are as follows:

Up: Play
Down: Stop
Right : Next Song/SFX
Left : Previous Song/SFX

Song0 is a silence song. Not selectable.
Song1 is a boss song from The Guardian Legend, almost the same as the original.
Song2 is the same short sound effect from last week.
Song3 is a song from Dragon Warrior, very close to the original.
Song4 is the same song4 as last week, but volume envelopes allow us to save some bytes by reducing rests.
Song5 is a short sound effect, same as last week.

Try creating your own songs and sound effects and add them into the mix. To add a new song you will need to take the following steps:

1) create a song header and song data (use the included songs as reference). Don't forget to select a volume envelope for each stream in your header. Data streams are terminated with $FF.
2) add your header to the song_headers pointer table at the bottom of sound_engine.asm
3) update the constant NUM_SONGS to reflect the new song number total (also at the bottom of sound_engine.asm)

Try making your own volume envelopes too. To do so you will need to modify vol_envelopes.i. Remember that volume envelopes are terminated with $FF.

Next Week: Opcodes, Looping

Gameboy Color Homebrew???

ACE — 2009-11-01T21:06:20 -05.0 0

I was on Wikipedia looking at the specs on the Gameboy Color and wondered if anyone was doing any homebrew projects for it. That processor in the GBC really is a serious peice of chip with the it having twice the speed RAM then the original Gameboy... In some respects it's just a little bit more powerful then the NES.

Best regards.

BK credits - Verbatim

Sivak — 2009-10-28T17:14:56 -05.0 0

Hey all. I know I posted this before, but I just wanted to do it again. This is just easier than going back and editing.

This is a verbatim version of the credits, everything spelled the way it is in-game. If you want to be called something else, please post.

It's written in all caps in-game, I just didn't want to use all caps for everything here.

PROGRAMMER, STORY, LEVEL DESIGNER, MUSIC, SOUND EFFECTS BY: Sivak
GRAPHICS BY: David Fiondella, Sivak, Megan Roberts, Isildur (not on this site)
ENEMY DESIGNERS: Sivak, David Fiondella, Thomas Hjelm, Dangevin
ASSEMBLED WITH: NESASM
MUSIC ENGINE: Drag NSF
CART PRODUCTION: Retrozone
LABEL ARTWORK: Nobody Yet
BETA TESTERS: Rob Bryant, Ross Burdge, David Fiondella, Nathan Graybeal, Penguin
INSPIRED BY: I Wanna be the Guy
SPECIAL THANKS: Disch, Braveheart69, Blargg, Kayin, Setz, Famitracker, Nintendoage.com, 6502.org, Retroware TV

The day I've been waiting for: BK is 100% finished

Sivak — 2009-10-28T16:58:48 -05.0 0

Hey one and all. I know that this is probably the post many of you have wanted to see, so here it is. Earlier today I finalized the last image for the ending and I literally have nothing left to add content-wise. I am pretty happy how it all came out.

Now, this does not mean it'll be on retrousb tomorrow. There are still things to do.

-Firstly, I'm going to do a big-time final analysis of everything in the ROM. I'm confident I won't want to change anything, but that's what this analysis is for. If I'm sure it's fine, then from that point on nothing will be changed except for the text on the title screen.
-After this, I'm going to have a personal prototype made up and play on the real hardware to ensure it is fine. This prototype may very well be for sale someday.
-Hopefully while this is going on, I'll have obtained the label art.
-When I have a planned date I'll make another video, this time being a trailer showing a little of all the areas of the game.
-The LE signups will occur when all is satisfactory and ready.
-The standard edition will probably be out a week or so after that.

That is my report.