melee-pc

melee-pc

Beta, for testing only. "melee-pc" is a working name. Online play with rollback netcode is in development. This branch includes LAN, internet friend codes, Unranked matchmaking and ranked best-of-three sets. See Netplay for setup and verification limits.

A native PC port of Super Smash Bros. Melee (NTSC-U 1.02), built from doldecomp/melee on top of aurora (GX/OS/PAD/DVD/CARD/THP compatibility layer with a WebGPU backend) and SDL3. Same approach as dusklight.

You need your own disc image. No game data ships here. The decompiled game code is not licensed and is not relicensed by this project; only the port code is GPL-3.0-or-later. Details under License.

New here? The project site has the five-step setup, the FAQ (supported disc, Windows first run, older Intel GPUs, first-use shader stutter, Android requirements, where the log and settings live) and the per-platform known-issues list. Bugs go through the bug report form; questions on Discord.

Features

• Native builds for Linux (x86-64, aarch64), Windows (x86-64, ARM64), macOS, Android and iOS, rendered through Dawn/WebGPU (Vulkan, D3D12, D3D11, Metal) and SDL3.
• RmlUi launcher with disc selection and SHA-1 verification against the Redump database before boot.
• In-game settings overlay on F1, with the game paused underneath.
• Internal resolution from Auto to 10x native (6400x4800).
• Post-processing shaders: area sampling, CRT scanlines, vibrant.
• 4x MSAA and anisotropic filtering up to 16x.
• Gamepad remapping, including C-stick directions, saved per device.
• Software AX audio mixer with Master, Music and SFX volume controls.
• User .ogg / .wav tracks replace stage BGM.
• Dolphin-compatible .gci memory cards and Dolphin-format HD texture packs.
• Cheats: Unlock Everything, hazardless (Frozen) Pokémon Stadium, free pause camera, Wide 16:9 HUD.
• UCF 0.8x dashback and shield drop, and a raw 1000 Hz read path for the official GameCube controller adapter.

What each of those actually covers, including the parts that are unfinished, is in the status table below.

Screenshots

Main menu	Character select
Stage select	Four-player match
Onett	F1 settings overlay

Status

Every mode boots and plays: VS, 1-P Classic / Adventure / All-Star to completion with results and score saved, Training, Stadium (Target Test, Home-Run Contest, 10-Man Melee), Event Match, Trophy gallery, memory card create / load, opening movie and attract demos.

This table is the single source of truth for feature status. The release notes, the project site and ROADMAP.md defer to it; when they disagree, this table is right and the other one is stale.

Feature	Status	Note
Linux x86-64 / aarch64	done	AppImage and tarball, both built in CI.
Windows x86-64 / ARM64	done	D3D12 or Vulkan; ARM64 via llvm-mingw.
Direct3D 11 backend (Windows)	partial	Compiled into the shipped Dawn for both architectures, ordered after D3D12 and selectable as MELEE_BACKEND=d3d11. The adapter enumerates and the fail-over to D3D12 is proven, but no working D3D11 device has been observed; Wine/Proton cannot create one (CreateDeviceContextState returns E_INVALIDARG), so it is unverified on real Windows and on the Intel Gen7 hardware it exists for.
Android arm64	done	Drawn on-screen GameCube overlay with opacity, deadzone and haptics settings; hides itself when a physical gamepad is connected.
iOS arm64	partial	Sideloadable IPA on Metal, cross-built from Linux. Touch input is fixed invisible screen regions (stick on the left half, face buttons bottom right) with no drawn overlay, no calibration and no gamepad auto-hide -- the Android overlay is Android-only.
macOS Apple Silicon / Intel	partial	Apple Silicon tested; both architectures must build before a release. Intel hardware remains untested.
Browser (WebGPU)	partial	Play in the browser with your own raw GALE01 rev 2 image; tested in Chrome. No online play, no gamepad remapping. Build: tools/browser/build.py.
PAL disc (GALP01)	partial	Experimental: USA game code on PAL data, English (UK) text, NTSC 60 Hz. Trophy tables are stubbed out rather than read, and there is no reference hash, so PAL images always verify as unknown.
Widescreen 16:9 / window aspect	partial	VS, Sudden Death and Training only; menus, results and cutscenes stay at the original 73:60.
Wide HUD anchoring	done	Separate on/off toggle from the aspect setting, and only moves anything while widescreen is on. Anchors the timer and the 2-4 player HUD groups (damage, stocks, tags); a 1-player HUD keeps its original placement. No configurable margins.
Custom texture packs (Dolphin format)	done	tex1_* .dds / .png including sidecar mips and TLUT hashes, scanned recursively, reloadable from the F1 menu.
Custom soundtrack (.ogg / .wav)	done	Replaces any track the game streams, not just stage BGM. Files are decoded whole into RAM (not streamed) and loop end to end, so a track's own loop point is ignored.
Unlock Everything / Frozen Stadium / Free camera	done	Gameplay page in the launcher and the F1 menu.
Multi-bus audio (Master / Music / SFX)	done	Three sliders; Master is the output stream gain, Music and SFX are per-voice.
In-app update check	done	Polls GitHub releases, downloads with progress.
Controller rumble	done	SDL gamepads through the game's own PADControlMotor calls, and the Android device vibrator when the pad has no rumble. Controller LED / port-colour sync is not implemented.
1000 Hz GameCube adapter (WUP-028)	partial	Implemented and wired, not yet confirmed against a physical adapter. Raw 0x21 reports are read through SDL's hidapi on the 1000 Hz input thread, so the game would see the controller's real 8-bit values instead of SDL's rescaled ones; adapter slot N is PAD port N, and the slot motors are driven from the game's rumble state. MELEE_GC_ADAPTER=0 hands the device back to SDL's driver. Linux needs a udev rule; the log prints it.
UCF (dashback, shield drop)	done	UCF 0.8x rules; launcher Gameplay page / F1 port menu, default off, MELEE_UCF=1. Reads the octagon-clamped stick rather than UCF's pre-clamp raw queue, which only differs past the 80-unit rim.
Discord Rich Presence	planned	Deferred until API credentials are available.
Extended hazardless stages	planned	Whispy, Randall, FoD platforms. Only Pokémon Stadium is implemented.
2-player keyboard remapping	planned	The keyboard is port 1 on a fixed layout.
High-refresh interpolation	planned
Training tools (hitboxes, savestates, frame advance)	planned
Replay recording (.slp)	done	Set MELEE_SLP_DIR to record offline or online VS matches; off by default.
Online play (LAN / direct IP)	partial	LAN/direct-IP plus signed internet Direct, Unranked and Ranked implemented. Every datagram is authenticated (protocol 9), so both peers must run the same build, and a connect code is 8 characters after the #. Phone VPN to home broadband Direct Connect reached results; broader two-NAT and live ranked acceptance remain pending. See platform matrix below.
RetroAchievements	planned

The phases behind the planned rows, and why they are ordered that way, are in ROADMAP.md.

Download

Builds for every platform are on the releases page. Release notes list the per-platform files, known issues and requirements.

./Melee-x86_64.AppImage                  # open the launcher
./Melee-x86_64.AppImage /path/to/melee.iso

Melee USA revision 2 (NTSC-U 1.02, GALE01) is the supported disc. A Europe (PAL, GALP01) image also boots, with the limits listed in the status table and the mechanics in porting-notes.md. .iso, .gcm, .ciso and .rvz images are accepted. A valid disc path on the command line boots straight in; a missing or invalid one returns to the launcher. Settings and the selected path live in launcher.cfg in SDL's melee-pc preference directory (usually ~/.local/share/melee-pc, %APPDATA%\melee-pc on Windows, or ~/Library/Application Support/melee-pc on macOS).

Verification reads the disc through nod, compressed images included, and compares SHA-1 against the Redump DAT: d4e70c064cc714ba8400a849cf299dbd1aa326fc, 1,459,978,240 bytes. It supports progress and cancellation, and is not cached between launches. Unverified images still play; PAL images have no reference hash and always report as unverified.

Building from source: docs/building.md.

Requirements

The renderer is WebGPU (Dawn) at its compatibility level, so the floor is Dawn's per-backend floor:

Platform	API tried, in order	Floor
Windows 10/11 (x86-64, ARM64)	Direct3D 12 → Direct3D 11 → Vulkan	Feature level 11_0. Dawn refuses D3D12 on Intel Gen7 (HD 4000/4400/4600, Ivy Bridge/Haswell); the intended fallback for those is Direct3D 11, which is untested on that hardware (see the status table). Vulkan 1.1 with a vendor ICD.
Linux (x86-64, aarch64)	Vulkan	Vulkan 1.1 (Mesa radv/anv/hasvk, NVIDIA proprietary or NVK).
macOS / iOS	Metal	Any Metal GPU; Apple Silicon tested, iOS 14+.
Android	Vulkan	Vulkan 1.1, arm64.

On Windows that means any Intel Gen8 (Broadwell, 2014) or newer, AMD GCN or newer, NVIDIA Fermi or newer runs on Direct3D 12. Direct3D 11 is a compatibility path, not a performance one (FXC shaders, no DXC). OpenGL is never picked automatically: MELEE_BACKEND=opengl exists, but Dawn needs desktop GL 4.4 for it, it draws with wrong (washed-out) colours on X11 and cannot create a surface on Wayland. The log records every backend that was skipped and why, then one summary line with the adapter and driver.

The CPU side is light: any x86-64 (SSE2) or arm64 CPU. A VS match holds a steady 60 fps with the whole game pinned to two 2.5 GHz Meteor Lake low-power E-cores, using about a third of one core in total.

• Keep resources/ (and on Windows the DLLs: webgpu_dawn.dll, dxcompiler.dll, dxil.dll, SDL3.dll, the VC++ runtime) beside the executable. dxcompiler.dll and dxil.dll are the D3D12 shader compiler; D3D11 needs no extra DLL, since d3d11.dll, dxgi.dll and the FXC compiler are Windows components.
• Packages use the project's patched SDL: SDL3.dll on Windows, libSDL3.so on Linux and libSDL3.0.dylib inside the macOS app. Keep the Linux tarball's lib/ directory and launch with run.sh. Android, iOS and browser builds link the same SDL source into the app. Windows builds include libusb inside SDL3.dll; no separate libusb DLL is required.
• Settings, memory cards, music/ and textures/ live in the melee-pc preference directory above.
• For portable desktop installs, create an empty portable.txt beside the executable. Settings, saves, caches, logs, music and textures then use its user/ directory. Existing preferences are not moved automatically; copy your existing data there if wanted. The install directory must be writable. In a macOS app bundle, the marker and user/ go in Contents/Resources/.
• Texture packs can also go in textures/ beside the executable; enable custom textures in Settings and use the F1 reload action after changing a pack.

Controls

Keyboard: arrows or WASD = stick, IJKL = C-stick, X = A, Z = B, C = X, V = Y, Q/E = L/R, Tab = Z, Enter = Start, TFGH = D-pad. Gamepads work through SDL; an official GameCube adapter is read directly instead (see the status table).

	Keyboard	Gamepad
Navigate	Up/Down, Tab	D-pad or left stick
Adjust	Left/Right	D-pad left/right
Choose category	Up/Down in the sidebar	D-pad up/down
Enter category	Right or Enter	Right or A
Select	Enter	A
Back / close overlay	Escape goes back, F1 closes	B goes back; Start or menu button closes

Settings overlay

F1, or Back/Select on a gamepad, opens the overlay. The game pauses while it is open.

• Display: fullscreen/windowed and VSync apply immediately. MELEE_VSYNC overrides the saved preference.
• Internal resolution and UI scale are sliders. UI scale covers 75% to 150%.
• Post-processing picks the presentation shader and applies immediately.
• Anti-aliasing and anisotropic filtering apply on the next launch. MSAA offers only off and 4x because WebGPU guarantees sample counts 1 and 4.
• Audio: master volume, mute, FPS counter, all immediate.
• Controls remaps gamepads and the player-one keyboard. Cycle the port selector to Keyboard to edit keys. Select a binding, then press the desired input; Escape cancels, Delete clears, and Restore defaults resets that device. Controller buttons accept stick directions, and stick directions accept either an axis or a button. Menu button changes the gamepad shortcut; F1 and Guide remain available. Keyboard F1 and Escape are reserved.
• Quit game in the sidebar exits through normal save and shutdown handling.
• On Android, launcher Settings → Launcher → Diagnostics → Export logs saves device details and recent app logs to a document you choose. Attach it to a crash report after reopening the app. Logs may be lost after reboot or when Android rotates its log buffer.

Melee's own menu sounds play in the overlay. Bindings are stored in aurora's per-device .controller files; keyboard bindings and the menu shortcut share launcher.cfg with the other preferences.

Environment variables

Variable	Effect
MELEE_BACKEND=<name>	Pin the graphics backend (vulkan, d3d12, d3d11, metal, ...) instead of the platform's preferred order; an unknown name lists the valid ones.
MELEE_VSYNC=0|1	Override the saved VSync preference.
MELEE_LOG_FILE=<path>	Write the log to a file (default melee-pc.log beside melee.exe on Windows; empty disables).
MELEE_WINDOW_TITLE=<t>	Window title.
MELEE_FILES_DIR=<dir>	Loose-file overlay: files here (or in ./files/) replace the disc's.
MELEE_CACHE_MAX_MB=<n>	In-memory archive cache budget (default picked from installed RAM).
MELEE_PREWARM=0	Skip the background asset pre-warm after boot.
MELEE_FAST_FADES=1	Clamp scene fade delays.
MELEE_PIPELINE_JOBS=<n>	Background shader-pipeline compile threads (default half the hardware threads, 1..8).
MELEE_UCF=1	Universal Controller Fix (UCF 0.8x dashback and shield-drop rules); overrides the ucf launcher.cfg pref.
MELEE_GC_ADAPTER=0	Hand the GameCube adapter (WUP-028) back to SDL's gamepad driver instead of reading it raw.
MELEE_SLP_DIR=<dir>	Record every VS match, offline or netplay, as a Slippi replay <dir>/Game_YYYYMMDDTHHMMSS.slp (replay format 3.18.0) that Slippi Launcher, slippi-js stats, Clippi and overlays read. Only frames no rollback can change are written, so both netplay peers' files hold the same frames. Off by default.
--no-card	Boot without a memory card.
--dvd <image>	Explicit form of the positional disc argument.
--version	Print the build version and exit.

Diagnostic knobs (MELEE_DEBUG, MELEE_FPS, MELEE_HEAP_CHECK, the AURORA_* draw filters, ...) are listed in docs/debugging.md.

Community

• Discord for questions and testing.
• Project site for setup, FAQ and known issues.
• Bug report form; attach the log (melee-pc.log on Windows, see docs/debugging.md).

Netplay (LAN and direct IP, prototype)

Two copies of the game play a rollback match over UDP (src/pc/net.c; design and current state in docs/netcode-plan.md). Both must run the same build and the same game image, with no memory card (--no-card). The LAN lobby announces a 32-bit id of the disc it booted (region, revision, file-table shape and the DOL, so a code mod counts), and a peer on a different image is listed as incompatible before a single game packet is exchanged — same as a different build version. Internet friend-code pairing also binds build and disc identity; the legacy direct-IP environment path retains its older protocol-version-only check.

In the menus: VS Mode → ONLINE → LAN PLAY finds other copies on the local network by mDNS and the first Start elects a host (lowest install id wins a tie). DIRECT CONNECT opens an in-game hub where either player can call a friend's NAME#XXXXXXXX code, enter its eight-character suffix, or choose a clipboard code or recent opponent. UNRANKED searches for an opponent; RANKED runs a rated best-of-three set. PROFILE shows your code and locally verified rating. Internet discovery may take about 30 seconds to bootstrap and some NATs cannot support a direct peer connection. Legacy MELEE_LAN_DIRECT=ip:port remains available for direct-IP sessions. The game port is UDP 41000 by default and discovery uses UDP 5353 multicast; allow both through the firewall (Windows asks on first launch). The install id used for the election is install_id in launcher.cfg.

If the link drops mid-match, the session no longer dies with it: after 7 s of silence it enters a reconnect phase and resumes where it left off if the peer comes back within 15 s and neither side's 64-frame input ring has been outrun. The lobby shows "reconnecting"; a failure that cannot be resumed says "Could not resume" instead of "Connection timed out".

A peer that is loading is not a peer that is gone. Silence is measured from the last datagram the peer sent, not from how long this side has been waiting: a machine whose game thread is inside a stage load, a character load or a first-time shader compile keeps its sender running, so the link carries it however long it takes and the transition screen simply waits. Before that distinction existed, any load over 7 s froze both games on "NOW LOADING" and one over ~22 s ended the session outright, which is what a phone's first match cost.

What works where. Only Linux x86-64 has played real matches, but a Linux recording now replays bit-identical on Windows, so the two builds compute the same game.

Platform	Netplay	Rollback	Notes
Linux x86-64	yes	yes	the configuration everything below was measured on; longest run 36 minutes and 126k frames of match
Windows x86-64 / ARM64	implemented	enabled	PE ranges cover both supported toolchains. x86-64 restore runs under Wine; ARM64 compiler-bridge and linked-range checks pass. Full Windows rollback gameplay remains unverified
macOS / iOS	builds; online gameplay unverified	enabled	Mach-O simulation sections support Intel/Apple Silicon macOS and ARM64 iOS. Cross-link/bridge checks pass; native restore is