From 126c3f33666f20a585d4d271a20a1e7270882de9 Mon Sep 17 00:00:00 2001
From: Narishma-gb <194818981+Narishma-gb@users.noreply.github.com>
Date: Sun, 17 Aug 2025 16:00:34 +0200
Subject: Document a bug in `PrintBenchGuyText` (#523)

---
 engine/events/hidden_objects/bench_guys.asm | 9 +++++++++
 1 file changed, 9 insertions(+)

(limited to 'engine')

diff --git a/engine/events/hidden_objects/bench_guys.asm b/engine/events/hidden_objects/bench_guys.asm
index 55090c01..e5a2a724 100644
--- a/engine/events/hidden_objects/bench_guys.asm
+++ b/engine/events/hidden_objects/bench_guys.asm
@@ -17,6 +17,15 @@ PrintBenchGuyText:
 	ld b, a
 	ld a, [wSpritePlayerStateData1FacingDirection]
 	cp b
+
+	; bug: an 'inc hl' instruction is needed before looping back. When trying to
+	; talk to a bench guy from above, this Sprite Facing test will fail, and the
+	; next loop iteration will be misaligned within BenchGuyTextPointers table.
+	; As a result, the routine will miss the terminator byte, and continue to
+	; process data beyond the table boundary.
+	; It seems that it will only return after starting to read data from VRAM
+	; (According to Pan Docs, during PPU mode 3, reads return garbage value,
+	; usually $FF).
 	jr nz, .loop ; player isn't facing the bench guy
 	ld a, [hl]
 	jp PrintPredefTextID
-- 
cgit v1.3.1-sl0p