Low health alarm documentation

RenaKunisaki

9 files changed, 73 insertions, 54 deletions

diff --git a/audio.asm b/audio.asm
index 2f161426..8b2ee0e3 100644
--- a/audio.asm
+++ b/audio.asm
@@ -365,7 +365,7 @@ SECTION "Audio Engine 1", ROMX, BANK[AUDIO_1]
 PlayBattleMusic:: ; 0x90c6
 	xor a
 	ld [wMusicHeaderPointer], a
-	ld [wd083], a
+	ld [wLowHealthAlarm], a
 	dec a
 	ld [wc0ee], a
 	call PlaySound ; stop music
@@ -455,63 +455,80 @@ Music_Cities1AlternateTempo:: ; 0x9b81
 
 SECTION "Audio Engine 2", ROMX, BANK[AUDIO_2]
 
-Func_2136e:: ; 2136e (8:536e)
-	ld a, [wd083]
+Music_DoLowHealthAlarm:: ; 2136e (8:536e)
+	ld a, [wLowHealthAlarm]
 	cp $ff
-	jr z, .asm_2139b
-	bit 7, a
-	ret z
-	and $7f
-	jr nz, .asm_21383
-	call Func_213a7
-	ld a, $1e
-	jr .asm_21395
+	jr z, .disableAlarm
+
+	bit 7, a  ;alarm enabled?
+	ret z     ;nope
+
+	and $7f   ;low 7 bits are the timer.
+	jr nz, .asm_21383 ;if timer > 0, play low tone.
+
+	call .playToneHi
+	ld a, 30 ;keep this tone for 30 frames.
+	jr .asm_21395 ;reset the timer.
+
 .asm_21383
-	cp $14
-	jr nz, .asm_2138a
-	call Func_213ac
+	cp 20
+	jr nz, .asm_2138a ;if timer == 20,
+	call .playToneLo  ;actually set the sound registers.
+
 .asm_2138a
 	ld a, $86
-	ld [wc02a], a
-	ld a, [wd083]
-	and $7f
+	ld [wc02a], a ;disable sound channel?
+	ld a, [wLowHealthAlarm]
+	and $7f ;decrement alarm timer.
 	dec a
+
 .asm_21395
+	; reset the timer and enable flag.
 	set 7, a
-	ld [wd083], a
+	ld [wLowHealthAlarm], a
 	ret
-.asm_2139b
+
+.disableAlarm
 	xor a
-	ld [wd083], a
-	ld [wc02a], a
-	ld de, Unknown_213c4 ; $53c4
-	jr asm_213af
-
-Func_213a7: ; 213a7 (8:53a7)
-	ld de, Unknown_213bc ; $53bc
-	jr asm_213af
-
-Func_213ac: ; 213ac (8:53ac)
-	ld de, Unknown_213c0 ; $53c0
-asm_213af: ; 213af (8:53af)
-	ld hl, $ff10
+	ld [wLowHealthAlarm], a  ;disable alarm
+	ld [wc02a], a  ;re-enable sound channel?
+	ld de, .toneDataSilence
+	jr .playTone
+
+;update the sound registers to change the frequency.
+;the tone set here stays until we change it.
+.playToneHi
+	ld de, .toneDataHi
+	jr .playTone
+
+.playToneLo
+	ld de, .toneDataLo
+
+;update sound channel 1 to play the alarm, overriding all other sounds.
+.playTone
+	ld hl, rNR10 ;channel 1 sound register
 	ld c, $5
 	xor a
-.asm_213b5
+
+.copyLoop
 	ld [hli], a
 	ld a, [de]
 	inc de
 	dec c
-	jr nz, .asm_213b5
+	jr nz, .copyLoop
 	ret
 
-Unknown_213bc: ; 213bc (8:53bc)
+;bytes to write to sound channel 1 registers for health alarm.
+;starting at FF11 (FF10 is always zeroed), so these bytes are:
+;length, envelope, freq lo, freq hi
+.toneDataHi
 	db $A0,$E2,$50,$87
 
-Unknown_213c0: ; 213c0 (8:53c0)
+.toneDataLo
 	db $B0,$E2,$EE,$86
 
-Unknown_213c4: ; 213c4 (8:53c4)
+;written to stop the alarm
+.toneDataSilence
 	db $00,$00,$00,$80
 
 
diff --git a/audio/engine_2.asm b/audio/engine_2.asm
index b4cb653b..067ecc0c 100644
--- a/audio/engine_2.asm
+++ b/audio/engine_2.asm
@@ -162,7 +162,7 @@ Music8_PlayNextNote: ; 21946 (8:5946)
 	ld a, c
 	cp CH4
 	jr nz, .beginChecks
-	ld a, [wd083]
+	ld a, [wLowHealthAlarm] ;low health alarm enabled?
 	bit 7, a
 	ret nz
 .beginChecks
@@ -931,7 +931,7 @@ Func_21e19: ; 21e19 (8:5e19)
 	ld a, c
 	cp CH4
 	jr nz, .asm_21e2e
-	ld a, [wd083]
+	ld a, [wLowHealthAlarm]
 	bit 7, a
 	jr z, .asm_21e2e
 	xor a
diff --git a/engine/battle/4_2.asm b/engine/battle/4_2.asm
index bac0a2d1..ea29cca7 100755
--- a/engine/battle/4_2.asm
+++ b/engine/battle/4_2.asm
@@ -45,7 +45,7 @@ EndOfBattle: ; 137aa (4:77aa)
 	predef EvolutionAfterBattle
 .resetVariables
 	xor a
-	ld [wd083], a
+	ld [wLowHealthAlarm], a ;disable low health alarm
 	ld [wc02a], a
 	ld [W_ISINBATTLE], a
 	ld [W_BATTLETYPE], a
diff --git a/engine/battle/core.asm b/engine/battle/core.asm
index 63be5676..e76a2720 100755
--- a/engine/battle/core.asm
+++ b/engine/battle/core.asm
@@ -947,7 +947,7 @@ EnemyMonFaintedText: ; 0x3c63e
 
 Func_3c643: ; 3c643 (f:4643)
 	xor a
-	ld [wd083], a
+	ld [wLowHealthAlarm], a ;disable low health alarm
 	ld [wc02a], a
 	inc a
 	ld [wccf6], a
@@ -1089,15 +1089,15 @@ RemoveFaintedPlayerMon: ; 3c741 (f:4741)
 	predef FlagActionPredef ; clear gain exp flag for fainted mon
 	ld hl, W_ENEMYBATTSTATUS1
 	res 2, [hl]   ; reset "attacking multiple times" flag
-	ld a, [wd083]
+	ld a, [wLowHealthAlarm]
 	bit 7, a      ; skip sound flag (red bar (?))
 	jr z, .skipWaitForSound
 	ld a, $ff
-	ld [wd083], a
+	ld [wLowHealthAlarm], a ;disable low health alarm
 	call WaitForSoundToFinish
 .skipWaitForSound
 ; bug? if the player mon faints while the enemy mon is using bide,
-; the accumulated damage is overwritten. xxx what values can [wd083] have here?
+; the accumulated damage is overwritten. xxx what values can [wLowHealthAlarm] have here?
 	ld hl, wEnemyBideAccumulatedDamage
 	ld [hli], a
 	ld [hl], a
@@ -1934,16 +1934,16 @@ DrawPlayerHUDAndHPBar: ; 3cd60 (f:4d60)
 	cp $2
 	jr z, .asm_3cde6
 .asm_3cdd9
-	ld hl, wd083
-	bit 7, [hl]
+	ld hl, wLowHealthAlarm
+	bit 7, [hl] ;low health alarm enabled?
 	ld [hl], $0
 	ret z
 	xor a
 	ld [wc02a], a
 	ret
 .asm_3cde6
-	ld hl, wd083
-	set 7, [hl]
+	ld hl, wLowHealthAlarm
+	set 7, [hl] ;enable low health alarm
 	ret
 
 DrawEnemyHUDAndHPBar: ; 3cdec (f:4dec)
diff --git a/engine/evolution.asm b/engine/evolution.asm
index 5842f1a2..7ae88fdf 100755
--- a/engine/evolution.asm
+++ b/engine/evolution.asm
@@ -7,7 +7,7 @@ Func_7bde9: ; 7bde9 (1e:7de9)
 	ld a, [wd0b5]
 	push af
 	xor a
-	ld [wd083], a
+	ld [wLowHealthAlarm], a
 	ld [wc02a], a
 	dec a
 	ld [wc0ee], a
diff --git a/engine/items/items.asm b/engine/items/items.asm
index c1268cd5..605e5dde 100755
--- a/engine/items/items.asm
+++ b/engine/items/items.asm
@@ -858,7 +858,7 @@ ItemUseMedicine: ; dabb (3:5abb)
 	jp .cureStatusAilment
 .notFullHP ; if the pokemon's current HP doesn't equal its max HP
 	xor a
-	ld [wd083],a
+	ld [wLowHealthAlarm],a ;disable low health alarm
 	ld [wc02a],a
 	push hl
 	push de
@@ -1645,7 +1645,7 @@ ItemUsePokeflute: ; e140 (3:6140)
 ; if some pokemon were asleep
 	ld hl,PlayedFluteHadEffectText
 	call PrintText
-	ld a,[wd083]
+	ld a,[wLowHealthAlarm]
 	and a,$80
 	jr nz,.skipMusic
 	call WaitForSoundToFinish ; wait for sound to end
diff --git a/home.asm b/home.asm
index 37e128f0..c403642f 100644
--- a/home.asm
+++ b/home.asm
@@ -3223,7 +3223,7 @@ PlaySoundWaitForCurrent:: ; 3740 (0:3740)
 
 ; Wait for sound to finish playing
 WaitForSoundToFinish:: ; 3748 (0:3748)
-	ld a, [wd083]
+	ld a, [wLowHealthAlarm]
 	and $80
 	ret nz
 	push hl
diff --git a/home/vblank.asm b/home/vblank.asm
index 5d49ec51..d8288187 100644
--- a/home/vblank.asm
+++ b/home/vblank.asm
@@ -65,7 +65,7 @@ VBlank::
 	cp BANK(Music8_UpdateMusic)
 	jr nz, .bank1F
 .bank8
-	call Func_2136e
+	call Music_DoLowHealthAlarm
 	call Music8_UpdateMusic
 	jr .afterMusic
 .bank1F
diff --git a/wram.asm b/wram.asm
index 7091bd4c..ee6cc20f 100755
--- a/wram.asm
+++ b/wram.asm
@@ -1091,7 +1091,9 @@ W_BASECOORDX:: ; d081
 W_BASECOORDY:: ; d082
 	ds 1
 
-wd083:: ds 1
+; low health alarm counter/enable
+; high bit = enable, others = timer to cycle frequencies
+wLowHealthAlarm:: ds 1 ; d083
 
 W_FBTILECOUNTER:: ; d084
 ; counts how many tiles of the current frame block have been drawn