Data interchange, editor suite, and runtime re-implementations for games by Retro Studios
Go to file
Phillip Stephens d29df977f3 Minor fixes 2023-06-21 13:22:49 -07:00
.github/workflows ci: Temporarily disable release workflow 2022-11-23 10:07:54 -05:00
NESEmulator Migrate to aurora submodule 2022-07-29 16:17:24 -04:00
Runtime Minor fixes 2023-06-21 13:22:49 -07:00
Shaders Fully decouple hecl from Metaforce 2022-02-21 08:01:06 -08:00
assets Add new screenshot + Trilogy note to 2021-06-03 10:28:39 -04:00
bintoc The Great Removal 2022-03-09 00:06:42 -05:00
ci ci: Fix build-dmg when crashpad_handler is disabled 2022-06-13 19:20:32 -04:00
extern Various minor fixes 2023-01-22 14:22:28 -08:00
gbalink gbalink: Amend code to compile with jbus changes 2019-09-04 01:56:04 -04:00
imgui Update submodules; changes for emscripten support 2022-08-03 18:19:57 -04:00
lldb-extras Rename everything 2021-04-10 01:42:06 -07:00
.clang-format Update .clang-{format,tidy} 2020-07-07 04:34:35 -04:00
.clang-tidy Resolve clang-tidy issues & update config 2021-05-29 18:45:08 -04:00
.gitignore Updates based on universal branch 2021-06-11 21:19:33 -04:00
.gitmodules Update nativefiledialog-extended 2022-08-29 12:49:49 -04:00
CMakeLists.txt Update submodules; changes for emscripten support 2022-08-03 18:19:57 -04:00
CMakePresets.json CMakePresets: Set VCPKG_SETUP_CMAKE_PROGRAM_PATH=OFF 2022-08-03 18:20:48 -04:00
LICENSE Start renaming project to Metaforce 2021-04-06 18:58:11 -04:00 Update 2022-11-23 10:49:13 -05:00
ios.toolchain.cmake iOS and tvOS support 2022-05-27 15:52:16 -04:00 The Great Removal 2022-03-09 00:06:42 -05:00 Update submodules; changes for emscripten support 2022-08-03 18:19:57 -04:00

Metaforce Build Status Discord Badge

A reverse-engineered, native reimplementation of Metroid Prime.

This project is currently in alpha state.
Builds are currently unavailable while the project undergoes large changes.

Separately, a matching decompilation of Metroid Prime is currently underway. Contributions are welcome.
Progress on the decompilation benefits Metaforce with bug fixes and new implementations.

Metaforce screenshot

Platform Support

  • Windows 10+ (64-bit, D3D12 / Vulkan / OpenGL)
  • macOS 10.15+ (Metal)
  • Linux (Vulkan / OpenGL)
    • Follow this guide to set up Vulkan & appropriate drivers for your distro.



  • Open metaforce.exe


  • Open


  • Ensure AppImage is marked as executable: chmod +x Metaforce-*.AppImage
  • Open Metaforce-*.AppImage

CLI options (non-exhaustive)

  • -l: Enable console logging
  • --warp [worldid] [areaid]: Warp to a specific world/area. Example: --warp 2 2
  • +developer=1: Enable developer UI

Build Prerequisites:

  • CMake 3.15+
    • Windows: Install CMake Tools in Visual Studio
    • macOS: brew install cmake
  • Python 3+
    • Windows: Microsoft Store
      • Verify it's added to %PATH% by typing python in cmd.
    • macOS: brew install python@3
  • [Windows] Visual Studio 2019 Community
    • Select C++ Development and verify the following packages are included:
      • Windows 10 SDK
      • CMake Tools
      • C++ Clang Compiler
      • C++ Clang-cl
  • [macOS] Xcode 11.5+
  • [Linux] Actively tested on Ubuntu 20.04, Arch Linux & derivatives.
    • Ubuntu 20.04+ packages
      build-essential curl git ninja-build clang lld zlib1g-dev libcurl4-openssl-dev \
      libglu1-mesa-dev libdbus-1-dev libvulkan-dev libxi-dev libxrandr-dev libasound2-dev libpulse-dev \
      libudev-dev libpng-dev libncurses5-dev cmake libx11-xcb-dev python3 python-is-python3 \
      libclang-dev libfreetype-dev libxinerama-dev libxcursor-dev python3-markupsafe libgtk-3-dev
    • Arch Linux packages
      base-devel cmake ninja llvm vulkan-headers python python-markupsafe clang lld alsa-lib libpulse libxrandr freetype2
    • Fedora packages
      cmake vulkan-headers ninja-build clang-devel llvm-devel libpng-devel
      • It's also important that you install the developer tools and libraries
        sudo dnf groupinstall "Development Tools" "Development Libraries"

Prep Directions

git clone --recursive
cd metaforce

Update Directions

cd metaforce
git pull
git submodule update --recursive

Build Directions

For Windows, it's recommended to use Visual Studio. See below.

ninja (Windows/macOS/Linux)

Builds using RelWithDebInfo by default.

cmake -B out -G Ninja # add extra options here
cmake --build out --target metaforce hecl visigen

CMake configure options

  • Build in debug mode (slower runtime speed, better backtraces): -DCMAKE_BUILD_TYPE=Debug
  • Use clang+lld (faster linking): -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++
  • Optimize for current CPU (resulting binaries are not portable): -DMETAFORCE_VECTOR_ISA=native

CLion (Windows/macOS/Linux)

(main development / debugging IDE)

Open the repository's CMakeLists.txt.

Optionally configure CMake options via File > Settings > Build, Execution, Deployment > CMake.

Qt Creator (Windows/macOS/Linux)

Open the repository's CMakeLists.txt via File > Open File or Project.

Configure the desired CMake targets to build in the Projects area of the IDE.

Visual Studio (Windows)

Verify all required VS packages are installed from the above Build Prerequisites section.

Open the metaforce directory in Visual Studio (imports CMake configuration).

MSVC and clang-cl configurations should import automatically.

Xcode (macOS)

cmake -G Xcode ../metaforce

Then open metaforce.xcodeproj