koro 1.1.6__py3-none-any.whl → 2.0.0.post1__py3-none-any.whl

koro-2.0.0.post1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,14 @@
+koro/__init__.py,sha256=xS3s862eN55uy83K2Dwchurhh9Euh1te2ZPia2lRVLI,200
+koro/slot/__init__.py,sha256=ldVeVLwXIgPZJsCp4-ix78ewRgsAKVwa8BnpcdnpfIc,419
+koro/slot/bin.py,sha256=XuvEc1rn85j6EYirjvDZhQ0y81lO8dRJPk4JVnyzln4,6686
+koro/slot/file.py,sha256=g5nlOddY2MiGdDVnxY7lpbxE74ZHWhG5VPJJddSY7PY,1726
+koro/slot/save.py,sha256=vZLftvjDyiHgZrMgthE8H-EbWIxtdT_MN3Jb-WIc4Eo,4582
+koro/slot/xml.py,sha256=C2g1OlGDwhlVocEeUg7tYxQf1mfRVNopH0yH1UG1Cvw,42992
+koro/stage/__init__.py,sha256=kQs0k1NwhrRBhNvZOj8edYpKH_v8AkrAkuNm1ioQfI8,2547
+koro/stage/model.py,sha256=h2d9w68iXjQHcpVpEK61QjbYq9p9diRv-aCTiUgpW9c,8717
+koro/stage/part.py,sha256=o7ox1Y2RsfXyWG0Z4MQ49f7rXKP7y_Xl4qYqBBOjtZM,48640
+koro-2.0.0.post1.dist-info/LICENSE,sha256=Q2ptU2E48gOsMzhYz_kqVovmJ5d1KzrblLyqD2_-fvY,1235
+koro-2.0.0.post1.dist-info/METADATA,sha256=7gV_yfq4OmhP8gXaDlU_RQpmCZu7Rff9pjtoKr-2W_4,4371
+koro-2.0.0.post1.dist-info/WHEEL,sha256=Z4pYXqR_rTB7OWNDYFOm1qRk0RX6GFP2o8LgvP453Hk,91
+koro-2.0.0.post1.dist-info/top_level.txt,sha256=Msq6ssMwv56hnBQqwaTdJJkxM7x7BZ-3JfQbkepQAEY,5
+koro-2.0.0.post1.dist-info/RECORD,,

{koro-1.1.6.dist-info → koro-2.0.0.post1.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.41.2)
+Generator: setuptools (70.3.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

koro/file/__init__.py

@@ -1,40 +0,0 @@
-from os import remove
-from os.path import abspath, exists
-from shutil import rmtree
-
-__all__ = ["Location"]
-
-
-class Location:
-    __match_args__ = ("path",)
-    __slots__ = ("_path",)
-
-    _path: str
-
-    def __init__(self, path: str, /) -> None:
-        self._path = abspath(path)
-
-    def __bool__(self) -> bool:
-        """Whether this file location is accessible and exists."""
-        return exists(self.path)
-
-    def delete(self) -> None:
-        try:
-            remove(self.path)
-        except IsADirectoryError:
-            rmtree(self.path)
-
-    def __eq__(self, other: object, /) -> bool:
-        return (
-            self.path == other.path if isinstance(other, Location) else NotImplemented
-        )
-
-    def __hash__(self) -> int:
-        return hash(self.path)
-
-    @property
-    def path(self) -> str:
-        return self._path
-
-    def __repr__(self) -> str:
-        return f"{type(self).__name__}({self.path!r})"

koro/file/dir.py

@@ -1,212 +0,0 @@
-from collections.abc import Sequence
-from operator import index
-from os import SEEK_CUR
-from os.path import abspath, dirname, isfile, join
-from typing import Final, Optional, SupportsIndex, TypeGuard, overload
-
-from ..item.group import Group
-from ..item.level import Level, LevelNotFoundError
-from ..item.save import Page, Save
-from . import Location
-
-__all__ = ["DirGroup", "DirLevel", "DirLevelNotFoundError", "DirSave"]
-
-_BLOCK_SIZE: Final[int] = 2048
-_EMPTY_BLOCK: Final[bytes] = b"\x00" * _BLOCK_SIZE
-_LEVEL_ALLOCATION_SIZE: Final[int] = 156864
-
-
-class DirLevelNotFoundError(LevelNotFoundError):
-    pass
-
-
-class DirLevel(Level):
-    __match_args__ = ("path", "page", "id")
-    __slots__ = ("_offset", "_path")
-
-    _offset: int
-    _path: str
-
-    def __init__(self, path: str, /, page: Page, id: SupportsIndex) -> None:
-        i = index(id)
-        if 0 <= i < 20:
-            self._offset = 8 + _LEVEL_ALLOCATION_SIZE * (i & 3)
-            self._path = join(abspath(path), f"ed0{(id >> 2) + 5 * page.value}.dat")
-        else:
-            raise ValueError(id)
-
-    def __bool__(self) -> bool:
-        with open(self._path, "rb") as f:
-            f.seek(self._offset)
-            return f.read(1) != b"\x00"
-
-    def delete(self) -> None:
-        with open(self._path, "r+b") as f:
-            f.seek(self._offset)
-            more: bool = f.read(1) != b"\x00"
-            if more:
-                while more:
-                    f.seek(-1, SEEK_CUR)
-                    f.write(_EMPTY_BLOCK)
-                    more = f.read(1) != b"\x00"
-            else:
-                raise DirLevelNotFoundError
-
-    def __eq__(self, other: object, /) -> bool:
-        return (
-            self._offset == other._offset and self._path == other._path
-            if isinstance(other, DirLevel)
-            else NotImplemented
-        )
-
-    def __hash__(self) -> int:
-        return hash((self._offset, self._path))
-
-    @property
-    def id(self) -> int:
-        return int(self._path[-5]) % 5 << 2 | self._offset // _LEVEL_ALLOCATION_SIZE
-
-    def __len__(self) -> int:
-        if self:
-            with open(self._path, "rb") as f:
-                f.seek(self._offset)
-                block: Final[bytearray] = bytearray(f.read(_BLOCK_SIZE))
-                block_offset: int = 0
-                while block[-1]:
-                    f.readinto(block)
-                    block_offset += _BLOCK_SIZE
-                hi: int = _BLOCK_SIZE - 1
-                lo: int = 0
-                test: int
-                while hi != lo:
-                    test = (hi - lo >> 1) + lo
-                    if block[test]:
-                        lo = test + 1
-                    else:
-                        hi = test
-                return block_offset + hi
-        else:
-            raise DirLevelNotFoundError
-
-    @property
-    def page(self) -> Page:
-        return Page(ord(self._path[-5]) > 52)
-
-    @property
-    def path(self) -> str:
-        return dirname(self._path)
-
-    def read(self) -> bytes:
-        with open(self._path, "rb") as f:
-            f.seek(self._offset)
-            block: Final[bytearray] = bytearray(f.read(_BLOCK_SIZE))
-            if block[0]:
-                result: Final[bytearray] = bytearray()
-                while block[-1]:
-                    result.extend(block)
-                    f.readinto(block)
-                hi: int = _BLOCK_SIZE - 1
-                lo: int = 0
-                test: int
-                while hi != lo:
-                    test = (hi - lo >> 1) + lo
-                    if block[test]:
-                        lo = test + 1
-                    else:
-                        hi = test
-                return bytes(result + block[:hi])
-            else:
-                raise DirLevelNotFoundError
-
-    def __repr__(self) -> str:
-        return f"{type(self).__name__}({self.path!r}, {self.page!r}, {self.id!r})"
-
-    def write(self, new_content: bytes, /) -> None:
-        with open(self._path, "r+b") as f:
-            f.seek(self._offset)
-            f.write(new_content)
-            while f.read(1) != b"\x00":
-                f.seek(-1, SEEK_CUR)
-                f.write(_EMPTY_BLOCK)
-
-
-class DirGroup(Group[DirLevel]):
-    __match_args__ = ("path", "page")
-    __slots__ = ("_page", "_path")
-
-    _page: Page
-    _path: str
-
-    def __init__(self, path: str, /, page: Page) -> None:
-        self._page = page
-        self._path = abspath(path)
-
-    def __contains__(self, value: object, /) -> TypeGuard[DirLevel]:
-        return (
-            isinstance(value, DirLevel)
-            and value.path == self.path
-            and value.page is self.page
-        )
-
-    def count(self, value: object) -> int:
-        return int(value in self)
-
-    def __eq__(self, other: object, /) -> bool:
-        return (
-            self.page == other.page and self.path == other.path
-            if isinstance(other, DirGroup)
-            else NotImplemented
-        )
-
-    @overload
-    def __getitem__(self, index: SupportsIndex, /) -> DirLevel:
-        pass
-
-    @overload
-    def __getitem__(self, indices: slice, /) -> Sequence[DirLevel]:
-        pass
-
-    def __getitem__(
-        self, key: SupportsIndex | slice, /
-    ) -> DirLevel | Sequence[DirLevel]:
-        if isinstance(key, slice):
-            return tuple((self[i] for i in range(*key.indices(20))))
-        else:
-            i: int = index(key)
-            if -20 <= i < 20:
-                return DirLevel(self.path, self.page, i % 20)
-            else:
-                raise IndexError(key)
-
-    def __hash__(self) -> int:
-        return hash((self.path, self.page))
-
-    def index(self, value: object, start: int = 0, stop: Optional[int] = None) -> int:
-        if value in self and value.id in range(*slice(start, stop).indices(20)):
-            return value.id
-        else:
-            raise ValueError
-
-    @property
-    def page(self) -> Page:
-        return self._page
-
-    @property
-    def path(self) -> str:
-        return self._path
-
-    def __repr__(self) -> str:
-        return f"{type(self).__name__}({self.path!r}, {self.page!r})"
-
-
-class DirSave(Location, Save[DirGroup]):
-    __slots__ = ()
-
-    def __bool__(self) -> bool:
-        return all((isfile(join(self.path, f"ed0{i}.dat")) for i in range(10)))
-
-    def __getitem__(self, key: Page, /) -> DirGroup:
-        if isinstance(key, Page):
-            return DirGroup(self.path, key)
-        else:
-            raise KeyError(key)

koro/file/lvl.py

@@ -1,40 +0,0 @@
-from os.path import getsize
-from warnings import warn
-
-from ..item.level import Level, LevelNotFoundError
-from . import Location
-
-__all__ = ["LvlLevel", "LvlLevelNotFoundError"]
-
-
-class LvlLevelNotFoundError(FileNotFoundError, LevelNotFoundError):
-    pass
-
-
-class LvlLevel(Location, Level):
-    __slots__ = ()
-
-    def __init__(self, path: str, /) -> None:
-        super().__init__(path)
-        warn(
-            FutureWarning(
-                "The LVL format for storing level data is deprecated. Level data should be converted to the BIN format using BinLevel for better compression and compatibility."
-            )
-        )
-
-    def delete(self) -> None:
-        try:
-            return super().delete()
-        except FileNotFoundError as e:
-            raise LvlLevelNotFoundError(*e.args)
-
-    def __len__(self) -> int:
-        return getsize(self.path)
-
-    def read(self) -> bytes:
-        with open(self.path, "rb") as f:
-            return f.read()
-
-    def write(self, new_content: bytes, /) -> None:
-        with open(self.path, "wb") as f:
-            f.write(new_content)

koro/file/zip.py

@@ -1,223 +0,0 @@
-from collections.abc import Iterable, Sequence
-from itertools import filterfalse
-from operator import index
-from os.path import abspath
-from re import fullmatch
-from typing import Final, Optional, SupportsIndex, TypeGuard, overload
-from warnings import warn
-from zipfile import ZipFile, ZipInfo
-
-from ..item.group import Group
-from ..item.level import Level, LevelNotFoundError
-from . import Location
-from .bin import BinLevel
-
-__all__ = ["ZipGroup", "ZipLevel", "ZipLevelNotFoundError"]
-
-
-def _id_to_fn(id: SupportsIndex, /) -> str:
-    return f"{str(index(id) + 1).zfill(2)}.bin"
-
-
-def _id_to_old_fn(id: SupportsIndex, /) -> str:
-    return f"{str(index(id) + 1).zfill(2)}.lvl"
-
-
-class ZipLevelNotFoundError(KeyError, LevelNotFoundError):
-    pass
-
-
-class ZipLevel(Level):
-    __match_args__ = ("path", "id")
-    __slots__ = ("_id", "_path")
-
-    _id: int
-    _path: str
-
-    def __init__(self, path: str, /, id: SupportsIndex) -> None:
-        i: int = index(id)
-        if 0 <= i < 20:
-            self._id = i
-            self._path = abspath(path)
-        else:
-            raise ValueError(id)
-
-    def __bool__(self) -> bool:
-        with ZipFile(self.path) as a:
-            return self.fn in a.namelist()
-
-    def delete(self) -> None:
-        with ZipFile(self.path) as a:
-            if self.fn not in a.namelist() and self.old_fn not in a.namelist():
-                raise ZipLevelNotFoundError
-            contents: Final[dict[ZipInfo, bytes]] = {}
-            for info in filterfalse(
-                lambda info: info.filename == self.fn or info.filename == self.old_fn,
-                a.infolist(),
-            ):
-                contents[info] = a.read(info)
-        with ZipFile(self.path, "w") as a:
-            for x in contents.items():
-                a.writestr(*x)
-
-    def __eq__(self, other: object, /) -> bool:
-        return (
-            self.path == other.path and self.id == other.id
-            if isinstance(other, ZipLevel)
-            else NotImplemented
-        )
-
-    def __hash__(self) -> int:
-        return hash((self.path, self.id))
-
-    @property
-    def fn(self) -> str:
-        return _id_to_fn(self.id)
-
-    @property
-    def id(self) -> int:
-        return self._id
-
-    def __len__(self) -> int:
-        with ZipFile(self.path) as a:
-            try:
-                a.getinfo(self.fn)
-            except KeyError:
-                try:
-                    return a.getinfo(self.old_fn).file_size
-                except KeyError:
-                    raise ZipLevelNotFoundError
-            else:
-                return int.from_bytes(a.read(self.fn)[8:12], byteorder="big")
-
-    @property
-    def old_fn(self) -> str:
-        return _id_to_old_fn(self.id)
-
-    @property
-    def path(self) -> str:
-        return self._path
-
-    def read(self) -> bytes:
-        with ZipFile(self.path) as a:
-            try:
-                a.getinfo(self.fn)
-            except KeyError:
-                try:
-                    a.getinfo(self.old_fn)
-                except KeyError:
-                    raise ZipLevelNotFoundError
-                else:
-                    return a.read(self.old_fn)
-            else:
-                return BinLevel.decompress(a.read(self.fn))
-
-    def __repr__(self) -> str:
-        return f"{type(self).__name__}({self.path!r}, {self.id!r})"
-
-    def write(self, new_content: bytes, /) -> None:
-        contents: Final[dict[ZipInfo, bytes]] = {}
-        with ZipFile(self.path, "a") as a:
-            for info in filterfalse(
-                lambda info: info.filename == self.fn or info.filename == self.old_fn,
-                a.infolist(),
-            ):
-                contents[info] = a.read(info)
-        with ZipFile(self.path, "w") as a:
-            for x in contents.items():
-                a.writestr(*x)
-            a.writestr(self.fn, BinLevel.compress(new_content))
-
-
-class ZipGroup(Location, Group[ZipLevel]):
-    __slots__ = ()
-
-    def __init__(self, path: str) -> None:
-        super().__init__(path)
-        try:
-            with ZipFile(self.path) as a:
-                for id in range(20):
-                    if _id_to_old_fn(id) in a.namelist():
-                        warn(
-                            FutureWarning(
-                                "This ZipGroup contains levels using the deprecated LVL format. Update this file by writing to it or by using the update function."
-                            )
-                        )
-                        break
-        except FileNotFoundError:
-            pass
-
-    def __contains__(self, value: object, /) -> TypeGuard[ZipLevel]:
-        return isinstance(value, ZipLevel) and value.path == self.path
-
-    def count(self, value: object) -> int:
-        return int(value in self)
-
-    @overload
-    def __getitem__(self, index: SupportsIndex, /) -> ZipLevel:
-        pass
-
-    @overload
-    def __getitem__(self, indices: slice, /) -> Sequence[ZipLevel]:
-        pass
-
-    def __getitem__(
-        self, key: SupportsIndex | slice, /
-    ) -> ZipLevel | Sequence[ZipLevel]:
-        if isinstance(key, slice):
-            return tuple((self[i] for i in range(*key.indices(20))))
-        elif -20 <= index(key) < 20:
-            return ZipLevel(self.path, index(key) % 20)
-        else:
-            raise IndexError(key)
-
-    def index(self, value: object, start: int = 0, stop: Optional[int] = None) -> int:
-        if value in self and value.id in range(*slice(start, stop).indices(20)):
-            return value.id
-        else:
-            raise ValueError
-
-    def fill_mask(self) -> Sequence[bool]:
-        with ZipFile(self.path) as a:
-            return [
-                _id_to_fn(i) in a.namelist() or _id_to_old_fn in a.namelist()
-                for i in range(20)
-            ]
-
-    def read(self) -> Iterable[Optional[bytes]]:
-        with ZipFile(self.path) as a:
-            return [
-                BinLevel.decompress(a.read(_id_to_fn(id)))
-                if _id_to_fn(id) in a.namelist()
-                else a.read(_id_to_old_fn(id))
-                if _id_to_old_fn(id) in a.namelist()
-                else None
-                for id in range(20)
-            ]
-
-    def update(self) -> None:
-        self.write(self.read())
-        warn(
-            FutureWarning(
-                "This function will be removed alongside support for the LVL format, and exists soley as a convienient way of converting existing ZIP files to the new BIN format."
-            )
-        )
-
-    def write(self, new_content: Iterable[Optional[bytes]], /) -> None:
-        contents: Final[dict[ZipInfo, bytes]] = {}
-        if self:
-            with ZipFile(self.path) as a:
-                for info in filterfalse(
-                    lambda info: fullmatch(
-                        r"(0[1-9]|1\d|20)\.(bin|lvl)", info.filename
-                    ),
-                    a.infolist(),
-                ):
-                    contents[info] = a.read(info)
-        with ZipFile(self.path, "w") as a:
-            for x in contents.items():
-                a.writestr(*x)
-            for id, content in filterfalse(
-                lambda x: x[1] is None, enumerate(new_content)
-            ):
-                a.writestr(_id_to_fn(id), BinLevel.compress(content))

koro/item/group.py

@@ -1,48 +0,0 @@
-from abc import ABC
-from collections.abc import Iterable, Sequence
-from itertools import chain, repeat
-from typing import Final, Generic, Optional, TypeVar
-
-from .level import Level, LevelNotFoundError
-
-__all__ = ["Group"]
-
-_L = TypeVar("_L", bound=Level)
-
-
-class Group(ABC, Generic[_L], Sequence[_L]):
-    """A group of 20 levels.
-    Note that levels are 0-indexed within this interface, but 1-indexed in-game.
-    """
-
-    __slots__ = ()
-
-    def fill_mask(self) -> Sequence[bool]:
-        """Return which level IDs within this Group exist."""
-        return [bool(l) for l in self]
-
-    def __len__(self) -> int:
-        return 20
-
-    def read(self) -> Iterable[Optional[bytes]]:
-        """Read all of the levels within this Group. Empty slots yield None."""
-        content: Optional[bytes]
-        result: Final[list[Optional[bytes]]] = []
-        for level in self:
-            try:
-                content = level.read()
-            except LevelNotFoundError:
-                content = None
-            result.append(content)
-        return result
-
-    def write(self, new_content: Iterable[Optional[bytes]], /) -> None:
-        """Replace the contents of this Group with the specified new content. None values will empty the slot they correspond to."""
-        for src, dest in zip(chain(new_content, repeat(None)), self):
-            if src is None:
-                try:
-                    dest.delete()
-                except LevelNotFoundError:
-                    pass
-            else:
-                dest.write(src)