From 6078257f9806ba45af17d89731ba4031ba0cafb0 Mon Sep 17 00:00:00 2001
From: "Matthew D. Steele" <mdsteele@alum.mit.edu>
Date: Wed, 20 Nov 2024 21:16:49 -0500
Subject: [PATCH] Rename/refactor some audio variables

---
 src/audio.asm          | 92 +++++++++++++++++++++---------------------
 src/audio.inc          | 17 ++++----
 src/inst.asm           | 76 +++++++++++++++++-----------------
 src/sample.asm         | 16 ++++----
 src/sound.asm          | 27 ++++++-------
 src/sounds/beep.asm    | 14 +++----
 src/sounds/dialog.asm  | 14 +++----
 src/sounds/explode.asm | 18 ++++-----
 8 files changed, 136 insertions(+), 138 deletions(-)

diff --git a/src/audio.asm b/src/audio.asm
index 273aeb8d..b7c640bb 100644
--- a/src/audio.asm
+++ b/src/audio.asm
@@ -56,7 +56,7 @@
 ;;; Assert that all the channel structs we use are exactly four bytes.  This
 ;;; allows us to use four times the channel number as a byte index into any the
 ;;; struct arrays.
-.ASSERT .sizeof(sChanInst) = 4, error
+.ASSERT .sizeof(sChanCtrl) = 4, error
 .ASSERT .sizeof(sChanNext) = 4, error
 .ASSERT .sizeof(sChanNote) = 4, error
 .ASSERT .sizeof(sChanRegs) = 4, error
@@ -125,15 +125,13 @@ Zp_AudioTmp_ptr: .res kSizeofAddr
 
 .SEGMENT "RAM_Audio"
 
-;;; Music channel state for all the different APU channels.
-.EXPORT Ram_Music_sChanInst_arr
-Ram_Music_sChanInst_arr: .res .sizeof(sChanInst) * kNumApuChannels
-.EXPORT Ram_Music_sChanNote_arr
-Ram_Music_sChanNote_arr: .res .sizeof(sChanNote) * kNumApuChannels
-
-;;; SFX channel state for all the different APU channels.
-.EXPORT Ram_Sound_sChanSfx_arr
-Ram_Sound_sChanSfx_arr: .res .sizeof(sChanSfx) * kNumApuChannels
+;;; Music/SFX channel state for all the different APU channels.
+.EXPORT Ram_Audio_sChanCtrl_arr
+Ram_Audio_sChanCtrl_arr: .res .sizeof(sChanCtrl) * kNumApuChannels
+.EXPORT Ram_Audio_sChanNote_arr
+Ram_Audio_sChanNote_arr: .res .sizeof(sChanNote) * kNumApuChannels
+.EXPORT Ram_Audio_sChanSfx_arr
+Ram_Audio_sChanSfx_arr: .res .sizeof(sChanSfx) * kNumApuChannels
 
 ;;;=========================================================================;;;
 
@@ -169,7 +167,7 @@ _HaltSfx:
     lda #0
     ldx #.sizeof(sChanSfx) * kNumApuChannels - 1
     @loop:
-    sta Ram_Sound_sChanSfx_arr, x
+    sta Ram_Audio_sChanSfx_arr, x
     dex
     .assert .sizeof(sChanSfx) * kNumApuChannels <= $80, error
     bpl @loop
@@ -216,17 +214,19 @@ _StartSfx:
     ;; If not, continue to the next channel.
     .assert eSound::None = 0, error
     beq @continue
-    ;; Otherwise, copy this sChanSfx struct into Ram_Sound_sChanSfx_arr.
-    sta Ram_Sound_sChanSfx_arr + sChanSfx::Sfx_eSound, x
-    lda Zp_Next_sChanSfx_arr + sChanSfx::Timer_u8, x
-    sta Ram_Sound_sChanSfx_arr + sChanSfx::Timer_u8, x
+    ;; Otherwise, copy this sChanSfx struct into Ram_Audio_sChanSfx_arr.
+    sta Ram_Audio_sChanSfx_arr + sChanSfx::Sfx_eSound, x
     lda Zp_Next_sChanSfx_arr + sChanSfx::Param1_byte, x
-    sta Ram_Sound_sChanSfx_arr + sChanSfx::Param1_byte, x
+    sta Ram_Audio_sChanSfx_arr + sChanSfx::Param1_byte, x
     lda Zp_Next_sChanSfx_arr + sChanSfx::Param2_byte, x
-    sta Ram_Sound_sChanSfx_arr + sChanSfx::Param2_byte, x
+    sta Ram_Audio_sChanSfx_arr + sChanSfx::Param2_byte, x
+    lda Zp_Next_sChanSfx_arr + sChanSfx::Param3_byte, x
+    sta Ram_Audio_sChanSfx_arr + sChanSfx::Param3_byte, x
+    lda #0
+    sta Ram_Audio_sChanCtrl_arr + sChanCtrl::SfxRepeat_u8, x
     ;; Null out the Sfx_eSound field in Zp_Next_sAudioCtrl, so we don't restart
     ;; this SFX again next frame.
-    lda #eSound::None
+    .assert eSound::None = 0, error
     sta Zp_Next_sChanSfx_arr + sChanSfx::Sfx_eSound, x
     ;; Disable the channel that the sound is about to play on, so as to reset
     ;; its state (it'll get enabled again when we call the SFX function).
@@ -264,13 +264,13 @@ _ResetChannels:
     tax  ; now X is zero
     @loop:
     ;; At this point, A is still zero.
-    sta Ram_Music_sChanNote_arr + sChanNote::ElapsedFrames_u8, x
-    sta Ram_Music_sChanNote_arr + sChanNote::DurationFrames_u8, x
-    sta Ram_Music_sChanNote_arr + sChanNote::TimerLo_byte, x
-    sta Ram_Music_sChanNote_arr + sChanNote::TimerHi_byte, x
-    sta Ram_Music_sChanInst_arr + sChanInst::Instrument_eInst, x
-    sta Ram_Music_sChanInst_arr + sChanInst::Param_byte, x
-    sta Ram_Music_sChanInst_arr + sChanInst::RepeatCount_u8, x
+    sta Ram_Audio_sChanNote_arr + sChanNote::ElapsedFrames_u8, x
+    sta Ram_Audio_sChanNote_arr + sChanNote::DurationFrames_u8, x
+    sta Ram_Audio_sChanNote_arr + sChanNote::TimerLo_byte, x
+    sta Ram_Audio_sChanNote_arr + sChanNote::TimerHi_byte, x
+    sta Ram_Audio_sChanCtrl_arr + sChanCtrl::Instrument_eInst, x
+    sta Ram_Audio_sChanCtrl_arr + sChanCtrl::InstParam_byte, x
+    sta Ram_Audio_sChanCtrl_arr + sChanCtrl::ChainRepeat_u8, x
     .assert Data_Empty_bChain_arr = Data_Empty_sPhrase, error
     ldy #<Data_Empty_bChain_arr
     sty Zp_Music_sChanNext_arr + sChanNext::Next_bChain_ptr + 0, x
@@ -430,14 +430,14 @@ _ContinuePhrase:
     rts
 _FinishRepeat:
     lda #0
-    sta Ram_Music_sChanInst_arr + sChanInst::RepeatCount_u8, x
+    sta Ram_Audio_sChanCtrl_arr + sChanCtrl::ChainRepeat_u8, x
     inc Zp_Music_sChanNext_arr + sChanNext::Next_bChain_ptr + 0, x
     bne _ReadNextItem
     inc Zp_Music_sChanNext_arr + sChanNext::Next_bChain_ptr + 1, x
     bne _ReadNextItem  ; unconditional
 _StartRepeat:
-    inc Ram_Music_sChanInst_arr + sChanInst::RepeatCount_u8, x
-    cmp Ram_Music_sChanInst_arr + sChanInst::RepeatCount_u8, x
+    inc Ram_Audio_sChanCtrl_arr + sChanCtrl::ChainRepeat_u8, x
+    cmp Ram_Audio_sChanCtrl_arr + sChanCtrl::ChainRepeat_u8, x
     beq _FinishRepeat
     ;; Decrement the channel's Next_bChain_ptr.
     lda Zp_Music_sChanNext_arr + sChanNext::Next_bChain_ptr + 0, x
@@ -475,12 +475,12 @@ _ChainFinished:
 ;;; @return C Set if no note/rest was played, and the phrase is now finished.
 ;;; @preserve X
 .PROC Func_AudioContinuePhrase
-    lda Ram_Music_sChanNote_arr + sChanNote::ElapsedFrames_u8, x
-    cmp Ram_Music_sChanNote_arr + sChanNote::DurationFrames_u8, x
+    lda Ram_Audio_sChanNote_arr + sChanNote::ElapsedFrames_u8, x
+    cmp Ram_Audio_sChanNote_arr + sChanNote::DurationFrames_u8, x
     bge _StartNextNote
 _ContinueNote:
     ;; If this channel is playing SFX, then don't play music on this channel.
-    lda Ram_Sound_sChanSfx_arr + sChanSfx::Sfx_eSound, x
+    lda Ram_Audio_sChanSfx_arr + sChanSfx::Sfx_eSound, x
     .assert eSound::None = 0, error
     bne _IncrementFramesAndReturn
     ;; Otherwise, if the channel is disabled, then we're playing a rest (rather
@@ -492,7 +492,7 @@ _ContinueTone:
     jsr Func_AudioCallInstrument  ; preserves X, returns A
     sta Hw_Channels_sChanRegs_arr5 + sChanRegs::Envelope_wo, x
 _IncrementFramesAndReturn:
-    inc Ram_Music_sChanNote_arr + sChanNote::ElapsedFrames_u8, x
+    inc Ram_Audio_sChanNote_arr + sChanNote::ElapsedFrames_u8, x
     clc  ; clear C to indicate that the phrase is still going
     rts
 _StartNextNote:
@@ -512,10 +512,10 @@ _StartNextNote:
     bpl _NoteInstOrRest
 _NoteToneOrSame:
     ;; If this channel is playing SFX, skip this tone.
-    lda Ram_Sound_sChanSfx_arr + sChanSfx::Sfx_eSound, x
+    lda Ram_Audio_sChanSfx_arr + sChanSfx::Sfx_eSound, x
     .assert eSound::None = 0, error
     bne _SkipToneOrSame
-    sta Ram_Music_sChanNote_arr + sChanNote::ElapsedFrames_u8, x  ; A is zero
+    sta Ram_Audio_sChanNote_arr + sChanNote::ElapsedFrames_u8, x  ; A is zero
     ;; For non-DMC channels, we need to enable the channel *before* writing the
     ;; registers (because otherwise the writes won't take effect), and we want
     ;; to reset sweep to kNoSweep by default.  For the DMC channel, the sweep
@@ -538,13 +538,13 @@ _NoteToneOrSame:
     ;; Read the second byte of the TONE/SAME note and use it as the TimerLo
     ;; value.
     lda (Zp_Music_sChanNext_arr + sChanNext::PhraseNext_ptr, x)
-    sta Ram_Music_sChanNote_arr + sChanNote::TimerLo_byte, x
+    sta Ram_Audio_sChanNote_arr + sChanNote::TimerLo_byte, x
     sta Hw_Channels_sChanRegs_arr5 + sChanRegs::TimerLo_wo, x
     ;; Mask the first byte of the TONE/SAME note and use it as the TimerHi
     ;; value.
     lda Zp_AudioTmp_byte  ; first note byte
     and #bNote::ToneSameMask
-    sta Ram_Music_sChanNote_arr + sChanNote::TimerHi_byte, x
+    sta Ram_Audio_sChanNote_arr + sChanNote::TimerHi_byte, x
     sta Hw_Channels_sChanRegs_arr5 + sChanRegs::TimerHi_wo, x
     ;; For the DMC channel, we need to enable the channel *after* updating the
     ;; registers (because otherwise it will restart the previous sample).
@@ -564,7 +564,7 @@ _NoteToneOrSame:
     bvs _ContinueTone
     ;; Read the third byte of the TONE note and use it as the note duration.
     lda (Zp_Music_sChanNext_arr + sChanNext::PhraseNext_ptr, x)
-    sta Ram_Music_sChanNote_arr + sChanNote::DurationFrames_u8, x
+    sta Ram_Audio_sChanNote_arr + sChanNote::DurationFrames_u8, x
     ;; Increment the channel's PhraseNext_ptr a third time.
     inc Zp_Music_sChanNext_arr + sChanNext::PhraseNext_ptr + 0, x
     bne _ContinueTone
@@ -575,11 +575,11 @@ _NoteInstOrRest:
     bvc _NoteRest
 _NoteInst:
     and #bNote::InstMask
-    sta Ram_Music_sChanInst_arr + sChanInst::Instrument_eInst, x
+    sta Ram_Audio_sChanCtrl_arr + sChanCtrl::Instrument_eInst, x
     .assert bNote::InstMask & $80 = 0, error
     ;; Read the second byte of the INST note and use it as the param byte.
     lda (Zp_Music_sChanNext_arr + sChanNext::PhraseNext_ptr, x)
-    sta Ram_Music_sChanInst_arr + sChanInst::Param_byte, x
+    sta Ram_Audio_sChanCtrl_arr + sChanCtrl::InstParam_byte, x
     ;; Increment the channel's PhraseNext_ptr a second time.
     inc Zp_Music_sChanNext_arr + sChanNext::PhraseNext_ptr + 0, x
     bne _StartNextNote
@@ -590,19 +590,19 @@ _NoteDone:
     bcs _DisableChannelUnlessSfx  ; unconditional
 _NoteRest:
     ;; Record the rest duration.
-    sta Ram_Music_sChanNote_arr + sChanNote::DurationFrames_u8, x
+    sta Ram_Audio_sChanNote_arr + sChanNote::DurationFrames_u8, x
     lda #1
-    sta Ram_Music_sChanNote_arr + sChanNote::ElapsedFrames_u8, x
+    sta Ram_Audio_sChanNote_arr + sChanNote::ElapsedFrames_u8, x
     clc  ; clear C to indicate that the phrase is still going
 _DisableChannelUnlessSfx:
     ;; Disable this channel unless it's playing SFX.
-    lda Ram_Sound_sChanSfx_arr + sChanSfx::Sfx_eSound, x
+    lda Ram_Audio_sChanSfx_arr + sChanSfx::Sfx_eSound, x
     .assert eSound::None = 0, error
     beq Func_DisableCurrentChannel  ; preserves C and X
     rts
 _SkipToneOrSame:
     lda #1
-    sta Ram_Music_sChanNote_arr + sChanNote::ElapsedFrames_u8, x
+    sta Ram_Audio_sChanNote_arr + sChanNote::ElapsedFrames_u8, x
     ;; Increment the channel's PhraseNext_ptr a second time.
     inc Zp_Music_sChanNext_arr + sChanNext::PhraseNext_ptr + 0, x
     bne @incDone2
@@ -615,7 +615,7 @@ _SkipToneOrSame:
     bvs @incDone3
     ;; Read the third byte of the TONE note and use it as the note duration.
     lda (Zp_Music_sChanNext_arr + sChanNext::PhraseNext_ptr, x)
-    sta Ram_Music_sChanNote_arr + sChanNote::DurationFrames_u8, x
+    sta Ram_Audio_sChanNote_arr + sChanNote::DurationFrames_u8, x
     ;; Increment the channel's PhraseNext_ptr a third time.
     inc Zp_Music_sChanNext_arr + sChanNext::PhraseNext_ptr + 0, x
     bne @incDone3
@@ -648,7 +648,7 @@ _SkipToneOrSame:
 ;;; @preserve X
 .PROC Func_AudioContinueOneSfx
     ;; Check if there's an active SFX.  If not, we're done.
-    ldy Ram_Sound_sChanSfx_arr + sChanSfx::Sfx_eSound, x  ; param: eSound
+    ldy Ram_Audio_sChanSfx_arr + sChanSfx::Sfx_eSound, x  ; param: eSound
     .assert eSound::None = 0, error
     beq _Return
     ;; For non-DMC channels, we need to enable the channel *before* calling the
@@ -669,7 +669,7 @@ _Return:
 _SoundFinished:
     ;; Halt the SFX.
     lda #eSound::None
-    sta Ram_Sound_sChanSfx_arr + sChanSfx::Sfx_eSound, x
+    sta Ram_Audio_sChanSfx_arr + sChanSfx::Sfx_eSound, x
     ;; Disable the channel.
     fall Func_DisableCurrentChannel  ; preserves X
 .ENDPROC
diff --git a/src/audio.inc b/src/audio.inc
index 64214ca3..886d8046 100644
--- a/src/audio.inc
+++ b/src/audio.inc
@@ -42,17 +42,18 @@
     TimerHi_byte       .byte
 .ENDSTRUCT
 
-;;; Music instrument state variables for a given APU channel.
-.STRUCT sChanInst
+;;; Music/SFX control variables for a given APU channel.
+.STRUCT sChanCtrl
     ;; Indicates which instrument function to call each frame to update the
     ;; tone.
     Instrument_eInst .byte
     ;; Parameter byte for the instrument.
-    Param_byte       .byte
-    ;; Currently-unused padding byte.
-    Unused           .byte
+    InstParam_byte   .byte
     ;; How many times the same chain repeat has been reached in a row.
-    RepeatCount_u8   .byte
+    ChainRepeat_u8   .byte
+    ;; How many times the same FUNC or WAIT operation has already been executed
+    ;; by the current sound effect on this channel.
+    SfxRepeat_u8     .byte
 .ENDSTRUCT
 
 ;;; SFX state variables for a given APU channel.
@@ -60,12 +61,10 @@
     ;; Indicates which SFX function to call each frame while the sound is
     ;; active.
     Sfx_eSound  .byte
-    ;; Typically used as a frame timer to track how long the sound effect
-    ;; should play, but the SFX function can use this however it wants.
-    Timer_u8    .byte
     ;; Arbitrary parameter/state bytes that can be used by the SFX function.
     Param1_byte .byte
     Param2_byte .byte
+    Param3_byte .byte
 .ENDSTRUCT
 
 ;;;=========================================================================;;;
diff --git a/src/inst.asm b/src/inst.asm
index 0033c7d8..4a68bb04 100644
--- a/src/inst.asm
+++ b/src/inst.asm
@@ -24,8 +24,8 @@
 .INCLUDE "macros.inc"
 .INCLUDE "music.inc"
 
-.IMPORT Ram_Music_sChanInst_arr
-.IMPORT Ram_Music_sChanNote_arr
+.IMPORT Ram_Audio_sChanCtrl_arr
+.IMPORT Ram_Audio_sChanNote_arr
 .IMPORTZP Zp_AudioTmp_byte
 .IMPORTZP Zp_AudioTmp_ptr
 .IMPORTZP Zp_Current_bAudio
@@ -72,10 +72,10 @@
 ;;; @preserve X
 .PROC Func_InstrumentPulseVibrato
 _Vibrato:
-    lda Ram_Music_sChanNote_arr + sChanNote::ElapsedFrames_u8, x
+    lda Ram_Audio_sChanNote_arr + sChanNote::ElapsedFrames_u8, x
     and #$07
     tay
-    lda Ram_Music_sChanNote_arr + sChanNote::TimerLo_byte, x
+    lda Ram_Audio_sChanNote_arr + sChanNote::TimerLo_byte, x
     add Data_VibratoDelta_i16_0_arr8, y
     sta Hw_Channels_sChanRegs_arr5 + sChanRegs::TimerLo_wo, x
     ;; Note that we intentionally *don't* carry the addition over into TimerHi
@@ -95,11 +95,11 @@ _Envelope:
 ;;; @return A The duty/envelope byte to use.
 ;;; @preserve X
 .PROC Func_InstrumentPulseBasic
-    lda Ram_Music_sChanInst_arr + sChanInst::Param_byte, x
+    lda Ram_Audio_sChanCtrl_arr + sChanCtrl::InstParam_byte, x
     and #bEnvelope::VolMask
     sta Zp_AudioTmp_byte  ; max volume
-    lda Ram_Music_sChanNote_arr + sChanNote::DurationFrames_u8, x
-    sub Ram_Music_sChanNote_arr + sChanNote::ElapsedFrames_u8, x
+    lda Ram_Audio_sChanNote_arr + sChanNote::DurationFrames_u8, x
+    sub Ram_Audio_sChanNote_arr + sChanNote::ElapsedFrames_u8, x
     mul #2
     bcs @useMaxVolume
     cmp Zp_AudioTmp_byte  ; max volume
@@ -118,14 +118,14 @@ _Envelope:
 ;;; @return A The duty/envelope byte to use.
 ;;; @preserve X
 .PROC Func_InstrumentPulseEcho
-    lda Ram_Music_sChanInst_arr + sChanInst::Param_byte, x
+    lda Ram_Audio_sChanCtrl_arr + sChanCtrl::InstParam_byte, x
     and #bEnvelope::VolMask
     tay  ; max volume
-    lda Ram_Music_sChanInst_arr + sChanInst::Param_byte, x
+    lda Ram_Audio_sChanCtrl_arr + sChanCtrl::InstParam_byte, x
     and #%00110000
     ora #%00001100
     div #4
-    cmp Ram_Music_sChanNote_arr + sChanNote::ElapsedFrames_u8, x
+    cmp Ram_Audio_sChanNote_arr + sChanNote::ElapsedFrames_u8, x
     blt _Quiet
 _Loud:
     tya  ; max volume
@@ -144,10 +144,10 @@ _Quiet:
 ;;; @return A The duty/envelope byte to use.
 ;;; @preserve X
 .PROC Func_InstrumentPulsePluck
-    lda Ram_Music_sChanInst_arr + sChanInst::Param_byte, x
+    lda Ram_Audio_sChanCtrl_arr + sChanCtrl::InstParam_byte, x
     and #bEnvelope::VolMask
     sta Zp_AudioTmp_byte  ; max volume
-    lda Ram_Music_sChanNote_arr + sChanNote::ElapsedFrames_u8, x
+    lda Ram_Audio_sChanNote_arr + sChanNote::ElapsedFrames_u8, x
     cmp #2
     bge _Decay
 _Pluck:
@@ -174,7 +174,7 @@ _Decay:
     div #2
     @noReduce:
     sta Zp_AudioTmp_byte  ; volume
-    lda Ram_Music_sChanInst_arr + sChanInst::Param_byte, x
+    lda Ram_Audio_sChanCtrl_arr + sChanCtrl::InstParam_byte, x
     and #bEnvelope::DutyMask
     ora #bEnvelope::NoLength | bEnvelope::ConstVol
     ora Zp_AudioTmp_byte  ; volume
@@ -188,10 +188,10 @@ _Decay:
 ;;; @preserve X
 .PROC Func_InstrumentPulsePiano
 _Vibrato:
-    lda Ram_Music_sChanNote_arr + sChanNote::ElapsedFrames_u8, x
+    lda Ram_Audio_sChanNote_arr + sChanNote::ElapsedFrames_u8, x
     and #$03
     tay
-    lda Ram_Music_sChanNote_arr + sChanNote::TimerLo_byte, x
+    lda Ram_Audio_sChanNote_arr + sChanNote::TimerLo_byte, x
     add _VibratoDelta_i8_arr4, y
     sta Hw_Channels_sChanRegs_arr5 + sChanRegs::TimerLo_wo, x
     ;; Note that we intentionally *don't* carry the addition over into TimerHi
@@ -201,14 +201,14 @@ _Vibrato:
     ;; instrument for pitches right next to a TimerLo carry boundary, then
     ;; TimerHi wouldn't change anyway, and everything will sound fine.
 _Envelope:
-    lda Ram_Music_sChanInst_arr + sChanInst::Param_byte, x
+    lda Ram_Audio_sChanCtrl_arr + sChanCtrl::InstParam_byte, x
     and #bEnvelope::VolMask
     sta Zp_AudioTmp_byte  ; max volume
     div #2
-    rsub Ram_Music_sChanNote_arr + sChanNote::ElapsedFrames_u8, x
+    rsub Ram_Audio_sChanNote_arr + sChanNote::ElapsedFrames_u8, x
     bge @decay
     @attack:
-    lda Ram_Music_sChanNote_arr + sChanNote::ElapsedFrames_u8, x
+    lda Ram_Audio_sChanNote_arr + sChanNote::ElapsedFrames_u8, x
     sec
     rol a
     bne Func_CombineVolumeWithDuty  ; unconditional
@@ -229,12 +229,12 @@ _VibratoDelta_i8_arr4:
 ;;; @return A The duty/envelope byte to use.
 ;;; @preserve X
 .PROC Func_InstrumentNoiseSnare
-    lda Ram_Music_sChanNote_arr + sChanNote::ElapsedFrames_u8, x
+    lda Ram_Audio_sChanNote_arr + sChanNote::ElapsedFrames_u8, x
     cmp #2
     bne @done
-    lda Ram_Music_sChanInst_arr + sChanInst::Param_byte, x
+    lda Ram_Audio_sChanCtrl_arr + sChanCtrl::InstParam_byte, x
     div #$10
-    add Ram_Music_sChanNote_arr + sChanNote::TimerLo_byte, x
+    add Ram_Audio_sChanNote_arr + sChanNote::TimerLo_byte, x
     mod #$10
     sta Hw_Channels_sChanRegs_arr5 + sChanRegs::TimerLo_wo, x
     @done:
@@ -249,9 +249,9 @@ _VibratoDelta_i8_arr4:
 ;;; @return A The duty/envelope byte to use.
 ;;; @preserve X
 .PROC Func_InstrumentStaccato
-    lda Ram_Music_sChanInst_arr + sChanInst::Param_byte, x
+    lda Ram_Audio_sChanCtrl_arr + sChanCtrl::InstParam_byte, x
     and #bEnvelope::VolMask
-    sub Ram_Music_sChanNote_arr + sChanNote::ElapsedFrames_u8, x
+    sub Ram_Audio_sChanNote_arr + sChanNote::ElapsedFrames_u8, x
     bge Func_CombineVolumeWithDuty
     fall Func_InstrumentSilent  ; preserves X
 .ENDPROC
@@ -273,15 +273,15 @@ _VibratoDelta_i8_arr4:
 ;;; @preserve X
 .PROC Func_InstrumentTriangleDrum
 _Pitch:
-    lda Ram_Music_sChanNote_arr + sChanNote::TimerLo_byte, x
-    add Ram_Music_sChanInst_arr + sChanInst::Param_byte, x
-    sta Ram_Music_sChanNote_arr + sChanNote::TimerLo_byte, x
+    lda Ram_Audio_sChanNote_arr + sChanNote::TimerLo_byte, x
+    add Ram_Audio_sChanCtrl_arr + sChanCtrl::InstParam_byte, x
+    sta Ram_Audio_sChanNote_arr + sChanNote::TimerLo_byte, x
     sta Hw_Channels_sChanRegs_arr5 + sChanRegs::TimerLo_wo, x
-    lda Ram_Music_sChanNote_arr + sChanNote::TimerHi_byte, x
+    lda Ram_Audio_sChanNote_arr + sChanNote::TimerHi_byte, x
     adc #0
     and #$07
     sta Hw_Channels_sChanRegs_arr5 + sChanRegs::TimerHi_wo, x
-    sta Ram_Music_sChanNote_arr + sChanNote::TimerHi_byte, x
+    sta Ram_Audio_sChanNote_arr + sChanNote::TimerHi_byte, x
 _Envelope:
     lda #$ff
     rts
@@ -294,16 +294,16 @@ _Envelope:
 ;;; @preserve X
 .PROC Func_InstrumentTriangleSlide
 _Slide:
-    lda Ram_Music_sChanNote_arr + sChanNote::ElapsedFrames_u8, x
+    lda Ram_Audio_sChanNote_arr + sChanNote::ElapsedFrames_u8, x
     and #$01
     beq @done
-    lda Ram_Music_sChanNote_arr + sChanNote::TimerLo_byte, x
+    lda Ram_Audio_sChanNote_arr + sChanNote::TimerLo_byte, x
     add #1
-    sta Ram_Music_sChanNote_arr + sChanNote::TimerLo_byte, x
-    lda Ram_Music_sChanNote_arr + sChanNote::TimerHi_byte, x
+    sta Ram_Audio_sChanNote_arr + sChanNote::TimerLo_byte, x
+    lda Ram_Audio_sChanNote_arr + sChanNote::TimerHi_byte, x
     adc #0
     and #$07
-    sta Ram_Music_sChanNote_arr + sChanNote::TimerHi_byte, x
+    sta Ram_Audio_sChanNote_arr + sChanNote::TimerHi_byte, x
     @done:
 _Vibrato:
     fall Func_InstrumentTriangleVibrato  ; preserves X
@@ -316,13 +316,13 @@ _Vibrato:
 ;;; @preserve X
 .PROC Func_InstrumentTriangleVibrato
 _Vibrato:
-    lda Ram_Music_sChanNote_arr + sChanNote::ElapsedFrames_u8, x
+    lda Ram_Audio_sChanNote_arr + sChanNote::ElapsedFrames_u8, x
     and #$07
     tay
-    lda Ram_Music_sChanNote_arr + sChanNote::TimerLo_byte, x
+    lda Ram_Audio_sChanNote_arr + sChanNote::TimerLo_byte, x
     add Data_VibratoDelta_i16_0_arr8, y
     sta Hw_Channels_sChanRegs_arr5 + sChanRegs::TimerLo_wo, x
-    lda Ram_Music_sChanNote_arr + sChanNote::TimerHi_byte, x
+    lda Ram_Audio_sChanNote_arr + sChanNote::TimerHi_byte, x
     adc Data_VibratoDelta_i16_1_arr8, y
     and #$07
     sta Hw_Channels_sChanRegs_arr5 + sChanRegs::TimerHi_wo, x
@@ -354,7 +354,7 @@ kSampleGap1Size = kDmcSampleAlign - (* .mod kDmcSampleAlign)
 ;;; @preserve X
 .EXPORT Func_AudioCallInstrument
 .PROC Func_AudioCallInstrument
-    ldy Ram_Music_sChanInst_arr + sChanInst::Instrument_eInst, x
+    ldy Ram_Audio_sChanCtrl_arr + sChanCtrl::Instrument_eInst, x
     lda Data_Instruments_func_ptr_0_arr, y
     sta Zp_AudioTmp_ptr + 0
     lda Data_Instruments_func_ptr_1_arr, y
@@ -368,7 +368,7 @@ kSampleGap1Size = kDmcSampleAlign - (* .mod kDmcSampleAlign)
 ;;; @return A The duty/envelope byte to use.
 ;;; @preserve X
 .PROC Func_InstrumentConstant
-    lda Ram_Music_sChanInst_arr + sChanInst::Param_byte, x
+    lda Ram_Audio_sChanCtrl_arr + sChanCtrl::InstParam_byte, x
     rts
 .ENDPROC
 
diff --git a/src/sample.asm b/src/sample.asm
index 4d75f68d..ece490da 100644
--- a/src/sample.asm
+++ b/src/sample.asm
@@ -24,7 +24,7 @@
 .INCLUDE "sound.inc"
 
 .IMPORT Data_SampleKickDrum_arr657
-.IMPORT Ram_Sound_sChanSfx_arr
+.IMPORT Ram_Audio_sChanSfx_arr
 .IMPORTZP Zp_Next_sChanSfx_arr
 
 ;;;=========================================================================;;;
@@ -106,9 +106,9 @@ kSampleGap2Size = kDmcSampleAlign - (* .mod kDmcSampleAlign)
 ;;; @preserve X, Y, T0+
 .EXPORT Func_PlaySfxSample
 .PROC Func_PlaySfxSample
-    sta Zp_Next_sChanSfx_arr + eChan::Dmc + sChanSfx::Param1_byte
+    sta Zp_Next_sChanSfx_arr + eChan::Dmc + sChanSfx::Param1_byte  ; eSample
     lda #0
-    sta Zp_Next_sChanSfx_arr + eChan::Dmc + sChanSfx::Timer_u8
+    sta Zp_Next_sChanSfx_arr + eChan::Dmc + sChanSfx::Param3_byte  ; timer
     lda #eSound::Sample
     sta Zp_Next_sChanSfx_arr + eChan::Dmc + sChanSfx::Sfx_eSound
     rts
@@ -172,15 +172,15 @@ kSampleGap2Size = kDmcSampleAlign - (* .mod kDmcSampleAlign)
 .ENDPROC
 
 ;;; SFX function for playing delta modulated samples on the DMC.  When starting
-;;; this sound, Param1_byte should hold the eSample value, and Timer_u8 should
-;;; be initialized to zero.
+;;; this sound, Param1_byte should hold the eSample value, and Param3_byte
+;;; should be initialized to zero.
 ;;; @param X The channel number (0-4) times four (so, 0, 4, 8, 12, or 16).
 ;;; @return C Set if the sound is finished, cleared otherwise.
 ;;; @preserve X, T0+
 .EXPORT Func_SfxSample
 .PROC Func_SfxSample
-    ldy Ram_Sound_sChanSfx_arr + sChanSfx::Param1_byte, x
-    lda Ram_Sound_sChanSfx_arr + sChanSfx::Timer_u8, x
+    ldy Ram_Audio_sChanSfx_arr + sChanSfx::Param1_byte, x  ; eSample
+    lda Ram_Audio_sChanSfx_arr + sChanSfx::Param3_byte, x  ; timer
     beq _Initialize
     cmp Data_SampleFrames_u8_arr, y
     blt _Continue
@@ -196,7 +196,7 @@ _Initialize:
     lda Data_SampleLength_u8_arr, y
     sta Hw_DmcSampleLength_wo
 _Continue:
-    inc Ram_Sound_sChanSfx_arr + sChanSfx::Timer_u8, x
+    inc Ram_Audio_sChanSfx_arr + sChanSfx::Param3_byte, x  ; timer
     clc  ; clear C to indicate that the sound is still going
     rts
 .ENDPROC
diff --git a/src/sound.asm b/src/sound.asm
index 2f2ffbd4..1e6fbb1b 100644
--- a/src/sound.asm
+++ b/src/sound.asm
@@ -28,7 +28,8 @@
 .IMPORT Func_SfxDialogText
 .IMPORT Func_SfxExplode
 .IMPORT Func_SfxSample
-.IMPORT Ram_Sound_sChanSfx_arr
+.IMPORT Ram_Audio_sChanCtrl_arr
+.IMPORT Ram_Audio_sChanSfx_arr
 .IMPORTZP Zp_AudioTmp_byte
 .IMPORTZP Zp_AudioTmp_ptr
 .IMPORTZP Zp_Next_sChanSfx_arr
@@ -43,9 +44,9 @@
 ;;; @preserve X, T0+
 .PROC Func_SfxBytecode
 _ExecuteNext:
-    lda Ram_Sound_sChanSfx_arr + sChanSfx::Param1_byte, x
+    lda Ram_Audio_sChanSfx_arr + sChanSfx::Param1_byte, x
     sta Zp_AudioTmp_ptr + 0
-    lda Ram_Sound_sChanSfx_arr + sChanSfx::Param2_byte, x
+    lda Ram_Audio_sChanSfx_arr + sChanSfx::Param2_byte, x
     sta Zp_AudioTmp_ptr + 1
     ldy #0
     lda (Zp_AudioTmp_ptr), y  ; opcode
@@ -57,9 +58,9 @@ _WaitOrSet:
     bit Data_PowersOfTwo_u8_arr8 + 6
     bne _SetRegisters
 _WaitFrames:
-    cmp Ram_Sound_sChanSfx_arr + sChanSfx::Timer_u8, x
+    cmp Ram_Audio_sChanCtrl_arr + sChanCtrl::SfxRepeat_u8, x
     beq _AdvanceByY
-    inc Ram_Sound_sChanSfx_arr + sChanSfx::Timer_u8, x
+    inc Ram_Audio_sChanCtrl_arr + sChanCtrl::SfxRepeat_u8, x
     clc  ; clear C to indicate that the sound is still going
     rts
 _SetRegisters:
@@ -96,12 +97,12 @@ _AdvanceByY:
     tya
 _AdvanceByA:
     ;; Add A to the param pointer, and reset repeat count to zero.
-    add Ram_Sound_sChanSfx_arr + sChanSfx::Param1_byte, x
-    sta Ram_Sound_sChanSfx_arr + sChanSfx::Param1_byte, x
+    add Ram_Audio_sChanSfx_arr + sChanSfx::Param1_byte, x
+    sta Ram_Audio_sChanSfx_arr + sChanSfx::Param1_byte, x
     lda #0
-    sta Ram_Sound_sChanSfx_arr + sChanSfx::Timer_u8, x
-    adc Ram_Sound_sChanSfx_arr + sChanSfx::Param2_byte, x
-    sta Ram_Sound_sChanSfx_arr + sChanSfx::Param2_byte, x
+    sta Ram_Audio_sChanCtrl_arr + sChanCtrl::SfxRepeat_u8, x
+    adc Ram_Audio_sChanSfx_arr + sChanSfx::Param2_byte, x
+    sta Ram_Audio_sChanSfx_arr + sChanSfx::Param2_byte, x
     jmp _ExecuteNext
 _EndSound:
     sec  ; set C to indicate that the sound is finished
@@ -113,8 +114,8 @@ _CallFunc:
     sta Zp_AudioTmp_ptr + 0
     pla  ; func addr (hi)
     sta Zp_AudioTmp_ptr + 1
-    ldy Ram_Sound_sChanSfx_arr + sChanSfx::Timer_u8, x  ; param: repeat count
-    inc Ram_Sound_sChanSfx_arr + sChanSfx::Timer_u8, x
+    ldy Ram_Audio_sChanCtrl_arr + sChanCtrl::SfxRepeat_u8, x  ; param: count
+    inc Ram_Audio_sChanCtrl_arr + sChanCtrl::SfxRepeat_u8, x
     jsr _CallAudioTmpPtr  ; preserves X and T0+, returns C
     lda #2  ; byte offset
     bcs _AdvanceByA
@@ -150,8 +151,6 @@ _CallAudioTmpPtr:
 .PROC Func_PlaySfxBytecode
     sta Zp_Next_sChanSfx_arr + sChanSfx::Param1_byte, x
     sty Zp_Next_sChanSfx_arr + sChanSfx::Param2_byte, x
-    lda #0
-    sta Zp_Next_sChanSfx_arr + sChanSfx::Timer_u8, x
     lda #eSound::Bytecode
     sta Zp_Next_sChanSfx_arr + sChanSfx::Sfx_eSound, x
     rts
diff --git a/src/sounds/beep.asm b/src/sounds/beep.asm
index 9794accb..c978f9e3 100644
--- a/src/sounds/beep.asm
+++ b/src/sounds/beep.asm
@@ -22,7 +22,7 @@
 .INCLUDE "../macros.inc"
 .INCLUDE "../sound.inc"
 
-.IMPORT Ram_Sound_sChanSfx_arr
+.IMPORT Ram_Audio_sChanSfx_arr
 .IMPORTZP Zp_Next_sChanSfx_arr
 
 ;;;=========================================================================;;;
@@ -38,14 +38,14 @@ kBeepEnvPeriod = 3
 .SEGMENT "PRG8"
 
 ;;; SFX function for the BEEP opcode.  When starting this sound, Param1_byte
-;;; should hold the tone number (0-9), and Timer_u8 should be initialized to
+;;; should hold the tone number (0-9), and Param3_byte should be initialized to
 ;;; zero.
 ;;; @param X The channel number (0-4) times four (so, 0, 4, 8, 12, or 16).
 ;;; @return C Set if the sound is finished, cleared otherwise.
 ;;; @preserve X, T0+
 .EXPORT Func_SfxBeep
 .PROC Func_SfxBeep
-    lda Ram_Sound_sChanSfx_arr + sChanSfx::Timer_u8, x
+    lda Ram_Audio_sChanSfx_arr + sChanSfx::Param3_byte, x  ; timer
     beq _Initialize
     cmp #kBeepDurationFrames
     blt _Continue
@@ -56,13 +56,13 @@ _Initialize:
     sta Hw_Channels_sChanRegs_arr5 + sChanRegs::Envelope_wo, x
     lda #0
     sta Hw_Channels_sChanRegs_arr5 + sChanRegs::Sweep_wo, x
-    ldy Ram_Sound_sChanSfx_arr + sChanSfx::Param1_byte, x
+    ldy Ram_Audio_sChanSfx_arr + sChanSfx::Param1_byte, x  ; tone
     lda _TimerLo_u8_arr10, y
     sta Hw_Channels_sChanRegs_arr5 + sChanRegs::TimerLo_wo, x
     lda _TimerHi_u8_arr10, y
     sta Hw_Channels_sChanRegs_arr5 + sChanRegs::TimerHi_wo, x
 _Continue:
-    inc Ram_Sound_sChanSfx_arr + sChanSfx::Timer_u8, x
+    inc Ram_Audio_sChanSfx_arr + sChanSfx::Param3_byte, x  ; timer
     clc  ; clear C to indicate that the sound is still going
     rts
 ;;; These values represent the ten natural notes from A3 through C5.
@@ -79,9 +79,9 @@ _TimerHi_u8_arr10: .byte $01, $01, $01, $01, $01, $01, $01, $00, $00, $00
 ;;; @preserve X, Y, T0+
 .EXPORT FuncA_Machine_PlaySfxBeep
 .PROC FuncA_Machine_PlaySfxBeep
-    sta Zp_Next_sChanSfx_arr + eChan::Pulse2 + sChanSfx::Param1_byte
+    sta Zp_Next_sChanSfx_arr + eChan::Pulse2 + sChanSfx::Param1_byte  ; tone
     lda #0
-    sta Zp_Next_sChanSfx_arr + eChan::Pulse2 + sChanSfx::Timer_u8
+    sta Zp_Next_sChanSfx_arr + eChan::Pulse2 + sChanSfx::Param3_byte  ; timer
     lda #eSound::Beep
     sta Zp_Next_sChanSfx_arr + eChan::Pulse2 + sChanSfx::Sfx_eSound
     rts
diff --git a/src/sounds/dialog.asm b/src/sounds/dialog.asm
index c06c74e9..c893e8bd 100644
--- a/src/sounds/dialog.asm
+++ b/src/sounds/dialog.asm
@@ -23,7 +23,7 @@
 .INCLUDE "../macros.inc"
 .INCLUDE "../sound.inc"
 
-.IMPORT Ram_Sound_sChanSfx_arr
+.IMPORT Ram_Audio_sChanSfx_arr
 .IMPORTZP Zp_Next_sChanSfx_arr
 
 ;;;=========================================================================;;;
@@ -48,19 +48,19 @@ kSfxDialogTextDurationFrames = 4
 
 ;;; SFX function for dialog text.  When starting this sound, Param1_byte should
 ;;; hold the TimerLo value, Param2_byte should hold the bSfxDialog value, and
-;;; Timer_u8 should be initialized to zero.
+;;; Param3_byte should be initialized to zero.
 ;;; @param X The channel number (0-4) times four (so, 0, 4, 8, 12, or 16).
 ;;; @return C Set if the sound is finished, cleared otherwise.
 ;;; @preserve X, T0+
 .EXPORT Func_SfxDialogText
 .PROC Func_SfxDialogText
-    lda Ram_Sound_sChanSfx_arr + sChanSfx::Timer_u8, x
+    lda Ram_Audio_sChanSfx_arr + sChanSfx::Param3_byte, x  ; timer
     beq _Initialize
     cmp #kSfxDialogTextDurationFrames
     bcc _Continue
     rts  ; C is set to indicate that sound is finished
 _Initialize:
-    ldy Ram_Sound_sChanSfx_arr + sChanSfx::Param2_byte, x
+    ldy Ram_Audio_sChanSfx_arr + sChanSfx::Param2_byte, x
     tya  ; Param2_byte
     and #bSfxDialog::TypeMask
     ora #bEnvelope::NoLength | 0
@@ -71,13 +71,13 @@ _Initialize:
     div #8
     ora #$88
     sta Hw_Channels_sChanRegs_arr5 + sChanRegs::Sweep_wo, x
-    lda Ram_Sound_sChanSfx_arr + sChanSfx::Param1_byte, x
+    lda Ram_Audio_sChanSfx_arr + sChanSfx::Param1_byte, x
     sta Hw_Channels_sChanRegs_arr5 + sChanRegs::TimerLo_wo, x
     tya  ; Param2_byte
     and #bSfxDialog::TimerHiMask
     sta Hw_Channels_sChanRegs_arr5 + sChanRegs::TimerHi_wo, x
 _Continue:
-    inc Ram_Sound_sChanSfx_arr + sChanSfx::Timer_u8, x
+    inc Ram_Audio_sChanSfx_arr + sChanSfx::Param3_byte, x  ; timer
     clc  ; clear C to indicate that the sound is still going
     rts
 .ENDPROC
@@ -106,7 +106,7 @@ _Continue:
     lda DataA_Dialog_SfxDialogTextParam1_u8_arr, y
     sta Zp_Next_sChanSfx_arr + sChanSfx::Param1_byte, x
     lda #0
-    sta Zp_Next_sChanSfx_arr + sChanSfx::Timer_u8, x
+    sta Zp_Next_sChanSfx_arr + sChanSfx::Param3_byte, x  ; timer
     lda #eSound::DialogText
     sta Zp_Next_sChanSfx_arr + sChanSfx::Sfx_eSound, x
     rts
diff --git a/src/sounds/explode.asm b/src/sounds/explode.asm
index 7850ad57..ed5b947e 100644
--- a/src/sounds/explode.asm
+++ b/src/sounds/explode.asm
@@ -23,15 +23,15 @@
 .INCLUDE "../macros.inc"
 .INCLUDE "../sound.inc"
 
-.IMPORT Ram_Sound_sChanSfx_arr
+.IMPORT Ram_Audio_sChanSfx_arr
 .IMPORTZP Zp_Next_sChanSfx_arr
 
 ;;;=========================================================================;;;
 
 ;;; Bitfield used for Param1_byte for the eSound::Explode SFX function.
 .SCOPE bSfxExplode
-    DivEnv   = %10000000  ; if set, halve Timer_u8 before setting envelope
-    ModTimer = %01000000  ; if set, mod Timer_u8 by 2 before indexing period
+    DivEnv   = %10000000  ; if set, halve timer before setting envelope
+    ModTimer = %01000000  ; if set, mod timer by 2 before indexing period
 .ENDSCOPE
 
 ;;;=========================================================================;;;
@@ -44,12 +44,12 @@
 ;;; @preserve X, T0+
 .EXPORT Func_SfxExplode
 .PROC Func_SfxExplode
-    lda Ram_Sound_sChanSfx_arr + eChan::Noise + sChanSfx::Timer_u8
+    lda Ram_Audio_sChanSfx_arr + eChan::Noise + sChanSfx::Param3_byte  ; timer
     bne _Continue
     sec  ; set C to indicate that the sound is finished
     rts
 _Continue:
-    bit Ram_Sound_sChanSfx_arr + eChan::Noise + sChanSfx::Param1_byte
+    bit Ram_Audio_sChanSfx_arr + eChan::Noise + sChanSfx::Param1_byte
     .assert bSfxExplode::DivEnv = bProc::Negative, error
     bpl @noDivEnv
     div #2
@@ -62,13 +62,13 @@ _Continue:
     tay
     bpl @loadTimer  ; unconditional
     @noModTimer:
-    ldy Ram_Sound_sChanSfx_arr + eChan::Noise + sChanSfx::Timer_u8
+    ldy Ram_Audio_sChanSfx_arr + eChan::Noise + sChanSfx::Param3_byte  ; timer
     @loadTimer:
     lda _NoisePeriod_u8_arr, y
     sta Hw_NoisePeriod_wo
     lda #0
     sta Hw_NoiseLength_wo
-    dec Ram_Sound_sChanSfx_arr + sChanSfx::Timer_u8, x
+    dec Ram_Audio_sChanSfx_arr + sChanSfx::Param3_byte, x  ; timer
     clc  ; clear C to indicate that the sound is still going
     rts
 _NoisePeriod_u8_arr:
@@ -116,10 +116,10 @@ _NoisePeriod_u8_arr:
 
 ;;; Starts playing a explosion sound.
 ;;; @prereq The Param1_byte is already initialized.
-;;; @param A The value to set for Timer_u8.
+;;; @param A The value to set for Param3_byte.
 ;;; @preserve X, Y, T0+
 .PROC Func_PlaySfxExplode
-    sta Zp_Next_sChanSfx_arr + eChan::Noise + sChanSfx::Timer_u8
+    sta Zp_Next_sChanSfx_arr + eChan::Noise + sChanSfx::Param3_byte  ; timer
     lda #eSound::Explode
     sta Zp_Next_sChanSfx_arr + eChan::Noise + sChanSfx::Sfx_eSound
     rts