From b1f1464f6fe8b21ae39a31c91e66c75a4e41a862 Mon Sep 17 00:00:00 2001
From: massimilianodelliubaldini
 <8584296+massimilianodelliubaldini@users.noreply.github.com>
Date: Tue, 30 Apr 2024 14:10:52 -0400
Subject: [PATCH] Jak 1: Fixed bug translating scout fly ID's.

---
 worlds/jakanddaxter/locs/ScoutLocations.py | 23 +++++++++++++++-------
 1 file changed, 16 insertions(+), 7 deletions(-)

diff --git a/worlds/jakanddaxter/locs/ScoutLocations.py b/worlds/jakanddaxter/locs/ScoutLocations.py
index 22587de2f7..c1349d0d63 100644
--- a/worlds/jakanddaxter/locs/ScoutLocations.py
+++ b/worlds/jakanddaxter/locs/ScoutLocations.py
@@ -14,6 +14,9 @@ from ..GameID import jak1_id
 # So we need to offset all of their ID's in order for Archipelago to separate them
 # from their power cells. We can use 1024 (2^10) for this purpose, because scout flies
 # only ever need 10 bits to identify themselves (3 for the index, 7 for the cell ID).
+
+# We're also going to compress the ID by bit-shifting the fly index down to lower bits,
+# keeping the scout fly ID range to a smaller set of numbers (1000 -> 2000, instead of 1 -> 400000).
 fly_offset = 1024
 
 
@@ -21,20 +24,26 @@ fly_offset = 1024
 # scout fly and translate its ID between AP and OpenGOAL.
 def to_ap_id(game_id: int) -> int:
     assert game_id < jak1_id, f"Attempted to convert {game_id} to an AP ID, but it already is one."
-    cell_id = get_cell_id(game_id)                         # This is AP/OpenGOAL agnostic, works on either ID.
-    buzzer_index = (game_id - cell_id) >> 9                # Subtract the cell ID, bit shift the index down 9 places.
-    return jak1_id + fly_offset + buzzer_index + cell_id   # Add the offsets, the bit-shifted index, and the cell ID.
+    cell_id = get_cell_id(game_id)                         # Get the power cell ID from the lowest 7 bits.
+    buzzer_index = (game_id - cell_id) >> 9                # Get the index, bit shift it down 9 places.
+    compressed_id = fly_offset + buzzer_index + cell_id    # Add the offset, the bit-shifted index, and the cell ID.
+    return jak1_id + compressed_id                         # Last thing: add the game's ID.
 
 
 def to_game_id(ap_id: int) -> int:
     assert ap_id >= jak1_id, f"Attempted to convert {ap_id} to a Jak 1 ID, but it already is one."
-    cell_id = get_cell_id(ap_id)                           # This is AP/OpenGOAL agnostic, works on either ID.
-    buzzer_index = ap_id - jak1_id - fly_offset - cell_id  # Reverse process, subtract the offsets and the cell ID.
-    return (buzzer_index << 9) + cell_id                   # Bit shift the index up 9 places, re-add the cell ID.
+    compressed_id = ap_id - jak1_id                        # Reverse process. First thing: subtract the game's ID.
+    cell_id = get_cell_id(compressed_id)                   # Get the power cell ID from the lowest 7 bits.
+    buzzer_index = compressed_id - fly_offset - cell_id    # Get the bit-shifted index.
+    return (buzzer_index << 9) + cell_id                   # Return the index to its normal place, re-add the cell ID.
 
 
+# Get the power cell ID from the lowest 7 bits.
+# Make sure to use this function ONLY when the input argument does NOT include jak1_id,
+# because that number may flip some of the bottom 7 bits, and that will throw off this bit mask.
 def get_cell_id(buzzer_id: int) -> int:
-    return buzzer_id & 0b1111111                           # Get the power cell ID from the lowest 7 bits.
+    assert buzzer_id < jak1_id, f"Attempted to bit mask {buzzer_id}, but it is polluted by the game's ID {jak1_id}."
+    return buzzer_id & 0b1111111
 
 
 # The ID's you see below correspond directly to that fly's 32-bit ID in the game.