Document unresolved conflicts in sprite loading integration and outline future work for dynamic sprite sets in ZSCustomOverworld.

Docs/Core/SystemInteractions.md

@@ -129,12 +129,11 @@ With ZSOW v3, the vanilla sprite loading hook (`Overworld_LoadSprites` at `$09C4
 
 ### Conclusion & Solution
 
-This conflict is **ongoing**. An attempted solution to integrate the `CheckIfNight` logic directly into ZSOW's sprite loading routine caused a regression, resulting in a `BRK` after returning from `LoadOverworldSprites_Interupt`.
+This is an **unresolved conflict**. The original day/night sprite logic is not being called by ZSOW's custom sprite loading routine, preventing day/night-specific sprites from appearing.
 
-**Attempted Solution (Caused Regression):**
-1.  **Modified `LoadOverworldSprites_Interupt`:** In `ZSCustomOverworld.asm`, a `JSL CheckIfNight` call was inserted at the beginning of this routine. `CheckIfNight` returns a potentially modified game state (e.g., `GameState + 1` for night) in the accumulator.
-2.  **Adjusted Game State Usage:** The `LoadOverworldSprites_Interupt` routine then attempted to use this adjusted game state to look up the appropriate sprite set in ZSOW's `.Overworld_SpritePointers_state_..._New` tables.
-3.  **`CheckIfNight` and `CheckIfNight16Bit`:** These routines in `Overworld/time_system.asm` were uncommented and available. `CheckIfNight16Bit` is already integrated into ZSOW's `Sprite_LoadGfxProperties_Interupt` (`$00FC67`), ensuring sprite graphics properties are also adjusted for day/night.
-
-**Impact of Regression:** The game crashes with a `BRK` after `LoadOverworldSprites_Interupt` returns, indicating an issue with the state or stack after the `CheckIfNight` call. This solution is currently not viable. Further investigation is required to correctly integrate day/night sprite loading with ZSOW v3 without causing crashes.
+**Status:**
+- An initial attempt was made to integrate the `CheckIfNight` logic into ZSOW's `LoadOverworldSprites_Interupt` routine.
+- This attempt introduced severe regressions, including game crashes (`BRK`) and build failures.
+- The changes have been **reverted** to restore stability.
+- As a result, the conflict remains, and a new solution is needed to make the two systems compatible.
 

Docs/GEMINI.md

@@ -94,6 +94,13 @@ The 65816 is an 8/16-bit microprocessor used in the Super Nintendo Entertainment
 
 - When hooking or modifying vanilla code, it is essential to understand the original context. The `usdasm` disassembly is the primary reference for this.
 - To find the original code for a patch at a given address (e.g., `$07A3DB`), you can search for the SNES address in the `usdasm` files (e.g., `#_07A3DB:`).
+- **Vanilla labels are not included by default.** The `usdasm` project is a reference, not part of the build. If you need to call a vanilla routine, you must find its implementation in the disassembly and explicitly copy or recreate it within the `Oracle of Secrets` source, giving it a new label (e.g., inside the `Oracle` namespace).
+
+### 3.5. Namespacing
+
+- **Guideline:** The majority of the *Oracle of Secrets* codebase is organized within an `Oracle` namespace, as defined in `Oracle_main.asm`. However, some modules, notably `ZSCustomOverworld.asm`, are included *outside* of this namespace.
+- **Interaction:** To call a function that is inside the `Oracle` namespace from a file that is outside of it (like `ZSCustomOverworld.asm`), you must prefix the function's label with `Oracle_`. For example, to call the `CheckIfNight16Bit` function (defined inside the namespace), you must use `JSL Oracle_CheckIfNight16Bit`.
+- **Rationale:** The build process correctly resolves these `Oracle_` prefixed labels to their namespaced counterparts (e.g., `Oracle.CheckIfNight16Bit`). Do not add the `Oracle_` prefix to the original function definition; it is only used by the calling code outside the namespace.
 
 ## 4. Build Process and ROM Management
 
@@ -134,6 +141,7 @@ When encountering unexpected crashes (often indicated by a `BRK` instruction in
     2.  **Use `print_debug`:** Strategically place `%print_debug()` macros to output register values or memory contents at critical points in the code. This can help track the flow and identify unexpected values.
     3.  **Emulator Debugger:** Learn to use your emulator's debugger effectively. Step-by-step execution, register viewing, and memory inspection are invaluable tools.
     4.  **Check `usdasm`:** Always cross-reference with the `usdasm` disassembly to understand the original vanilla code and how your hooks are interacting with it.
+    5.  **Efficiently Search Large Files:** When analyzing large assembly files, especially those with large data blocks like `Overworld/ZSCustomOverworld.asm`, prefer using `search_file_content` or `grep` to find specific labels or code sections instead of reading the entire file in chunks. This avoids confusion and is more efficient.
 
 
 

Docs/World/Overworld/ZSCustomOverworld.md

@@ -57,3 +57,13 @@ ZSCustomOverworld replaces dozens of vanilla routines. Some of the most critical
 
 - **`!UseVanillaPool`:** A flag that, when set to 1, forces the system to use data tables that mimic the vanilla game's behavior. This is useful for debugging.
 - **`!Func...` Flags:** A large set of individual flags that allow for enabling or disabling specific hooks. This provides granular control for debugging and compatibility testing.
+
+## 6. Analysis & Future Work: Sprite Loading
+
+The `LoadOverworldSprites_Interupt` hook at `org $09C4C7` is a critical component that requires further investigation to support dynamic sprite sets, such as those needed for a day/night cycle.
+
+- **Identified Conflict:** The current ZScream implementation for sprite loading conflicts with external logic that attempts to swap sprite sets based on in-game conditions (e.g., time of day). The original hook's design, which calls `JSL.l Sprite_OverworldReloadAll`, can lead to recursive loops and stack overflows if not handled carefully.
+
+- **Investigation Goal:** The primary goal is to modify `LoadOverworldSprites_Interupt` to accommodate multiple sprite sets for a single area. The system needs to be able to check a condition (like whether it is currently night) and then select the appropriate sprite pointer, rather than relying solely on the static `state_..._New` tables.
+
+- **Technical Challenges:** A previous attempt to integrate this functionality was reverted due to build system issues where labels from other modules (like `Oracle_CheckIfNight16Bit`) were not visible to `ZSCustomOverworld.asm`. A successful solution will require resolving these cross-module dependencies and carefully merging the day/night selection logic with ZScream's existing data-driven approach to sprite loading.