koro 1.1.6__tar.gz → 2.0.0.post1__tar.gz

koro-2.0.0.post1/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.1
+Name: koro
+Version: 2.0.0.post1
+Summary: Tools for manipulating levels made in Marble Saga: Kororinpa
+Home-page: https://github.com/DigitalDetective47/koro
+Author: DigitalDetective47
+Author-email: ninji2701@gmail.com
+Project-URL: Bug Tracker, https://github.com/DigitalDetective47/koro/issues
+Project-URL: Documentation, https://github.com/DigitalDetective47/koro/wiki
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: The Unlicense (Unlicense)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: File Formats
+Classifier: Topic :: Games/Entertainment
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+License-File: LICENSE
+
+koro (stylized in all lowercase) is a Python package that can read and modify stages from *Marble Saga: Kororinpa*.
+
+# *Marble Saga: Kororinpa*
+
+*Marble Saga: Kororinpa* is a video game released for the Nintendo Wii in March of 2009 in North America; the game was released in PAL regions under the title *Marbles! Balance Challenge* in May of the same year. Like its predecessor *Kororinpa*/*Kororinpa: Marble Mania*, it is a ball‐rolling game which is very similar to the *Super Monkey Ball* series in which the player character is controlled by tilting the game world. This game makes use of the Wii Remote's motion control capabilities by using the orientation of the controller to manipulate the world.
+
+# Problems
+
+*Marble Saga: Kororinpa* included a stage editor in which parts could be created by combining junk parts collected within the main game. The game provides the player with 20 slots in which to save stages that they have created. During the time period following the game's release, players could share their created stages using the WiiConnect24 service. After WiiConnect24 shut down on the 28<sup>th</sup> of June 2013, sharing stages with other players became impossible through official means. Sharing save files is not possible through the Wii system menu as the game had online leaderboards for ten stages specifically designed for online competition. As a result, saves of this game are marked as protected and cannot be copied from the save manager present in the Wii system menu.
+
+# This package
+
+This package allows you to extract the saved stages from your save file and store them in their own files, and to import stages downloaded online into your existing save file. (This package does not provide tools to get saves to or from the Wii console, there is plenty of homebrew software already in existence for this purpose.) This package also contains reverse&hyphen;engineered replicas of the game's compression format used internally, allowing for stage substitution in mods.
+
+# Usage
+
+To install this package, simply run
+```
+pip install koro
+```
+in a command prompt. For detailed documentation of the contents of the package, please view the wiki. For basic users, simple command&hyphen;line tools are available in the `scripts` folder of this repository. **Use of these tools requires installing the package from PyPI.**
+
+## Playing downloaded stages
+
+`unpacker.py` is a script designed to inject stages downloaded online into your save file. Simply run the script with the stages, the data directory of your save file, and if injecting a single stage, the slot to inject it into. The stages should then appear in the **Friend** tab. To find the location of your save in Dophin, right&hyphen;click the game and select **Open Wii Save Folder**.
+
+## Uploading your stages
+
+`packer.py` is a script that allows you to easily extract and upload stages that you've created. Run the script with your save directory, destination (ZIP archive), and optionally which stages to export. This script only exports stages stored in the **Original** tab of the editor. To specify which stages to export, simply enter the stage numbers in the order that they should appear when downloaded. If a custom ordering is not specified, the default is to extract all 20 stages in the order that they appear in&hyphen;game. To share single levels, extract files from the resulting archive.

koro-2.0.0.post1/README.md

@@ -0,0 +1,29 @@
+koro (stylized in all lowercase) is a Python package that can read and modify stages from *Marble Saga: Kororinpa*.
+
+# *Marble Saga: Kororinpa*
+
+*Marble Saga: Kororinpa* is a video game released for the Nintendo Wii in March of 2009 in North America; the game was released in PAL regions under the title *Marbles! Balance Challenge* in May of the same year. Like its predecessor *Kororinpa*/*Kororinpa: Marble Mania*, it is a ball‐rolling game which is very similar to the *Super Monkey Ball* series in which the player character is controlled by tilting the game world. This game makes use of the Wii Remote's motion control capabilities by using the orientation of the controller to manipulate the world.
+
+# Problems
+
+*Marble Saga: Kororinpa* included a stage editor in which parts could be created by combining junk parts collected within the main game. The game provides the player with 20 slots in which to save stages that they have created. During the time period following the game's release, players could share their created stages using the WiiConnect24 service. After WiiConnect24 shut down on the 28<sup>th</sup> of June 2013, sharing stages with other players became impossible through official means. Sharing save files is not possible through the Wii system menu as the game had online leaderboards for ten stages specifically designed for online competition. As a result, saves of this game are marked as protected and cannot be copied from the save manager present in the Wii system menu.
+
+# This package
+
+This package allows you to extract the saved stages from your save file and store them in their own files, and to import stages downloaded online into your existing save file. (This package does not provide tools to get saves to or from the Wii console, there is plenty of homebrew software already in existence for this purpose.) This package also contains reverse&hyphen;engineered replicas of the game's compression format used internally, allowing for stage substitution in mods.
+
+# Usage
+
+To install this package, simply run
+```
+pip install koro
+```
+in a command prompt. For detailed documentation of the contents of the package, please view the wiki. For basic users, simple command&hyphen;line tools are available in the `scripts` folder of this repository. **Use of these tools requires installing the package from PyPI.**
+
+## Playing downloaded stages
+
+`unpacker.py` is a script designed to inject stages downloaded online into your save file. Simply run the script with the stages, the data directory of your save file, and if injecting a single stage, the slot to inject it into. The stages should then appear in the **Friend** tab. To find the location of your save in Dophin, right&hyphen;click the game and select **Open Wii Save Folder**.
+
+## Uploading your stages
+
+`packer.py` is a script that allows you to easily extract and upload stages that you've created. Run the script with your save directory, destination (ZIP archive), and optionally which stages to export. This script only exports stages stored in the **Original** tab of the editor. To specify which stages to export, simply enter the stage numbers in the order that they should appear when downloaded. If a custom ordering is not specified, the default is to extract all 20 stages in the order that they appear in&hyphen;game. To share single levels, extract files from the resulting archive.

{koro-1.1.6 → koro-2.0.0.post1}/setup.cfg

@@ -1,24 +1,31 @@
 [metadata]
 name = koro
-version = 1.1.6
+version = 2.0.0.post1
 author = DigitalDetective47
 author_email = ninji2701@gmail.com
 description = Tools for manipulating levels made in Marble Saga: Kororinpa
+long_description = file: README.md
 url = https://github.com/DigitalDetective47/koro
 project_urls = 
 	Bug Tracker = https://github.com/DigitalDetective47/koro/issues
+	Documentation = https://github.com/DigitalDetective47/koro/wiki
 classifiers = 
 	Development Status :: 5 - Production/Stable
 	License :: OSI Approved :: The Unlicense (Unlicense)
 	Operating System :: OS Independent
 	Programming Language :: Python :: 3
+	Programming Language :: Python :: 3 :: Only
+	Programming Language :: Python :: 3.11
+	Programming Language :: Python :: 3.12
+	Topic :: File Formats
 	Topic :: Games/Entertainment
+	Typing :: Typed
 
 [options]
 package_dir = 
 	= src
 packages = find:
-python_requires = >=3.9
+python_requires = >=3.11
 
 [options.packages.find]
 where = src

koro-2.0.0.post1/src/koro/__init__.py

@@ -0,0 +1,8 @@
+from .slot import *
+from .slot.bin import *
+from .slot.file import *
+from .slot.save import *
+from .slot.xml import *
+from .stage import *
+from .stage.model import *
+from .stage.part import *

koro-2.0.0.post1/src/koro/slot/__init__.py

@@ -0,0 +1,21 @@
+from abc import ABC, abstractmethod
+
+from ..stage import Stage
+
+__all__ = ["Slot"]
+
+
+class Slot(ABC):
+    __slots__ = ()
+
+    def __bool__(self) -> bool:
+        """Return whether this slot is filled."""
+        return self.load() is not None
+
+    @abstractmethod
+    def load(self) -> Stage | None:
+        pass
+
+    @abstractmethod
+    def save(self, data: Stage | None, /) -> None:
+        pass

{koro-1.1.6/src/koro/file → koro-2.0.0.post1/src/koro/slot}/bin.py

@@ -1,22 +1,19 @@
 from itertools import chain
 from typing import Final
 
-from ..item.level import Level, LevelNotFoundError
-from . import Location
+from ..stage import Stage
+from .file import FileSlot
+from .xml import XmlSlot
 
-__all__ = ["BinLevel", "BinLevelNotFoundError"]
 
+__all__ = ["BinSlot"]
 
-class BinLevelNotFoundError(FileNotFoundError, LevelNotFoundError):
-    pass
 
-
-class BinLevel(Location, Level):
+class BinSlot(FileSlot):
     __slots__ = ()
 
     @staticmethod
     def compress(data: bytes, /) -> bytes:
-        """Compress the given level data into the game's format."""
         buffer: bytearray = bytearray(1024)
         buffer_index: int = 958
         chunk: bytearray
@@ -117,11 +114,10 @@ class BinLevel(Location, Level):
                 )
                 data_index += test_length
             output.extend(chunk)
-        return bytes(output + b"\x00" * (len(output) & 1))
+        return bytes(output)
 
     @staticmethod
     def decompress(data: bytes, /) -> bytes:
-        """Decompress the given data into raw level data."""
         buffer: Final[bytearray] = bytearray(1024)
         buffer_index: int = 958
         handle: int | bytearray
@@ -151,29 +147,12 @@ class BinLevel(Location, Level):
                         buffer_index = buffer_index + 1 & 1023
                     result.extend(handle)
                 flags >>= 1
-        return bytes(result.replace(b"<EDITUSER> 3 </EDITUSER>", b"<EDITUSER> 2 </EDITUSER>"))
-
-    def delete(self) -> None:
-        try:
-            return super().delete()
-        except FileNotFoundError as e:
-            raise BinLevelNotFoundError(*e.args)
-
-    def __len__(self) -> int:
-        try:
-            with open(self.path, "rb") as f:
-                f.seek(8)
-                return int.from_bytes(f.read(4), byteorder="big")
-        except FileNotFoundError as e:
-            BinLevelNotFoundError(*e.args)
+        return bytes(result)
 
-    def read(self) -> bytes:
-        try:
-            with open(self.path, "rb") as f:
-                return self.decompress(f.read())
-        except FileNotFoundError as e:
-            raise BinLevelNotFoundError(*e.args)
+    @staticmethod
+    def deserialize(data: bytes, /) -> Stage:
+        return XmlSlot.deserialize(BinSlot.decompress(data))
 
-    def write(self, new_content: bytes, /) -> None:
-        with open(self.path, "wb") as f:
-            f.write(self.compress(new_content))
+    @staticmethod
+    def serialize(stage: Stage, /) -> bytes:
+        return BinSlot.compress(XmlSlot.serialize(stage))

koro-2.0.0.post1/src/koro/slot/file.py

@@ -0,0 +1,70 @@
+from abc import ABC, abstractmethod
+from os import remove
+from os.path import isfile
+from typing import TYPE_CHECKING, Any
+
+from ..stage import Stage
+from . import Slot
+
+if TYPE_CHECKING:
+    from _typeshed import StrOrBytesPath
+else:
+    StrOrBytesPath = Any
+
+
+__all__ = ["FileSlot"]
+
+
+class FileSlot(Slot, ABC):
+    __match_args__ = ("path",)
+    __slots__ = ("_path",)
+
+    _path: StrOrBytesPath
+
+    def __init__(self, path: StrOrBytesPath, /) -> None:
+        self._path = path
+
+    def __bool__(self) -> bool:
+        return isfile(self.path)
+
+    @staticmethod
+    @abstractmethod
+    def deserialize(data: bytes, /) -> Stage:
+        pass
+
+    def __eq__(self, other: object, /) -> bool:
+        if isinstance(other, FileSlot) and (
+            isinstance(other, type(self)) or isinstance(self, type(other))
+        ):
+            return self.path == other.path
+        else:
+            return NotImplemented
+
+    def __hash__(self) -> int:
+        return hash(self.path)
+
+    def load(self) -> Stage | None:
+        try:
+            with open(self.path, "rb") as f:
+                return self.deserialize(f.read())
+        except FileNotFoundError:
+            return None
+
+    @property
+    def path(self) -> StrOrBytesPath:
+        return self._path
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self.path!r})"
+
+    def save(self, data: Stage | None) -> None:
+        if data is None:
+            remove(self.path)
+        else:
+            with open(self.path, "wb") as f:
+                f.write(self.serialize(data))
+
+    @staticmethod
+    @abstractmethod
+    def serialize(stage: Stage, /) -> bytes:
+        pass

koro-2.0.0.post1/src/koro/slot/save.py

@@ -0,0 +1,137 @@
+from enum import Enum, unique
+from io import BytesIO
+from operator import index as ix
+from os.path import basename, dirname, join
+from typing import TYPE_CHECKING, Annotated, Any, Literal, SupportsIndex
+from collections.abc import Mapping, Sequence
+
+from ..stage import Stage
+
+from . import Slot
+from .xml import XmlSlot
+
+if TYPE_CHECKING:
+    from _typeshed import StrOrBytesPath
+else:
+    StrOrBytesPath = Any
+
+
+__all__ = ["EditorPage", "get_slots", "SaveSlot"]
+
+
+@unique
+class EditorPage(Enum):
+    ORIGINAL = 0
+    FRIEND = 1
+    HUDSON = 2
+
+
+class SaveSlot(Slot):
+    __match_args__ = ("path", "page", "index")
+    __slots__ = ("_offset", "_path")
+
+    _offset: Literal[8, 156392, 312776, 469160]
+    _path: str | bytes
+
+    def __init__(
+        self,
+        path: StrOrBytesPath,
+        page: EditorPage,
+        index: Annotated[
+            SupportsIndex,
+            Literal[
+                1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20
+            ],
+        ],
+    ) -> None:
+        index = ix(index) - 1
+        if index in range(0, 20):
+            self._offset = 8 + 156864 * (index & 3)  # type: ignore[assignment]
+            self._path = join(path, f"ed{(index >> 2) + 5 * page.value:02}.dat")  # type: ignore[arg-type]
+        else:
+            raise ValueError("index must be between 1 and 20")
+
+    def __bool__(self) -> bool:
+        try:
+            with open(self._path, "rb") as f:
+                f.seek(self._offset)
+                return f.read(1) != b"\x00"
+        except FileNotFoundError:
+            return False
+
+    def __eq__(self, other: Any, /) -> bool:
+        if isinstance(other, SaveSlot):
+            return self._path == other._path and self._offset == other._offset
+        else:
+            return NotImplemented
+
+    def __hash__(self) -> int:
+        return hash((self._offset, self._path))
+
+    @property
+    def index(
+        self,
+    ) -> Literal[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20]:
+        return (int(basename(self._path)[2:4]) % 5 >> 2 | self._offset // 156864) + 1  # type: ignore[return-value]
+
+    def load(self) -> Stage | None:
+        try:
+            with open(self._path, "rb") as f:
+                f.seek(self._offset)
+                with BytesIO() as b:
+                    block: bytearray = bytearray()
+                    while True:
+                        block.clear()
+                        f.readinto1(block)
+                        if len(b.getbuffer()) + len(block) > 156864:
+                            del block[156864 - len(b.getbuffer()) :]
+                        if block[-1]:
+                            b.write(block)
+                        else:
+                            while block:
+                                if block[len(block) >> 1]:
+                                    b.write(block[: (len(block) >> 1) + 1])
+                                    del block[: (len(block) >> 1) + 1]
+                                else:
+                                    del block[len(block) >> 1 :]
+                            data: bytes = b.getvalue()
+                            if data:
+                                return XmlSlot.deserialize(data)
+                            else:
+                                return None
+        except FileNotFoundError:
+            return None
+
+    @property
+    def page(self) -> EditorPage:
+        return EditorPage(int(basename(self._path)[2:4]) // 5)
+
+    @property
+    def path(self) -> StrOrBytesPath:
+        return dirname(self._path)
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self.path!r}, {self.page!r}, {self.index!r})"
+
+    def save(self, data: Stage | None) -> None:
+        binary: bytes = b"" if data is None else XmlSlot.serialize(data)
+        if len(binary) > 156864:
+            raise ValueError("serialized stage data is too large to save")
+        try:
+            with open(self._path, "xb") as f:
+                f.write(bytes(638976))
+            if data is None:
+                return
+        except FileExistsError:
+            pass
+        with open(self._path, "r+b") as f:
+            f.seek(self._offset)
+            f.write(binary)
+            f.write(bytes(156864 - len(binary)))
+
+
+def get_slots(save: StrOrBytesPath, /) -> Mapping[EditorPage, Sequence[SaveSlot]]:
+    return {
+        page: tuple(SaveSlot(save, page, i) for i in range(1, 21))
+        for page in EditorPage
+    }