smrpgpatchbuilder 5.0.10__tar.gz → 6.1.0__tar.gz

{smrpgpatchbuilder-5.0.10/src/smrpgpatchbuilder.egg-info → smrpgpatchbuilder-6.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: smrpgpatchbuilder
-Version: 5.0.10
+Version: 6.1.0
 Summary: Patchable base class support for some SMRPG concepts similar to their definitions in Lazy Shell
 Author-email: pidgezero_one <s.kischak@gmail.com>
 License-Expression: MIT

{smrpgpatchbuilder-5.0.10 → smrpgpatchbuilder-6.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "smrpgpatchbuilder"
-version = "5.0.10"
+version = "6.1.0"
 authors = [
   { name="pidgezero_one", email="s.kischak@gmail.com" },
 ]

{smrpgpatchbuilder-5.0.10 → smrpgpatchbuilder-6.1.0}/src/smrpgpatchbuilder/datatypes/overworld_scripts/event_scripts/commands/commands.py

@@ -2570,22 +2570,42 @@ class CopyVarToVar(UsableEventScriptCommand, EventScriptCommand):
 
 
 class DarkenLayersExceptPaletteRows(UsableEventScriptCommand, EventScriptCommand):
-    """Darken the level background and all NPCs except the palette rows whose bit is
-    set in `preserve_rows_mask`. The handler at $C0:4FD9 stores `fade_arg` into the
-    fade-depth control word ($318B / $318C / $318E) and `preserve_rows_mask` into the
-    palette-row exclusion bitmask ($003185). The palette processor at $C0:3AEE walks 8
-    rows and skips any row whose mask bit is set, leaving only the unmasked rows
-    darkened.
-
-    **Important:** the mask targets palette rows, not NPC indices. When a room's
-    `ally_sprite_buffer_size` is increased (e.g. when the protagonist needs more VRAM
-    for tilemap molds), every NPC palette row shifts by the same delta, so this mask
-    must shift left by the same delta to keep targeting the same NPCs.
-
-    Bit `n` of `preserve_rows_mask` corresponds to palette row `n`. Bit set = preserve
-    (skip darkening); bit clear = darken normally.
-
-    The middle arg byte is filler, ignored by the handler.
+    """Darken the level background and all NPCs except the OBJ palette rows listed
+    in `preserve_rows`, ramping over `duration_frames` frames. The handler at
+    $C0:4FD9 unpacks three bytes:
+
+        byte 2 (offset 0): low 6 bits → fade depth ($318B);
+                           high 2 bits → bits 0-1 of duration counter
+        byte 3 (offset 1): bits 2-9 of the duration counter
+        byte 4 (offset 2): 8-bit OBJ palette-row exclusion mask ($003185)
+
+    The two duration-related bytes get combined as a 16-bit load and shifted right
+    by 6, giving a 10-bit duration value written to $318C and $318E. The palette
+    processor at $C0:3A44 decrements $318C each frame and ends the fade when it
+    reaches zero.
+
+    The palette processor at $C0:3AEE walks 8 rows (the OBJ palette set, rows
+    8-15) and skips any row whose bit is set in the exclusion mask, leaving only
+    the unmasked rows darkened. Mask bits correspond to:
+
+        bit 0 → MARIO_PALETTE        (PaletteRow 8 — the player)
+        bit 1 → NPC_PALETTE_ROW_1    (PaletteRow 9)
+        bit 2 → NPC_PALETTE_ROW_2    (PaletteRow 10)
+        bit 3 → NPC_PALETTE_ROW_3    (PaletteRow 11)
+        bit 4 → NPC_PALETTE_ROW_4    (PaletteRow 12)
+        bit 5 → NPC_PALETTE_ROW_5    (PaletteRow 13)
+        bit 6 → NPC_PALETTE_ROW_6    (PaletteRow 14)
+        bit 7 → NPC_PALETTE_ROW_7    (PaletteRow 15)
+
+    `fade_depth=50` (0x32) is treated as a sentinel "max" by the processor at
+    $C0:3A4C — when the duration counter expires at this depth, the fade state is
+    cleared completely instead of transitioning into "fade-out completed" mode.
+
+    **Note on ally-buffer growth:** when a room's `ally_sprite_buffer_size`
+    increases (e.g. for non-Mario protagonists with tilemap molds), every NPC
+    palette row shifts by the same delta, so the NPC entries in `preserve_rows`
+    must shift forward by the same delta to keep targeting the same NPCs.
+    `MARIO_PALETTE` does not shift.
 
     ## Lazy Shell command
         (not available in Lazy Shell)
@@ -2597,63 +2617,107 @@ class DarkenLayersExceptPaletteRows(UsableEventScriptCommand, EventScriptCommand
         5 bytes
 
     Args:
-        fade_arg (int): 8-bit fade-depth control. Low 6 bits → $318B (fade depth);
-            high 2 bits → $318C / $318E (fade-mode bits).
-        filler (int): Ignored by the handler. Set to 0 unless preserving original
-            byte sequences.
-        preserve_rows_mask (int): 8-bit palette-row exclusion bitmask. Bit n set =
-            palette row n is preserved (not darkened).
+        fade_depth (int): Color-subtraction intensity, 0-63. Higher = darker.
+            Special value 50 (0x32) is the "max depth" sentinel that triggers
+            full state-clear when the fade ends.
+        duration_frames (int): How many frames the fade lasts, 0-1023.
+        preserve_rows (list[PaletteRow]): Palette rows to preserve from the
+            darken effect. Each entry must be `MARIO_PALETTE` or
+            `NPC_PALETTE_ROW_1` through `NPC_PALETTE_ROW_7` (PaletteRow values
+            8-15). Empty list = darken all rows.
         identifier (str | None): Give this command a label if you want another
             command to jump to it.
     """
 
     _opcode = bytearray([0xFD, 0x8E])
     _size: int = 5
-    _fade_arg: UInt8
-    _filler: UInt8
-    _preserve_rows_mask: UInt8
+    _OBJ_PALETTE_BASE = 8  # PaletteRow(8) = MARIO_PALETTE = bit 0 of the mask.
+    _MAX_FADE_DEPTH = 0x3F  # 6-bit field
+    _MAX_DURATION = 0x3FF   # 10-bit field
+    _fade_depth: UInt8
+    _duration_frames: UInt16
+    _preserve_rows: list[PaletteRow]
 
     @property
-    def fade_arg(self) -> UInt8:
-        """8-bit fade-depth control: low 6 bits → fade depth, high 2 bits → fade mode."""
-        return self._fade_arg
+    def fade_depth(self) -> UInt8:
+        """Color-subtraction intensity, 0-63. 50 (0x32) is the max-depth sentinel."""
+        return self._fade_depth
 
-    def set_fade_arg(self, fade_arg: int) -> None:
-        """Set the 8-bit fade-depth control byte."""
-        self._fade_arg = UInt8(fade_arg)
+    def set_fade_depth(self, fade_depth: int) -> None:
+        """Set the fade depth (0-63)."""
+        if not 0 <= fade_depth <= self._MAX_FADE_DEPTH:
+            raise InvalidCommandArgumentException(
+                f"DarkenLayersExceptPaletteRows fade_depth must be 0-{self._MAX_FADE_DEPTH}; "
+                f"got {fade_depth}"
+            )
+        self._fade_depth = UInt8(fade_depth)
 
     @property
-    def filler(self) -> UInt8:
-        """Filler byte ignored by the handler at $C0:4FD9."""
-        return self._filler
+    def duration_frames(self) -> UInt16:
+        """Fade duration in frames, 0-1023."""
+        return self._duration_frames
 
-    def set_filler(self, filler: int) -> None:
-        """Set the filler byte (no effect in-game)."""
-        self._filler = UInt8(filler)
+    def set_duration_frames(self, duration_frames: int) -> None:
+        """Set the fade duration in frames (0-1023)."""
+        if not 0 <= duration_frames <= self._MAX_DURATION:
+            raise InvalidCommandArgumentException(
+                f"DarkenLayersExceptPaletteRows duration_frames must be 0-{self._MAX_DURATION}; "
+                f"got {duration_frames}"
+            )
+        self._duration_frames = UInt16(duration_frames)
+
+    @property
+    def preserve_rows(self) -> list[PaletteRow]:
+        """Palette rows that the fade should preserve. Always sorted ascending."""
+        return sorted(self._preserve_rows)
+
+    def set_preserve_rows(self, preserve_rows: list[PaletteRow | int]) -> None:
+        """Set the palette rows to preserve. Each entry must be a PaletteRow in
+        the OBJ range (8-15)."""
+        rows: list[PaletteRow] = []
+        seen: set[int] = set()
+        for r in preserve_rows:
+            row = PaletteRow(r)
+            if not (
+                self._OBJ_PALETTE_BASE <= row <= self._OBJ_PALETTE_BASE + 7
+            ):
+                raise InvalidCommandArgumentException(
+                    f"DarkenLayersExceptPaletteRows preserve_rows entries must be "
+                    f"MARIO_PALETTE or NPC_PALETTE_ROW_1 through NPC_PALETTE_ROW_7 "
+                    f"(PaletteRow {self._OBJ_PALETTE_BASE} through "
+                    f"{self._OBJ_PALETTE_BASE + 7}); got PaletteRow {int(row)}"
+                )
+            if int(row) not in seen:
+                rows.append(row)
+                seen.add(int(row))
+        self._preserve_rows = rows
 
     @property
     def preserve_rows_mask(self) -> UInt8:
-        """8-bit palette-row exclusion mask. Bit n set = preserve palette row n."""
-        return self._preserve_rows_mask
-
-    def set_preserve_rows_mask(self, preserve_rows_mask: int) -> None:
-        """Set the 8-bit palette-row exclusion mask."""
-        self._preserve_rows_mask = UInt8(preserve_rows_mask)
+        """The 8-bit bitmask written to $003185 (derived from `preserve_rows`)."""
+        mask = 0
+        for row in self._preserve_rows:
+            mask |= 1 << (int(row) - self._OBJ_PALETTE_BASE)
+        return UInt8(mask)
 
     def __init__(
         self,
-        fade_arg: int,
-        preserve_rows_mask: int,
-        filler: int = 0,
+        fade_depth: int,
+        duration_frames: int,
+        preserve_rows: list[PaletteRow | int],
         identifier: str | None = None,
     ) -> None:
         super().__init__(identifier)
-        self.set_fade_arg(fade_arg)
-        self.set_filler(filler)
-        self.set_preserve_rows_mask(preserve_rows_mask)
+        self.set_fade_depth(fade_depth)
+        self.set_duration_frames(duration_frames)
+        self.set_preserve_rows(preserve_rows)
 
     def render(self, *args) -> bytearray:
-        return super().render(self.fade_arg, self.filler, self.preserve_rows_mask)
+        # The handler reads byte 2 (low 6 bits = depth, high 2 bits = duration[0:2])
+        # and byte 3 (duration[2:10]), so re-pack here.
+        byte_2 = ((self._duration_frames & 0x03) << 6) | (self._fade_depth & 0x3F)
+        byte_3 = (self._duration_frames >> 2) & 0xFF
+        return super().render(UInt8(byte_2), UInt8(byte_3), self.preserve_rows_mask)
 
 
 class StoreBytesTo0335And0556(UsableEventScriptCommand, EventScriptCommand):

{smrpgpatchbuilder-5.0.10 → smrpgpatchbuilder-6.1.0/src/smrpgpatchbuilder.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: smrpgpatchbuilder
-Version: 5.0.10
+Version: 6.1.0
 Summary: Patchable base class support for some SMRPG concepts similar to their definitions in Lazy Shell
 Author-email: pidgezero_one <s.kischak@gmail.com>
 License-Expression: MIT