From 18efb2fab3cec16c8f82ebec71b6c2201c349f1d Mon Sep 17 00:00:00 2001
From: mid-kid <esteve.varela@gmail.com>
Date: Fri, 24 Feb 2023 11:46:09 +0100
Subject: [PATCH] Document scripting engine fix for MBC30

---
 docs/design_flaws.md | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/docs/design_flaws.md b/docs/design_flaws.md
index 4904f5871..213c35ffc 100644
--- a/docs/design_flaws.md
+++ b/docs/design_flaws.md
@@ -14,6 +14,7 @@ These are parts of the code that do not work *incorrectly*, like [bugs and glitc
 - [The 6-bit caught level can only record up to level 63](#the-6-bit-caught-level-can-only-record-up-to-level-63)
 - [Identical sine wave code and data is repeated five times](#identical-sine-wave-code-and-data-is-repeated-five-times)
 - [`GetForestTreeFrame` works, but it's still bad](#getforesttreeframe-works-but-its-still-bad)
+- [The overworld scripting engine assumes no more than 127 banks](#the-overworld-scripting-engine-assumes-no-more-than-127-banks)
 
 
 ## Pic banks are offset by `PICS_FIX`
@@ -816,3 +817,36 @@ Edit `GetForestTreeFrame`:
 +	add a
  	ret
 ```
+
+
+## The overworld scripting engine assumes no more than 127 banks
+
+The `CallCallback` and `ExitScriptSubroutine` functions in [engine/overworld/scripting.asm](https://github.com/pret/pokecrystal/blob/master/engine/overworld/scripting.asm) use the highest bit of the bank value, to store whether a certain script stack position should be treated as a return from a callback. However, it seems it was opted to explicitly use the `endcallback` command for this purpose, instead.
+
+As such, this bit serves no purpose but to make map scripts living in the higher banks of mappers such as Japanese Crystal's MBC30 crash for weird reasons.
+
+**Fix:**
+
+Remove the bit mask for the bank value in `ExitScriptSubroutine`:
+
+```diff
+ ExitScriptSubroutine:
+ 	...
+ 	add hl, de
+ 	ld a, [hli]
+ 	ld b, a
+-	and $7f
+ 	ld [wScriptBank], a
+ 	ld a, [hli]
+ 	ld e, a
+```
+
+And in `CallCallback`:
+
+```diff
+ CallCallback::
+-	ld a, [wScriptBank]
+-	or $80
+-	ld [wScriptBank], a
+ 	jp ScriptCall
+```