Super Smash Bros Melee

This repo contains a WIP decompilation of Super Smash Bros Melee (US).

It builds the following DOL:

v1.02 - main.dol: sha1: 08e0bf20134dfcb260699671004527b2d6bb1a45

Building

Windows

The easiest way to get set up is with scoop. You will also need our compilers (linked below).

1. Open a PowerShell window (Win+X). You do not need admin privileges.
2. Install scoop, git, python, and mingw. You can skip these if you already have git, python (3.9+), bash, gcc, and make in your PATH.

   Set-ExecutionPolicy RemoteSigned -Scope CurrentUser # Optional: Needed to run a remote script the first time
   irm get.scoop.sh | iex
   scoop install git python mingw

3. Clone the repository and change directory into it.

   cd ~/Documents # Or wherever you want to put Melee
   git clone 'https://github.com/doldecomp/melee.git'
   cd melee

4. Download our compilers zip archive and rename the GC subfolder to mwcc_compiler, and place it in /tools. You can do this manually, or use the following PowerShell snippet (from inside your melee directory):

   $url = 'https://cdn.discordapp.com/attachments/727909624342380615/1129879865433264158/MELEE_COMPILERS_N.zip'
   $tmp = New-TemporaryFile
   Invoke-WebRequest -Uri $url -OutFile $tmp
   $zip = Rename-Item $tmp -NewName ($tmp.BaseName + '.zip') -PassThru
   
   $dir = New-Item -ItemType Directory `
       -Path (Join-Path $env:Temp 'MELEE_COMPILERS')
   
   Expand-Archive -Path $zip -DestinationPath $dir
   
   $path = Get-ChildItem -Path $dir.FullName | `
           Select-Object -ExpandProperty FullName
   Copy-Item -Path $path -Destination "tools/mwcc_compiler" -Recurse
   
   Remove-Item -Force $zip
   Remove-Item -Recurse -Force $dir

5. Run make using bash to build the project:

   bash -c 'make -j"$NUMBER_OF_PROCESSORS" GENERATE_MAP=1'

6. Optional: Install a Python virtual environment. If you want to use the Python tooling we have in /tools, you can create a venv. This tooling is not required to build the project, but you'll need it if you want to use asm-differ, m2ctx, etc.

   python -m venv --upgrade-deps 'venv'

   • You'll need to activate it whenever you open a new shell.

     venv/Scripts/Activate.ps1

   • After that, you can install or update our packages with:

     pip install -r 'requirements.txt' --use-pep517

   • Now you can run m2ctx to get a context to use with decomp.me. The following command will add it to your clipboard automatically; you can run with --help to see all the options:

     python tools/m2ctx/m2ctx.py -px

7. Check out our Getting Started guide!

Linux

Requirements

• devkitPro
• python3 (pacman -S python3)
• gcc (pacman -S gcc)

Instructions

1. Download MELEE_COMPILERS.zip and extract the GC compilers to tools/mwcc_compiler/.
2. Run the make command:

   make -j$(nproc) GENERATE_MAP=1

You can refer to our Dockerfile to see how our CI builds on Ubuntu.

Containers

We offer containerized Linux and Windows build environments, which you can run through podman or docker on any supported platform, including macOS.

melee_path="$PWD"
make_flags='GENERATE_MAP=1'
build_target="$melee_path/build"

docker run --rm \
  --volume "$melee_path:/input:ro" \
  --volume "$build_target:/output" \
  --env MAKE_FLAGS="$make_flags" \
  ghcr.io/doldecomp/melee/build-linux:latest

Contributing

Contributions are welcome! If you're new to decomp, check out our Getting Started guide. Before opening a pull request, please read our contributing guidelines. If you're new to Git and don't know how to create a pull request, we encourage you to create an issue with your decomp.me link and a maintainer will add your code to the repository.

We're also happy to answer any questions in the #melee channel on Discord.

FAQ

What can be done after decompiling Melee?

Note that this project's purpose is to only match the ASM with C code. This is entirely for research and archival purposes. After this is created, you essentially have a C project that can be compiled into Melee, but it won't be portable (aka you can't compile it to run on a normal computer).

So creating mods would be a lot easier as C code is much easier to consume than ASM. However, there are additional projects that could be undertaken once this is complete, but those technical endeavours are out-of-scope for this repo.

Do we know how the compiler works?

• Kind of. We don’t have its source though.

How do we get the compiler to pick a certain register allocation?

Considering we don't have the source for the compiler, this is kind of "anything goes" territory. Unfortunately register allocation is an NP-hard problem which means there are all types of heuristics you can use to select registers, some of which can be confused by things as silly as variable names.

One option is to attempt to automatically permute the source code to get the correct register allocation.