legacy-puyo-tools 2025.7.24

A tool to edit text for older Puyo Puyo games.

Legacy Puyo Tools

A command line tool for modding older Puyo Puyo games (Yes, the name is using a reversed naming scheme).

Installation

Install Python 3.10 or later, preferably the latest version.

legacy-python-tools is published to PyPI. It is recommended to install tools from PyPI into an isolated Python environment.

You can use pipx:

pipx install legacy-python-tools
# Or to run the cli without installing legacy-python-tools
pipx run legacy-python-tools

Or uv:

uv tool install legacy-python-tools
# Or to run the cli without installing legacy-python-tools
uv tool run legacy-python-tools
# Or the shorter uvx
uvx legacy-python-tools

And of course, you can use good old pip in a virtual Python environment using virualenv or the built-in venv library:

# Create a virtual python environment
python -m venv .venv
# Activate the virtual environment
./.venv/Scripts/activate
# Install legacy-python-tools
python -m pip install legacy-python-tools

Usage

Create a fpd file from a UTF-16 little-endian encoded text file.

legacy-puyo-tools create fpd puyo14.txt

Or convert a mtx file to an editable XML file using a fpd file.

legacy-puyo-tools convert mtx --output custom_als.mtx --fpd puyo14.fpd als.xml

You can use the --help flag to see what sub-commands and options are available.

Supported Games

This tool will try to support formats from the following Puyo games:

• Puyo Puyo! 15th Annversivery
• Puyo Puyo 7
• Puyo Puyo!! 20th Annversivery (If there is demand)

See Formats for detailed information about these formats, and the current progress on creating and converting them.

Why

The Puyo Text Editor 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.
• Easier migration when upgrade away from end of life language versions.
• Formats are stored in an intermediate representation before conversion.

Contributing

If you want to contribute to the project check out Contributing.

License

Under the MIT License. Based on Puyo Text Editor which is also under the MIT License. Some code is generated using AI in which they are licensed under the MIT-0 License.