FarString -> PlaceFarString, and document a BrokenPlaceFarString bug

docs/bugs_and_glitches.md

@@ -84,6 +84,7 @@ Fixes in the [multi-player battle engine](#multi-player-battle-engine) category
   - [Magikarp lengths can be miscalculated](#magikarp-lengths-can-be-miscalculated)
   - [`CheckOwnMon` only checks the first five letters of OT names](#checkownmon-only-checks-the-first-five-letters-of-ot-names)
   - [`CheckOwnMonAnywhere` does not check the Day-Care](#checkownmonanywhere-does-not-check-the-day-care)
+  - [The unused `phonecall` script command may crash](#the-unused-phonecall-script-command-may-crash)
 - [Internal engine routines](#internal-engine-routines)
   - [Saves corrupted by mid-save shutoff are not handled](#saves-corrupted-by-mid-save-shutoff-are-not-handled)
   - [`ScriptCall` can overflow `wScriptStack` and crash](#scriptcall-can-overflow-wscriptstack-and-crash)
@@ -2026,6 +2027,28 @@ This bug can prevent you from talking to Eusine in Celadon City or encountering
 ```
 
 
+### The unused `phonecall` script command may crash
+
+The `phonecall` script command calls the `PhoneCall` routine, which calls the `BrokenPlaceFarString` routine; this switches banks without being in bank 0, so it would start running arbitrary data as code.
+
+**Fix:** Edit `PhoneCall.CallerTextboxWithName` in [engine/phone/phone.asm](https://github.com/pret/pokecrystal/blob/master/engine/phone/phone.asm):
+
+```diff
+-	ld a, [wPhoneScriptBank]
+-	ld b, a
+ 	ld a, [wPhoneCaller]
+ 	ld e, a
+ 	ld a, [wPhoneCaller + 1]
+ 	ld d, a
+-	call BrokenPlaceFarString
++	ld a, [wPhoneScriptBank]
++	call PlaceFarString
+ 	ret
+```
+
+You can also delete the now-unused `BrokenPlaceFarString` routine.
+
+
 ## Internal engine routines
 
 

engine/phone/phone.asm

@@ -93,7 +93,8 @@ GetRemainingSpaceInPhoneList:
 
 INCLUDE "data/phone/permanent_numbers.asm"
 
-FarPlaceString:
+BrokenPlaceFarString:
+; This routine is not in bank 0 and will fail or crash if called.
 	ldh a, [hROMBank]
 	push af
 	ld a, b
@@ -455,14 +456,14 @@ RingTwice_StartCall:
 .Ring:
 	call Phone_StartRinging
 	call Phone_Wait20Frames
-	call Phone_CallerTextboxWithName
+	call .CallerTextboxWithName
 	call Phone_Wait20Frames
 	call Phone_CallerTextbox
 	call Phone_Wait20Frames
-	call Phone_CallerTextboxWithName
+	call .CallerTextboxWithName
 	ret
 
-Phone_CallerTextboxWithName:
+.CallerTextboxWithName:
 	ld a, [wCurCaller]
 	ld b, a
 	call Phone_TextboxWithName
@@ -475,22 +476,22 @@ PhoneCall::
 	ld [wPhoneCaller], a
 	ld a, d
 	ld [wPhoneCaller + 1], a
-	call Phone_FirstOfTwoRings
+	call .Ring
-	call Phone_FirstOfTwoRings
+	call .Ring
 	farcall StubbedTrainerRankings_PhoneCalls
 	ret
 
-Phone_FirstOfTwoRings:
+.Ring:
 	call Phone_StartRinging
 	call Phone_Wait20Frames
-	call Phone_CallerTextboxWithName2
+	call .CallerTextboxWithName
 	call Phone_Wait20Frames
 	call Phone_CallerTextbox
 	call Phone_Wait20Frames
-	call Phone_CallerTextboxWithName2
+	call .CallerTextboxWithName
 	ret
 
-Phone_CallerTextboxWithName2:
+.CallerTextboxWithName:
 	call Phone_CallerTextbox
 	hlcoord 1, 2
 	ld [hl], "☎"
@@ -502,7 +503,7 @@ Phone_CallerTextboxWithName2:
 	ld e, a
 	ld a, [wPhoneCaller + 1]
 	ld d, a
-	call FarPlaceString
+	call BrokenPlaceFarString
 	ret
 
 Phone_NoSignal:

engine/pokedex/pokedex_2.asm

@@ -86,7 +86,7 @@ DisplayDexEntry:
 	ld a, b
 	push af
 	hlcoord 9, 5
-	call FarString ; dex species
+	call PlaceFarString ; dex species
 	ld h, b
 	ld l, c
 	push de
@@ -182,7 +182,7 @@ DisplayDexEntry:
 	pop af
 	hlcoord 2, 11
 	push af
-	call FarString
+	call PlaceFarString
 	pop bc
 	ld a, [wPokedexStatus]
 	or a ; check for page 2
@@ -211,7 +211,7 @@ DisplayDexEntry:
 	inc de
 	pop af
 	hlcoord 2, 11
-	call FarString
+	call PlaceFarString
 	ret
 
 POKeString: ; unreferenced

engine/printer/print_party.asm

@@ -37,7 +37,7 @@ PrintPage1:
 	pop af
 	ld a, b
 	hlcoord 1, 11, wPrinterTilemapBuffer
-	call nz, FarString
+	call nz, PlaceFarString
 	hlcoord 19, 0, wPrinterTilemapBuffer
 	ld [hl], $35
 	ld de, SCREEN_WIDTH
@@ -86,7 +86,7 @@ PrintPage2:
 	pop af
 	hlcoord 1, 1, wPrinterTilemapBuffer
 	ld a, b
-	call nz, FarString
+	call nz, PlaceFarString
 	ret
 
 .FillColumn:

engine/printer/printer.asm

@@ -567,7 +567,7 @@ PlacePrinterStatusString:
 	ld d, [hl]
 	hlcoord 1, 7
 	ld a, BANK(GBPrinterStrings)
-	call FarString
+	call PlaceFarString
 	hlcoord 2, 15
 	ld de, String_PressBToCancel
 	call PlaceString
@@ -600,7 +600,7 @@ PlacePrinterStatusStringBorderless: ; unreferenced
 	ld d, [hl]
 	hlcoord 4, 7
 	ld a, BANK(GBPrinterStrings)
-	call FarString
+	call PlaceFarString
 	hlcoord 4, 15
 	ld de, String_PressBToCancel
 	call PlaceString

home/text.asm

@@ -640,7 +640,7 @@ UnloadBlinkingCursor::
 	ldcoord_a 18, 17
 	ret
 
-FarString::
+PlaceFarString::
 	ld b, a
 	ldh a, [hROMBank]
 	push af