Data interchange, editor suite, and runtime re-implementations for games by Retro Studios
Go to file
Phillip Stephens c979a925d8
Implement CMediumAllocPool
2022-01-16 18:30:47 -08:00
.github/workflows ci: Use buildcache fork for release builds 2021-10-26 21:29:50 -04:00
DataSpec Fix VISI being broken 2022-01-09 17:16:32 -08:00
NESEmulator Rename everything 2021-04-10 01:42:06 -07:00
Runtime Implement CMediumAllocPool 2022-01-16 18:30:47 -08:00
Shaders Move all submodules to extern 2021-04-06 15:07:45 -04:00
assetnameparser Fix macOS/Linux issues 2021-06-30 16:27:53 -04:00
assets Add new screenshot + Trilogy note to 2021-06-03 10:28:39 -04:00
ci ci: Fix file arg in altool 2021-06-12 12:48:20 -04:00
extern Update submodules 2022-01-10 23:29:33 -08:00
gbalink gbalink: Amend code to compile with jbus changes 2019-09-04 01:56:04 -04:00
gmm Start renaming project to Metaforce 2021-04-06 18:58:11 -04:00
hecl Blender detection fixes 2022-01-10 21:54:18 -08:00
imgui Use UTF-8 exclusively internally 2021-06-30 14:20:45 -04:00
lldb-extras Rename everything 2021-04-10 01:42:06 -07:00
metaforce-gui Blender detection fixes 2022-01-10 21:54:18 -08:00
mpcksum CActorContraption fixes, better CMake dependency handling 2019-06-11 16:05:17 -10:00
visigen Fix macOS/Linux issues 2021-06-30 16:27:53 -04: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 Remove freetype2 submodule 2021-05-29 18:45:08 -04:00
CMakeLists.txt Add -wno-unused-but-set-variable to disabled warnings 2021-11-22 23:52:13 -08:00
CMakePresets.json [ci] Disable LTO for Linux builds (memory issue) 2021-10-25 19:16:57 -04:00
LICENSE Start renaming project to Metaforce 2021-04-06 18:58:11 -04:00 Add blender known issues with workarounds 2021-12-06 23:09:51 -08:00 Typo fix 2019-04-06 19:49:21 -10:00 Remove Editor & specter 2021-05-29 18:45:07 -04:00 Fix version info 2022-01-09 21:51:34 -08:00


Formerly known as URDE

Status: Metroid Prime 1 In-Game (all retail GC & Wii versions)

Official Discord Channel:

Metaforce screenshot


This project is currently in Alpha state, so expect bugs.
Builds available at

Platform Support

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

Usage (GUI)


  • Open metaforce-gui.exe


  • Open


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

CLI usage (GC versions)

  • Extract ISO: hecl extract [path].iso -o mp1
    • mp1 can be substituted with the directory name of your choice
  • Repackage game for Metaforce: cd mp1; hecl package
  • Run Metaforce: metaforce mp1/out

CLI usage (Wii versions)

IMPORTANT: Trilogy main menu currently doesn't work, and requires the --warp 1 0 command line arguments to get in-game.

NFS files dumped from Metroid Prime Trilogy on Wii U VC can be used directly without converting to ISO.

  • Extract ISO or NFS: hecl extract [path].[iso/nfs] -o mpt
    • mpt can be substituted with the directory name of your choice
  • Repackage game for Metaforce: cd mpt; hecl package MP1
    • The MP1 parameter is important here.
  • Run Metaforce: metaforce mpt/out --warp 1 0

Metaforce 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 \
      qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools libclang-dev
    • Arch Linux packages
      base-devel cmake ninja llvm vulkan-headers python3 qt6 clang lld alsa-lib libpulse libxrandr
    • Fedora packages
      cmake vulkan-headers ninja-build clang-devel llvm-devel libpng-devel qt6-qtbase-devel 
      qt6-linguist qt6-qttools-devel qt6-qtscxml-devel qt6-qtsvg-devel qt6-qt5compat-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

Optional Debug Models

We provide custom debug models for use to visualize certain aspects of the game such as lighting, in order to use these models you may download them from and extract to MP1/URDE in an existing HECL project (assuming paths are relative), then run the following command:

hecl package MP1/URDE

This will cook and package the debug models and will automatically enable rendering of lights in a debug build of Metaforce.

Blender Known Issues

On Windows it is known that paths >240 characters will cause blender to fail while attempting to open/create a file, causing hecl to stall.
We currently do not have a good fix for this issue, however a workaround is to place hecl near the root of your directory tree and executing from there e.g:
Another work around is to install a version of python that matches the one blender ships with and renaming the python directory in the blender directory to python.bak.
This will force blender to use the system's python if it's available and will not have the same path limitation