Document BG Map decompression stuff

7 files changed, 486 insertions, 521 deletions

diff --git a/src/engine/bank03.asm b/src/engine/bank03.asm
index 87c9401..932de23 100644
--- a/src/engine/bank03.asm
+++ b/src/engine/bank03.asm
@@ -490,20 +490,21 @@ Func_c38f: ; c38f (3:438f)
 	push bc
 	ld a, [wd23a]
 	ld e, a
-	ld a, [wd23b]
+	ld a, [wd23a + 1]
 	ld d, a
 	or e
-	jr z, .asm_c3c7
+	jr z, .skip
+
 	push hl
-	ld b, $c0
-	call Func_08bf
+	ld b, HIGH(wc000)
+	call InitBGMapDecompression
 	ld a, [wd23d]
 	ld [wTempPointerBank], a
-	ld a, [wd130]
+	ld a, [wBGMapHeight]
 	inc a
 	srl a
 	ld b, a
-	ld a, [wd12f]
+	ld a, [wBGMapWidth]
 	inc a
 	srl a
 	ld c, a
@@ -511,7 +512,7 @@ Func_c38f: ; c38f (3:438f)
 .asm_c3b7
 	push bc
 	ld b, $00
-	call Func_3be4
+	call DecompressBGMapFromBank
 	ld hl, $10
 	add hl, de
 	ld d, h
@@ -519,7 +520,8 @@ Func_c38f: ; c38f (3:438f)
 	pop bc
 	dec b
 	jr nz, .asm_c3b7
-.asm_c3c7
+
+.skip
 	pop bc
 	pop hl
 	ret
@@ -571,10 +573,10 @@ Func_c3ee: ; c3ee (3:43ee)
 	ret
 
 Func_c3ff: ; c3ff (3:43ff)
-	ld a, [wd12f]
+	ld a, [wBGMapWidth]
 	sub $14
 	ld [wd237], a
-	ld a, [wd130]
+	ld a, [wBGMapHeight]
 	sub $12
 	ld [wd238], a
 	call Func_c41c
diff --git a/src/engine/bank1c.asm b/src/engine/bank1c.asm
index b8ac4fb..10bd58d 100644
--- a/src/engine/bank1c.asm
+++ b/src/engine/bank1c.asm
@@ -260,11 +260,11 @@ Func_701e9: ; 701e9 (1c:41e9)
 	push bc
 	ld e, l
 	ld d, h
-	ld b, $c0
-	call Func_08bf
+	ld b, HIGH(wc000)
+	call InitBGMapDecompression
 	pop bc
 	pop de
-	call Func_08de
+	call DecompressBGMap
 	ret
 
 Func_701fe: ; 701fe (1c:41fe)
diff --git a/src/engine/bank20.asm b/src/engine/bank20.asm
index e11b4d5..c47f37b 100644
--- a/src/engine/bank20.asm
+++ b/src/engine/bank20.asm
@@ -15,11 +15,12 @@ Func_80028: ; 80028 (20:4028)
 
 Func_80077: ; 80077 (20:4077)
 	ld a, $1
-	ld [wd292], a
+	ld [wBGMapCopyMode], a
 	jr Func_80082
 
 	xor a
-	ld [wd292], a
+	ld [wBGMapCopyMode], a
+;	fallthrough
 
 Func_80082: ; 80082 (20:4082)
 	push hl
@@ -30,24 +31,29 @@ Func_80082: ; 80082 (20:4082)
 	ld [hl], e
 	inc hl
 	ld [hl], d
+
+; get pointer and bank for BG Map
 	call Func_803b9
 	ld a, [wTempPointerBank]
 	ld [wd23d], a
-	ld de, wLoadedPalData
-	ld bc, $0006
+
+; store header data
+	ld de, wBGMapBuffer
+	ld bc, $0006 ; header + 1st instruction
 	call CopyBankedDataToDE
 	ld l, e
 	ld h, d
 	ld a, [hli]
-	ld [wd12f], a
+	ld [wBGMapWidth], a
 	ld a, [hli]
-	ld [wd130], a
+	ld [wBGMapHeight], a
 	ld a, [hli]
 	ld [wd23a], a
 	ld a, [hli]
-	ld [wd23b], a
+	ld [wd23a + 1], a
 	ld a, [hli]
 	ld [wd23c], a
+
 	call Func_800bd
 	pop de
 	pop bc
@@ -65,7 +71,7 @@ Func_800bd: ; 800bd (20:40bd)
 	adc $00
 	ld d, a
 	ld b, HIGH(wc000)
-	call Func_08bf
+	call InitBGMapDecompression
 	ld a, [wVRAMPointer]
 	ld e, a
 	ld a, [wVRAMPointer + 1]
@@ -77,9 +83,10 @@ Func_800bd: ; 800bd (20:40bd)
 	ret
 
 Func_800e0: ; 800e0 (20:40e0)
+; if wd23c != 0, then use double wBGMapWidth
 	push hl
 	ld hl, wd28e
-	ld a, [wd12f]
+	ld a, [wBGMapWidth]
 	ld [hl], a
 	ld a, [wd23c]
 	or a
@@ -88,14 +95,15 @@ Func_800e0: ; 800e0 (20:40e0)
 .asm_800f0
 
 	ld c, $40
-	ld hl, wLoadedPalData
+	ld hl, wBGMapBuffer
 	xor a
 .loop_clear
 	ld [hli], a
 	dec c
 	jr nz, .loop_clear
 
-	ld a, [wd130]
+; loop each row, up to the number of tiles in height
+	ld a, [wBGMapHeight]
 	ld c, a
 .loop
 	push bc
@@ -103,36 +111,37 @@ Func_800e0: ; 800e0 (20:40e0)
 	ld b, $00
 	ld a, [wd28e]
 	ld c, a
-	ld de, wLoadedPalData
-	call Func_3be4
-	ld a, [wd12f]
+	ld de, wBGMapBuffer
+	call DecompressBGMapFromBank
+
+	ld a, [wBGMapWidth]
 	ld b, a
 	pop de
 	push de
-	ld hl, wLoadedPalData
-	call Func_8016e
+	ld hl, wBGMapBuffer
+	call CopyBGDataToVRAMOrSRAM
 	ld a, [wConsole]
 	cp CONSOLE_CGB
-	jr nz, .asm_8013b
+	jr nz, .next_row
 
 	; cgb only
 	call BankswitchVRAM1
-	ld a, [wd12f]
+	ld a, [wBGMapWidth]
 	ld c, a
 	ld b, $00
-	ld hl, wLoadedPalData
+	ld hl, wBGMapBuffer
 	add hl, bc
 	pop de
 	push de
-	ld a, [wd12f]
+	ld a, [wBGMapWidth]
 	ld b, a
 	call Func_80148
-	call Func_8016e
+	call CopyBGDataToVRAMOrSRAM
 	call BankswitchVRAM0
 
-.asm_8013b
+.next_row
 	pop de
-	ld hl, $20
+	ld hl, BG_MAP_WIDTH
 	add hl, de
 	ld e, l
 	ld d, h
@@ -150,36 +159,47 @@ Func_80148: ; 80148 (20:4148)
 	ld a, [wd23c]
 	or a
 	jr z, .asm_80162
+
+; add wd291 to b bytes in hl
 	push hl
 	push bc
-.asm_80155
+.loop_1
 	push bc
 	ld a, [wd291]
 	add [hl]
 	ld [hli], a
 	pop bc
 	dec b
-	jr nz, .asm_80155
+	jr nz, .loop_1
 	pop bc
 	pop hl
 	ret
+
+; store wd291 to b bytes in hl
 .asm_80162
 	push hl
 	push bc
 	ld a, [wd291]
-.asm_80167
+.loop_2
 	ld [hli], a
 	dec b
-	jr nz, .asm_80167
+	jr nz, .loop_2
 	pop bc
 	pop hl
 	ret
 
-Func_8016e: ; 8016e (20:416e)
-	ld a, [wd292]
+; copies BG Map data pointed by hl
+; to either VRAM or SRAM, depending on wBGMapCopyMode
+; de is the target address in VRAM,
+; if SRAM is the target address to copy,
+; copies data to s0BGMap or s1BGMap
+; for VRAM0 or VRAM1 respectively
+CopyBGDataToVRAMOrSRAM: ; 8016e (20:416e)
+	ld a, [wBGMapCopyMode]
 	or a
 	jp z, SafeCopyDataHLtoDE
 
+; copies b bytes from hl to SRAM1
 	push hl
 	push bc
 	push de
@@ -188,12 +208,12 @@ Func_8016e: ; 8016e (20:416e)
 	ld a, BANK("SRAM1")
 	call BankswitchSRAM
 	push hl
-	ld hl, $800
+	ld hl, s0BGMap - v0BGMap0
 	ldh a, [hBankVRAM]
 	or a
-	jr z, .asm_8018c
-	ld hl, $c00
-.asm_8018c
+	jr z, .got_pointer
+	ld hl, s1BGMap - v1BGMap0
+.got_pointer
 	add hl, de
 	ld e, l
 	ld d, h
@@ -412,6 +432,7 @@ Func_802bb: ; 802bb (20:42bb)
 
 	INCROM $802d4, $803b9
 
+; gets pointer to BG map with ID from wd131
 Func_803b9: ; 803b9 (20:43b9)
 	ld l, $00
 	ld a, [wd131]
@@ -578,7 +599,7 @@ Func_80b89: ; 80b89 (20:4b89)
 	push af
 	ld c, a
 	ld a, $01
-	ld [wd292], a
+	ld [wBGMapCopyMode], a
 	ld b, $00
 	ld hl, wd323
 	add hl, bc
@@ -596,7 +617,7 @@ Func_80b89: ; 80b89 (20:4b89)
 Func_80ba4: ; 80ba4 (20:4ba4)
 	push af
 	xor a
-	ld [wd292], a
+	ld [wBGMapCopyMode], a
 	pop af
 ;	Fallthrough
 
@@ -609,13 +630,13 @@ Func_80baa: ; 80baa (20:4baa)
 	push af
 	ld a, [wd23d]
 	push af
-	ld a, [wd12f]
+	ld a, [wBGMapWidth]
 	push af
-	ld a, [wd130]
+	ld a, [wBGMapHeight]
 	push af
 	ld a, [wd23a]
 	push af
-	ld a, [wd23b]
+	ld a, [wd23a + 1]
 	push af
 	ld b, $0
 	ld hl, wd323
@@ -658,13 +679,13 @@ Func_80baa: ; 80baa (20:4baa)
 	add hl, bc
 	farcall Func_c38f
 	pop af
-	ld [wd23b], a
+	ld [wd23a + 1], a
 	pop af
 	ld [wd23a], a
 	pop af
-	ld [wd130], a
+	ld [wBGMapHeight], a
 	pop af
-	ld [wd12f], a
+	ld [wBGMapWidth], a
 	pop af
 	ld [wd23d], a
 	pop af
@@ -1415,373 +1436,332 @@ MapDataPointers_81697: ; 81697 (20:5697)
 	palette_pointer Palette160, 1, 0 ; PALETTE_160
 
 Data_8191b:: ; 8191b (20:591b)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $0000
 	db $00
-	db $dd
 
-	INCROM $81921, $81a22
+	INCROM $81920, $81a22
 
 Data_81a22:: ; 81a22 (20:5a22)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $0000
 	db $01
-	db $dd
 
-	INCROM $81a28, $81c13
+	INCROM $81a27, $81c13
 
 Data_81c13:: ; 81c13 (20:5c13)
-	db $1c
-	db $1e
+	db $1c ; width
+	db $1e ; height
 	dw $5d11
 	db $00
-	db $e7
 
-	INCROM $81c19, $81d2e
+	INCROM $81c18, $81d2e
 
 Data_81d2e:: ; 81d2e (20:5d2e)
-	db $1c
-	db $1e
+	db $1c ; width
+	db $1e ; height
 	dw $5eb4
 	db $01
-	db $e7
 
-	INCROM $81d34, $81ed1
+	INCROM $81d33, $81ed1
 
 Data_81ed1:: ; 81ed1 (20:5ed1)
-	db $04
-	db $06
+	db $04 ; width
+	db $06 ; height
 	dw $5ef0
 	db $00
-	db $ff
 
-	INCROM $81ed7, $81ef5
+	INCROM $81ed6, $81ef5
 
 Data_81ef5:: ; 81ef5 (20:5ef5)
-	db $04
-	db $06
+	db $04 ; width
+	db $06 ; height
 	dw $5f21
 	db $01
-	db $fb
 
-	INCROM $81efb, $81f26
+	INCROM $81efa, $81f26
 
 Data_81f26:: ; 81f26 (20:5f26)
-	db $18
-	db $1e
+	db $18 ; width
+	db $1e ; height
 	dw $5fd3
 	db $00
-	db $fd
 
-	INCROM $81f2c, $81feb
+	INCROM $81f2b, $81feb
 
 Data_81feb:: ; 81feb (20:5feb)
-	db $18
-	db $1e
+	db $18 ; width
+	db $1e ; height
 	dw $612b
 	db $01
-	db $fd
 
-	INCROM $81ff1, $82143
+	INCROM $81ff0, $82143
 
 Data_82143:: ; 82143 (20:6143)
-	db $04
-	db $01
+	db $04 ; width
+	db $01 ; height
 	dw $614d
 	db $00
-	db $f0
 
-	INCROM $82149, $82150
+	INCROM $82148, $82150
 
 Data_82150:: ; 82150 (20:6150)
-	db $04
-	db $01
+	db $04 ; width
+	db $01 ; height
 	dw $615d
 	db $01
-	db $f8
 
-	INCROM $82156, $82160
+	INCROM $82155, $82160
 
 Data_82160:: ; 82160 (20:6160)
-	db $14
-	db $18
+	db $14 ; width
+	db $18 ; height
 	dw $620e
 	db $00
-	db $ef
 
-	INCROM $82166, $82222
+	INCROM $82165, $82222
 
 Data_82222:: ; 82222 (20:6222)
-	db $14
-	db $18
+	db $14 ; width
+	db $18 ; height
 	dw $6322
 	db $01
-	db $ee
 
-	INCROM $82228, $82336
+	INCROM $82227, $82336
 
 Data_82336:: ; 82336 (20:6336)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $63ec
 	db $00
-	db $ef
 
-	INCROM $8233c, $82400
+	INCROM $8233b, $82400
 
 Data_82400:: ; 82400 (20:6400)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $6509
 	db $01
-	db $ef
 
-	INCROM $82406, $8251d
+	INCROM $82405, $8251d
 
 Data_8251d:: ; 8251d (20:651d)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $65d3
 	db $00
-	db $ef
 
-	INCROM $82523, $825e7
+	INCROM $82522, $825e7
 
 Data_825e7:: ; 825e7 (20:65e7)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $66f0
 	db $01
-	db $ef
 
-	INCROM $825ed, $82704
+	INCROM $825ec, $82704
 
 Data_82704:: ; 82704 (20:6704)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $67ba
 	db $00
-	db $ef
 
-	INCROM $8270a, $827ce
+	INCROM $82709, $827ce
 
 Data_827ce:: ; 827ce (20:67ce)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $68d7
 	db $01
-	db $ef
 
-	INCROM $827d4, $828eb
+	INCROM $827d3, $828eb
 
 Data_828eb:: ; 828eb (20:68eb)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $69a1
 	db $00
-	db $ef
 
-	INCROM $828f1, $829b5
+	INCROM $828f0, $829b5
 
 Data_829b5:: ; 829b5 (20:69b5)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $6abe
 	db $01
-	db $ef
 
-	INCROM $829bb, $82ad2
+	INCROM $829ba, $82ad2
 
 Data_82ad2:: ; 82ad2 (20:6ad2)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $6b88
 	db $00
-	db $ef
 
-	INCROM $82ad8, $82b9c
+	INCROM $82ad7, $82b9c
 
 Data_82b9c:: ; 82b9c (20:6b9c)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $6ca5
 	db $01
-	db $ef
 
-	INCROM $82ba2, $82cb9
+	INCROM $82ba1, $82cb9
 
 Data_82cb9:: ; 82cb9 (20:6cb9)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $6d6f
 	db $00
-	db $ef
 
-	INCROM $82cbf, $82d83
+	INCROM $82cbe, $82d83
 
 Data_82d83:: ; 82d83 (20:6d83)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $6e8c
 	db $01
-	db $ef
 
-	INCROM $82d89, $82ea0
+	INCROM $82d88, $82ea0
 
 Data_82ea0:: ; 82ea0 (20:6ea0)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $6f56
 	db $00
-	db $ef
 
-	INCROM $82ea6, $82f6a
+	INCROM $82ea5, $82f6a
 
 Data_82f6a:: ; 82f6a (20:6f6a)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $7073
 	db $01
-	db $ef
 
-	INCROM $82f70, $83087
+	INCROM $82f6f, $83087
 
 Data_83087:: ; 83087 (20:7087)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $713d
 	db $00
-	db $ef
 
-	INCROM $8308d, $83151
+	INCROM $8308c, $83151
 
 Data_83151:: ; 83151 (20:7151)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $725a
 	db $01
-	db $ef
 
-	INCROM $83157, $8326e
+	INCROM $83156, $8326e
 
 Data_8326e:: ; 8326e (20:726e)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $730d
 	db $00
-	db $ef
 
-	INCROM $83274, $83321
+	INCROM $83273, $83321
 
 Data_83321:: ; 83321 (20:7321)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $7410
 	db $01
-	db $ef
 
-	INCROM $83327, $83424
+	INCROM $83326, $83424
 
 Data_83424:: ; 83424 (20:7424)
-	db $1c
-	db $1a
+	db $1c ; width
+	db $1a ; height
 	dw $7529
 	db $00
-	db $e7
 
-	INCROM $8342a, $83545
+	INCROM $83429, $83545
 
 Data_83545:: ; 83545 (20:7545)
-	db $1c
-	db $1a
+	db $1c ; width
+	db $1a ; height
 	dw $76bf
 	db $01
-	db $e7
 
-	INCROM $8354b, $836db
+	INCROM $8354a, $836db
 
 Data_836db:: ; 836db (20:76db)
-	db $18
-	db $12
+	db $18 ; width
+	db $12 ; height
 	dw $777b
 	db $00
-	db $e7
 
-	INCROM $836e1, $8378c
+	INCROM $836e0, $8378c
 
 Data_8378c:: ; 8378c (20:778c)
-	db $18
-	db $12
+	db $18 ; width
+	db $12 ; height
 	dw $787c
 	db $01
-	db $e7
 
-	INCROM $83792, $8388d
+	INCROM $83791, $8388d
 
 Data_8388d:: ; 8388d (20:788d)
-	db $1c
-	db $1e
+	db $1c ; width
+	db $1e ; height
 	dw $79b5
 	db $00
-	db $e7
 
-	INCROM $83893, $839d6
+	INCROM $83892, $839d6
 
 Data_839d6:: ; 839d6 (20:79d6)
-	db $1c
-	db $1e
+	db $1c ; width
+	db $1e ; height
 	dw $7bd0
 	db $01
-	db $e7
 
-	INCROM $839dc, $83bf1
+	INCROM $839db, $83bf1
 
 Data_83bf1:: ; 83bf1 (20:7bf1)
-	db $04
-	db $03
+	db $04 ; width
+	db $03 ; height
 	dw $7c00
 	db $00
-	db $d8
 
-	INCROM $83bf7, $83c03
+	INCROM $83bf6, $83c03
 
 Data_83c03:: ; 83c03 (20:7c03)
-	db $04
-	db $03
+	db $04 ; width
+	db $03 ; height
 	dw $7c17
 	db $01
-	db $d6
 
-	INCROM $83c09, $83c1a
+	INCROM $83c08, $83c1a
 
 Data_83c1a:: ; 83c1a (20:7c1a)
-	db $04
-	db $03
+	db $04 ; width
+	db $03 ; height
 	dw $7c23
 	db $00
-	db $80
 
-	INCROM $83c20, $83c26
+	INCROM $83c1f, $83c26
 
 Data_83c26:: ; 83c26 (20:7c26)
-	db $04
-	db $03
+	db $04 ; width
+	db $03 ; height
 	dw $7c33
 	db $01
-	db $a0
 
-	INCROM $83c2c, $83c36
+	INCROM $83c2b, $83c36
 
 Data_83c36:: ; 83c36 (20:7c36)
-	db $03
-	db $03
+	db $03 ; width
+	db $03 ; height
 	dw $0000
 	db $01
-	db $f7
 
-	INCROM $83c3c, $83c4c
+	INCROM $83c3b, $83c4c
 
 AnimData1:: ; 83c4c (20:7c4c)
 	frame_table AnimFrameTable0
@@ -1792,4 +1772,6 @@ AnimData1:: ; 83c4c (20:7c4c)
 Palette110:: ; 83c5b (20:7c5b)
 	db $00, $00
 
-	INCROM $83c5d, $84000
+rept $3a3
+	db $ff
+endr
diff --git a/src/engine/home.asm b/src/engine/home.asm
index bb800df..47e48ff 100644
--- a/src/engine/home.asm
+++ b/src/engine/home.asm
@@ -1519,7 +1519,13 @@ UpdateRNGSources: ; 089b (0:089b)
 	pop hl
 	ret
 
-Func_08bf: ; 08bf (0:08bf)
+; initilizes variables used to decompress
+; BG Map data in DecompressBGMap
+; de points to the source of compressed data
+; b is used as the HIGH byte of the
+; WRAM address to write to ($100 bytes of buffer space)
+; also clears this $100 byte space
+InitBGMapDecompression: ; 08bf (0:08bf)
 	ld hl, wcad6
 	ld [hl], e
 	inc hl
@@ -1528,32 +1534,37 @@ Func_08bf: ; 08bf (0:08bf)
 	ld [hl], $1
 	inc hl
 	xor a
-	ld [hli], a
-	ld [hli], a
-	ld [hli], a
-	ld [hli], a
-	ld [hl], b
+	ld [hli], a ; wcad9
+	ld [hli], a ; wcada
+	ld [hli], a ; wcadb
+	ld [hli], a ; wcadc
+	ld [hl], b  ; wcadd
 	inc hl
-	ld [hli], a ; 0
-	ld [hl], $ef
+	ld [hli], a ; wcade
+	ld [hl], $ef ; wcadf
 
-; clear wc000
+; clear buffer
 	ld h, b
 	ld l, LOW(wc000)
 	xor a
-.asm_8d9
+.loop
 	ld [hl], a
 	inc l
-	jr nz, .asm_8d9
+	jr nz, .loop
 	ret
 
-; loops bc times
-Func_08de: ; 08de (0:08de)
+; decompresses BG Map data
+; uses values initialized by InitBGMapDecompression
+; wcad6 holds the pointer for compressed source
+; input:
+; bc = map width
+; de = buffer to place decompressed data
+DecompressBGMap: ; 08de (0:08de)
 	push hl
 	push de
 .loop
 	push bc
-	call Func_08ef
+	call .Decompress
 	ld [de], a
 	inc de
 	pop bc
@@ -1565,36 +1576,48 @@ Func_08de: ; 08de (0:08de)
 	pop hl
 	ret
 
-Func_08ef: ; 08ef (0:08ef)
+; instructions start with a byte stored in wcad9
+; its bits are read from higher to lower bit
+; wcad8 stores the current bit being read
+; bit set:
+; - 1 byte read and copied literally
+; bit not set:
+; - 2 bytes read WW XY ZZ, byte in pos WW
+; copied (X + 1) times, then in pos ZZ
+; copied (Y + 1) times
+.Decompress: ; 08ef (0:08ef)
 	ld hl, wcadc
 	ld a, [hl]
 	or a
-	jr z, .asm_902
+	jr z, .read_instruction
+
+; still repeating byte
 	dec [hl]
 	inc hl
-.asm_8f8
-	ld b, [hl]
+.repeat_byte
+	ld b, [hl] ; wcadd
 	inc hl
-	ld c, [hl]
+	ld c, [hl] ; wcade
 	inc [hl]
 	inc hl
 	ld a, [bc]
-	ld c, [hl]
+	ld c, [hl] ; wcadf
 	inc [hl]
 	ld [bc], a
 	ret
-.asm_902
+
+.read_instruction
 	ld hl, wcad6
 	ld c, [hl]
 	inc hl
 	ld b, [hl]
-	inc hl
+	inc hl ; wcad8
 	dec [hl]
-	inc hl
+	inc hl ; wcad9
 	jr nz, .asm_914
-	dec hl
-	ld [hl], $8
-	inc hl
+	dec hl ; wcad8
+	ld [hl], $8 ; number of bits
+	inc hl ; wcad9
 	ld a, [bc]
 	inc bc
 	ld [hl], a
@@ -1603,6 +1626,8 @@ Func_08ef: ; 08ef (0:08ef)
 	ld a, [bc]
 	inc bc
 	jr nc, .asm_92a
+
+; copy 1 byte literally
 	ld hl, wcad6
 	ld [hl], c
 	inc hl
@@ -1611,10 +1636,11 @@ Func_08ef: ; 08ef (0:08ef)
 	ld b, [hl]
 	inc hl
 	inc hl
-	ld c, [hl]
+	ld c, [hl] ; wcadf
 	inc [hl]
 	ld [bc], a
 	ret
+
 .asm_92a
 	ld [wcade], a
 	ld hl, wcada
@@ -1624,23 +1650,24 @@ Func_08ef: ; 08ef (0:08ef)
 	inc hl
 	ld a, [bc]
 	inc bc
-	ld [hli], a
+	ld [hli], a ; wcadb
 	swap a
 .asm_93c
 	and $f
-	inc a
-	ld [hli], a
+	inc a ; number of times to repeat
+	ld [hli], a ; wcadc
 	push hl
 	ld hl, wcad6
 	ld [hl], c
 	inc hl
 	ld [hl], b
 	pop hl
-	jr .asm_8f8
+	jr .repeat_byte
+
 .asm_94a
 	res 0, [hl]
 	inc hl
-	ld a, [hli]
+	ld a, [hli] ; wcadb
 	jr .asm_93c
 
 ; set attributes for [hl] sprites starting from wOAM + [wOAMOffset] / 4
@@ -11206,13 +11233,17 @@ ResetDoFrameFunction: ; 3bdb (0:3bdb)
 	pop hl
 	ret
 
-; runs function bc times
-Func_3be4: ; 3be4 (0:3be4)
+; decompresses BG Map data from a given bank
+; uses values initialized by InitBGMapDecompression
+; input:
+; bc = map width
+; de = buffer to place decompressed data
+DecompressBGMapFromBank: ; 3be4 (0:3be4)
 	ldh a, [hBankROM]
 	push af
 	ld a, [wTempPointerBank]
 	call BankswitchROM
-	call Func_08de
+	call DecompressBGMap
 	pop af
 	call BankswitchROM
 	ret
diff --git a/src/gfx.asm b/src/gfx.asm
index 0e5a4cc..727c146 100644
--- a/src/gfx.asm
+++ b/src/gfx.asm
@@ -48,589 +48,524 @@ endr
 SECTION "Gfx 3", ROMX
 
 Data_84000:: ; 84000 (21:4000)
-	db $1c
-	db $20
+	db $1c ; width
+	db $20 ; height
 	dw $4164
 	db $00
-	db $e7
 
-	INCROM $84006, $84188
+	INCROM $84005, $84188
 
 Data_84188:: ; 84188 (21:4188)
-	db $1c
-	db $20
+	db $1c ; width
+	db $20 ; height
 	dw $4397
 	db $01
-	db $e7
 
-	INCROM $8418e, $843bb
+	INCROM $8418d, $843bb
 
 Data_843bb:: ; 843bb (21:43bb)
-	db $1c
-	db $20
+	db $1c ; width
+	db $20 ; height
 	dw $4511
 	db $00
-	db $e7
 
-	INCROM $843c1, $84533
+	INCROM $843c0, $84533
 
 Data_84533:: ; 84533 (21:4533)
-	db $1c
-	db $20
+	db $1c ; width
+	db $20 ; height
 	dw $470c
 	db $01
-	db $e7
 
-	INCROM $84539, $8472e
+	INCROM $84538, $8472e
 
 Data_8472e:: ; 8472e (21:472e)
-	db $1c
-	db $20
+	db $1c ; width
+	db $20 ; height
 	dw $48b4
 	db $00
-	db $e7
 
-	INCROM $84734, $848d8
+	INCROM $84733, $848d8
 
 Data_848d8:: ; 848d8 (21:48d8)
-	db $1c
-	db $20
+	db $1c ; width
+	db $20 ; height
 	dw $4b4f
 	db $01
-	db $e7
 
-	INCROM $848de, $84b73
+	INCROM $848dd, $84b73
 
 Data_84b73:: ; 84b73 (21:4b73)
-	db $1c
-	db $1c
+	db $1c ; width
+	db $1c ; height
 	dw $4c50
 	db $00
-	db $e7
 
-	INCROM $84b79, $84c6f
+	INCROM $84b78, $84c6f
 
 Data_84c6f:: ; 84c6f (21:4c6f)
-	db $1c
-	db $1c
+	db $1c ; width
+	db $1c ; height
 	dw $4ddf
 	db $01
-	db $e7
 
-	INCROM $84c75, $84dfe
+	INCROM $84c74, $84dfe
 
 Data_84dfe:: ; 84dfe (21:4dfe)
-	db $1c
-	db $20
+	db $1c ; width
+	db $20 ; height
 	dw $4efe
 	db $00
-	db $eb
 
-	INCROM $84e04, $84f1d
+	INCROM $84e03, $84f1d
 
 Data_84f1d:: ; 84f1d (21:4f1d)
-	db $1c
-	db $20
+	db $1c ; width
+	db $20 ; height
 	dw $5097
 	db $01
-	db $eb
 
-	INCROM $84f23, $850b6
+	INCROM $84f22, $850b6
 
 Data_850b6:: ; 850b6 (21:50b6)
-	db $1c
-	db $20
+	db $1c ; width
+	db $20 ; height
 	dw $5175
 	db $00
-	db $e7
 
-	INCROM $850bc, $85191
+	INCROM $850bb, $85191
 
 Data_85191:: ; 85191 (21:5191)
-	db $1c
-	db $20
+	db $1c ; width
+	db $20 ; height
 	dw $52f9
 	db $01
-	db $e7
 
-	INCROM $85197, $85315
+	INCROM $85196, $85315
 
 Data_85315:: ; 85315 (21:5315)
-	db $20
-	db $20
+	db $20 ; width
+	db $20 ; height
 	dw $5484
 	db $00
-	db $e7
 
-	INCROM $8531b, $854b3
+	INCROM $8531a, $854b3
 
 Data_854b3:: ; 854b3 (21:54b3)
-	db $20
-	db $20
+	db $20 ; width
+	db $20 ; height
 	dw $56db
 	db $01
-	db $e7
 
-	INCROM $854b9, $8570a
+	INCROM $854b8, $8570a
 
 Data_8570a:: ; 8570a (21:570a)
-	db $20
-	db $12
+	db $20 ; width
+	db $12 ; height
 	dw $57ba
 	db $00
-	db $ee
 
-	INCROM $85710, $857ce
+	INCROM $8570f, $857ce
 
 Data_857ce:: ; 857ce (21:57ce)
-	db $20
-	db $12
+	db $20 ; width
+	db $12 ; height
 	dw $58db
 	db $01
-	db $ee
 
-	INCROM $857d4, $858ef
+	INCROM $857d3, $858ef
 
 Data_858ef:: ; 858ef (21:58ef)
-	db $20
-	db $20
+	db $20 ; width
+	db $20 ; height
 	dw $5a58
 	db $00
-	db $ec
 
-	INCROM $858f5, $85a79
+	INCROM $858f4, $85a79
 
 Data_85a79:: ; 85a79 (21:5a79)
-	db $20
-	db $20
+	db $20 ; width
+	db $20 ; height
 	dw $5cc1
 	db $01
-	db $ec
 
-	INCROM $85a7f, $85ce2
+	INCROM $85a7e, $85ce2
 
 Data_85ce2:: ; 85ce2 (21:5ce2)
-	db $18
-	db $1a
+	db $18 ; width
+	db $1a ; height
 	dw $5ddc
 	db $00
-	db $e7
 
-	INCROM $85ce8, $85df4
+	INCROM $85ce7, $85df4
 
 Data_85df4:: ; 85df4 (21:5df4)
-	db $18
-	db $1a
+	db $18 ; width
+	db $1a ; height
 	dw $5f64
 	db $01
-	db $e7
 
-	INCROM $85dfa, $85f7c
+	INCROM $85df9, $85f7c
 
 Data_85f7c:: ; 85f7c (21:5f7c)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $0000
 	db $01
-	db $90
 
-	INCROM $85f82, $8607f
+	INCROM $85f81, $8607f
 
 Data_8607f:: ; 8607f (21:607f)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $0000
 	db $01
-	db $81
 
-	INCROM $86085, $8617d
+	INCROM $86084, $8617d
 
 Data_8617d:: ; 8617d (21:617d)
-	db $03
-	db $03
+	db $03 ; width
+	db $03 ; height
 	dw $0000
 	db $01
-	db $f7
 
-	INCROM $86183, $86193
+	INCROM $86182, $86193
 
 Data_86193:: ; 86193 (21:6193)
-	db $03
-	db $03
+	db $03 ; width
+	db $03 ; height
 	dw $0000
 	db $01
-	db $f7
 
-	INCROM $86199, $861a9
+	INCROM $86198, $861a9
 
 Data_861a9:: ; 861a9 (21:61a9)
-	db $03
-	db $03
+	db $03 ; width
+	db $03 ; height
 	dw $0000
 	db $01
-	db $f7
 
-	INCROM $861af, $861bf
+	INCROM $861ae, $861bf
 
 Data_861bf:: ; 861bf (21:61bf)
-	db $03
-	db $03
+	db $03 ; width
+	db $03 ; height
 	dw $0000
 	db $01
-	db $f7
 
-	INCROM $861c5, $861d5
+	INCROM $861c4, $861d5
 
 Data_861d5:: ; 861d5 (21:61d5)
-	db $03
-	db $03
+	db $03 ; width
+	db $03 ; height
 	dw $0000
 	db $01
-	db $f7
 
-	INCROM $861db, $861eb
+	INCROM $861da, $861eb
 
 Data_861eb:: ; 861eb (21:61eb)
-	db $03
-	db $03
+	db $03 ; width
+	db $03 ; height
 	dw $0000
 	db $01
-	db $f7
 
-	INCROM $861f1, $86201
+	INCROM $861f0, $86201
 
 Data_86201:: ; 86201 (21:6201)
-	db $03
-	db $03
+	db $03 ; width
+	db $03 ; height
 	dw $0000
 	db $01
-	db $f7
 
-	INCROM $86207, $86217
+	INCROM $86206, $86217
 
 Data_86217:: ; 86217 (21:6217)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $0000
 	db $01
-	db $80
 
-	INCROM $8621d, $862da
+	INCROM $8621c, $862da
 
 Data_862da:: ; 862da (21:62da)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $0000
 	db $00
-	db $83
 
-	INCROM $862e0, $86364
+	INCROM $862df, $86364
 
 Data_86364:: ; 86364 (21:6364)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $0000
 	db $01
-	db $80
 
-	INCROM $8636a, $86443
+	INCROM $86369, $86443
 
 Data_86443:: ; 86443 (21:6443)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $0000
 	db $00
-	db $83
 
-	INCROM $86449, $864df
+	INCROM $86448, $864df
 
 Data_864df:: ; 864df (21:64df)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $0000
 	db $01
-	db $80
 
-	INCROM $864e5, $865b5
+	INCROM $864e4, $865b5
 
 Data_865b5:: ; 865b5 (21:65b5)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $0000
 	db $00
-	db $8f
 
-	INCROM $865bb, $86647
+	INCROM $865ba, $86647
 
 Data_86647:: ; 86647 (21:6647)
-	db $08
-	db $0c
+	db $08 ; width
+	db $0c ; height
 	dw $0000
 	db $00
-	db $ff
 
-	INCROM $8664d, $866b8
+	INCROM $8664c, $866b8
 
 Data_866b8:: ; 866b8 (21:66b8)
-	db $08
-	db $0c
+	db $08 ; width
+	db $0c ; height
 	dw $0000
 	db $01
-	db $d6
 
-	INCROM $866be, $8673e
+	INCROM $866bd, $8673e
 
 Data_8673e:: ; 8673e (21:673e)
-	db $08
-	db $0c
+	db $08 ; width
+	db $0c ; height
 	dw $0000
 	db $00
-	db $ff
 
-	INCROM $86744, $867af
+	INCROM $86743, $867af
 
 Data_867af:: ; 867af (21:67af)
-	db $08
-	db $0c
+	db $08 ; width
+	db $0c ; height
 	dw $0000
 	db $01
-	db $d6
 
-	INCROM $867b5, $86833
+	INCROM $867b4, $86833
 
 Data_86833:: ; 86833 (21:6833)
-	db $08
-	db $0c
+	db $08 ; width
+	db $0c ; height
 	dw $0000
 	db $00
-	db $ff
 
-	INCROM $86839, $868a4
+	INCROM $86838, $868a4
 
 Data_868a4:: ; 868a4 (21:68a4)
-	db $08
-	db $0c
+	db $08 ; width
+	db $0c ; height
 	dw $0000
 	db $01
-	db $d6
 
-	INCROM $868aa, $86925
+	INCROM $868a9, $86925
 
 Data_86925:: ; 86925 (21:6925)
-	db $08
-	db $0c
+	db $08 ; width
+	db $0c ; height
 	dw $0000
 	db $00
-	db $ff
 
-	INCROM $8692b, $86996
+	INCROM $8692a, $86996
 
 Data_86996:: ; 86996 (21:6996)
-	db $08
-	db $0c
+	db $08 ; width
+	db $0c ; height
 	dw $0000
 	db $01
-	db $d6
 
-	INCROM $8699c, $86a14
+	INCROM $8699b, $86a14
 
 Data_86a14:: ; 86a14 (21:6a14)
-	db $08
-	db $0c
+	db $08 ; width
+	db $0c ; height
 	dw $0000
 	db $00
-	db $ff
 
-	INCROM $86a1a, $86a85
+	INCROM $86a19, $86a85
 
 Data_86a85:: ; 86a85 (21:6a85)
-	db $08
-	db $0c
+	db $08 ; width
+	db $0c ; height
 	dw $0000
 	db $01
-	db $ff
 
-	INCROM $86a8b, $86b28
+	INCROM $86a8a, $86b28
 
 Data_86b28:: ; 86b28 (21:6b28)
-	db $08
-	db $0c
+	db $08 ; width
+	db $0c ; height
 	dw $0000
 	db $00
-	db $ff
 
-	INCROM $86b2e, $86b99
+	INCROM $86b2d, $86b99
 
 Data_86b99:: ; 86b99 (21:6b99)
-	db $08
-	db $0c
+	db $08 ; width
+	db $0c ; height
 	dw $0000
 	db $01
-	db $ff
 
-	INCROM $86b9f, $86c34
+	INCROM $86b9e, $86c34
 
 Data_86c34:: ; 86c34 (21:6c34)
-	db $08
-	db $0c
+	db $08 ; width
+	db $0c ; height
 	dw $0000
 	db $00
-	db $ff
 
-	INCROM $86c3a, $86ca5
+	INCROM $86c39, $86ca5
 
 Data_86ca5:: ; 86ca5 (21:6ca5)
-	db $08
-	db $0c
+	db $08 ; width
+	db $0c ; height
 	dw $0000
 	db $01
-	db $ff
 
-	INCROM $86cab, $86d37
+	INCROM $86caa, $86d37
 
 Data_86d37:: ; 86d37 (21:6d37)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $0000
 	db $00
-	db $9e
 
-	INCROM $86d3d, $86dcc
+	INCROM $86d3c, $86dcc
 
 Data_86dcc:: ; 86dcc (21:6dcc)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $0000
 	db $01
-	db $91
 
-	INCROM $86dd2, $86e8a
+	INCROM $86dd1, $86e8a
 
 Data_86e8a:: ; 86e8a (21:6e8a)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $0000
 	db $01
-	db $bf
 
-	INCROM $86e90, $86f18
+	INCROM $86e8f, $86f18
 
 Data_86f18:: ; 86f18 (21:6f18)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $0000
 	db $01
-	db $b0
 
-	INCROM $86f1e, $86fc0
+	INCROM $86f1d, $86fc0
 
 Data_86fc0:: ; 86fc0 (21:6fc0)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $0000
 	db $01
-	db $a3
 
-	INCROM $86fc6, $8704f
+	INCROM $86fc5, $8704f
 
 Data_8704f:: ; 8704f (21:704f)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $0000
 	db $00
-	db $ff
 
-	INCROM $87055, $871a5
+	INCROM $87054, $871a5
 
 Data_871a5:: ; 871a5 (21:71a5)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $0000
 	db $01
-	db $ff
 
-	INCROM $871ab, $87397
+	INCROM $871aa, $87397
 
 Data_87397:: ; 87397 (21:7397)
-	db $08
-	db $04
+	db $08 ; width
+	db $04 ; height
 	dw $0000
 	db $01
-	db $bf
 
-	INCROM $8739d, $873b7
+	INCROM $8739c, $873b7
 
 Data_873b7:: ; 873b7 (21:73b7)
-	db $06
-	db $06
+	db $06 ; width
+	db $06 ; height
 	dw $0000
 	db $00
-	db $ff
 
-	INCROM $873bd, $873e5
+	INCROM $873bc, $873e5
 
 Data_873e5:: ; 873e5 (21:73e5)
-	db $06
-	db $06
+	db $06 ; width
+	db $06 ; height
 	dw $0000
 	db $00
-	db $ff
 
-	INCROM $873eb, $87413
+	INCROM $873ea, $87413
 
 Data_87413:: ; 87413 (21:7413)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $0000
 	db $00
-	db $7e
 
-	INCROM $87419, $87538
+	INCROM $87418, $87538
 
 Data_87538:: ; 87538 (21:7538)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $0000
 	db $01
-	db $7e
 
-	INCROM $8753e, $8769f
+	INCROM $8753d, $8769f
 
 Data_8769f:: ; 8769f (21:769f)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $0000
 	db $00
-	db $03
 
-	INCROM $876a5, $876f6
+	INCROM $876a4, $876f6
 
 Data_876f6:: ; 876f6 (21:76f6)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $0000
 	db $01
-	db $00
 
-	INCROM $876fc, $8777c
+	INCROM $876fb, $8777c
 
 Data_8777c:: ; 8777c (21:777c)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $0000
 	db $00
-	db $01
 
-	INCROM $87782, $877c4
+	INCROM $87781, $877c4
 
 Data_877c4:: ; 877c4 (21:77c4)
-	db $14
-	db $12
+	db $14 ; width
+	db $12 ; height
 	dw $0000
 	db $00
-	db $07
 
-	INCROM $877ca, $87828
+	INCROM $877c9, $87828
 
 
 IshiharaTilesetGfx: ; 87828 (21:7828)
diff --git a/src/sram.asm b/src/sram.asm
index 09c4e67..512d96a 100644
--- a/src/sram.asm
+++ b/src/sram.asm
@@ -98,6 +98,11 @@ sba68:: ; ba68
 
 SECTION "SRAM1", SRAM
 
+; from VRAM0
+s0BGMap:: ds $400 ; a000
+; from VRAM1
+s1BGMap:: ds $400 ; a400
+
 SECTION "SRAM2", SRAM
 
 	ds $1c00
diff --git a/src/wram.asm b/src/wram.asm
index 753923a..849b45c 100644
--- a/src/wram.asm
+++ b/src/wram.asm
@@ -2076,10 +2076,10 @@ wPCLastDirectionPressed:: ; d12d
 
 	ds $1
 
-wd12f:: ; d12f
+wBGMapWidth:: ; d12f
 	ds $1
 
-wd130:: ; d130
+wBGMapHeight:: ; d130
 	ds $1
 
 wd131:: ; d131
@@ -2127,10 +2127,7 @@ wd239:: ; d239
 	ds $1
 
 wd23a:: ; d23a
-	ds $1
-
-wd23b:: ; d23b
-	ds $1
+	ds $2
 
 wd23c:: ; d23c
 	ds $1
@@ -2138,10 +2135,20 @@ wd23c:: ; d23c
 wd23d:: ; d23d
 	ds $1
 
+UNION
+
 ; palette loaded from Palette* data
 wLoadedPalData:: ; d23e
 	ds $50
 
+NEXTU
+
+; where BG map data is decompressed
+wBGMapBuffer:: ; d23e
+	ds $40
+
+ENDU
+
 wd28e:: ; d28e
 	ds $1
 
@@ -2154,7 +2161,10 @@ wd290:: ; d290
 wd291:: ; d291
 	ds $1
 
-wd292:: ; d292
+; determines where to copy BG Map data
+; $0 = copies to VRAM
+; $1 = copies to SRAM
+wBGMapCopyMode:: ; d292
 	ds $1
 
 	ds $4