Skip to content

ps4-native-mac v0.3.0

Choose a tag to compare

@manjarqo manjarqo released this 26 Oct 07:53
· 18 commits to main since this release

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 addr64 bit 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: addr64 loads 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 addr64 forms 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 CAMetalLayer is now tagged sRGB, so macOS colour-matches the frame to the panel.
    PS4_COLORSPACE=native restores 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.py computes CIE L*C*h statistics of frame regions against reference frames.
  • tools/gamma_candidates.py and tools/tlou_color_run.sh (window captures through the macOS
    display path).
  • PS4_SCREENSHOT_STAGE=output takes the internal screenshots after the gamma pass.
  • docs/color-measurement.md describes 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 libraries libgcn_recompiler.a, libspirv-cross.a,
    libatrac9.a with the headers the build needs, and the minimp3 headers;
  • LICENSE, the third-party license files (3rdparty/*/LICENSE, licenses/) and INSTALL.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)

  1. 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
  2. Dump your own game. The project works only on a decrypted, extracted game folder that
    contains eboot.bin, sce_module/ and sce_sys/. It does not decrypt or unpack PKG files and
    no game files are provided.

  3. Recompile. /path/to/CUSA00557 stands 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 -c

    Rebuild 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.

  4. Sign ad hoc (again after every rebuild): codesign -f -s - /path/to/build/eboot.app

  5. Run: open /path/to/build/eboot.app. PS4_GNM_METAL=4 selects 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
    analyze coverage list, the old name in places, not notarized, an assets folder near the
    build, FreeType at run time, symlinks to ps4-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.git

Then 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 analyze of 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. The eboot.app was
    then signed ad hoc and verified with codesign --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 new addr64 and HTILE slice tests. go vet, gofmt and go test are 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 .app bundles, guest_image.bin or 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