Repository navigation
ps4-native-mac v0.2.0
ps4-native-mac v0.2.0
ps4-native-mac is an ahead-of-time (AOT) static recompiler for Apple Silicon Macs. It translates
the x86-64 code of a PlayStation 4 game (eboot.bin and the PRX modules shipped with the game)
into a native arm64 macOS app. The game code is lifted once, at build time, into ARM64 assembly.
It then runs against a high-level emulation (HLE) runtime of the Orbis OS libraries and a GNM
command processor that renders with Metal. There is no JIT, no interpreter and no MoltenVK.
The project is a fork of PS4Recomp, developed
independently under the new name since 2026-10. License: GPL-2.0.
No game is included. You recompile a game that you own and dumped yourself.
What's new since v0.1.0
Renderer: two Metal backends.
- Every game build now contains two renderer backends behind one interface: Metal 3 (the
default) and Metal 4 (PS4_GNM_METAL=4). The log line[gnm-draw] backend metal3 (...)
and the end of the Metal HUD's first line show which one runs. - The Metal 4 backend uses
MTL4CommandQueue, command allocators that are reused once their work
completed, argument tables, a bytes arena instead ofsetBytes, residency sets for every
resource, and a barrier at each encoder start.PS4_GNM_RESIDENCY_CHECK=1checks every
resource a command uses against the residency sets. - Both backends share the command processor, the caches, shader translation, capture and replay.
Replays of two captured TLOU frames (570 and 267 passes) give byte-identical outputs on both. - An explicit
PS4_GNM_METAL=4that cannot be honoured (for example a GPU without
MTLGPUFamilyMetal4) stops at start with the reason; it never falls back silently. - Metal 3 stays the default because Metal 4 is slower: 85.5 fps against 98.9 on the TLOU route.
The loss is GPU time (11.4 against 9.3 ms per frame). Metal 4's encoder-start barriers keep its
command buffers from overlapping on the GPU, while Metal 3's hazard tracking lets them overlap.
Seedocs/metal4-backend.md,docs/gnm-ordering.mdanddocs/metal4-baseline.md.
Renderer: faster on both backends.
- Batched compute commits: while at least two command buffers are in flight, the end of a compute
submission is held for at most 0.5 ms, so back-to-back submissions share a command buffer. TLOU
went from 49 to 9 command buffers per frame, and from about 82 to 92 fps on Metal 3 in that
change's own A/B.PS4_GNM_COMPUTE_BATCH=0turns it off. Seedocs/compute-batching.md. - Guest memory windows that alias the same bytes are ordered explicitly on Metal 3 (an access
fence per encoder), and GPU detiles of a texture are ordered after the work that wrote it.
Uncharted 4 graphics (already on main after v0.1.0, first released here):
- Wave64 predication in the shader translator: code under a per-lane EXEC mask that needs the whole
wave runs predicated on both 32-lane halves, so every thread reaches every barrier. This fixes
the boat cutscene's motion-blur smear. v_writelaneis a real per-lane select again.- Image descriptor (T#) tables indexed at run time are bound as images when the CPU can bound the
index to at most 8 entries. - Guest memory dispatches: an opt-in fast path (
PS4_GNM_GUEST_MEMORY_FAST=1). Buffer stores that
fully overwrite a GPU-owned target refresh it before its next GPU use. sceGnmSubmitAndFlipCommandBuffersandsceVideoOutSubmitFlipno longer wait for the display.- Capture tooling: replayable passes selected by shader, a pass extractor for host-test fixtures.
Tools and tests.
PS4_SCREENSHOT_EVERY_SEC=<s>saves a frame everysseconds of wall time, to compare runs at
the same moments.- The benchmark scripts behind the TLOU numbers are in
tools/(metal4_route.sh,
metal4_perf_ab.sh). They are written for the developer's workspace and need your own save and
pad script. - The host test suite runs every renderer-level test on both backends, Metal 4 with the residency
check. Tests that need shaders dumped from a game skip without those local fixtures.
Status
Measured on an Apple M1 Pro (16 GB), macOS 27.0.1. Only measured numbers are listed; "TBD" means
not measured yet.
| Game | Stage | fps | Resolution |
|---|---|---|---|
| The Last of Us Remastered (CUSA00557) | Playable: boot, menus, movies, gameplay, saves | Chapter 1 courtyard route (300 s, median of 5 runs): 98.9 fps on Metal 3 (default), 85.5 fps on Metal 4 | 1920x1080 (base PS4 mode, PS4_PRO=0), MetalFX off. Pro mode: TBD |
| Uncharted 4: A Thief's End (CUSA04529) | In progress: boots, menus, New Game, chapter 1 (boat cutscene and boat gameplay), saves, audio | Title screen about 21–22 fps, boat gameplay about 20–21 fps (PS4_PRO=0, measured before this release's renderer changes, while other work ran on the machine) |
1920x1080 (PS4_PRO=0); 2560x1440 in Pro mode |
The Last of Us Remastered:
- The route is
tools/metal4_route.sh: a scripted pad route from a copy of a chapter 1 save, with
PS4_PRO=0, separate data and cache directories and no screenshots.tools/metal4_perf_ab.sh
alternated the backends on one build; the noise between runs was ±1.3 fps. - 300 s runs of the release's runtime on both backends: no fatal errors, GPU errors or watchdog
reports; screenshots taken every 20 s show the same scenes on both. - 30-minute courtyard soak (v0.1.0 code): no fatal errors, no hangs, memory footprint flat at
~3.5 GB. - The frame rate is uncapped (
PS4_PRESENT_MODE=uncappedis the default). The machine's
background load moves the numbers by a few fps between runs.
Uncharted 4:
- Title screen: the scene is lit, but fog and light shafts are missing.
- Boat cutscene: Drake and Sully are lit and the motion-blur smear is fixed.
- Gameplay: water colour and foam differ from a PS4 and the sky is too dark.
- Base mode is recommended.
Assets
| File | What it is |
|---|---|
ps4-native-mac-v0.2.0-macos-arm64.tar.gz |
The prebuilt ps4-recomp tool with everything it needs at run time (see below) |
ps4-native-mac-v0.2.0-src.tar.gz |
The source of tag v0.2.0 (git archive; the submodules are not included, see "Building from source") |
SHA256SUMS |
SHA-256 checksums of both archives |
The prebuilt archive contains:
ps4-recomp: the recompiler (arm64, ad-hoc signed, not notarized);pkg/runtime/: the HLE runtime sources (C / Objective-C). They are copied into every game build
and compiled there together with the lifted game code;3rdparty/: the prebuilt static librarieslibgcn_recompiler.a,libspirv-cross.a,
libatrac9.awith the headers the build needs, and the minimp3 headers;LICENSE, the third-party license files (3rdparty/*/LICENSE,licenses/) andINSTALL.txt.
Keep the layout as it is: ps4-recomp looks for pkg/runtime and 3rdparty/ next to its own
executable or in the current directory.
Requirements
| Requirement | Notes |
|---|---|
| Apple Silicon Mac | Developed and measured on M1 Pro, 16 GB. Game code is built with -mcpu=apple-m1. |
| macOS | Tested on macOS 27.0.1. New in v0.2.0: building a game needs the macOS 26 SDK or later (Xcode or Command Line Tools 26+), because the Metal 4 backend is compiled into every build. The game binary is linked for the SDK of the Mac it is built on. The prebuilt ps4-recomp needs macOS 13 or later. MetalFX upscaling needs macOS 13 or later. The Metal 4 backend needs a GPU with MTLGPUFamilyMetal4. |
| Xcode Command Line Tools | xcode-select --install. clang assembles and links every game build. Building gcn-recompiler from source needs Apple clang 17+ (C++23); tested with Apple clang 21. |
| Ninja | brew install ninja. It drives the parallel game build. |
| FreeType 2 | brew install freetype pkg-config. Found through pkg-config, or at /opt/homebrew/opt/freetype. The game binary also loads it at run time. |
| Go, CMake | Only to build from source: Go 1.27.1 (go.mod), CMake ≥ 3.20. |
Quick start (prebuilt archive)
-
Unpack.
tar -xzf ps4-native-mac-v0.2.0-macos-arm64.tar.gz # only if macOS blocks the tool after a browser download: xattr -dr com.apple.quarantine ps4-native-mac-v0.2.0-macos-arm64 -
Dump your own game. The project works only on a decrypted, extracted game folder that
containseboot.bin,sce_module/andsce_sys/. It does not decrypt or unpack PKG files and
no game files are provided. Dump a game you own legally, using your own console and the tools
of your choice. -
Recompile.
/path/to/CUSA00557stands for your game folder.ps4-native-mac-v0.2.0-macos-arm64/ps4-recomp analyze /path/to/CUSA00557/eboot.bin # optional check ps4-native-mac-v0.2.0-macos-arm64/ps4-recomp /path/to/CUSA00557/eboot.bin \ --app-dir /path/to/CUSA00557 -o /path/to/build -cThe result is
/path/to/build/eboot.app. The bundle holdsguest_image.bin,sce_sysand
the icon; the game files are read at run time from the--app-dirfolder (PS4_APP_DIR
changes it,--copy-resourcescopies the whole game into the bundle instead). -
Sign ad hoc (again after every rebuild):
codesign -f -s - /path/to/build/eboot.app
-
Run.
open /path/to/build/eboot.app # or, to see the log: /path/to/build/eboot.app/Contents/MacOS/eboot > run.log 2>&1 # the Metal 4 backend instead of the default Metal 3: PS4_GNM_METAL=4 /path/to/build/eboot.app/Contents/MacOS/eboot > run.log 2>&1
Controllers that GameController.framework supports (DualShock 4, DualSense and others) act as
the pad.
Launch settings (hold Option)
A settings window opens before the game starts on the first launch of a game, and on any later
launch while Option (⌥) is held as the app starts. It sets the language, PS4 Pro mode (on by
default), MetalFX upscaling, the FPS counter (Metal HUD) and whether to remember the choices.
Environment variables override the stored values: PS4_LANG, PS4_PRO=0|1,
PS4_UPSCALE=off|metalfx, MTL_HUD_ENABLED=0|1. PS4_NO_DIALOGS=1 (or setting PS4_LANG)
never shows the window. The README describes each option.
Saves go to ~/Library/Application Support/PS4Recomp/saves (or $PS4RECOMP_DATA_DIR/saves),
shader caches and the pipeline archive to ~/Library/Caches/PS4Recomp/<game folder name>/.
Known issues
- Metal 4 is slower than Metal 3 (85.5 against 98.9 fps on the TLOU route), so it is not the
default. - Quit after a GPU hang. If the command buffer watchdog gave up on the GPU, a normal quit waits
10 s for the GPU and then stops with a FATAL message. - Uncharted 4.
- The title screen has no fog and no light shafts.
- In gameplay the water colour and foam differ from a PS4, and the sky is too dark.
- Image descriptor (T#) tables with more than 8 entries, or indexed only by the GPU, read a null
image (counted and logged once per shader). - Decals are not applied (CMASK is not emulated).
- The shadow cube map is resolved from a 2D target ("texture type mismatch" in the log).
- Frame rate is below a PS4's 30 fps.
- The faster guest-memory dispatch path (
PS4_GNM_GUEST_MEMORY_FAST=1) is opt-in: in long runs
it showed rare anomalies that the default path did not show, not yet explained.
- x87. 80-bit values are kept as doubles, which loses 11 mantissa bits.
- Misaligned atomics. A LOCK operation on an operand that crosses a 16-byte boundary raises
SIGBUS. TLOU has none. - NaN sign. The sign of NaN results from invalid operations differs from x86.
- Unresolved imports. Any import without an implementation is bound to a stub that stops the
game with a log message naming the import. TLOU has 2, inlibSceGnmDriver; it was never seen
calling them. - Screenshot frames. With screenshots on, the frames that capture one take ~130–150 ms.
- Shader cache sharing. The cache key is the game folder's name, so two games in folders with
the same name share a cache. - Bundle ID. Every bundle gets the ID
org.ps4recomp.<executable name>, so everyeboot.app
has the same ID. - macOS metadata files. On exFAT/FAT volumes, AppleDouble
._*files next to the PRX modules
produce harmless "Skipping module" messages. ps4-recomp analyzecoverage list is out of date. Its "Missing Instructions" table comes
from an opcode list that predates the ARM64 backend. Use it as an inventory, not as a list of
gaps.- Old name in places. The tool's
--helpbanner, the bundle ID and the on-disk folders still
sayPS4Recomp. - Not notarized.
ps4-recompis only ad-hoc signed; see the quarantine note in Quick start. - A folder named
assetsnear the build overrides--app-dir. Keep the build out of folders
that contain anassets/folder, or setPS4_APP_DIR=/path/to/CUSA00557, which always takes
precedence. - FreeType at run time. The game binary links Homebrew's FreeType dynamically
(/opt/homebrew/opt/freetype/lib/libfreetype.6.dylib), so keep it installed. - Do not call
ps4-recompthrough a symlink elsewhere. It searches forpkg/runtimeand
3rdparty/next to the path it was started from.
Building from source
The full source of this release is the tag v0.2.0. The source asset is a git archive of that
tag and does not include the submodules (SPIRV-Cross, LibAtrac9, minimp3); a recursive clone gets
them at their pinned commits:
git clone --recursive --branch v0.2.0 https://github.com/manjarqo/ps4-native-mac.gitThen follow "Build the third-party libraries and the recompiler" in the README. The prebuilt
ps4-recomp was built with go build -trimpath -o ps4-recomp ./cmd/ps4-recomp.
How this release was checked
- From the prebuilt archive, unpacked into an empty folder and used from another empty
folder, on an M1 Pro with macOS 27.0.1:ps4-recomp --help,ps4-recomp analyzeof The Last
of Us Remastered (CUSA00557) and a full recompile (1 min 25 s). Every library and header came
from the unpacked archive, and the build's runtime sources are the tag's. Theeboot.appwas
then signed ad hoc and verified withcodesign --verify. - Host test suite (
tests/host/run_host_tests.sh) on the tag's tree: PASS with 38 cases
skipped without the local game fixtures, and PASS with none skipped with them. Every
renderer-level test runs on both backends, Metal 4 with the residency check.go vet,gofmt
andgo testare clean. - Game runs. The runtime and recompiler code of this tag are the same as in the build used
for the final gate of the backend work (only tests and documentation changed after it):- TLOU, 300 s per backend with a screenshot every 20 s: Metal 3 97.8 fps, Metal 4 77.5 fps
with the residency check on (res_assert=0throughout); the screenshots show the same scenes; - Uncharted 4, 120 s from an empty data folder (the first-boot settings screen): both backends
ran and gave identical screenshots; - no fatal errors, GPU errors, watchdog reports or GPU fault reports in any of these runs.
- The performance A/B in "Status" ran on commit 8bdffe7. The runtime changes after it are the
Metal 4 texture keep list (measured within noise), thePS4_GNM_COMPUTE_BATCHswitch,
explicit fence overrides and the Metal 3 default.
- TLOU, 300 s per backend with a screenshot every 20 s: Metal 3 97.8 fps, Metal 4 77.5 fps
- The release build of the archive itself was not started as a game.
Legal notice
- You must own every game you use with this project. It works only on a game you dumped
yourself from a copy you legally own. - This release contains only the project's own tool and its third-party libraries. It does not
distribute game files, PS4 system software, firmware, encryption keys or recompiled game
binaries. Do not share the.appbundles,guest_image.binor other build outputs; they contain
the game's code. Frame captures and shader dumps contain game data too. - ps4-native-mac is an independent project. It is not affiliated with, endorsed by or sponsored by
Sony Interactive Entertainment, Naughty Dog or the original PS4Recomp authors. - "PlayStation", "PlayStation 4", "PS4" and "Orbis OS" are trademarks of Sony Interactive
Entertainment Inc. All game titles and assets belong to their respective owners.
Credits
- The PS4Recomp authors: this project is a fork of their recompiler, runtime and tooling.
- shadPS4: HLE module architecture and system
behaviour documentation, and the shader recompiler packaged as gcn-recompiler. - OpenOrbis: open-source PS4 toolchain and reverse engineering.
- ps4libdoc: symbol dictionaries and NID-to-name mappings.
- The authors of SPIRV-Cross, LibAtrac9 and minimp3.
License
ps4-native-mac is licensed under the GNU General Public License v2.0. The complete corresponding
source of the prebuilt tool is the tag v0.2.0 (also attached as
ps4-native-mac-v0.2.0-src.tar.gz). Third-party components keep their own licenses; their license
files are in the prebuilt archive.
| Component | License |
|---|---|
gcn-recompiler (from shadPS4 32021e4) |
GPL-2.0-or-later |
| SPIRV-Cross | Apache-2.0 |
| LibAtrac9 | MIT |
| minimp3 | CC0-1.0 |
| sirit / SPIRV-Headers, fmt, magic_enum, Boost subset (inside gcn-recompiler) | BSD-3 / MIT, MIT, MIT, BSL-1.0 |
Checksums (SHA-256)
d20ae793772b440db851085f12f422a8fc463ab85aaa47b3a1bad2d5e203f235 ps4-native-mac-v0.2.0-macos-arm64.tar.gz
f893d78925a7c5302f3de7bb938e65c3742672ec7c2c2e184c51048c03b792ce ps4-native-mac-v0.2.0-src.tar.gz