legacy-puyo-tools 0.0.1__py3-none-any.whl

legacy_puyo_tools/__init__.py

@@ -0,0 +1,8 @@
+"""A conversion tool for files used by the older Puyo games.
+
+Supports Puyo Puyo 7 and possibly Puyo Puyo! 15th Anniversary `mtx` and
+`fpd` files. Puyo Puyo!! 20th Anniversary is still not supported yet.
+
+SPDX-FileCopyrightText: 2025 Samuel Wu
+SPDX-License-Identifier: MIT
+"""

legacy_puyo_tools/cli.py

@@ -0,0 +1,177 @@
+"""A commandline application that interfaces with conversion tools.
+
+SPDX-FileCopyrightText: 2025 Samuel Wu
+SPDX-License-Identifier: MIT
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from codecs import BOM_UTF16_LE
+from collections.abc import Callable
+from importlib import metadata
+from pathlib import Path
+from typing import BinaryIO
+
+from attrs import define
+
+from legacy_puyo_tools.exceptions import FileFormatError
+from legacy_puyo_tools.fpd import Fpd
+from legacy_puyo_tools.mtx import Mtx
+
+
+@define
+class _CliNamespace(argparse.Namespace):
+    func: Callable[[type[_CliNamespace]], None]
+    input: BinaryIO
+    output: BinaryIO
+    unicode: BinaryIO
+    fpd: BinaryIO
+    version: bool
+
+
+def _create_fpd(args: _CliNamespace) -> None:
+    if args.input.read(2) != BOM_UTF16_LE:
+        raise FileFormatError(
+            f"{args.input.name} is not a UTF-16 little-endian encoded text"
+            "file."
+        )
+
+    if args.output:
+        Fpd.read_unicode(args.input).write_fpd(args.output)
+        return
+
+    path = Path(args.input.name).with_suffix("")
+
+    if path.suffix != ".fpd":
+        path = path.with_suffix(".fpd")
+
+    Fpd.read_unicode(args.input).write_fpd_to_path(path)
+
+
+def _create_mtx(args: _CliNamespace) -> None:
+    raise NotImplementedError()
+
+
+def _convert_fpd(args: _CliNamespace) -> None:
+    if args.output:
+        args.output.write(BOM_UTF16_LE)
+        Fpd.read_fpd(args.input).write_fpd(args.output)
+        return
+
+    path = Path(args.input.name).with_suffix("")
+
+    if path.suffix != ".fpd":
+        path = path.with_suffix(".fpd")
+
+    Fpd.read_fpd(args.input).write_unicode_to_path(path)
+
+
+def _convert_mtx(args: _CliNamespace) -> None:
+    if args.fpd:
+        fpd_data = Fpd.read_fpd(args.fpd)
+    else:
+        if args.unicode.read(2) != BOM_UTF16_LE:
+            raise FileFormatError(
+                f"{args.input.name} is not a UTF-16 little-endian encoded text"
+                "file."
+            )
+
+        fpd_data = Fpd.read_unicode(args.unicode)
+
+    if args.output:
+        Mtx.read_mtx(args.input).write_xml(args.output, fpd_data)
+        return
+
+    path = Path(args.input.name).with_suffix("")
+
+    if path.suffix != ".xml":
+        path = path.with_suffix(".xml")
+
+    Mtx.read_mtx(args.input).write_xml_to_file(path, fpd_data)
+
+
+def _create_parsers(main_parser: argparse.ArgumentParser) -> None:
+    shared_options = argparse.ArgumentParser(add_help=False)
+    shared_options.add_argument(
+        "input", type=argparse.FileType("rb"), help="input file"
+    )
+    shared_options.add_argument(
+        "-o", "--output", type=argparse.FileType("wb"), help="output file"
+    )
+
+    mtx_options = argparse.ArgumentParser(
+        add_help=False, parents=[shared_options]
+    )
+    mtx_options_group = mtx_options.add_mutually_exclusive_group(required=True)
+    mtx_options_group.add_argument(
+        "--fpd", type=argparse.FileType("rb"), help="fpd file"
+    )
+    mtx_options_group.add_argument(
+        "--unicode", type=argparse.FileType("rb"), help="unicode text file"
+    )
+
+    sub_parser = main_parser.add_subparsers()
+
+    create_parser = sub_parser.add_parser("create")
+    create_sub_parser = create_parser.add_subparsers(required=True)
+
+    create_fpd_parser = create_sub_parser.add_parser(
+        "fpd",
+        help="create a fpd file from a unicode text file",
+        parents=[shared_options],
+    )
+    create_fpd_parser.set_defaults(func=_create_fpd)
+
+    create_mtx_parser = create_sub_parser.add_parser(
+        "mtx", help="create a mtx file from a XML file", parents=[mtx_options]
+    )
+    create_mtx_parser.set_defaults(func=_create_mtx)
+
+    convert_parser = sub_parser.add_parser("convert")
+    convert_sub_parser = convert_parser.add_subparsers(required=True)
+
+    convert_fpd_parser = convert_sub_parser.add_parser(
+        "fpd",
+        help="convert a fpd file to a unicode file",
+        parents=[shared_options],
+    )
+    convert_fpd_parser.set_defaults(func=_convert_fpd)
+
+    convert_mtx_parser = convert_sub_parser.add_parser(
+        "mtx", help="convert a mtx file to XML file", parents=[mtx_options]
+    )
+    convert_mtx_parser.set_defaults(func=_convert_mtx)
+
+
+def main() -> None:
+    """Entry point for the commandline application."""
+    main_parser = argparse.ArgumentParser(
+        description="A conversion tool for files used by older Puyo games."
+    )
+    main_parser.add_argument(
+        "-v", "--version", help="show version", action="store_true"
+    )
+
+    _create_parsers(main_parser)
+
+    args = main_parser.parse_args(namespace=_CliNamespace)
+
+    if args.version is True:
+        package_name = "legacy-puyo-tools"
+        version = metadata.version(package_name)
+
+        print(f"{package_name} {version}")
+
+        sys.exit(0)
+
+    if not hasattr(args, "func"):
+        main_parser.print_help(sys.stderr)
+        sys.exit(1)
+
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

legacy_puyo_tools/exceptions.py

@@ -0,0 +1,13 @@
+"""Exceptions that might be thrown when parsing files.
+
+SPDX-FileCopyrightText: 2025 Samuel Wu
+SPDX-License-Identifier: MIT
+"""
+
+
+class FormatError(Exception):
+    """The current input data does not conform to an expected format."""
+
+
+class FileFormatError(FormatError):
+    """The file does not conform to a file format or is malformed."""

legacy_puyo_tools/fpd.py

@@ -0,0 +1,288 @@
+"""fpd conversion tool for older puyo games.
+
+This module supports the encoding and decoding of the fpd format used by
+Puyo Puyo! 15th Anniversary and Puyo Puyo 7.
+
+SPDX-FileCopyrightText: 2025 Samuel Wu
+SPDX-License-Identifier: MIT
+"""
+
+from codecs import BOM_UTF16_LE
+from io import BytesIO
+from pathlib import Path
+from typing import BinaryIO, Self
+
+from attrs import define
+
+from legacy_puyo_tools.exceptions import FileFormatError, FormatError
+
+ENCODING = "utf-16-le"
+FPD_ENTRY_LENGTH = 3
+UTF16_LENGTH = 2
+WIDTH_ENTRY_OFFSET = 2
+
+
+@define
+class FpdCharacter:
+    """A fpd character entry.
+
+    A fpd character is a binary entry that is 3 bytes long and formatted
+    as follows: `XX XX YY`. Where `XX XX` is the character encoded in
+    UTF-16 LE and `YY` is the width of the character.
+
+    Attributes:
+        code_point:
+            A string that stores a single character.
+        width:
+            How wide should the character be, only used in the Nintendo
+            DS versions of the games.
+    """
+
+    code_point: str
+    width: int
+
+    def __init__(self, code_point: bytes, width: int = 0x00) -> None:
+        """Initializes a fpd character.
+
+        Args:
+            code_point:
+                A Unicode character in the UTF-16 LE format.
+            width:
+                The width of the character. Defaults to 0x00.
+        """
+        self.code_point = code_point.decode(ENCODING)
+        self.width = width
+
+    def encode(self) -> bytes:
+        """Encodes the character back to a fpd character entry.
+
+        Returns:
+            The character in UTF-16 LE format and its width.
+        """
+        return self.code_point.encode(ENCODING) + self.width.to_bytes()
+
+    @classmethod
+    def decode(cls, fpd_entry: bytes) -> Self:
+        """Decodes a fpd character into its code point and width.
+
+        Args:
+            fpd_entry:
+                A fpd character entry that is 3 bytes long.
+
+        Raises:
+            FormatError:
+                The entry given does not conform to the fpd character
+                format.
+
+        Returns:
+            A fpd character entry containing its code point and width.
+        """
+        if len(fpd_entry) != FPD_ENTRY_LENGTH:
+            raise FormatError(
+                f"{fpd_entry} does not matches size {FPD_ENTRY_LENGTH}"
+            )
+
+        return cls(fpd_entry[:UTF16_LENGTH], fpd_entry[WIDTH_ENTRY_OFFSET])
+
+
+@define
+class Fpd:
+    """A fpd character table.
+
+    The fpd stores character table in which each entry is placed right
+    next to each other and the indices is offset by multiples of `0x03`.
+    I.e. The 1st character is at index `0x00`, the 2nd character is at
+    index `0x03`, the 3rd character is at index `0x06`, etc.
+
+    Attributes:
+        entries:
+            A list of fpd character entries.
+    """
+
+    entries: list[FpdCharacter]
+
+    def __getitem__(self, index: int) -> str:
+        """Retrieves a character from the fpd character table.
+
+        Args:
+            index:
+                The index of the character to retrieve.
+
+        Returns:
+            A string that contains the requested character.
+        """
+        return self.entries[index].code_point
+
+    @classmethod
+    def read_fpd_from_path(cls, path: Path) -> Self:
+        """Reads and extract characters from a fpd file.
+
+        Args:
+            path:
+                A path to a fpd encoded file that contains a fpd
+                character table.
+
+        Raises:
+            FileFormatError:
+                The fpd file contain a entry that does not conform
+                to the fpd character format.
+
+        Returns:
+            A fpd character table.
+        """
+        with Path(path).open("rb") as fp:
+            try:
+                return cls.read_fpd(fp)
+            except FormatError as e:
+                raise FileFormatError(f"{path} is not a valid fpd file") from e
+
+    @classmethod
+    def read_fpd(cls, fp: BinaryIO) -> Self:
+        """Reads and extract characters from a file object.
+
+        Args:
+            fp:
+                A file object that points to a fpd encoded stream.
+
+        Returns:
+            A fpd character table.
+        """
+        return cls.decode_fpd(fp.read())
+
+    @classmethod
+    def decode_fpd(cls, data: bytes) -> Self:
+        """Extracts the fpd character table from a fpd encoded stream.
+
+        Args:
+            data:
+                A fpd encoded stream that contains a fpd character
+                table.
+
+        Returns:
+            A fpd character table.
+        """
+        return cls([
+            FpdCharacter.decode(data[i : i + FPD_ENTRY_LENGTH])
+            for i in range(0, len(data), FPD_ENTRY_LENGTH)
+        ])
+
+    def write_fpd_to_path(self, path: Path) -> None:
+        """Writes the fpd character table to a fpd encoded file.
+
+        Args:
+            path:
+                A path to write the fpd encoded stream.
+        """
+        with Path(path).open("wb") as fp:
+            self.write_fpd(fp)
+
+    def write_fpd(self, fp: BinaryIO) -> None:
+        """Writes the fpd character table to a file object.
+
+        Args:
+            fp:
+                A binary file object.
+        """
+        fp.write(self.encode_fpd())
+
+    def encode_fpd(self) -> bytes:
+        """Encodes the fpd character table into a fpd encoded stream.
+
+        Returns:
+            A fpd encoded stream that contains the fpd character table.
+        """
+        with BytesIO() as bytes_buffer:
+            for character in self.entries:
+                bytes_buffer.write(character.encode())
+
+            return bytes_buffer.getvalue()
+
+    @classmethod
+    def read_unicode_from_path(cls, path: Path) -> Self:
+        """Reads and convert characters from a UTF-16 LE text file.
+
+        Arguments:
+            path:
+                A path to a UTF-16 LE text file.
+
+        Raises:
+            FileFormatError:
+                The file is not a UTF-16 LE encoded text file or is
+                missing the Byte Order Mark for UTF-16 LE.
+
+        Returns:
+            A fpd character table.
+        """
+        with Path(path).open("rb") as fp:
+            # Check the Byte Order Mark (BOM) to see if it is really a
+            # UTF-16 LE text file
+            if fp.read(2) != BOM_UTF16_LE:
+                raise FileFormatError(f"{path} is not a UTF-16 LE text file.")
+
+            return cls.read_unicode(fp)
+
+    @classmethod
+    def read_unicode(cls, fp: BinaryIO) -> Self:
+        """Reads and convert UTF-16 LE characters from a file object.
+
+        Args:
+            fp:
+                A binary file object.
+
+        Returns:
+            A fpd character table.
+        """
+        return cls.decode_unicode(fp.read())
+
+    # TODO: Somehow allow people to specify the width of the character
+    # during decoding
+    @classmethod
+    def decode_unicode(cls, unicode: bytes) -> Self:
+        """Converts a UTF-16 LE stream into a fpd character table.
+
+        Args:
+            unicode:
+                A UTF-16 LE encoded character stream.
+
+        Returns:
+            A fpd character table.
+        """
+        return cls([
+            FpdCharacter(unicode[i : i + UTF16_LENGTH])
+            for i in range(0, len(unicode), UTF16_LENGTH)
+        ])
+
+    def write_unicode_to_path(self, path: Path) -> None:
+        """Writes the fpd character table to a UTF-16 LE text file.
+
+        Args:
+            path:
+                A path to store the converted UTF-16 LE text file.
+        """
+        with Path(path).open("wb") as fp:
+            # Write the Byte Order Mark (BOM) for plain text editors
+            fp.write(BOM_UTF16_LE)
+
+            self.write_unicode(fp)
+
+    def write_unicode(self, fp: BinaryIO) -> None:
+        """Writes the fpd character table to a file object.
+
+        Args:
+            fp:
+                A binary file object.
+        """
+        fp.write(self.encode_unicode())
+
+    def encode_unicode(self) -> bytes:
+        """Encodes the fpd character table into a UTF-16 LE text stream.
+
+        Returns:
+            A UTF-16 LE encoded text stream with characters from the
+            fpd.
+        """
+        with BytesIO() as bytes_buffer:
+            for character in self.entries:
+                bytes_buffer.write(character.code_point.encode(ENCODING))
+
+            return bytes_buffer.getvalue()

legacy_puyo_tools/mtx.py

@@ -0,0 +1,141 @@
+"""Manzai text conversion tool for older Puyo Puyo games.
+
+This module converts `mtx` files to and from XML for modding Puyo games.
+Currently supports Puyo Puyo 7 and might support Puyo Puyo! 15th
+Anniversary.
+
+SPDX-FileCopyrightText: 2025 Samuel Wu
+SPDX-License-Identifier: MIT
+"""
+
+from collections.abc import Callable
+from itertools import pairwise
+from pathlib import Path
+from typing import BinaryIO, Literal, Self
+
+from attrs import define
+from lxml import etree
+
+from legacy_puyo_tools.exceptions import FileFormatError, FormatError
+from legacy_puyo_tools.fpd import Fpd
+
+CHARACTER_WIDTH = 2
+ENDIAN = "little"
+
+INT32_OFFSET = 8
+INT32_SIZE = 4
+INT64_OFFSET = 16
+INT64_SIZE = 8
+
+
+def _read_character(data: bytes, i: int) -> int:
+    return int.from_bytes(data[i : i + CHARACTER_WIDTH], ENDIAN)
+
+
+def _create_offset_reader(width: int) -> Callable[[bytes, int], int]:
+    def offset_reader(data: bytes, i: int) -> int:
+        return int.from_bytes(data[i : i + width], ENDIAN)
+
+    return offset_reader
+
+
+def _identify_mtx(data: bytes) -> tuple[Literal[8, 16], Literal[4, 8]]:
+    if int.from_bytes(data[:4], ENDIAN) == INT32_OFFSET:
+        return (INT32_OFFSET, INT32_SIZE)
+
+    if int.from_bytes(data[8:16], ENDIAN) == INT64_OFFSET:
+        return (INT64_OFFSET, INT64_SIZE)
+
+    raise FormatError("The given data is not in a valid `mtx` format")
+
+
+type MtxString = list[int]
+
+
+@define
+class Mtx:
+    strings: list[MtxString]
+
+    @classmethod
+    def read_mtx_from_file(cls, path: Path) -> Self:
+        with Path(path).open("rb") as fp:
+            try:
+                return cls.read_mtx(fp)
+            except FormatError as e:
+                raise FileFormatError(
+                    f"{path} is not a valid `mtx` file"
+                ) from e
+
+    @classmethod
+    def read_mtx(cls, fp: BinaryIO) -> Self:
+        return cls.decode_mtx(fp.read())
+
+    @classmethod
+    def decode_mtx(cls, data: bytes) -> Self:
+        length = int.from_bytes(data[:4], ENDIAN)
+
+        if length != len(data):
+            raise FormatError("The size of the given data does not match")
+
+        section_table_index_offset, int_width = _identify_mtx(data[4:16])
+        read_offset = _create_offset_reader(int_width)
+
+        section_table_offset = read_offset(data, section_table_index_offset)
+        string_table_offset = read_offset(data, section_table_offset)
+
+        sections = [
+            read_offset(data, section_table_offset + (i * int_width))
+            for i in range(
+                (string_table_offset - section_table_offset) // int_width
+            )
+        ]
+
+        # Add the length to the sections so we can read to end of stream
+        sections.append(length)
+
+        strings: list[MtxString] = []
+
+        for current_string_offset, next_string_offset in pairwise(sections):
+            strings.append([
+                _read_character(
+                    data, current_string_offset + (i * CHARACTER_WIDTH)
+                )
+                for i in range(next_string_offset - current_string_offset)
+            ])
+
+        return cls(strings)
+
+    def write_xml_to_file(self, path: Path, fpd: Fpd) -> None:
+        with Path(path).open("wb") as fp:
+            self.write_xml(fp, fpd)
+
+    def write_xml(self, fp: BinaryIO, fpd: Fpd) -> None:
+        fp.write(self.encode_xml(fpd))
+
+    def encode_xml(self, fpd: Fpd) -> bytes:
+        root = etree.Element("mtx")
+        sheet = etree.SubElement(root, "sheet")
+
+        for string in self.strings:
+            dialog = etree.SubElement(sheet, "text")
+            dialog.text = "\n"
+
+            for character in string:
+                match character:
+                    case 0xF813:
+                        dialog.append(etree.Element("arrow"))
+                    # TODO: Figure out what this control character does
+                    case 0xF883:
+                        dialog.text += "0xF883"
+                    case 0xFFFD:
+                        dialog.text += "\n"
+                    case 0xFFFF:
+                        break
+                    case _:
+                        dialog.text += fpd[character]
+
+        etree.indent(root)
+
+        return etree.tostring(
+            root, encoding="utf-8", xml_declaration=True, pretty_print=True
+        )

legacy_puyo_tools-0.0.1.dist-info/METADATA

@@ -0,0 +1,34 @@
+Metadata-Version: 2.4
+Name: legacy-puyo-tools
+Version: 0.0.1
+Summary: A tool to edit text for older Puyo Puyo games.
+Author-email: Samuel Wu <twopizza9621536@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: attrs>=25.3.0
+Requires-Dist: lxml>=6.0.0
+Description-Content-Type: text/markdown
+
+# Legacy Puyo Tools
+
+Supports Puyo Puyo 7 and possibly Puyo Puyo! 15th Anniversary `mtx` and `fpd`
+files. Puyo Puyo!! 20th Anniversary is still not supported yet. (Create an issue
+or pull request to support `fnt` and additional `mtx` controls). Also, legacy as
+in older Puyo Puyo games, not that this tool is decapitated.
+
+## Why
+
+The [Puyo Text Editor][1] can already do what Legacy Puyo Tools does and is the
+inspiration of this tool, but there are advantages to rewrite it in Python:
+
+- Better cross compatibility with Linux.
+- Don't have to update the language version every time it becomes End of Life.
+- Avoids the rigidness of using a pure object-oriented design.
+
+## License
+
+Under the MIT License. Based on [Puyo Text Editor][1] which is also under the
+MIT License.
+
+[1]: https://github.com/nickworonekin/puyo-text-editor

legacy_puyo_tools-0.0.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+legacy_puyo_tools/__init__.py,sha256=tTzyNju0CFsXWki9ttjO6qnNx4Dlmur-1zgJ-n9toB0,277
+legacy_puyo_tools/cli.py,sha256=gqwjiuSqAzuJRc_Tei1WRxRWGMC0AycWhf940oY-UrY,4934
+legacy_puyo_tools/exceptions.py,sha256=vqoMG7VjUddzWGMIvzWtE18U6fnmMW7VcpwdOIoOiBc,341
+legacy_puyo_tools/fpd.py,sha256=XXVCMlYD_eJAhmIQzDlRFvqm-FG9imm68bLooM2-mi4,8306
+legacy_puyo_tools/mtx.py,sha256=8dGHE719LuOZ9fi8uEgAKh5YIdCuvo9bXAEbcwxaC8Q,4253
+legacy_puyo_tools/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+legacy_puyo_tools-0.0.1.dist-info/METADATA,sha256=PCxhnsrQHopcml8PQbgEuBGBP4z_4rPbZWHMkFftFxc,1167
+legacy_puyo_tools-0.0.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+legacy_puyo_tools-0.0.1.dist-info/entry_points.txt,sha256=SWkgMVVrmWMKaFJXbb0vx-qAjqMWnxm3_0AVwYCdZLs,65
+legacy_puyo_tools-0.0.1.dist-info/licenses/LICENSE,sha256=hu6L3ztT5uuc-EMaEgsjrhAHSTh56efyD-tVaEpc7Rw,1066
+legacy_puyo_tools-0.0.1.dist-info/RECORD,,

legacy_puyo_tools-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

legacy_puyo_tools-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+legacy-puyo-tools = legacy_puyo_tools.cli:main

legacy_puyo_tools-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2025 Samuel Wu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.