Explain pack.asm changes

1 files changed, 18 insertions, 12 deletions

diff --git a/Add-a-new-Pack-pocket.md b/Add-a-new-Pack-pocket.md
index 6a655e5..5417b03 100644
--- a/Add-a-new-Pack-pocket.md
+++ b/Add-a-new-Pack-pocket.md
@@ -380,7 +380,7 @@ In most of these cases we just based the Berry pocket case on the Ball pocket ca
 
 ## 9. Update the Pack engine
 
-We've saved editing the longest file for last: [engine/items/pack.asm](../blob/master/engine/items/pack.asm). Let's go over it piece by piece.
+We've saved editing the longest file for last: [engine/items/pack.asm](../blob/master/engine/items/pack.asm). Let's go over it piece by piece. (Don't worry, a lot of it is just copy+pasting chunks of code with the word "Berry" substituted for "Ball" or "Item".)
 
 ```diff
  ; Pack.Jumptable and BattlePack.Jumptable indexes
@@ -400,7 +400,9 @@ We've saved editing the longest file for last: [engine/items/pack.asm](../blob/m
  	const PACKSTATE_QUITRUNSCRIPT      ; 10
 ```
 
-TODO: Explain.
+These are jumptable indexes. Jumptables are a common design pattern you'll see for interfaces with a lot of different states and transitions between states, like the Pokédex and Pokégear. In general, there's a table of pointers corresponding to these index constants, and each pointer is to a different subroutine. Control jumps to whichever pointer corresponds to the value in `wJumptableIndex`, which usually starts at 0. Each subroutine can change `wJumptableIndex`, often by incrementing it to automatically reach the next state in the table, or by setting particular values depending on which buttons are pressed.
+
+Notice the pattern to this table: for each pocket, there's a `PACKSTATE_INIT*POCKET` state followed by a `PACKSTATE_*POCKETMENU` state. They happen to be in the same order as the `*_POCKET` constants, although that isn't actually significant; all that matters is that the default pocket be the first one (since the `PACKSTATE_INITGFX` state increments `wJumptableIndex` and advances to the next state, which should thus be the default pocket's `INIT` state).
 
 ```diff
  Pack: ; 10000
@@ -423,7 +425,7 @@ TODO: Explain.
  	dw Pack_QuitRunScript  ; 10
 ```
 
-TODO: Explain.
+Here's the first jumptable corresponding to those constants. It's the "core" jumptable for when you enter the Pack via the Start Menu.
 
 ```diff
  .KeyItemsPocketMenu: ; 100a6 (4:40a6)
@@ -496,7 +498,11 @@ TODO: Explain.
 +	ret
 ```
 
-TODO: Explain.
+We're doing two things here.
+
+One, we insert the Berry pocket in-between the Ball and Key Item pockets. Originally you can scroll left and right through the pockets in order: Items ↔ Balls ↔ Key Items ↔ TM/HM ↔ Items again. This is done by explicitly hard-coding each pocket's left and right ones. So the Berry pocket just had to be coded in.
+
+Two, we actually write the subroutines that we just added pointers to in the jumptable. Really they're just copy+pasted from the Ball pocket's subroutines, but with "Berry" substituted for "Ball". (As we discussed earlier, the Ball pocket is safe to use as a base, since it stores regular items and isn't a default like the Items pocket.)
 
 ```diff
  BattlePack: ; 10493
@@ -519,7 +525,7 @@ TODO: Explain.
  	dw Pack_QuitRunScript  ; 10
 ```
 
-TODO: Explain.
+This is another jumptable, but for using the Pack during battle. Again, we add pointers for the Berry pocket, and will next have to define them.
 
 ```diff
  .KeyItemsPocketMenu: ; 10539 (4:4539)
@@ -592,7 +598,7 @@ TODO: Explain.
 +	ret
 ```
 
-TODO: Explain.
+Just like before, we insert the Berry pocket between the Ball and Key Item pockets, and base the Berry pocket's subroutines on the pre-existing Ball pocket ones.
 
 ```diff
  DepositSellPack: ; 106be
@@ -641,7 +647,7 @@ TODO: Explain.
 +	ret
 ```
 
-TODO: Explain.
+Here's a jumptable for when the Pack is opened to deposit or sell an item; it has entries for each individual pocket, less complicated than the previous jumptables with their intermediate `INIT` states. As usual, we just look at how the other pockets work and do what they do but with the word "Berry" in the right places.
 
 ```diff
  .d_left
@@ -677,7 +683,7 @@ TODO: Explain.
  	ret
 ```
 
-TODO: Explain.
+This is somewhat tricky to notice. Here the code is decrementing or incrementing `wJumptableIndex` (that is, subtracting or adding 1) when you press Left or Right. But doing that can go beyond the valid range, since it might decrement the minimum or increment the maximum. When there were only four pockets, they neatly took up two bits, so a bitmask could be used to efficiently clamp them within the valid range. But five pockets requires more explicit checks so that the minimum and maximum values (0 and `NUM_POCKETS` − 1) wrap around.
 
 ```diff
  TutorialPack: ; 107bb
@@ -738,7 +744,7 @@ TODO: Explain.
 +	dba UpdateItemDescription
 ```
 
-TODO: Explain.
+Another jumptable, this time used by the catch tutorial dude. Once again, we just add an entry to the jumptable for the Berry pocket and base its code and data on whatever the Ball pocket does.
 
 ```diff
  PackGFXPointers: ; 108cc
@@ -750,7 +756,7 @@ TODO: Explain.
  ; 108d4
 ```
 
-TODO: Explain.
+This is a table of pointers to the individual highlighted pocket pictures in pack.png and pack_f.png. Remember how they were out of order compared to the constants? That's why this table is necessary. For example, the first (#0) picture was of the Key Item pocket, and `KEY_ITEM_POCKET` is 2, so the third (#2) entry here points to the first picture. Anyway, all we have to do is add a pointer for the Berry pocket again.
 
 ```diff
  .tilemap ; 109e1
@@ -777,7 +783,7 @@ TODO: Explain.
  ; 10a1d
 ```
 
-TODO: Explain.
+These are tilemaps for the pocket name labels in pack_menu.png. Each one is three rows of five tiles each, with tile indexes starting at 0. Take a look at pack_menu.png and notice how the hexadecimal indexes here correspond to tiles that form sensible pictures.
 
 ```diff
  BallsPocketMenuHeader: ; 0x10aaf
@@ -845,7 +851,7 @@ TODO: Explain.
 +	dba UpdateItemDescription
 ```
 
-TODO: Explain.
+We saw `BallsPocketMenuHeader` used in the subroutines for the Start Menu Pack and the battle Pack, and `PC_Mart_BallsPocketMenuHeader` in the subroutine for the Pack when depositing or selling. Here they're finally being defined. And since we created the corresponding names `BerryPocketMenuHeader` and `PC_Mart_BerryPocketMenuHeader`, they need defining too; as usual, we can just copy whatever the Ball pocket does and substitute "Berry" for "Ball".
 
 
 ## 10. Update the Crystal-only Pack engine