dansalvato/melee-gci-compiler

Melee GCI Compiler is an application and scripting language that makes it easy for Super Smash Bros. Melee mod developers to inject custom code and data into Melee save files.

Melee GCI Compiler

Melee GCI Compiler is an application and scripting language that makes it easy for Super Smash Bros. Melee mod developers to inject custom code and data into Melee save files.

Background

Melee contains a buffer overflow exploit that can be used to trigger ACE (Arbitrary Code Execution). Developers can package their own custom code into a Melee save file, and then trigger the exploit in-game to run their code. This enables Melee mods to run natively on unmodified consoles using nothing more than a memory card and a special save file.

The exploit was originally discovered by wParam (website) in 2008 but went largely unnoticed by the competitive Melee community, as mods at the time were focused more on wacky fun than on competitive play.

Starting around 2013, training-focused AR/Gecko codes started to appear, with complete mod packs soon following, such as the 20XX Training Hack Pack (Smashboards).

When the save file exploit was rediscovered in 2014, 20XX Tournament Edition (website) became the second memory card mod and focused on the competitive Melee community by encouraging tournament organizers to use it.

In 2018, 20XXTE was used as a base to deliver UCF (Universal Controller Fix) as a memory card mod (website).

In 2019, UnclePunch's Training Mode (GitHub) built upon old knowledge with modern programming tools to deliver a refined and powerful training toolkit in memory card form.

During Melee's peak competitive years, mod developers were concerned that memory card mods could be used to easily cheat at major tournaments. So, they opted for "security by obscurity" and chose not to share the knowledge and tools they developed to create memory card mods. However, both the modding and competitive communities have evolved since then. I believe the time has come to preserve developer knowledge and ensure that this formerly enigmatic capability becomes accessible to future enthusiasts and competitive players. Preservation of the past and accessibility for the future are the core reasons I decided to make Melee GCI Compiler.

Requirements

Melee GCI Compiler requires Python 3.6 or higher. It also uses pre-compiled GNU GCC binaries powerpc-eabi-as, powerpc-eabi-ld, and powerpc-eabi-objcopy. For convenience, x86 binaries for Windows, macOS, and Linux are already included and will be called with no user configuration needed. ARM binaries are included for macOS (Apple Silicon) and Linux (Raspberry Pi, etc.).

macOS

You may get some permission-related errors on macOS. If you get a Permission denied error during ASM compilation, you will need to run chmod +x on the binary files in mgc/pyiiasmh/bin/darwin_xxxx (i386 or arm64 depending on your architecture).

It is also likely that macOS will block these binaries from being run due to being from an unidentified developer. If so, the system will tell you in a pop-up dialog. To get around this, go to Settings > Security & Privacy > General, where at the bottom you will find a "Run Anyway" button. You will need to do this three times, one for each binary. After doing so, run Melee GCI Compiler again, and the ASM compilation should succeed.

Documentation

Please see the doc folder for basic usage and an overview of the MGC scripting language features. The example folder contains example MGC script files with plenty of explanation text inside. Please feel free to examine the example script and try compiling it yourself.

Bugs

The most obvious sign of bugs is if you receive a Python stack trace - that means some case has been unhandled. If you want to hunt for bugs, try to cause stack traces and report them in the issue tracker!

If you believe MGC is mistakenly logging an error or some data is not being compiled correctly, please feel free to submit those issues as well, and they will be reviewed.

Attributions

Thanks to wParam for discovering and documenting the Melee save file exploit.

Thanks to metaconstruct for doing some incredible work to reverse engineer the encoding/decoding routines Melee uses to obfuscate its save files. Melee GCI Compiler is possible thanks to that. meleegci.py was written by metaconstruct, and gci_encode.py, the GCI encoding/decoding routine, is a Python re-implementation of his C program.

Thanks to Sean Power for PyiiASMH (Google Code), a Python wrapper for the PPC toolchain with a focus on generating Gecko codes, which is used (and thoroughly butchered) in Melee GCI Compiler.

Thanks to JoshuaMKW for updating and maintaining PyiiASMH (GitHub) with Python 3 support, even though I somehow didn't know about it until I started writing this readme, and therefore didn't use it.

Thanks to all my friends in the Melee modding community. I'm sorry I peaced out to go make an anime dating sim. Everyone is doing all these incredible things that I never dreamed would be possible with Melee.

melee-gci-compiler's Issues

Ironic second buffer overflow (in a buffer overflow exploit)

Hi Dan,

In the provided example !string "UCF Datafile" is placed in a 12-byte region of memory. This does not leave room for the null terminator, and the filename ends up overflowing. As a result, if you try to create a savefile after executing the payload, it crashes on console. In emulator, it throws a warning which can be ignored... but console behavior is a crash.

One possible fix to this would be to just choose a string which is 11 characters or less, leaving room for the null terminator. "UCF Datafi" was tested and works flawlessly on console. Other fixes are of course possible, but that would be the quickest and easiest in the provided example.

Thanks to @UnclePunch for figuring debugging the underlying reason for this.

Refactor compiler.py to avoid global variables

compiler.py should be refactored so that functions don't modify the state of non-local variables unless they are part of a class.

Possible solutions:

1. Put most of compiler.py in an encapsulating class so that the functions are modifying its own members, rather than something out of scope
2. Use a functional approach so that any mutable data belongs to the top-level function, and other functions return a "write table" instead of directly writing to the mutable data

[Question] Optional refactoring

Hey there, Dan.

This might read a bit weird, but I'm in the habit of offering random refactorings to people so that I don't get too rusty with my Python.

I wanted to check if there's interest in PRs before going ahead, though. Still, one of the parts I thought about touching up is command-line args processing, e.g. by switching to argparse, which should improve that section's readability compared to the additional logic you have to use for getopt to give equivalent results.