smrpgpatchbuilder 5.0.8__tar.gz → 5.0.10__tar.gz

{smrpgpatchbuilder-5.0.8 → smrpgpatchbuilder-5.0.10}/MANIFEST.in

@@ -1,3 +1,3 @@
-global-exclude __pycache__
-global-exclude *.py[cod]
-prune src/disassembler_output
+global-exclude __pycache__
+global-exclude *.py[cod]
+prune src/disassembler_output

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: smrpgpatchbuilder
-Version: 5.0.8
+Version: 5.0.10
 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.8 → smrpgpatchbuilder-5.0.10}/pyproject.toml

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

{smrpgpatchbuilder-5.0.8 → smrpgpatchbuilder-5.0.10}/src/smrpgpatchbuilder/datatypes/graphics/classes.py

@@ -739,7 +739,7 @@ class SpriteCollection:
         
         return bytearray(sprite_data), bytearray(image_data), bytearray(animation_pointers), anim_tile_ranges, output_tile_ranges
 
-    def assemble_from_tables(self, sprites: list[CompleteSprite], insert_whitespace=False, shared_image_groups: list[list[int]] | None = None, no_clone_sprites: list[int] | None = None) -> tuple[bytearray, bytearray, bytearray, list[tuple[int, bytearray]], list[tuple[int, bytearray]]]:
+    def assemble_from_tables(self, sprites: list[CompleteSprite], insert_whitespace=False, shared_image_groups: list[list[int]] | None = None) -> tuple[bytearray, bytearray, bytearray, list[tuple[int, bytearray]], list[tuple[int, bytearray]]]:
         # CRITICAL: Reset all banks before assembling to prevent data from previous runs
         for bank in self.uncompressed_tile_banks:
             bank.tiles = bytearray([])
@@ -1150,12 +1150,7 @@ class SpriteCollection:
                     this_mold = copy.deepcopy(m)
 
                     # create clones and use in mold
-                    # Skip clone optimization for sprites that need vanilla-compatible
-                    # animation layout (e.g., Smithy sprites used in battle events)
-                    skip_clones = no_clone_sprites is not None and sprite_index in no_clone_sprites
-                    if skip_clones and mold_index == 0:
-                        print(f"[GFX] Skipping clone optimization for sprite {sprite_index}")
-                    if not this_mold.gridplane and not skip_clones:
+                    if not this_mold.gridplane:
                         clones = find_clones(these_tiles, molds, sprite_index, mold_index)
                         these_tiles = clones
                     this_mold.tiles = these_tiles
@@ -1212,8 +1207,8 @@ class SpriteCollection:
 
         return self.assemble_from_tables_(complete_sprites, complete_images, complete_animations, output_tile_ranges)
 
-    def render(self, whitespace: bool = False, shared_image_groups: list[list[int]] | None = None, no_clone_sprites: list[int] | None = None) -> list[tuple[int, bytearray]]:
-        sprite_data, image_data, animation_pointers, animation_data, tiles = self.assemble_from_tables(self.sprites, whitespace, shared_image_groups, no_clone_sprites)
+    def render(self, whitespace: bool = False, shared_image_groups: list[list[int]] | None = None) -> list[tuple[int, bytearray]]:
+        sprite_data, image_data, animation_pointers, animation_data, tiles = self.assemble_from_tables(self.sprites, whitespace, shared_image_groups)
 
         # Zero out all sprite data ranges before writing to prevent leftover data
         zero_ranges = []

{smrpgpatchbuilder-5.0.8 → smrpgpatchbuilder-5.0.10}/src/smrpgpatchbuilder/datatypes/levels/room_collection.py

@@ -865,6 +865,17 @@ class RoomCollection:
                 action_offset = obj.action_script - base_action_script
                 event_offset = obj.event_script - base_event_script
 
+                if event_offset < 0 or event_offset > 7:
+                    raise ValueError(
+                        f"Room {room_idx} object {obj_idx} (RegularClone):\n"
+                        f"  event_script offset {event_offset} out of range [0, 7]\n"
+                        f"  Clone event_script: {obj.event_script}\n"
+                        f"  Parent event_script: {parent.event_script}\n"
+                        f"  Base event_script: {base_event_script}\n"
+                        f"  A clone's event_script must be within 7 of the base "
+                        f"(min of parent + sibling clones); the encoding only has 3 bits."
+                    )
+
                 data[0] = (
                     ((event_offset & 0x07) << 5)
                     | ((action_offset & 0x03) << 3)

{smrpgpatchbuilder-5.0.8 → smrpgpatchbuilder-5.0.10}/src/smrpgpatchbuilder/datatypes/overworld_scripts/action_scripts/commands/__init__.py

@@ -78,7 +78,9 @@ from .commands import (
     A_SetSequenceSpeed,
     A_SetWalkingSpeed,
     A_SetAllSpeeds,
+    A_ToggleSubroutineSlots,
     A_EmbeddedAnimationRoutine,
+    A_SetSubroutineXTargets,
     A_MaximizeSequenceSpeed,
     A_MaximizeSequenceSpeed86,
     A_FixedFCoordOn,

{smrpgpatchbuilder-5.0.8 → smrpgpatchbuilder-5.0.10}/src/smrpgpatchbuilder/datatypes/overworld_scripts/action_scripts/commands/commands.py

@@ -379,11 +379,11 @@ _valid_unknowncmd_queue_opcodes = [
     1,
     1,
     1,
-    2,  # 20
+    0,  # 20  (handled by A_ToggleSubroutineSlots)
     0,
     0,
     2,
-    5,
+    0,  # 24  (handled by A_SetSubroutineXTargets)
     5,
     0,
     0,
@@ -4047,8 +4047,78 @@ class A_SetAllSpeeds(_SetAnimationSpeed, UsableActionScriptCommand):
         super().__init__(speed, sequence=True, walking=True, identifier=identifier)
 
 
+class A_ToggleSubroutineSlots(UsableActionScriptCommand, ActionScriptCommand):
+    """Toggle the active state of the NPC's three sub-routine slots ($26,X / $27,X /
+    $28,X) according to a 3-bit mask. Bit 0 controls slot $26, bit 1 controls slot $27,
+    bit 2 controls slot $28. For each slot: if the corresponding bit is set and the slot
+    is currently inactive, the engine allocates a new sub-routine record (via $C0:E87E);
+    if the bit is clear and the slot is currently active, the engine deallocates the
+    existing record (via $C0:E8FE). Slots whose state already matches the mask are left
+    alone.
+
+    Sub-routines spawned this way drive per-NPC motion or animation independently of the
+    main action script. Pair with `A_SetSubroutineXTargets` (opcode 0x24) to give them
+    targets, or `A_EmbeddedAnimationRoutine` (opcode 0x26/0x27/0x28) to spawn a fully
+    parameterised routine.
+
+    ## Lazy Shell command
+        (not documented in Lazy Shell)
+
+    ## Opcode
+        `0x20`
+
+    ## Size
+        2 bytes
+
+    Args:
+        mask (int): 3-bit mask (bits 0-2). 1 = slot should be active; 0 = slot should be
+            inactive. Bit 0 = slot $26, bit 1 = slot $27, bit 2 = slot $28.
+        identifier (str | None): Give this command a label if you want another command to jump to it.
+    """
+
+    _opcode = 0x20
+    _size: int = 2
+    _mask: UInt8
+
+    @property
+    def mask(self) -> UInt8:
+        """3-bit slot-active mask. Bit 0 = $26, bit 1 = $27, bit 2 = $28."""
+        return self._mask
+
+    def set_mask(self, mask: int) -> None:
+        """Set the 3-bit slot-active mask."""
+        if mask & ~0x07:
+            raise InvalidCommandArgumentException(
+                f"A_ToggleSubroutineSlots mask 0x{mask:02X} has bits set outside the low 3 bits"
+            )
+        self._mask = UInt8(mask)
+
+    def __init__(self, mask: int, identifier: str | None = None) -> None:
+        super().__init__(identifier)
+        self.set_mask(mask)
+
+    def render(self, *args) -> bytearray:
+        return super().render(self.mask)
+
+
 class A_EmbeddedAnimationRoutine(UsableActionScriptCommand, ActionScriptCommand):
-    """(unknown)
+    """Spawn a fully-parameterised sub-routine into one of the NPC's three sub-routine
+    slots ($26,X / $27,X / $28,X). The opcode byte selects the slot: 0x26 → slot $26,
+    0x27 → slot $27, 0x28 → slot $28. Any sub-routine already in that slot is cleared
+    first (via $C0:E9DC).
+
+    The 14 payload bytes are copied into the NPC's per-slot scratch region:
+        [1..2]   X coord (16-bit)
+        [3..4]   Y coord (16-bit)
+        [5]      sprite sequence index
+        [6]      sprite control bits
+        [7..8]   Z coord (16-bit)
+        [9..10]  motion bits
+        [11..12] face direction
+        [13..14] (unidentified pair, written to $0C,X)
+        [15] high 2 bits → upper bits of $1E,X; low 3 bits → $1F,X
+
+    See $C0:D211 for the handler.
 
     ## Lazy Shell command
         `Embedded animation routine ($26)...`
@@ -4073,11 +4143,11 @@ class A_EmbeddedAnimationRoutine(UsableActionScriptCommand, ActionScriptCommand)
 
     @property
     def args(self) -> bytearray:
-        """(unknown)"""
+        """The full 16-byte payload (opcode + 14 data bytes + flag-byte)."""
         return self._args
 
     def set_args(self, args: bytearray) -> None:
-        """(unknown)"""
+        """Set the full 16-byte payload (opcode + 14 data bytes + flag-byte)."""
         assert len(args) == 16
         assert args[0] in [0x26, 0x27, 0x28]
         self._args = args
@@ -4090,6 +4160,65 @@ class A_EmbeddedAnimationRoutine(UsableActionScriptCommand, ActionScriptCommand)
         return super().render(self.args)
 
 
+class A_SetSubroutineXTargets(UsableActionScriptCommand, ActionScriptCommand):
+    """Set destination X-coordinates for whichever of the NPC's first two sub-routine
+    slots ($26,X and $27,X) are currently active. For each active slot, the existing
+    sub-routine state is reset (via $C0:E9DC) and the corresponding 16-bit X target is
+    written into the NPC's $00,X (X coord); $02,X (Y coord low) and $1E,X (state flags)
+    are zeroed. Slot $28,X is **not** touched by this opcode.
+
+    Pair with `A_ToggleSubroutineSlots` (opcode 0x20) to first activate the slots whose
+    targets you intend to set.
+
+    ## Lazy Shell command
+        (not documented in Lazy Shell)
+
+    ## Opcode
+        `0x24`
+
+    ## Size
+        5 bytes
+
+    Args:
+        slot_26_x (int): 16-bit destination X coord written into slot $26,X if active.
+        slot_27_x (int): 16-bit destination X coord written into slot $27,X if active.
+        identifier (str | None): Give this command a label if you want another command to jump to it.
+    """
+
+    _opcode = 0x24
+    _size: int = 5
+    _slot_26_x: UInt16
+    _slot_27_x: UInt16
+
+    @property
+    def slot_26_x(self) -> UInt16:
+        """16-bit X target for slot $26,X (consumed only if slot is active)."""
+        return self._slot_26_x
+
+    def set_slot_26_x(self, slot_26_x: int) -> None:
+        """Set the 16-bit X target for slot $26,X."""
+        self._slot_26_x = UInt16(slot_26_x)
+
+    @property
+    def slot_27_x(self) -> UInt16:
+        """16-bit X target for slot $27,X (consumed only if slot is active)."""
+        return self._slot_27_x
+
+    def set_slot_27_x(self, slot_27_x: int) -> None:
+        """Set the 16-bit X target for slot $27,X."""
+        self._slot_27_x = UInt16(slot_27_x)
+
+    def __init__(
+        self, slot_26_x: int, slot_27_x: int, identifier: str | None = None
+    ) -> None:
+        super().__init__(identifier)
+        self.set_slot_26_x(slot_26_x)
+        self.set_slot_27_x(slot_27_x)
+
+    def render(self, *args) -> bytearray:
+        return super().render(self.slot_26_x, self.slot_27_x)
+
+
 class A_MaximizeSequenceSpeed(UsableActionScriptCommand, ActionScriptCommandNoArgs):
     """Set the NPC's sequence speed to its highest value. Not known if this actually works.
 
@@ -7024,7 +7153,12 @@ class A_IncPaletteRow(UsableActionScriptCommand, ActionScriptCommandNoArgs):
 
 
 class A_BPL262728(UsableActionScriptCommand, ActionScriptCommandNoArgs):
-    """(ASM instruction, effect unknown)
+    """Kill all three of the NPC's currently-active sub-routines (slots $26,X / $27,X /
+    $28,X) and zero the slot bytes. Implemented at $C0:D18F as `JSR $C0:E8E2`; the
+    `BPL` references in the LazyShell-derived class name come from the helper at
+    $C0:E8E2 which iterates the three slots and uses BPL to skip slots whose bit 7 is
+    already clear. Inverse pairing for `A_ToggleSubroutineSlots` (opcode 0x20) when you
+    want to clear all slots in one command.
 
     ## Lazy Shell command
         (not documented in Lazy Shell)

smrpgpatchbuilder-5.0.10/src/smrpgpatchbuilder/datatypes/overworld_scripts/event_scripts/commands/__init__.py

@@ -0,0 +1,2 @@
+from .types import *
+from .commands import ActionQueueAsync, ActionQueueSync, Add7000ToCurrentFP, Add7000ToMaxFP, AddCoins, AddConstToVar, AddFrogCoins, AddToInventory, AddVarTo7000, AppendDialogAt7000ToCurrentDialog, ApplySolidityModToLevel, ApplyTileModToLevel, CharacterJoinsParty, CharacterLeavesParty, CircleMaskExpandFromScreenCenter, CircleMaskShrinkToObject, CircleMaskShrinkToScreenCenter, Clear0158Bit7Offset, Clear7016To7018AndIsolate701AHighByteIf7018Bit0Set, ClearBit, ClearMem704XAt7000Bit, CloseDialog, Compare7000ToVar, CompareVarToConst, CopyVarToVar, CreatePacketAt7010, CreatePacketAt7010WithEvent, CreatePacketAtObjectCoords, DarkenLayersExceptPaletteRows, DeactivateSoundChannels, Dec, Dec7000FromCoins, Dec7000FromCurrentFP, Dec7000FromCurrentHP, Dec7000FromFrogCoins, DecVarFrom7000, DisableObjectTrigger, DisableObjectTriggerInSpecificLevel, DisableTriggerOfObjectAt70A8InCurrentLevel, DisplayIntroTitleText, EnableControls, EnableControlsUntilReturn, EnableObjectTrigger, EnableObjectTriggerInSpecificLevel, EnableTriggerOfObjectAt70A8InCurrentLevel, EndLoop, EnterArea, EquipItemToCharacter, ExitToWorldMap, ExorCrashesIntoKeep, FadeInFromBlack, FadeInFromColour, FadeInMusic, FadeOutMusic, FadeOutMusicFDA3, FadeOutMusicToVolume, FadeOutSoundToVolume, FadeOutToBlack, FadeOutToColour, FreezeAllNPCsUntilReturn, FreezeCamera, GenerateRandomNumFromRangeVar, If0210Bits012ClearDoNotJump, Inc, IncEXPByPacket, IncreaseMusicPitchBy, InitiateBattleMask, Jmp, JmpIf316DIs3, JmpIf7000AllBitsClear, JmpIf7000AnyBitsSet, JmpIfAudioMemoryEquals, JmpIfAudioMemoryIsAtLeast, JmpIfBitClear, JmpIfBitSet, JmpIfComparisonResultIsGreaterOrEqual, JmpIfComparisonResultIsLesser, JmpIfDialogOptionBOrCSelected, JmpIfDialogOptionBSelected, JmpIfLoadedMemoryIs0, JmpIfLoadedMemoryIsAboveOrEqual0, JmpIfLoadedMemoryIsBelow0, JmpIfLoadedMemoryIsNot0, JmpIfMarioInAir, JmpIfMarioOnAnObjectOrNot, JmpIfMarioOnObject, JmpIfMem704XAt7000BitClear, JmpIfMem704XAt7000BitSet, JmpIfObjectActionScriptIsRunning, JmpIfObjectInAir, JmpIfObjectInCurrentLevel, JmpIfObjectInSpecificLevel, JmpIfObjectIsUnderwater, JmpIfObjectNotInSpecificLevel, JmpIfObjectTriggerDisabledInSpecificLevel, JmpIfObjectTriggerEnabledInSpecificLevel, JmpIfObjectsAreLessThanXYStepsApart, JmpIfObjectsAreLessThanXYStepsApartSameZCoord, JmpIfRandom1of2, JmpIfRandom2of3, JmpIfVarEqualsConst, JmpIfVarNotEqualsConst, JmpToEvent, JmpToStartOfThisScript, JmpToStartOfThisScriptFA, JmpToSubroutine, LearnSpell, MarioGlows, MarioStopsGlowing, Mem7000AndConst, Mem7000AndVar, Mem7000OrConst, Mem7000OrVar, Mem7000XorConst, Mem7000XorVar, Move70107015To7016701B, Move7016701BTo70107015, MoveScriptToBackgroundThread1, MoveScriptToBackgroundThread2, MoveScriptToMainThread, MultiplyAndAddMem3148StoreToOffset7fB000PlusOutputX2, NonEmbeddedActionQueue, OpenSaveMenu, OpenShop, PaletteSet, PaletteSetMorphs, Pause, PauseActionScript, PauseScriptIfMenuOpen, PauseScriptResumeOnNextDialogPageA, PauseScriptResumeOnNextDialogPageB, PauseScriptUntilEffectDone, PixelateLayers, PlayMusic, PlayMusicAtCurrentVolume, PlayMusicAtDefaultVolume, PlaySound, PlaySoundBalance, PlaySoundBalanceFD9D, PrioritySet, ReactivateObject70A8TriggerIfMarioOnTopOfIt, ReadFromAddress, ReduceMusicPitchBy, RememberLastObject, RemoveObjectAt70A8FromCurrentLevel, RemoveObjectFromCurrentLevel, RemoveObjectFromSpecificLevel, RemoveOneOfItemFromInventory, ResetAndChooseGame, ResetCoords, ResetGame, ResetPrioritySet, RestoreAllFP, RestoreAllHP, ResumeActionScript, ResumeBackgroundEvent, Return, ReturnAll, ReturnFD, RunBackgroundEvent, RunBackgroundEventWithPause, RunBackgroundEventWithPauseReturnOnExit, RunDialog, RunDialogForDuration, RunEndingCredits, RunEventAsSubroutine, RunEventAtReturn, RunEventSequence, RunLevelupBonusSequence, RunMenuOrEventSequence, RunMenuTutorial, RunMolevilleMountainIntroSequence, RunMolevilleMountainSequence, RunStarPieceSequence, ScreenFlashesWithColour, Set0158Bit3Offset, Set0158Bit7Offset, Set7000To7FMemVar, Set7000ToCurrentLevel, Set7000ToIDOfMemberInSlot, Set7000ToMinecartTimer, Set7000ToObjectCoord, Set7000ToPartySize, Set7000ToPressedButton, Set7000ToTappedButton, Set70107015ToObjectXYZ, Set7016701BToObjectXYZ, SetAsyncActionScript, SetBit, SetEXPPacketTo7000, SetMem704XAt7000Bit, SetObjectMemoryToVar, SetSyncActionScript, SetTempAsyncActionScript, SetTempSyncActionScript, SetVarToConst, SetVarToRandom, SlowDownMusic, SlowDownMusicTempoBy, SpeedUpMusicTempoBy, SpeedUpMusicToDefault, StarMaskExpandFromScreenCenter, StarMaskShrinkToScreenCenter, StartAsyncEmbeddedActionScript, StartBattleAtBattlefield, StartBattleWithPackAt700E, StartLoopNFrames, StartLoopNTimes, StartSyncEmbeddedActionScript, StopAllBackgroundEvents, StopBackgroundEvent, StopEmbeddedActionScript, StopMusic, StopMusicFD9F, StopMusicFDA0, StopMusicFDA1, StopMusicFDA2, StopMusicFDA6, StopSound, Store00To0248, Store00To0334, Store01To0248, Store01To0335, Store02To0248, Store70A7ToEquipsInventory, StoreBytesTo0335And0556, StoreCharacterEquipmentTo7000, StoreCoinCountTo7000, StoreCurrentFPTo7000, StoreEmptyItemInventorySlotCountTo7000, StoreFFTo0335, StoreFrogCoinCountTo7000, StoreItemAmountTo7000, StoreItemAt70A7QuantityTo7000, StoreSetBits, SummonObjectAt70A8ToCurrentLevel, SummonObjectToCurrentLevel, SummonObjectToCurrentLevelAtMariosCoords, SummonObjectToSpecificLevel, SwapVars, TintLayers, UnfreezeAllNPCs, UnfreezeCamera, UnknownCommand, UnsyncActionScript, UnsyncDialog, VarShiftLeft, Xor3105With01