Repository navigation
ps4-native-mac v0.1.0
ps4-native-mac v0.1.0
First release of ps4-native-mac, 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.
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 | Walking (330 s scripted routes): chapter 1 courtyard 89.7 fps, spore corridor 99.6 fps, 0 frames > 100 ms. Standing: courtyard 78.5–78.9 fps, Sarah's house 113.7–114.5 fps. | 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 | TBD (being re-measured after the guest-memory dispatch fix) | 1920x1080 (PS4_PRO=0); 2560x1440 in Pro mode |
The Last of Us Remastered:
- 30-minute courtyard soak: no fatal errors, no hangs, memory footprint flat at ~3.5 GB.
- Exit: 3/3 by closing the window, 3/3 by terminate, no crash reports.
- The frame rate is uncapped (
PS4_PRESENT_MODE=uncappedis the default). The walking numbers come
from a scripted pad route withPS4_PRO=0; the machine's background load moves them by a few
fps between runs. - Its fps in PS4 Pro mode has not been measured yet (TBD).
Uncharted 4:
- The title screen renders like a PS4 (lit scene, light shafts).
- Boat cutscene: Drake and Sully are lit; a motion-blur smear remains (fix in progress).
- Gameplay still shows red streaks and flat water.
- Base mode is recommended: Pro mode stays under 30 fps.
Upstream milestones that were not verified in this fork: Hollow Knight: Silksong (upstream
reported a boot into the Unity runtime with a Metal display) and Hogwarts Legacy (upstream reported
a boot up to a virtual address space allocation failure).
Assets
| File | What it is |
|---|---|
ps4-native-mac-v0.1.0-macos-arm64.tar.gz |
The prebuilt ps4-recomp tool with everything it needs at run time (see below) |
ps4-native-mac-v0.1.0-src.tar.gz |
The source of tag v0.1.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.aand the headers the runtime includes (gcn_recompiler.h, the LibAtrac9 headers,
minimp3.h);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. The prebuilt ps4-recomp needs macOS 13 or later. Game bundles declare 12.0 as their minimum, but the game binary is linked for the macOS SDK of the Mac it is built on, and older versions are untested (TBD). MetalFX upscaling needs macOS 13 or later. |
| 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.1.0-macos-arm64.tar.gz # only if macOS blocks the tool after a browser download: xattr -dr com.apple.quarantine ps4-native-mac-v0.1.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.1.0-macos-arm64/ps4-recomp analyze /path/to/CUSA00557/eboot.bin # optional check ps4-native-mac-v0.1.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). For TLOU,
generation takes ~25 s and a full build took ~85 s on the M1 Pro. -
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
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.
| Option | What it does | Default |
|---|---|---|
| Language | The console system language reported to the game. The list shows only the languages whose speech packs are in your game data, and English if none are found. | macOS language |
| PS4 Pro mode | The game is told it runs on a PS4 Pro (sceKernelIsNeoMode) and takes its Pro rendering path. TLOU then renders at 3200x1800 instead of 1920x1080. This costs more GPU time. |
On |
| MetalFX upscaling | Scales the presented frame up to the window size with MetalFX spatial upscaling (macOS 13+). | Off |
| FPS counter (Metal HUD) | An on-screen overlay with fps, frame time, the longest frame, the mode and the render (and MetalFX output) resolution. | On |
| Remember | Saves the choices for this game, so the window does not open on later launches unless Option is held. | On |
- Settings are stored per game folder in
~/Library/Application Support/PS4Recomp/settings/<game folder name>.cfg(under
PS4RECOMP_DATA_DIRwhen that is set). - 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 settingPS4_LANG)
never shows the window. - TLOU stores its text, subtitle and speech language in its save. Once a save exists, change the
language in the game's own Options menu. - PS4 Pro mode is on by default, but the measured TLOU numbers above use base mode, and for
Uncharted 4 base mode is recommended.
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
- Uncharted 4.
- Gameplay: red streaks and flat, blocky water; the sky is dark.
- Boat cutscene: a motion-blur smear remains; its fix is in progress.
- The title-screen fog is weaker than on a PS4.
- Images read through descriptors (T#) loaded at run time read a null image (counted and logged
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).
v_writelanereturns 0 (a counted, logged gap).- Inside per-lane EXEC scopes,
v_readfirstlaneandv_mbcntof a wave64 shader act per
32-lane half.
- 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 and names instructions the backend does lift
(for exampleSFENCE,VPSHUFD). 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. At start the runtime looks for
anassets/folder next to the executable and in up to four parent folders of
eboot.app/Contents/MacOS(that is, up to the folder that contains your build folder) and, if it
finds one, uses that folder as/app0instead of the game folder given at build time. The game
then cannot find its files and stops. 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.1.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.1.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
The prebuilt archive was unpacked into an empty folder and used from there, on an M1 Pro with
macOS 27.0.1: ps4-recomp --help, ps4-recomp analyze of The Last of Us Remastered (CUSA00557)
and a full recompile (1 min 29 s, all libraries taken from the unpacked archive). The ad-hoc signed
eboot.app was then started for 60 s with a fresh data folder, an empty shader cache and
PS4_PRO=0: according to its log it rendered ~6300 frames, created the profile save and
opened the game's save dialog for new game data (which TLOU shows after the main menu), with no
fatal error.
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.1.0 (also attached as
ps4-native-mac-v0.1.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)
8f7a55759b1ecf6f9638c4e26e62d50252a913481e1aba580902600dc33c3a70 ps4-native-mac-v0.1.0-macos-arm64.tar.gz
345fed365bb0bdcc44245ffe23949b536072572fc669116b539b18727f94cd47 ps4-native-mac-v0.1.0-src.tar.gz