Skip to content

ps4-native-mac v0.1.0

Choose a tag to compare

@manjarqo manjarqo released this 21 Oct 19:25

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=uncapped is the default). The walking numbers come
    from a scripted pad route with PS4_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 libraries libgcn_recompiler.a, libspirv-cross.a,
    libatrac9.a and the headers the runtime includes (gcn_recompiler.h, the LibAtrac9 headers,
    minimp3.h);
  • 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. 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)

  1. 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
  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.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 -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). For TLOU,
    generation takes ~25 s and a full build took ~85 s on the M1 Pro.

  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

    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_DIR when 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 setting PS4_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_writelane returns 0 (a counted, logged gap).
    • Inside per-lane EXEC scopes, v_readfirstlane and v_mbcnt of 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, 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 and names instructions the backend does lift
    (for example SFENCE, VPSHUFD). 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. At start the runtime looks for
    an assets/ 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 /app0 instead 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 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.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.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

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