SMASH ULTIMATE / NATIVE MAC BUILD

Super Smash Bros. Ultimate on Mac: GitHub Build Guide

Build the Mac app from your own game files.

Prepare the Mac ↓

  • Apple silicon, macOS 26+
  • Full Xcode and Metal toolchain
  • Python 3.14
  • About 30 GB free on the work drive for a fresh build

Your own files

  • 1.0.0 base game, XCI or NSP
  • Separate 13.0.2 or 13.0.5 update NSP
  • Your prod.keys

A base NSP also needs system fonts.

Sheik and Yoshi in a Smash Ultimate Mac match, cropped from Human Sirat’s 13.0.2 demonstration.
13.0.2 Mac game footage · Human Sirat’s 24 October demonstration ↗, 0:03. Cropped to the game.

Match the base game, update and Mac target

The update’s verified contents choose the supported runtime
InputMatchHow to use it
Base game1.0.0 · 01006A800016E000Your own XCI card image. A base NSP also works when you provide system fonts.
Update13.0.2 or 13.0.5 · 01006A800016E800Separate update NSP. The script identifies its ExeFS hashes, rather than trusting the filename.
Keys / fontsYour own prod.keysXCI can supply its system-update fonts. For base NSP, add --firmware or a verified --shared-fonts folder.
DLCYour purchased fighter/costume packagesOptional owned dumps; add at build time or through the Mac app’s DLC menu.

This guide is the MacNativeGames SSBU target. Its runtime and scripts live inside games/ssbu. The top-level TOTK wizard is not its build command. This source has no iPhone/iPad build: Smash loads 98 code modules while running, which this iOS route cannot load.

13.0.2

Use the matching update

The project records World of Light, Smash matches, DLC, sound, photos and save/reload. Keep this update with its own verified build inputs.

13.0.5

Same fighters and modes, different main

The source supports a separate verified main executable for 13.0.5. It reuses the same 98 fighter/stage/mode modules; renaming a 13.0.2 package will not make it this update.

Prepare Xcode, Python and codec libraries

  1. Check the Mac and full Xcode

    Use an Apple silicon Mac with macOS 26 or later. Install full Xcode, finish its first-run setup and make its Metal compiler available. Command Line Tools alone do not meet this target’s stated toolchain requirement.

    Install the Xcode Metal component
    xcodebuild -downloadComponent MetalToolchain
  2. Install the four codec libraries

    Use native Apple silicon Homebrew and Python 3.14. The build checks the libraries under /opt/homebrew/opt; an Intel Homebrew installation is a different prefix.

    SSBU Homebrew dependencies
    brew install python@3.14 opus libvpx libvorbis libogg
  3. Reserve the work space

    The script asks for about 30 GB free for a fresh workspace. Its game resource image is about 17.6 GB. On the same APFS volume, the app uses a clone of those resources; copying to another volume needs additional space. Keep work, source and output paths outside temporary or cloud-synced folders.

Run the dedicated SSBU builder

  1. Open this fixed source folder

    The following checkout matches this guide. Run it in a new source folder, then stay inside games/ssbu.

    Download the source and open the SSBU target
    git clone https://github.com/ly05010419/MacNativeGames.git
    cd MacNativeGames
    git checkout 32d8643554d2f106b60fa7c5a0d6e57cf16aca49
    cd games/ssbu
  2. Replace the example paths with your own

    The example uses the 13.0.5 update and an XCI base. For 13.0.2, select your actual 13.0.2 NSP instead. Keep base and update as separate inputs.

    Build Smash 13.0.5 from an XCI base
    python3.14 scripts/build_ssbu.py \
      --game "$HOME/Games/Smash/base.xci" \
      --update "$HOME/Games/Smash/update-13.0.5.nsp" \
      --keys "$HOME/keys/prod.keys" \
      --out "$HOME/Applications/Super Smash Bros. Ultimate.app"
    Base NSP, existing fonts, NSZ or a custom workspace
    • Base NSP: replace --game with its path and add --firmware "$HOME/Games/firmware-nca", pointing to your unpacked firmware NCA folder.
    • Alternatively, use --shared-fonts "/path/to/verified-shared-fonts". It must contain the verified manifest and six font files, not an arbitrary font directory.
    • An NSZ update must first be decompressed with nsz -D; the builder takes an NSP update.
    • Add --work "$HOME/Games/SSBU-work" to change the work location. Default: games/ssbu/SSBU_build.
    • Optional purchased DLC: add --dlc "$HOME/Games/Smash/DLC".
  3. Wait through verification and shader preparation

    The build identifies the update, verifies game inputs, rewrites code/modules, extracts resources/fonts and prepares startup shaders. A later build reuses verified steps. If the game is running from the workspace, the build waits for it to close.

  4. Open the resulting app

    The example writes to ~/Applications/Super Smash Bros. Ultimate.app. Without --out, the app goes next to the base game file. Open that app, check sound and input, then try a short match before changing settings. Use the macOS first-open guide for a specific launch warning.

Base + supported update + keys→games/ssbu/scripts/build_ssbu.py→Super Smash Bros. Ultimate.app

32d8643: exact flags, input checks, work-space guard and output path ↗

Set the picture size before starting the next session

Sheik and Yoshi fighting on the same stage in the 13.0.2 Mac demonstration.
13.0.2 Mac demonstration · Human Sirat ↗

Start with one familiar match

Start at 1080p. Check sound, movement and attacks before changing the picture.

Then choose 2K, restart and compare the same fighters and stage. MetalFX upscales the finished image to the window; it is separate from the source render size.

English shortcut labels: overlays, interpolation, picture, aspect ratio, edge smoothing, controller type and mouse.

Separate overlay shortcuts from render-size selection

Find the picture and controller shortcuts

English overlay from the 24 October 13.0.2 demonstration, 0:03. Key 3 controls upscaling; use the Picture menu for the base render size. The table below gives the full shortcut descriptions.

Image source ↗
View the full overlay Historical English Smash Mac overlay showing numbered shortcuts for overlays, interpolation, picture, aspect ratio, smoothing, controller and mouse.Open full-size image ↗
Current guide source 32d8643 · game-specific controls
ControlAction
1Cycle all overlays → FPS only → off. The FPS line includes picture size and MetalFX.
2Frame interpolation produces no additional frames in this target. Leave it off.
3Toggle MetalFX upscaling of the finished picture.
4Change picture aspect ratio in the window.
5Toggle MetalFX Temporal edge smoothing.
6Choose automatic or a fixed controller type.
7Toggle mouse mode.

The project’s older M1 Max 64 GB/macOS 27 record covers 1–2 hour 2K sessions. Its later M5 32 GB/macOS 27.2 record covers 13.0.5 matches with MetalFX on/off. For your first setup, keep the same scene and change one option at a time rather than treating either machine’s result as a preset for every Mac.

Connect a controller or learn the keyboard mapping

Physical controller

  1. Pair by Bluetooth or connect by USB in macOS. Check the device appears before opening the game.
  2. Open Smash and start with automatic controller selection.
  3. Test movement, confirm/back and shoulder buttons in a short match. Key 6 cycles controller type if automatic detection needs correction.

The source maps recognized devices as a Pro Controller and also has a direct HID path for some pads, including PowerA. Follow Mac pairing and connection fixes if the device is absent.

Keyboard

WASD
Left stick
Arrow keys
Right stick
J / K or Space
A / B
I / U
X / Y
Q / E
L / R
Return
+

The Mac host’s numbered shortcuts are separate from Smash’s own in-game control settings. Changing a controller type does not change an unrelated game’s keyboard file.

Add your DLC without rebuilding the whole app

  1. Keep purchased packages together

    Put your own DLC dumps in one stable folder. The build can include it with --dlc; packages are verified with your keys.

  2. Choose the folder in the Mac menu bar

    While the app runs, open DLC → Choose DLC Folder… and select that folder. The menu reports the number of DLC packages and fighters it found. Use the same menu to enable or disable DLC.

  3. Restart and check the added fighters

    The selection applies at the next start. Relaunch and check the game’s announcement and fighter selection. An unchanged session will not reload the new folder immediately.

The source’s online menu returns to offline play. DLC packages add owned content; they do not enable online services or Labo VR.

Back up the whole SSBU state before switching builds

Game state
~/Library/Application Support/MacNativeGames/SSBU
Saves, local shader cache and per-game state. The builder leaves this folder in place.
Session log
~/Library/Logs/MacNativeGames/ssbu.log
The app’s Log menu controls logging for the next start; session archives remain.
Photos
~/Pictures/Super Smash Bros. Ultimate
Default PNG destination. Photos → Show in Finder opens it; the game’s Album remains empty.
  1. Save and close the game

    Wait for the save operation, then quit before copying files.

  2. Open the state folder in Finder

    Press ⌘⇧G, paste the game-state path above and copy the complete SSBU folder to an external backup location. Include the game version and date in its name.

  3. Test the new build without losing the old copy

    Use a separate output app/workspace and the intended update. Both apps still use the same default SSBU state, so another app filename is not save isolation. Keep the old app and backup until the expected World of Light or other progress loads.

  4. Restore a copy if needed

    Close the game. Rename the current state folder to keep it, copy the backup back as SSBU under MacNativeGames, then launch the matching game version and load the expected slot. Keep the original backup unchanged.

For an update, changing the source revision and changing the game patch are separate actions. Start with one change, rebuild into a separate output and check the same save before continuing.

Fix the exact symptom

Update or ExeFS hash is rejected
  1. Use the supported13.0.2 or 13.0.5 update NSP with the 1.0.0 base.
  2. Check whether the selected package is an update, not the base or an NSZ. The script checks contents; a renamed file will still fail.
NSP build reports missing fonts
  1. Add --firmware pointing to your unpacked firmware NCA folder, or --shared-fonts pointing to a previously verified manifest plus six fonts.
  2. Do not combine both font flags. Keep the game and font-input paths readable for the whole build.
Build reports missing Homebrew packages or Metal tools
  1. Install opus, libvpx, libvorbis and libogg using native /opt/homebrew. Check Python 3.14.
  2. Select full Xcode and download its MetalToolchain component, then retry the failed build with the verified workspace retained.
Build waits, or a new stage pauses
  1. Close the game if it is running from the build workspace.
  2. The first build extracts resources and prepares shaders. Retain the work cache for later builds; check free space and the first relevant build log before deleting anything.
Resolution or DLC did not change
  1. Picture size and DLC selection apply on the next start.
  2. Quit and reopen the intended app. Use Picture for 1080p/2K and DLC for the owned package folder. Keep key 3 for MetalFX in this guide’s source.
Key 2 does not raise the displayed frame rate
  1. This SSBU host does not generate interpolation frames.
  2. Use1080p first, compare the same stage and tune MetalFX separately. Do not paste TOTK interpolation variables into the SSBU recipe.
Photos are missing from Album, or online closes
  1. Open Photos → Show in Finder for the saved PNGs. The in-game Album is not populated.
  2. The online menu is answered as an offline console; return to the supported local modes.
A save disappeared after rebuilding
  1. Check the game version and default SSBU state folder before starting new progress.
  2. Separate app names share the same default state. Restore a copy of the matching version’s backup with the game closed.

For a report, include Mac/chip/memory, macOS, source revision, game update, selected picture mode and the first error from the build or session log. Attach the relevant screen, not game packages, keys or the compiled game.

11 November 2026 · MacNativeGames source 32d8643 · Game 13.0.2 / 13.0.5 · Apple silicon, macOS 26+.

Source versions and next steps

The game and English overlay excerpts are cropped from that demonstration to remove the desktop and profile. The key 3 picture/upscaling label is explained beside the image; current settings follow the pinned source. Game images belong to Nintendo and the respective rights holders.