Document RNG

7 files changed, 73 insertions, 64 deletions

diff --git a/engine/pinball_game/evolution_mode.asm b/engine/pinball_game/evolution_mode.asm
index 226ba48..d6db1a8 100755
--- a/engine/pinball_game/evolution_mode.asm
+++ b/engine/pinball_game/evolution_mode.asm
@@ -443,7 +443,7 @@ InitEvolutionModeForMon: ; 0x10d1d
 	jr nz, .asm_10d8a

 	xor a

 .asm_10d8a

-	call Func_a21

+	call RandomRange

 	sla a

 	ld c, a

 	pop hl

@@ -478,7 +478,7 @@ InitEvolutionModeForMon: ; 0x10d1d
 .asm_10dc0

 	push bc

 	ld a, c

-	call Func_a21

+	call RandomRange

 	ld c, a

 	ld b, $0

 	ld hl, wd55c

diff --git a/engine/pinball_game/evolution_mode/evolution_mode_blue_field.asm b/engine/pinball_game/evolution_mode/evolution_mode_blue_field.asm
index afcb9ea..5dac074 100644
--- a/engine/pinball_game/evolution_mode/evolution_mode_blue_field.asm
+++ b/engine/pinball_game/evolution_mode/evolution_mode_blue_field.asm
@@ -638,7 +638,7 @@ asm_210c7:
 

 Func_2111d: ; 0x2111d

 	ld a, $11

-	call Func_a21

+	call RandomRange

 	ld c, a

 	ld b, $0

 	ld hl, wd566

diff --git a/engine/pinball_game/evolution_mode/evolution_mode_red_field.asm b/engine/pinball_game/evolution_mode/evolution_mode_red_field.asm
index 5bbf336..018ea91 100644
--- a/engine/pinball_game/evolution_mode/evolution_mode_red_field.asm
+++ b/engine/pinball_game/evolution_mode/evolution_mode_red_field.asm
@@ -640,7 +640,7 @@ asm_20a9f:
 

 Func_20af5: ; 0x20af5

 	ld a, $11

-	call Func_a21

+	call RandomRange

 	ld c, a

 	ld b, $0

 	ld hl, wd566

diff --git a/engine/pinball_game/slot.asm b/engine/pinball_game/slot.asm
index a81fc14..11998fa 100644
--- a/engine/pinball_game/slot.asm
+++ b/engine/pinball_game/slot.asm
@@ -269,7 +269,7 @@ SlotRewardBonusMultiplier: ; 0xefa7
 

 SlotRewardSmallPoints: ; 0xefb2

 	ld a, $8

-	call Func_a21

+	call RandomRange

 	ld [wCurSlotBonus], a

 	ld b, $80

 .asm_efbc

@@ -308,7 +308,7 @@ SlotRewardSmallPoints: ; 0xefb2
 

 SlotRewardBigPoints: ; 0xeff3

 	ld a, $8

-	call Func_a21

+	call RandomRange

 	ld [wCurSlotBonus], a

 	ld b, $80

 .asm_effd

@@ -417,7 +417,7 @@ BallTypeProgressionBlueField: ; 0xf0bb
 

 SlotBonusMultiplier: ; 0xf0c1

 	ld a, $4

-	call Func_a21

+	call RandomRange

 	ld [wCurSlotBonus], a

 	ld b, $80

 .asm_f0cb

diff --git a/home.asm b/home.asm
index 1f1e6fa..7da2d24 100644
--- a/home.asm
+++ b/home.asm
@@ -147,8 +147,8 @@ Start: ; 0x150
 	ld [rIE], a  ; Only enable LCD Status interrupt
 	ei
 	ld a, $ff
-	ld [wd810], a
-	call Func_97a
+	ld [wRNGModulus], a
+	call ResetRNG
 	xor a
 	ld [wBootCheck], a
 	ld a, BANK(Func_1ffc)
@@ -236,8 +236,8 @@ SoftReset:
 	ld [rIE], a
 	ei
 	ld a, $ff
-	ld [wd810], a
-	call Func_97a
+	ld [wRNGModulus], a
+	call ResetRNG
 	ld a, [hGameBoyColorFlag]
 	ld [$fffd], a
 	xor a
@@ -785,7 +785,7 @@ INCLUDE "home/random.asm"
 INCLUDE "home/joypad.asm"
 INCLUDE "home/palettes.asm"
 
-Func_dd4: ; 0xdd4
+HorrendousMultiplyAbyL: ; 0xdd4
 ; Return a * l to hl
 ; Stupid waste of space
 	push bc
diff --git a/home/random.asm b/home/random.asm
index e2b8c32..ce34f69 100644
--- a/home/random.asm
+++ b/home/random.asm
@@ -2,18 +2,18 @@ GenRandom: ; 0x959
 	push bc
 	push de
 	push hl
-	ld a, [wd811]
+	ld a, [wRNGPointer]
 	ld c, a
 	ld b, $0 ;load ??? into c
 	inc a
 	cp 54 + 1 ;inc ???, if ??? is 55 do alot of subtraction and make ??? 0
 	jr nz, .asm_96e
-	call Func_9fa
+	call UpdateRNG
 	xor a
 	ld bc, $0000
 .asm_96e
-	ld [wd811], a ;place wd811 + 1 back in
-	ld hl, wd812 ;choose number generated based on wd811 and all the subtraction
+	ld [wRNGPointer], a ;place wRNGPointer + 1 back in
+	ld hl, wRNGValues ;choose number generated based on wRNGPointer and all the subtraction
 	add hl, bc
 	ld a, [hl]
 	pop hl
@@ -21,53 +21,55 @@ GenRandom: ; 0x959
 	pop bc
 	ret
 
-Func_97a: ; 0x97a
-	ld a, [wd810]
+ResetRNG: ; 0x97a
+	ld a, [wRNGModulus]
 	ld d, a
-	ld a, $0
+	ld a, $0 ; wasted instruction (debug that was never commented out?)
+	; [wRNGSub] = [sRNGMod] % [wRNGModulus]
 	ld a, [sRNGMod]
-.asm_983
+.modulo
 	cp d
-	jr c, .asm_989
+	jr c, .okay
 	sub d
-	jr .asm_983
+	jr .modulo
 
-.asm_989
-	ld [wd80f], a
-	ld [wd848], a
+.okay
+	ld [wRNGSub], a
+	ld [wRNGSub2], a
 	ld e, $1
-	ld hl, Data_9c4
-	ld a, $36
-.asm_996
+	ld hl, .Data
+	ld a, 54
+.copy_prng
 	push af
 	ld c, [hl]
 	inc hl
 	ld b, $0
 	push hl
-	ld hl, wd812
+	ld hl, wRNGValues
 	add hl, bc
 	ld [hl], e
-	ld a, [wd80f]
+	ld a, [wRNGSub]
 	sub e
-	jr nc, .asm_9a8
+	jr nc, .next
 	add d
-.asm_9a8
+.next
 	ld e, a
 	ld a, [hl]
-	ld [wd80f], a
+	ld [wRNGSub], a
 	pop hl
 	pop af
 	dec a
-	jr nz, .asm_996
-	call Func_9fa
-	call Func_9fa
-	call Func_9fa
-	ld a, $0
+	jr nz, .copy_prng
+	call UpdateRNG
+	call UpdateRNG
+	call UpdateRNG
+	ld a, $0 ; wasted instruction (debug that was never commented out?)
 	call GenRandom
 	ld [sRNGMod], a
 	ret
 
-Data_9c4:
+.Data
+; offsets from wRNGValues
 	db $14, $29, $07, $1c, $31, $0f, $24, $02, $17
 	db $2c, $0a, $1f, $34, $12, $27, $05, $1a, $2f
 	db $0d, $22, $00, $15, $2a, $08, $1d, $32, $10
@@ -75,45 +77,49 @@ Data_9c4:
 	db $06, $1b, $30, $0e, $23, $01, $16, $2b, $09
 	db $1e, $33, $11, $26, $04, $19, $2e, $0c, $21
 
-Func_9fa: ; 0x9fa
-	ld a, [wd810]
+UpdateRNG: ; 0x9fa
+; Adjusts two RNG values using wRNGModulus
+	ld a, [wRNGModulus]
 	ld d, a
-	ld bc, wd812
-	ld hl, wd812 + $1f ;d831
+ ; [d812] = ([d812] - 24 * [d831]) % [d810]
+	ld bc, wRNGValues
+	ld hl, wRNGValues + $1f
 	ld e, $18
-.asm_a06
+.loop
 	ld a, [bc]
-	sub [hl] ;sub d831 from wd812, add wd810 if it does not carry, put result in wd812. repeat 24 times
-	jr nc, .asm_a0b
+	sub [hl]
+	jr nc, .no_carry
 	add d
-.asm_a0b
+.no_carry
 	ld [bc], a
 	dec e
-	jr nz, .asm_a06
-	ld bc, wd812 + $18
-	ld hl, wd812
+	jr nz, .loop
+ ; [d82a] = ([d82a] - 31 * [d812]) % [d810]
+	ld bc, wRNGValues + $18 ; d82a
+	ld hl, wRNGValues
 	ld e, $1f
-.asm_a17
+.loop2
 	ld a, [bc]
 	sub [hl]
-	jr nc, .asm_a1c
+	jr nc, .no_carry2
 	add d
-.asm_a1c
+.no_carry2
 	ld [bc], a
 	dec e
-	jr nz, .asm_a17
+	jr nz, .loop2
 	ret
 
-Func_a21: ; 0xa21
+RandomRange: ; 0xa21
+; Random value 0 <= x < a
 	push bc
 	push hl
 	ld c, a
 	ld b, $0
-	ld hl, Data_a38 ;jump to c in table, load (twice c?) into l
+	ld hl, EvensAndOdds
 	add hl, bc
 	ld l, [hl]
-	call GenRandom ;a = a psuedo random number
-	call Func_dd4 ;a * l
+	call GenRandom
+	call HorrendousMultiplyAbyL
 	inc h
 	srl h
 	ld a, h
@@ -121,7 +127,10 @@ Func_a21: ; 0xa21
 	pop bc
 	ret
 
-Data_a38: ;starting from 0, go up 2 each byte
+EvensAndOdds:
+; The first 128 bytes are the first 128 even numbers starting at 0.
+; The next 128 bytes are the first 128 odd numbers starting at 1.
+; The (a)th element is essentially what you'd get from rlca.
 x = 0
 REPT 128
 	db x | ((x >> 7) & 1)
diff --git a/wram.asm b/wram.asm
index a753245..b45f4f7 100644
--- a/wram.asm
+++ b/wram.asm
@@ -1921,19 +1921,19 @@ wOBP0:: ; 0xd80d
 wOBP1:: ; 0xd80e
 	ds $1
 
-wd80f:: ; 0xd80f
+wRNGSub:: ; 0xd80f
 	ds $1
 
-wd810:: ; 0xd810 loaded by Func_9fa, RNG related
+wRNGModulus:: ; 0xd810 loaded by UpdateRNG, RNG related
 	ds $1
 
-wd811:: ; 0xd811
+wRNGPointer:: ; 0xd811
 	ds $1
 
-wd812:: ; 0xd812
+wRNGValues:: ; 0xd812
 	ds $36
 
-wd848:: ; 0xd848
+wRNGSub2:: ; 0xd848
 	ds $1
 
 wUpdateAudioEngineUsingTimerInterrupt:: ; 0xd849