Repository navigation
ps4-native-mac v0.3.0
ps4-native-mac v0.3.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.2.0: The Last of Us colours are fixed
Before this release, The Last of Us Remastered looked too bright and washed out, Joel's hair was
blond instead of dark brown, foliage was neon green, and much of the sun shadow was missing or
wrong. Three bugs caused this. Each was found by comparing frames with a PS4 reference video and
by replaying captured passes, and each is fixed here.
1. The output gamma was inverted.
- The game sets its output gamma with
sceVideoOutAdjustColor. At its default brightness TLOU
passes gamma 0.8. - The old presenter re-encoded the image with the exponent 1/(3.4 − gamma). For 0.8 that
brightened the image and washed it out. - Now the encoded value is raised to 1/gamma: gamma below 1 darkens, above 1 brightens, and 1.0
leaves the image unchanged. This was calibrated against a PS4 reference video. - The in-game brightness slider now goes the right way.
2. Hair and foliage were never shadowed.
- The GCN shader recompiler ignored the
addr64bit of MUBUF/MTBUF buffer instructions. - TLOU's hair and foliage pixel shaders (18 programs) load their shadow-cascade matrix with
buffer_load_dwordx4 ... addr64. Without the bit they read zeros, so they were always lit.
That made Joel's hair blond instead of dark brown and the foliage neon. - Fix:
addr64loads are now general guest-memory loads (descriptor base plus the 64-bit address
in VGPRs plus the offsets). Draw shaders got their own guest-memory path: the page table,
read-only windows and their own fault slot. - Draw-stage stores and
addr64forms that are not supported fail shader translation with an
error instead of reading wrong data quietly.
3. Sun shadow cascades 1–2 were always in shadow.
- The sun shadow map is a depth array with 3 slices. Its compute HTILE fast clear was applied
only to slice 0, so cascades 1 and 2 kept stale depth and shadowed everything. - Now the clear's coverage is sized from the bytes it cleared and the addrlib HTILE layout (2, 8
and 16 pipes, and linear HTILE), so every cleared slice is covered. - Pro (Neo) depth targets fall back to one slice, and this is logged.
Window colour space.
- The window's
CAMetalLayeris now tagged sRGB, so macOS colour-matches the frame to the panel.
PS4_COLORSPACE=nativerestores the old untagged layer. - The on-screen effect is expected but not measured: window captures look the same with both
settings.
Tools.
tools/color_compare.pycomputes CIE L*C*h statistics of frame regions against reference frames.tools/gamma_candidates.pyandtools/tlou_color_run.sh(window captures through the macOS
display path).PS4_SCREENSHOT_STAGE=outputtakes the internal screenshots after the gamma pass.docs/color-measurement.mddescribes the method. The reference frames and game captures are not
in the repository.
Measured colour
Location-matched frames, our window captures against the PS4 reference video, CIE L* (lightness,
0–100):
| Frame | v0.2.0 | v0.3.0 | PS4 reference |
|---|---|---|---|
| Interior save point, median L* (p50) | 10.2 | 3.2 | 2.6 |
| Joel's hair, L* | 32 | 9 | 4; hue within 20° |
| Plank courtyard in daylight, median L* | not measured | 11–19 (two captures) | 32 |
Known remaining:
- Sunlit daylight surfaces are still darker than on the PS4 reference (the plank courtyard row
above). The sun direction was checked: it is the game's own data. So the remaining gap is in the
evaluation of lighting or shadows, and it is under investigation. - Pro (Neo) depth arrays keep single-slice HTILE coverage.
Performance
- The shadow work that now runs for hair and foliage costs about +0.4 ms of GPU time per frame in
scenes with much hair and foliage. - The last A/B of that change was within noise: 93.5 against 89.7 fps (±6.6).
- No new A/B was run for the HTILE change.
- The screenshot in the README (Beyond the Wall, Metal 3, MetalFX 1920x1080 → 2560x1440) shows
about 89 fps on the developer's Mac. - The route numbers in "Status" are from v0.2.0 and were not re-measured.
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, v0.2.0 code): 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 v0.2.0's renderer changes) |
1920x1080 (PS4_PRO=0); 2560x1440 in Pro mode |
Uncharted 4 was checked only for this release's colour change: its first-run brightness menu
renders byte-identical to v0.2.0. It was not checked further.
Assets
| File | What it is |
|---|---|
ps4-native-mac-v0.3.0-macos-arm64.tar.gz |
The prebuilt ps4-recomp tool with everything it needs at run time (see below) |
ps4-native-mac-v0.3.0-src.tar.gz |
The source of tag v0.3.0 (git archive; the submodules are not included, see "Building from source") |
SHA256SUMS |
SHA-256 checksums of both archives |
The prebuilt archive has the same layout as in v0.2.0:
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
Unchanged from v0.2.0:
| 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. 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 prebuilt ps4-recomp 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.3.0-macos-arm64.tar.gz # only if macOS blocks the tool after a browser download: xattr -dr com.apple.quarantine ps4-native-mac-v0.3.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. -
Recompile.
/path/to/CUSA00557stands for your game folder.ps4-native-mac-v0.3.0-macos-arm64/ps4-recomp /path/to/CUSA00557/eboot.bin \ --app-dir /path/to/CUSA00557 -o /path/to/build -cRebuild games built with v0.2.0: the colour fixes are in the runtime and the shader translator.
The shader cache ID is a hash of the translator's sources, so old cached shaders are not
reused and the cache does not need to be cleared. -
Sign ad hoc (again after every rebuild):
codesign -f -s - /path/to/build/eboot.app -
Run:
open /path/to/build/eboot.app.PS4_GNM_METAL=4selects the Metal 4 backend.
Known issues
- TLOU daylight is darker than on a PS4 (see "Measured colour").
- HTILE on Pro depth arrays: a compute HTILE clear covers only the first slice in Pro (Neo)
mode. - Window colour space: the effect of the sRGB tag on screen is not measured.
- Metal 4 is slower than Metal 3 (85.5 against 98.9 fps on the TLOU route in v0.2.0), so it is
not the default. - Uncharted 4: no fog and no light shafts on the title screen; water colour, foam and sky
differ from a PS4; large or GPU-indexed T# tables read a null image; no decals (CMASK); frame
rate below 30 fps; the guest-memory fast path stays opt-in. - The other known issues of v0.2.0 are unchanged (x87 precision, misaligned atomics, NaN sign,
unresolved imports, screenshot frame cost, shader cache key, bundle ID, AppleDouble files, the
analyzecoverage list, the old name in places, not notarized, anassetsfolder near the
build, FreeType at run time, symlinks tops4-recomp). The README lists them all.
Building from source
The full source of this release is the tag v0.3.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 (unchanged since v0.2.0):
git clone --recursive --branch v0.3.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, and
gcn-recompiler with -ffile-prefix-map so that the library holds no build paths.
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 39 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 Metal 3 and Metal 4 (Metal 4 with the residency check), including
the newaddr64and HTILE slice tests.go vet,gofmtandgo testare clean; the Python
tool tests pass (98). - Game runs on the development build with the same runtime and recompiler code:
- TLOU on Metal 3: the colour measurements above;
- TLOU on Metal 4, 120 s smoke run: no fatal errors, GPU errors or watchdog reports, no
artefacts seen; - Uncharted 4, 240 s from an empty data folder: its first-run brightness menu renders
byte-identical to v0.2.0. Uncharted 4 was not checked further.
- 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, shader dumps and colour reference frames 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.3.0 (also attached as
ps4-native-mac-v0.3.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)
49371574119615a8490f44af1c40c2cc2b8b39b92237ac3267df75bd3744e9be ps4-native-mac-v0.3.0-macos-arm64.tar.gz
c511dd17fcb7f70f237c165771f4f872746b4a3d5cc3f63e0d66a2fc6f817148 ps4-native-mac-v0.3.0-src.tar.gz