Super Paper Mario - Level Dumper

This is a Node.js script that reads a .wbfs archive of Super Paper Mario and dumps the level geometry for each level into a .obj file, so that the levels/maps can be opened with other tools and programs, such as Blender.

To use this script, just follow the directions below. You will provide your .wbfs file, and the script will generate a folder called "output" filled with 300+ levels in .obj format. Enjoy!

Right now, only geometry and collision data are converted. No vertex colors/textures are applied to the models, and camera data is ignored.

In the future, I hope to create (or help to create) a new version of this tool which dumps colors, textures, camera info, animations, and more- and switch to exporting in .glTF instead of .obj format. But until then, I hope some of you find this script useful!

System requirements:

• Free disk space: 1.25GB - Only needed while the script is running (to unpack the .wbfs archive). The resulting collection of .obj files will only take up 127MB.
• OS: Tested with x86_64 Debian-based Linux - This script only works on Linux systems with BASH shell (ZSH probably works too). Feel free to use WSL or a VM like VirtualBox (Windows) or UTM (MacOS) if you want to run it on another system.
• Installed tools: Node.js and Python3 - Tested and working with Node 18.13.0 and Python 3.11.2, but any realtively recent version of Node and Python should work fine. You don't need to use any package managers or install any dependencies. Just make sure Python is available in your path. (As long as you can open a terminal and type "python" or "python3" to launch the interpreter, you're all good here!)

Usage

1. Make sure you are using Linux and that a recent copy of Node.js and Python 3 are installed
2. Obtain a .wbfs copy of Super Paper Mario (in a legitimate manor)
3. Rename the .wbfs file to "spm.wbfs"
4. Download this repository (and extract it if you need to), or clone it:

git clone https://github.com/BraidenPsiuk/spm-level-dumper.git

5. Move your spm.wbfs file into the root of the repository
6. Open the repo using a terminal (cd into it)
7. Set the following permissions on bin-utils:

sudo chmod +x ./utils/bin-utils/*

8. Make sure you are still inside the repo, then run the script (no need to install any dependencies first, there are none):

node ./spm-level-dumper.mjs

That's it! Please note that the script may take a few minutes to complete. When it's finished, you'll find all of the levels in the "output" folder in the root of the repository. You might also find this document handy, it provides IDs and descriptions for each level.

Thanks to all the hard work by Andrew Ekstedt (magical), PistonMiner, Wiimm, and everyone else on the SPM/TTYD scene! Please see the "Credits" section below for more information about the scripts used in this repo.

Troubleshooting

• If you get a "python: not found" error, make sure Python 3+ is installed and available in your path. You might need to open the script in an editor and change the constant "PYTHON_BIN_NAME" from "python3" to "python".
• For a "Permission denied" error, make sure you've first set the proper permissions on the binaries inside "./utils/bin-utils". See step 7 under "Usage" above.
• If wit produces "ERROR #76 [CAN'T OPEN FILE]", you probably just need to ensure you've provided the .wbfs file as described in steps 3 and 5 under "Usage" above.

Can I just download the .obj files from somewhere?

For legal reasons, I don't feel comfortable distributing them. Please obtain your own .wbfs copy of the game and run this script to dump the levels yourself.

Credits

This script, simply put, is just a bunch of various community scripts hot-glued together to form one cohesive way to dump levels. I did not write any of the lower-level scripts that actually perform the raw decompression, unarchiving, and conversion. Here are the following scripts used, and their authors:

• Andrew Ekstedt's (magical's) nlzss: Specifically, their lzss3.py
• PistonMiner's ttyd-tools: Specifically, their ttydview.py
• Wiimm's ISO and SZS tools: Specifically, their wit ISO manipulation tool and wszst SZS tool.

I have copied and included the above scripts and binaries in this repo to make it convenient for users to download everything all at once. However, I want to make it clear that I had no part in writing any script other than spm-level-dumper.mjs. They are only included here in this repo for convenience and archival purposes. (If you have any problem with this, please open an issue.)

Safety / Security

This script has two instances where it uses "rm -rf" (a destructive operation). All file paths referenced in the script are relative to the repository root, so it should be safe as long as you run the script from inside the repository folder, and don't store anything important in the repository folder. But still, use caution. To avoid potential data loss, only run scripts you've inspected yourself first.