Document some text engine functions

11 files changed, 137 insertions, 92 deletions

diff --git a/src/constants/text_constants.asm b/src/constants/text_constants.asm
index b5e6e22..70e0ab7 100644
--- a/src/constants/text_constants.asm
+++ b/src/constants/text_constants.asm
@@ -15,6 +15,10 @@ done EQUS "db TX_END"
 	charmap "♀", "%"
 	charmap "”", "\""
 
+; wFontWidth constants
+FULL_WIDTH EQU $0
+HALF_WIDTH EQU $1 ; non-0
+
 ; TX_SYMBOL (full-tile icons/symbols loaded at the beginning of v0Tiles2)
 ; TODO: Use symbols in menus (cursor tile number, tile behind cursor), draw text boxes, WriteByteToBGMap0, etc
 ;       If user-defined functions ever become a thing a symbol(*) syntax would probably be preferred over SYM_*
diff --git a/src/engine/bank01.asm b/src/engine/bank01.asm
index d08d128..a67d672 100644
--- a/src/engine/bank01.asm
+++ b/src/engine/bank01.asm
@@ -45,7 +45,7 @@ Func_405a: ; 405a (1:405a)
 	xor a
 	ld [wTileMapFill], a
 	call DisableLCD
-	call LoadDuelHUDTiles
+	call LoadSymbolsFont
 	call SetDefaultPalettes
 	ld de, $387f
 	call Func_2275
@@ -281,7 +281,7 @@ Func_420b: ; 420b (1:420b)
 	ld [wTileMapFill], a
 	call ZeroObjectPositionsAndToggleOAMCopy
 	call EmptyScreen
-	call LoadDuelHUDTiles
+	call LoadSymbolsFont
 	call SetDefaultPalettes
 	ld de, $389f
 	call Func_2275
@@ -1558,7 +1558,7 @@ Func_49ed: ; 49ed (1:49ed)
 	INCROM $4a35, $4a97
 
 Func_4a97: ; 4a97 (1:4a97)
-	call LoadDuelHUDTiles
+	call LoadSymbolsFont
 	ld de, wDefaultText
 	push de
 	call CopyPlayerName
@@ -2003,7 +2003,7 @@ DrawDuelMainScene: ; 4f9d (1:4f9d)
 	ret z
 	call ZeroObjectPositionsAndToggleOAMCopy
 	call EmptyScreen
-	call LoadDuelHUDTiles
+	call LoadSymbolsFont
 	ld a, $01
 	ld [wcac2], a
 	ld a, DUELVARS_ARENA_CARD
@@ -2507,7 +2507,7 @@ DrawCardListScreenLayout: ; 559a (1:559a)
 .draw
 	call ZeroObjectPositionsAndToggleOAMCopy
 	call EmptyScreen
-	call LoadDuelHUDTiles
+	call LoadSymbolsFont
 	call LoadDuelCardSymbolTiles
 	; draw the surrounding box
 	lb de, 0, 0
@@ -3311,7 +3311,7 @@ _DisplayCardDetailScreen: ; 5e5f (1:5e5f)
 DrawLargePictureOfCard: ; 5e75 (1:5e75)
 	call ZeroObjectPositionsAndToggleOAMCopy
 	call EmptyScreen
-	call LoadDuelHUDTiles
+	call LoadSymbolsFont
 	call SetDefaultPalettes
 	ld a, $08
 	ld [wcac2], a
diff --git a/src/engine/bank02.asm b/src/engine/bank02.asm
index 87810fa..ffcc1d8 100644
--- a/src/engine/bank02.asm
+++ b/src/engine/bank02.asm
@@ -46,7 +46,7 @@ Func_8d56: ; 8d56 (2:4d56)
 	call ZeroObjectPositions
 	ld a, $1
 	ld [wVBlankOAMCopyToggle], a
-	call LoadDuelHUDTiles
+	call LoadSymbolsFont
 	call LoadDuelCardSymbolTiles
 	call Func_8d0b
 	bank1call SetDefaultPalettes
diff --git a/src/engine/bank03.asm b/src/engine/bank03.asm
index 865cc5b..b44d07a 100644
--- a/src/engine/bank03.asm
+++ b/src/engine/bank03.asm
@@ -14,7 +14,7 @@ LoadMap: ; c000 (3:4000)
 	call ZeroObjectPositions
 	xor a
 	ld [wTileMapFill], a
-	call LoadDuelHUDTiles
+	call LoadSymbolsFont
 	call Set_OBJ_8x8
 	xor a
 	ld [wLineSeparation], a
diff --git a/src/engine/bank04.asm b/src/engine/bank04.asm
index 215132c..256a2f6 100644
--- a/src/engine/bank04.asm
+++ b/src/engine/bank04.asm
@@ -2,7 +2,7 @@ Func_10000: ; 10000 (4:4000)
 	ld a, $0
 	ld [wTileMapFill], a
 	call EmptyScreen
-	call LoadDuelHUDTiles
+	call LoadSymbolsFont
 	ld de, $307f
 	call Func_2275
 	call Set_OBJ_8x8
diff --git a/src/engine/home.asm b/src/engine/home.asm
index ab209eb..cc00b7d 100644
--- a/src/engine/home.asm
+++ b/src/engine/home.asm
@@ -5941,10 +5941,10 @@ LoadDuelCoinTossResultTiles: ; 210f (0:210f)
 	ld b, $8
 	jr CopyFontsOrDuelGraphicsTiles
 
-LoadDuelHUDTiles: ; 2119 (0:2119)
-	ld hl, DuelHUDGraphics - $4000
+LoadSymbolsFont: ; 2119 (0:2119)
+	ld hl, SymbolsFont - $4000
 	ld de, v0Tiles2 ; destination
-	ld b, (DuelCardHeaderGraphics - DuelHUDGraphics) / TILE_SIZE ; number of tiles
+	ld b, (DuelCardHeaderGraphics - SymbolsFont) / TILE_SIZE ; number of tiles
 ;	fallthrough
 
 ; if hl ≤ $3fff
@@ -5960,9 +5960,9 @@ CopyFontsOrDuelGraphicsTiles: ; 2121 (0:2121)
 	ret
 ; 0x212f
 
-; this function appears to copy duel gfx data into sram
+; this function appears to copy gfx data into sram
 Func_212f: ; 212f (0:212f)
-	ld hl, DuelHUDGraphics - $4000
+	ld hl, SymbolsFont - $4000
 	ld de, $a400
 	ld b, $30
 	call CopyFontsOrDuelGraphicsTiles
@@ -5998,7 +5998,7 @@ DrawDuelBoxMessage: ; 2167 (0:2167)
 	; hl = a * $280
 	ld de, DuelBoxMessages
 	add hl, de
-	ld de, v0Tiles1 + $200
+	ld de, v0Tiles1 + $20 tiles
 	ld b, $28
 	call CopyFontsOrDuelGraphicsTiles
 	ld a, $a0
@@ -6059,12 +6059,12 @@ Func_21f2: ; 21f2 (0:21f2)
 	scf
 	ret
 .asm_220f
-	ld a, $1
+	ld a, HALF_WIDTH
 	ld [wFontWidth], a
 	ret
 .asm_2215
 	call Func_230f
-	xor a
+	xor a ; FULL_WIDTH
 	ld [wFontWidth], a
 	ld a, $f
 	ldh [hffaf], a
@@ -6076,7 +6076,7 @@ Func_21f2: ; 21f2 (0:21f2)
 .asm_2225
 	ld a, [wFontWidth]
 	push af
-	ld a, $1
+	ld a, HALF_WIDTH
 	ld [wFontWidth], a
 	call Func_230f
 	pop af
@@ -6148,12 +6148,12 @@ Func_2275: ; 2275 (0:2275)
 	jr nz, .asm_2292
 	ret
 
-; wFontWidth <- 0
+; wFontWidth <- FULL_WIDTH
 ; hTextLineCurPos <- 0
 ; wcd0b <- 0
 ; hffaf <- $f
 Func_2298: ; 2298 (0:2298)
-	xor a
+	xor a ; FULL_WIDTH
 	ld [wFontWidth], a
 	ldh [hTextLineCurPos], a
 	ld [wcd0b], a
@@ -6246,7 +6246,7 @@ PlaceNextTextTile: ; 22f2 (0:22f2)
 
 Func_230f: ; 230f (0:230f)
 	ld a, [wFontWidth]
-	or a
+	or a ; FULL_WIDTH
 	ret z
 	ld a, [wcd0b]
 	or a
@@ -6254,7 +6254,7 @@ Func_230f: ; 230f (0:230f)
 	push hl
 	push de
 	push bc
-	ld e, $20
+	ld e, " "
 	call Func_22ca
 	pop bc
 	pop de
@@ -6311,7 +6311,7 @@ Func_2325: ; 2325 (0:2325)
 Func_235e: ; 235e (0:235e)
 	ld a, [wFontWidth]
 	or a                 ;
-	jr z, .asm_2376      ; if [wFontWidth] nonzero:
+	jr z, .asm_2376      ; if [wFontWidth] == HALF_WIDTH:
 	                     ;   uppercase e if wUppercaseHalfWidthLetters != 0
 	call CaseHalfWidthLetter
 	ld a, [wcd0b]
@@ -6396,7 +6396,7 @@ Func_23c1: ; 23c1 (0:23c1)
 	sub b
 	ret
 .asm_23cf
-	xor a
+	xor a ; FULL_WIDTH
 	ld [wFontWidth], a
 Func_23d3: ; 23d3 (0:23d3)
 	push hl
@@ -6493,9 +6493,9 @@ TwoByteNumberToTxSymbol_TrimLeadingZeros: ; 245d (0:245d)
 	ret
 
 ; generates a text tile and copies it to VRAM
-; if wFontWidth == 0
+; if wFontWidth == FULL_WIDTH
 	; de = full-width font tile number (d = $e and d = $f are treated differently)
-; if wFontWidth != 0
+; if wFontWidth == HALF_WIDTH
 	; d = half-width character 1 (left)
 	; e = half-width character 2 (right)
 ; b = destination VRAM tile number
@@ -6630,7 +6630,7 @@ CreateFullWidthFontTile: ; 252e (0:252e)
 
 Func_2546: ; 2546 (0:2546)
 	ld a, [wFontWidth]
-	or a
+	or a ; FULL_WIDTH
 	jr nz, .asm_255f
 	ld a, e
 	cp $10
@@ -7829,7 +7829,7 @@ Func_2c37: ; 2c37 (0:2c37)
 
 Func_2c62: ; 2c62 (0:2c62)
 	call .asm_2c67
-	jr Func_2c77
+	jr WaitForPlayerToAdvanceText
 .asm_2c67
 	push hl
 	ld hl, wTextBoxLabel
@@ -7844,7 +7844,9 @@ Func_2c73: ; 2c73 (0:2c73)
 	xor a
 	call Func_2c84
 
-Func_2c77: ; 2c77 (0:2c77)
+; when a text box is full, prompt the player to press A or B
+; in order to clear the text and print the next lines.
+WaitForPlayerToAdvanceText: ; 2c77 (0:2c77)
 	lb bc, SYM_CURSOR_D, SYM_BOX_BOTTOM ; cursor tile, tile behind cursor
 	lb de, 18, 17 ; x, y
 	call SetCursorParametersForTextBox
@@ -7857,50 +7859,58 @@ Func_2c84: ; 2c84 (0:2c84)
 	push af
 	call GetTextOffsetFromTextID
 	call Func_2d15
-	call Func_2cc8
-.asm_2c93
+	call InitRegistersForPrintingText
+.print_char_loop
 	ld a, [wTextSpeed]
 	ld c, a
 	inc c
 	jr .asm_2cac
-.asm_2c9a
+.nonzero_text_speed
 	ld a, [wTextSpeed]
-	cp $2
-	jr nc, .asm_2ca7
+	cp 2
+	jr nc, .apply_delay
+	; if text speed is 1, pressing b ignores it
 	ldh a, [hButtonsHeld]
 	and B_BUTTON
-	jr nz, .asm_2caf
-.asm_2ca7
+	jr nz, .skip_delay
+.apply_delay
 	push bc
 	call DoFrame
 	pop bc
 .asm_2cac
 	dec c
-	jr nz, .asm_2c9a
-.asm_2caf
+	jr nz, .nonzero_text_speed
+.skip_delay
 	call Func_2d43
 	jr c, .asm_2cc3
 	ld a, [wCurTextLine]
 	cp 3
-	jr c, .asm_2c93
-	call Func_2c77
+	jr c, .print_char_loop
+	; two lines of text already printed, so need to advance text
+	call WaitForPlayerToAdvanceText
 	call Func_2d15
-	jr .asm_2c93
+	jr .print_char_loop
 .asm_2cc3
 	pop af
 	call BankswitchHome
 	ret
 
-Func_2cc8: ; 2cc8 (0:2cc8)
+; zero wWhichTextStruct, wWhichTxRam2 and wWhichTxRam3, and set hffaf to $f
+; fill wTextStruct1 with $f, wFontWidth, hBankROM, and register bc for the text's pointer.
+InitRegistersForPrintingText: ; 2cc8 (0:2cc8)
 	xor a
-	ld [wce48], a
-	ld [wce49], a
-	ld [wce4a], a
+	ld [wWhichTextStruct], a
+	ld [wWhichTxRam2], a
+	ld [wWhichTxRam3], a
 	ld a, $f
 	ld [hffaf], a
-Func_2cd7: ; 2cd7 (0:2cd7)
+;	fallthrough
+
+; fill the wTextStruct specified in wWhichTextStruct (0-3) with hffaf,
+; wFontWidth, hBankROM, and register bc for the text's pointer.
+WriteToTextStruct: ; 2cd7 (0:2cd7)
 	push hl
-	call Func_2d06
+	call GetPointerToTextStruct
 	pop bc
 	ld a, [hffaf]
 	ld [hli], a
@@ -7913,14 +7923,20 @@ Func_2cd7: ; 2cd7 (0:2cd7)
 	ld [hl], b
 	ret
 
-Func_2ceb: ; 2ceb (0:2ceb)
-	call Func_2cd7
-	ld hl, wce48
+; same as WriteToTextStruct, except it then increases wWhichTextStruct to
+; set the following text struct to the current one (usually, because
+; it will soon be written to due to a TX_RAM command).
+WriteToTextStruct_MoveToNext: ; 2ceb (0:2ceb)
+	call WriteToTextStruct
+	ld hl, wWhichTextStruct
 	inc [hl]
 	ret
 
-Func_2cf3: ; 2cf3 (0:2cf3)
-	call Func_2d06
+; read the wTextStruct specified in wWhichTextStruct (0-3) and use the data to
+; populate the corresponding memory addresses. also switch to the text's rombank
+; and return the address of the next character in hl.
+ReadTextStruct: ; 2cf3 (0:2cf3)
+	call GetPointerToTextStruct
 	ld a, [hli]
 	ld [hffaf], a
 	ld a, [hli]
@@ -7932,15 +7948,16 @@ Func_2cf3: ; 2cf3 (0:2cf3)
 	ld l, a
 	ret
 
-Func_2d06: ; 2d06 (0:2d06)
-	ld a, [wce48]
+; return in hl, the address of the wTextStruct specified in wWhichTextStruct (0-3)
+GetPointerToTextStruct: ; 2d06 (0:2d06)
+	ld a, [wWhichTextStruct]
 	ld e, a
 	add a
 	add a
 	add e
 	ld e, a
 	ld d, $0
-	ld hl, wce2b
+	ld hl, wTextStruct1
 	add hl, de
 	ret
 
@@ -7970,7 +7987,7 @@ Func_2d15: ; 2d15 (0:2d15)
 	ret
 
 Func_2d43: ; 2d43 (0:2d43)
-	call Func_2cf3
+	call ReadTextStruct
 	ld a, [hli]
 	or a ; TX_END
 	jr z, .asm_2d79
@@ -7998,49 +8015,49 @@ Func_2d43: ; 2d43 (0:2d43)
 	xor a
 	call Func_21f2
 .asm_2d74
-	call Func_2cd7
+	call WriteToTextStruct
 	or a
 	ret
 .asm_2d79
-	ld a, [wce48]
+	ld a, [wWhichTextStruct]
 	or a
 	jr z, .asm_2d85
 	dec a
-	ld [wce48], a
+	ld [wWhichTextStruct], a
 	jr Func_2d43
 .asm_2d85
 	call Func_230f
 	scf
 	ret
 .tx_ram2
-	call Func_2ceb
+	call WriteToTextStruct_MoveToNext
 	ld a, $f
 	ld [hffaf], a
-	xor a
+	xor a ; FULL_WIDTH
 	ld [wFontWidth], a
 	ld de, wTxRam2
-	ld hl, wce49
-	call Func_2de0
+	ld hl, wWhichTxRam2
+	call HandleTxRam2Or3
 	ld a, l
 	or h
 	jr z, .asm_2dab
 	call GetTextOffsetFromTextID
-	call Func_2cd7
+	call WriteToTextStruct
 	jr Func_2d43
 .asm_2dab
 	ld hl, wDefaultText
-	call Func_2cd7
+	call WriteToTextStruct
 	jr Func_2d43
 .tx_ram3
-	call Func_2ceb
+	call WriteToTextStruct_MoveToNext
 	ld de, wTxRam3
-	ld hl, wce4a
-	call Func_2de0
+	ld hl, wWhichTxRam3
+	call HandleTxRam2Or3
 	call TwoByteNumberToText_CountLeadingZeros
-	call Func_2cd7
+	call WriteToTextStruct
 	jp Func_2d43
 .tx_ram1
-	call Func_2ceb
+	call WriteToTextStruct_MoveToNext
 	call CopyTurnDuelistName
 	ld a, [wcaa0]
 	cp $6
@@ -8048,12 +8065,15 @@ Func_2d43: ; 2d43 (0:2d43)
 	ld a, $7
 	call Func_21f2
 .asm_2dda
-	call Func_2cd7
+	call WriteToTextStruct
 	jp Func_2d43
 
-; inc [hl]
-; hl = [de + 2*[hl]]
-Func_2de0: ; 2de0 (0:2de0)
+; input:
+  ; de: wTxRam2 or wTxRam3
+  ; hl: wWhichTxRam2 or wWhichTxRam3
+; return, in hl, the contents of the contents of the
+; wTxRam* buffer's current entry, and increment wWhichTxRam*.
+HandleTxRam2Or3: ; 2de0 (0:2de0)
 	push de
 	ld a, [hl]
 	inc [hl]
@@ -8097,15 +8117,15 @@ GetTextOffsetFromTextID: ; 2ded (0:2ded)
 	pop de
 	ret
 
-; if [wFontWidth] != 0:
+; if [wFontWidth] == HALF_WIDTH:
 ;   convert the number at hl to text (ascii) format and write it to wcaa0
 ;   return c = 4 - leading_zeros
-; if [wFontWidth] == 0:
+; if [wFontWidth] == FULL_WIDTH:
 ;   convert the number at hl to TX_SYMBOL text format and write it to wcaa0
 ;   replace leading zeros with SYM_SPACE
 TwoByteNumberToText_CountLeadingZeros: ; 2e12 (0:2e12)
 	ld a, [wFontWidth]
-	or a
+	or a ; FULL_WIDTH
 	jp z, TwoByteNumberToTxSymbol_TrimLeadingZeros
 	ld de, wcaa0
 	push de
@@ -8151,7 +8171,7 @@ PrintText: ; 2e41 (0:2e41)
 .from_ram
 	ld hl, wDefaultText
 .print_text
-	call Func_2cc8
+	call InitRegistersForPrintingText
 .next_tile_loop
 	ldh a, [hButtonsHeld]
 	ld b, a
@@ -8179,7 +8199,7 @@ PrintTextNoDelay: ; 2e76 (0:2e76)
 	ldh a, [hBankROM]
 	push af
 	call GetTextOffsetFromTextID
-	call Func_2cc8
+	call InitRegistersForPrintingText
 .next_tile_loop
 	call Func_2d43
 	jr nc, .next_tile_loop
diff --git a/src/gfx.asm b/src/gfx.asm
index bee55be..f26662c 100644
--- a/src/gfx.asm
+++ b/src/gfx.asm
@@ -8,10 +8,10 @@ INCBIN "gfx/fonts/full_width.t3.1bpp"
 HalfWidthFont:: ; 76668 (1d:6668)
 INCBIN "gfx/fonts/half_width.1bpp"
 
-DuelGraphics::
+SymbolsFont:: ; 76968 (1d:6968)
+INCBIN "gfx/fonts/symbols.2bpp"
 
-DuelHUDGraphics:: ; 76968 (1d:6968)
-INCBIN "gfx/duel/hud.2bpp"
+DuelGraphics::
 
 DuelCardHeaderGraphics:: ; 76ce8 (1d:6ce8)
 INCBIN "gfx/duel/card_headers.2bpp"
diff --git a/src/gfx/duel/hud.png b/src/gfx/fonts/symbols.png
index 81afc3b..81afc3b 100644
--- a/src/gfx/duel/hud.png
+++ b/src/gfx/fonts/symbols.png
diff --git a/src/macros/wram.asm b/src/macros/wram.asm
index cedb0dd..a904d87 100644
--- a/src/macros/wram.asm
+++ b/src/macros/wram.asm
@@ -39,6 +39,13 @@ move_data_struct: MACRO
 \1Animation::      ds 1
 ENDM
 
+text_struct: MACRO
+\1Unknown::   ds 1
+\1FontWidth:: ds 1
+\1Address::   ds 2
+\1RomBank::   ds 1
+ENDM
+
 ; TODO: Figure out what the rest are for
 sprite_anim_struct: MACRO
 \1Field0x00::  ds 1
diff --git a/src/text/text3.asm b/src/text/text3.asm
index 3231b66..0617435 100644
--- a/src/text/text3.asm
+++ b/src/text/text3.asm
@@ -1201,7 +1201,7 @@ Text035b: ; 3eb62 (f:6b62)
 	done
 
 Text035c: ; 3eb88 (f:6b88)
-	db "ppppp"
+	db $70,$70,$70,$70,$70
 	done
 
 Text035d: ; 3eb8e (f:6b8e)
@@ -1587,7 +1587,7 @@ Text03a6: ; 3f631 (f:7631)
 	done
 
 Text03a7: ; 3f643 (f:7643)
-	db TX_END
+	done
 
 Text03a8: ; 3f644 (f:7644)
 	text "COLOSSEUM"
diff --git a/src/wram.asm b/src/wram.asm
index 330a9ed..0691a19 100644
--- a/src/wram.asm
+++ b/src/wram.asm
@@ -1094,10 +1094,17 @@ wce22:: ; ce22
 wCardPalette:: ; ce23
 	ds CGB_PAL_SIZE
 
-wce2b:: ; ce2b
-	ds $1
-
-	ds $13
+; information about the text being currently processed, like the font width
+; the rom bank, and the memory address of the next character to be printed.
+; supports up to four nested texts (used with TX_RAM).
+wTextStruct1:: ; ce2b
+	text_struct wTextStruct1
+wTextStruct2:: ; ce30
+	text_struct wTextStruct2
+wTextStruct3:: ; ce35
+	text_struct wTextStruct3
+wTextStruct4:: ; ce3a
+	text_struct wTextStruct4
 
 ; text id for the first TX_RAM2 of a text
 ; prints from wDefaultText if $0000
@@ -1108,23 +1115,30 @@ wTxRam2:: ; cd3f
 wTxRam2_b:: ; ce41
 	ds $2
 
-; a number between 0 and 65535 for TX_RAM3
+; text id for the first TX_RAM3 of a text
+; a number between 0 and 65535
 wTxRam3:: ; ce43
 	ds $2
 
+; text id for the second TX_RAM3 of a text
+; a number between 0 and 65535
+wTxRam3_b:: ; ce45
 	ds $2
 
 ; when printing text, number of frames to wait between each text tile
 wTextSpeed:: ; ce47
 	ds $1
 
-wce48:: ; ce48
+; a number between 0 and 3 to select a wTextStruct to use for the current text
+wWhichTextStruct:: ; ce48
 	ds $1
 
-wce49:: ; ce49
+; selects wTxRam2 or wTxRam2_b
+wWhichTxRam2:: ; ce49
 	ds $1
 
-wce4a:: ; ce4a
+; selects wTxRam3 or wTxRam3_b
+wWhichTxRam3:: ; ce4a
 	ds $1
 
 wIsTextBoxLabeled:: ; ce4b