Skip to content

ps4-native-mac v0.2.0

Choose a tag to compare

@manjarqo manjarqo released this 25 Oct 06:07
· 19 commits to main since this release

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 of setBytes, residency sets for every
    resource, and a barrier at each encoder start. PS4_GNM_RESIDENCY_CHECK=1 checks 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=4 that 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.
    See docs/metal4-backend.md, docs/gnm-ordering.md and docs/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=0 turns it off. See docs/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_writelane is 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.
  • sceGnmSubmitAndFlipCommandBuffers and sceVideoOutSubmitFlip no 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 every s seconds 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=uncapped is 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 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

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)

  1. 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
  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. Dump a game you own legally, using your own console and the tools
    of your choice.

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

    The result is /path/to/build/eboot.app. The bundle holds guest_image.bin, sce_sys and
    the icon; the game files are read at run time from the --app-dir folder (PS4_APP_DIR
    changes it, --copy-resources copies the whole game into the bundle instead).

  4. Sign ad hoc (again after every rebuild):

    codesign -f -s - /path/to/build/eboot.app
  5. 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, in libSceGnmDriver; 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 every eboot.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 analyze coverage 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 --help banner, the bundle ID and the on-disk folders still
    say PS4Recomp.
  • Not notarized. ps4-recomp is only ad-hoc signed; see the quarantine note in Quick start.
  • A folder named assets near the build overrides --app-dir. Keep the build out of folders
    that contain an assets/ folder, or set PS4_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-recomp through a symlink elsewhere. It searches for pkg/runtime and
    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.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.

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 25 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 both backends, Metal 4 with the residency check. go vet, gofmt
    and go test are 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=0 throughout); 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), the PS4_GNM_COMPUTE_BATCH switch,
      explicit fence overrides and the Metal 3 default.
  • 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 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