A native Linux and Windows version of Ninja Gaiden Black (Xbox, 2005), with an experimental Android one, made by statically recompiling the game's own code to run directly on a PC — not an emulator. It draws with its own Vulkan renderer, which takes over the game's Direct3D calls instead of emulating the Xbox GPU. It plays at a steady 60 fps on modest hardware (including the Steam Deck) and adds PC options: higher resolutions, widescreen and ultrawide, keyboard and mouse, rebindable controls and more.

You need your own copy of the game. This project contains none of the game's data (graphics, sound, movies, text): on first start it asks for your disc image and installs the game from it. It is made for the retail USA release (NTSC-U, title ID 5443000D) and checks for it.

Screenshots

<table> <tr> <td><img src="https://github.com/user-attachments/assets/e9fb1579-2320-4ff9-8fc0-0ea2a724316b" alt="Ultrawide 21:9: Ryu in front of Han's Bar"></td> </tr> <tr> <td align="center"><sub>21:9 at 6x render resolution</sub></td> </tr> </table> <table> <tr> <td><img src="https://github.com/user-attachments/assets/6dc8bc0d-c5c7-418d-9432-184055bbe3e1" alt="Chapter 1"></td> <td><img src="https://github.com/user-attachments/assets/c4944721-b04b-4061-a42f-dbff16fbd29b" alt="A fight, the HUD hidden"></td> </tr> <tr> <td align="center"><sub>16:9 at 6x render resolution</sub></td> <td align="center"><sub>HUD hidden</sub></td> </tr> </table>

Features

Native Linux (AppImage) and Windows (x64) builds; Steam Deck friendly
Android (arm64), experimental, with Xbox 360 touch controls
Render resolution up to 10x, anisotropic filtering, MSAA, sharper shadows
16:9, 16:10, 21:9 and 32:9 as well as 4:3: the 3D fills the screen, the HUD goes to the screen's corners, optional HUD-free view, menus keep the game's own 16:19
Keyboard and mouse with key prompts in the game, Xbox, PlayStation and Nintendo button prompts, rebindable controls for keyboard, mouse and controller (Ninpo and Wind Run on any two buttons), mouse support in the menus
Mods: replacement game files in a mods folder, without touching the installed game
Skippable intros, movies and cutscenes (an option), unlock-all options for difficulties and costumes, optional cheats
The arcade Ninja Gaiden on the Han's Bar cabinet and the main menu, recompiled as well
Sound mixed on the PC: positional 3D sound, the console's room reverb, and 5.1 surround on a 5.1 or 7.1 output
Smooth frame pacing and low input latency; shaders prepared in the background

Getting started

On every system, the first start after installing takes longer to load (the shaders are prepared then and kept); later starts are quicker.

Linux and Steam Deck

Download NinjaGaidenBlack-x86_64.AppImage from the releases page and make it executable (chmod +x, or Properties → Allow executing).
Run it. On the first start a window asks for your copy of the game: a disc image (.iso, a full Redump dump, or the .7z/.zip it came in) or a folder of extracted files with default.xbe. The game is installed once (about 6 GB).
On a Steam Deck, add the AppImage to Steam (Add a Non-Steam Game) to play it in Game Mode, and choose 16:10 in the settings.

If it closes as soon as you press Play in Game Mode, that's a bug in the current stable Steam client with non-Steam games (fixed in the Steam Beta). Until the next stable release, either switch Steam to the Beta, or set the game's Launch Options in Steam to APPIMAGE_EXTRACT_AND_RUN=1 %command% (#11).

Needs a 64-bit Linux with glibc 2.35 or newer and a GPU with Vulkan 1.3 drivers (or older drivers that have its dynamic rendering and synchronization2 as extensions).

Windows

Download NinjaGaidenBlack-windows-x64.zip and extract it anywhere.
Run NinjaGaidenBlack.exe and choose your disc image as above.

Needs Windows 10 or 11 (64-bit) and a GPU with Vulkan 1.3 drivers (or older drivers that have its dynamic rendering and synchronization2 as extensions).

Antivirus warnings: the program isn't code-signed, and a new unsigned program is sometimes flagged by one antivirus's heuristics (McAfee quarantined it in #88; VirusTotal shows no other detections). That's a false positive. Each release lists the SHA-256 hash of both downloads in its notes and in SHA256SUMS.txt, so you can check that your download is the one published here: in PowerShell, Get-FileHash NinjaGaidenBlack-windows-x64.zip; on Linux, sha256sum -c SHA256SUMS.txt. If you'd rather not run a prebuilt program, you can build it yourself from your own disc (Building from source).

Android (experimental)

The Android version is new and has only been tested on one phone (a Pixel 9a, where it plays at 60 fps). Expect problems on other phones, and please report them (below).

Install:

Download NinjaGaidenBlack-android-arm64.apk from the releases page and open it on the phone. Allow installing apps from your browser or file manager when Android asks.
Copy your disc image (.iso, from the retail USA disc) to the phone or its SD card, anywhere. A .7z or .zip has to be unpacked on a computer first: the phone has no unpacker.
Start the game. The first time, it asks you to choose the image with Android's file picker, then installs the game into its own folder (about 6 GB, a minute or two; with an SD card in, it asks whether to put it on the phone or on the card). It needs no storage permission. You can delete the image afterwards.

Plays with the on-screen touch controls (an Xbox 360 pad), or with any controller the phone supports: the touch controls hide while one is connected. Needs Android 10 or newer (13 or newer for full speed: the game tells the system how long its frames take, which keeps the CPU clocks up), a GPU with Vulkan 1.3, or an older Vulkan with its dynamic rendering and synchronization2 as extensions (on Adreno, Turnip has them).

On Adreno GPUs (Snapdragon phones) whose own driver lacks what the game needs, it uses Turnip, Mesa's open driver for Adreno, built into the app; otherwise the phone's own.

Not there yet on Android: the arcade Ninja Gaiden, and "Return to Main Menu" from the pause menu (it closes the game instead).

Reporting a problem: open an issue and give the phone's model, its chip (Snapdragon, Tensor, Dimensity, Exynos...), the Android version, what happened, and the log: log.txt in Android/data/io.github.gamboozino.ngbrecomp/files on the phone's storage. Some file managers can't open that folder on recent Android; a computer can, over USB (or adb pull /sdcard/Android/data/io.github.gamboozino.ngbrecomp/files/log.txt).

macOS (unsupported)

The macOS code is a community contribution (#49) that I can't build or test, so there are no official macOS packages and macOS bugs may go unfixed. Build the Apple Silicon app using the commands below, extract the resulting zip, and open Ninja Gaiden Black.app. Choose your own disc image or extracted game folder on first start. Current dependencies require macOS 26. Intel Macs and the xemu renderer are unsupported; packages are signed ad hoc, without Developer ID signing or notarization.

Where things are kept

	Linux	Windows	macOS	Android
Installed game, saves	`~/.local/share/NinjaGaidenBlack`	`%LOCALAPPDATA%\NinjaGaidenBlack`	`~/Library/Application Support/NinjaGaidenBlack/saves`	`Android/data/io.github.gamboozino.ngbrecomp/files`
Settings (`settings.ini`, `controls.ini`)	`~/.config/NinjaGaidenBlack`	`%APPDATA%\NinjaGaidenBlack`	`~/Library/Application Support/NinjaGaidenBlack/config`	`config` in the folder above
Shader cache	`~/.cache/NinjaGaidenBlack`	`%LOCALAPPDATA%\NinjaGaidenBlack\shaders`	`~/Library/Application Support/NinjaGaidenBlack/cache/NinjaGaidenBlack/shaders`	`cache` in the folder above
Log	the terminal, or `log.txt` beside the saves when started without one	`log.txt` beside the saves (or the console it was started from)	`log.txt` beside the saves	`log.txt` beside the saves

Portable mode: with a file named portable.txt next to NinjaGaidenBlack.exe (or the AppImage or Mac app), all of these go into a userdata folder next to it instead. The first-run setup offers this as a checkbox. The folder must be writable, so not inside Program Files. Delete portable.txt to go back.

Mods

Files placed in a mods folder beside the saves (the first row above; userdata/mods in portable mode) are read instead of the game's own: textures, models, sounds, movies, anything the game loads from its files. Use the same path the file has in the game's folder, for example mods/movie/cre.sfd for movie/cre.sfd. A mod replaces a whole file (no patches or scripts), the installed game is never changed, and deleting the file goes back to the original. The log lists each file taken from mods ([MODS]).

Settings

Everything is in the game's own menus: RECOMP SETTINGS on the main menu, and the Settings tab of the pause menu. Changes apply at once and are saved.

Graphics: render resolution (1x–10x), texture filtering (the console's, or 2x–16x anisotropic), anti-aliasing (MSAA), shadow resolution, Smoother Glow (a softer, fainter glow on bright lights; off is the console's look), Lower Detail Under Load, Multithreaded Renderer (drawing on a thread of its own, for slower CPUs; on by default on Android, off unless chosen on a PC)
Display: aspect ratio (4:3, 16:9, 16:10, 21:9, 32:9), window size, windowed / fullscreen / borderless, V-Sync (Off, Mailbox, FIFO, Adaptive), frame-rate counter, the HUD on or off, skip the warnings and intro movies
Sound: Positional Audio (3D sounds placed left and right: Mixed, the default, half the sound chip's filters and half panned by direction, the easiest to place; Clear, by level only; Console, through the sound chip's filters as on the Xbox, duller; Off, centred), Audio Output (Auto, Stereo or 5.1; Auto is 5.1 on a 5.1 or 7.1 output; a change needs a restart of the game)
Gameplay (each off unless chosen): the Quick Menu, an NG2-style d-pad menu for weapons, Ninpo and items, and whether the game pauses while it is open; Intercept (Black or Hurricane), the Hurricane Pack's guard counter Black left out: tap guard as an attack lands to turn it aside; Essence-Only Charging, Ultimate Techniques charged only by absorbing essence, not by holding attack (#120); Skip Any Cutscene, Start skipping movies and in-game cutscenes not yet watched (#139); Responsive Menus, Start taken at once at the title, in a cutscene's opening wait and in the pause menu after equipping, where the game ignores it for a while (#116)
Cheats (for the session only): infinite health, ninpo, essence, items, projectiles; golden scarabs; one hit kill (any hit that hurts an enemy or a boss kills it). Its Unlocks page: all difficulties from the start, all costumes, and the main menu's Missions (with every mission), Arcade Ninja Gaiden and Movie Theater without earning them (saved); All Weapons (every melee and projectile weapon at its highest level), All Armlets (the armlets and bands) and All Scrolls (the Izuna Drop, Counter Attack and Guillotine Throw technique scrolls; the story's own can still be picked up while it is on), for the session: turned off, each takes back what it gave and puts back your own pickups; a save made while one is on keeps what it gave
Controls: rebind every action (two keys or mouse buttons and a controller button each; Ninpo and Wind Run can take two controller buttons pressed together); camera inversion; start in third person; Camera Sensitivity; Button Prompts; Toggle HUD (not bound unless chosen). The page shows each binding as its key or button picture. A key or button bound to an action is taken from the one that had it (Pause always keeps a controller button). The bindings follow the game's own Button Settings: an action keeps its key or button whatever the game's Options assign

The game's own Options (sound, movie aspect, controller vibration and so on) are where they always were.

Controls

On Android, an Xbox 360 pad is drawn over the screen: the two sticks, the d-pad, A B X Y, the bumpers and triggers, Back, Start and the stick clicks. It hides while a controller is connected.

A controller works as on the Xbox. The keyboard and mouse can be used at any time — the game follows whichever was touched last, and its button prompts change to match (or stay on one set: "Button Prompts" on the "Controls" page, Auto, Xbox, PlayStation, Nintendo or PC).

On a Nintendo controller the buttons work by position, as on an Xbox pad: the bottom face button (marked B) jumps, and two-button moves sit where the game puts them; the prompts show its own letters. On Android a Nintendo controller works by label instead (the button marked A jumps).

To bind Ninpo or Wind Run to two buttons, choose its controller slot and hold the first button, then press the second; letting go of a single button binds just that one. Moved to other buttons, the game's own pair for it (Y + B, X + A) no longer does it.

Action	Keys	Action	Keys
Move	W A S D	Camera	mouse (numpad 8 4 5 6)
Attack	left mouse, J	Special attack	right mouse, K
Jump	Space	Projectile	E
Ninpo	F	Wind run	C
Guard / roll	Shift	Center camera	Q, middle mouse
Map	Tab	Karma window	R
Pause	Esc, Enter	First-person view	Z

After loading, the right stick (or the mouse) turns the third-person camera; click it (V) to look around in first person. Turn off Start in Third Person (RECOMP SETTINGS → Controls) to start each load in first person, as on the Xbox. Invert Camera X / Y flips the stick and mouse for the third-person camera, Invert First-Person X first-person left and right; first-person up and down is the game's own Options → Controller Settings → 1st Person Camera Control. Camera Sensitivity (25%–300%) sets how fast the mouse, the right stick and the camera keys turn it; over 100% the camera turns faster than the game's own top speed (the third-person camera's left and right; its up and down stays the game's). Holding Start and Back (Select) is the game's own reset to the title screen; turn off Start+Back Reset (Controls) if another program uses that combination.

With the Quick Menu on (RECOMP SETTINGS → Gameplay), Up and Down on the d-pad (or the Up / Down arrows, 1 / 2) open it on the melee weapons or the items, and Left and Right on the previous or next melee weapon; Up and Down then change category, Left and Right choose, A / Enter equips or uses, B / Escape closes. Its keys are in Controls.

In the menus the mouse points and clicks, Esc goes back and Q / E switch the pause menu's tabs. With Skip Any Cutscene (Gameplay), movies and in-game cutscenes can be skipped with Start (or its key), watched before or not.

Other keys: F10 frame-rate counter, F11 or Alt+Enter fullscreen.

The arcade Ninja Gaiden

The 1988 arcade Ninja Gaiden is a separate program on the disc (NinjaTrilogy.xbe, and NinjaTomoe.xbe for the Japanese version) that the Xbox switches to. It is recompiled too: the packages carry NinjaTrilogy and NinjaTomoe next to the game, and the game hands over to them from the main menu's ARCADE NINJA GAIDEN and the cabinet in Han's Bar. In the arcade, Back pauses: B quits back to Ninja Gaiden Black, Y goes to the arcade's title. It opens in the window mode the game was in.

Known issues

Above 1x render resolution, a faint light line can show across the dagger in the pause menu (#83).
The Windows build has been tested under Proton and in a Windows 11 virtual machine; reports from real Windows PCs are especially welcome.

When reporting a graphics glitch, pressing F7 while it is on screen records the next few seconds of drawing to ~/ngb-trace-<n> on Linux, or C:\Users\<you>\ngb-trace-<n> on Windows — attach that folder (zipped), it shows exactly what went wrong.

Building from source

The build needs the game's code, so it starts from your own disc image.

Requirements: clang, CMake, Ninja, Python 3, git, SDL2, GLib, glslang and SPIRV-Tools (Qt 6 Widgets for the setup window, optional). The recompiler and Xbox runtime, xboxrecomp with this port's changes, is included in xboxrecomp/.

xboxrecomp/third_party/fetch.sh                # once: Vulkan headers, volk, VMA and the like
tools/pipeline.sh /path/to/your/ngb.iso        # extract, disassemble and lift to C (a few minutes)
cmake -S . -B build/linux -G Ninja -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++
ninja -C build/linux
build/linux/NinjaGaidenBlack

Packages: packaging/appimage/build.sh (in a Docker container, for an AppImage that runs on older systems), packaging/windows/build.sh (cross-compiled from Linux with llvm-mingw), packaging/android/build.sh (below), and packaging/macos/build.sh (native Apple Silicon). Packages contain no game data.

For Android, after the fetch and pipeline steps above (on Linux), install the Android SDK with an NDK, build-tools and a platform (Android Studio's SDK Manager, or sdkmanager "ndk;27.2.12479018" "build-tools;35.0.0" "platforms;android-35"), and a JDK, then:

packaging/android/build.sh      # ANDROID_HOME=<sdk> if it is not ~/Android/Sdk
adb install -r build/android-release/NinjaGaidenBlack-android-arm64.apk

It builds SDL2 and glslang for the phone once (into build/android-deps), then the game, and signs the APK with a key it makes there (debug.keystore): keep that file, as Android only installs an update over an app signed with the same key.

On macOS, install the build dependencies below, then run the fetch and pipeline steps above and package the app:

brew install cmake ninja sdl2-compat sdl3 libepoxy glib glslang molten-vk vulkan-loader qt
packaging/macos/build.sh

The zip is build/macos-release/NinjaGaidenBlack-macos-arm64.zip. Homebrew is needed only to build; runtime libraries, including MoltenVK, are bundled. NGB_MAC_PREFIX overrides the build dependency prefix (default: brew --prefix).

How it works, and the details of every feature: docs/TECHNICAL.md and docs/renderer.md. How to contribute: CONTRIBUTING.md; the layout, tools and test rules, also for coding agents: AGENTS.md.

Support

If you'd like to support the project: ko-fi.com/gamboozino

Credits

xboxrecomp by sp00nznet: the recompiler and Xbox runtime this is built on (MIT)
xemu: the NV2A GPU model and the APU's voice processor (the files used here are LGPL-2.1-or-later, its shader generators GPL-2.0 or 3.0; xemu as a whole is GPL-2.0)
TGP482's SCDA-XBERecomp and Xbox-XBERecomp: the renderer's shader, vertex and texture code, and the sound mixer's model (MIT)
Fonts: EB Garamond and Liberation Serif (SIL Open Font License)
Keyboard, mouse and controller prompts (the Xbox, PlayStation and Nintendo Switch buttons), and the touch controls' buttons: Xelu's Free Controller & Key Prompts (CC0)
The touch controls' sticks and d-pad: Kenney's Mobile Controls (CC0)
Banner lettering: Chakra Petch by Cadson Demak (SIL Open Font License)

Contributors

Code:

akirahayabusa: the freeze in scenes with the sun (#40), folders with non-ASCII names on Windows (#41), the Difficulty Selection highlight (#42); and the Hurricane patch (vb-zh x2.1), whose Intercept switch showed where Black had left the mechanic out (#109, #132)
ManemanFTW (Manuel Flores): the Windows start-up hang (#9) and the audio crackling on Windows (#34)
HammerD72: the audio timing fix (#32); the two spots where the game picks the camera view at a load, for Start in Third Person (#23); impact sparks at 21:9 (#65); Smoother Glow (#64); the Quick Menu (#60)
retro-meister: the macOS port (#49), and the community macOS builds

Testing, saves and traces:

Radarzo, hj-0, hyperspeedgx, serguntchik, PaulAndrewClift and phantuannghia95-rgb: seven test builds, screenshots and logs on Nvidia cards that tracked down the banded water (#16)
HammerD72: testing on Nvidia across many issues (shadows #53, water #16, menus and controls)
DAVID106-debug: the missing particles and the Xbox comparison (#51), the high-resolution shadow flicker (#53)
hyperspeedgx: saves across chapters 1 to 9, traces for the torch embers (#51) and the Chapter 5 roof (#29)
hj-0: saves for chapters 11 to 13 and a guide to moving saves from xemu (#61)
yoyooo941-sys: the save that made the volcano strip reproducible (#55)
firepro1211 and huokunlongCHAIN: the Chapter 5 roof, including a comparison on the Xbox One (#29)
matitone71: the Steam Deck Game Mode log that found the launch problem (#11)

To report a bug, test a build or send a change, see CONTRIBUTING.md.

Ninja Gaiden is a trademark of Koei Tecmo. This project is not affiliated with or endorsed by Koei Tecmo or Team Ninja.

License

This project's code is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version (GPL-3.0-or-later; the text is in LICENSE). Up to 0.9.24 it was GPL-2.0-or-later. It is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY. The parts it is built from keep their own licenses: see THIRD_PARTY.md.

Leer guía oficial