AnyPS5 OSX Edition v1.0.0 - Hybrid Suite

AnyPS5 OSX Edition v1.0.0 — Hybrid PS5 + Switch Suite

Native macOS (Metal/MetalFX) port of AnyPS5, packaged as a hybrid console suite with the real Ryujinx Switch engine and an optional OptiScaler enhancement layer for Windows.

Highlights

• Native Metal backend (MetalDevice.mm): CAMetalLayer presentation, MSL composite pipeline, MetalFX SpatialScaler upscaling (macOS 14+), SPIRV-Cross SPIR-V→MSL compute dispatch — verified on Apple hardware (METALFX_SPATIAL=available on the CI runner probe)
• Full-fidelity execution fallback: Vulkan on MoltenVK (loader chain libvulkan.1.dylib → libvulkan.dylib → libMoltenVK.dylib)
• Mach-O relinker output (--macos): PS5 ELF → x86_64 Mach-O with LC_MAIN, LC_DYLD_INFO binds, build version, UUID; Mach-O NID export-trie/symtab patching
• Darwin compatibility layers: guest-memory fault tracking (mach_vm_region + shm backing), Itanium C++ ABI views for libc++abi, jthread/stop_token shim, Mach-O export aliasing, dyld-based unwind tables
• Hybrid launcher (anyps5-launcher): auto-routes PS5 titles (.elf/.self + sce_sys/param.sfo) vs Switch titles (.nsp/.xci/.nca/.nro)
• Switch engine: authentic Ryujinx C# source (MIT), pinned submodule, dotnet CI build
• CI matrix green: macOS x64 + arm64 (Metal probe), Linux, Windows (MinGW), Switch engine — workflow run

Integrity notice

The ryujinxemul/Ryujinx-Nintendo-Switch-Emulator repository was analyzed and found to be fake (stub files, no emulator code, placeholder key files). This suite integrates the genuine Ryujinx source via alula/Ryujinx instead. Details in the report.

Quick start (macOS)

git clone --recursive https://github.com/romangalaxys10-spec/AnyPS5-OSX.git
cd AnyPS5-OSX && ./scripts/build-macos.sh
brew install molten-vk   # Vulkan fallback runtime
./scripts/fetch-moltenvk.sh build   # or bundle libMoltenVK.dylib manually
./build/core/relinker/relinker game.elf game-mac --macos
ANYPS5_GPU_BACKEND=metal ./build/core/relinker/relinker  # backend selection is runtime

Honest capability statement

Guest graphics draw pipelines execute through MoltenVK on macOS in this edition; the native Metal backend owns presentation, MetalFX upscaling, and compute dispatch. The native Metal Draw path is the roadmap headline. "Runs any modern PS5 game" remains aspirational for the whole AnyPS5 family (upstream is pre-first-release); this edition delivers the platform, acceleration, and verification infrastructure that makes that goal reachable on Apple hardware.

---

Full engineering report below.

---

AnyPS5 OSX Edition — Engineering Report

Version 1.0.0-osx · 2026-09-26 · branch osx-edition

This report documents the macOS (Metal/MetalFX) port of AnyPS5, the hybrid PS5 + Switch suite architecture, the verification status of every deliverable, and the roadmap toward running modern PS5 titles on Apple hardware.

---

1. Executive summary

The OSX Edition turns AnyPS5 — a PS5 executable porting toolkit that relinks PlayStation 5 executables into native host binaries — into a three-platform product line. The macOS path gains a native Metal backend with MetalFX spatial upscaling, a Mach-O relinker output (--macos), Darwin support across the kernel/libc compatibility layers, and a MoltenVK-backed Vulkan path retained as the full-fidelity execution engine. A unified launcher (anyps5-launcher) turns the repository into a hybrid console suite: PS5 titles route into the relinker pipeline, Nintendo Switch titles route into the pinned Ryujinx engine (the authentic community source mirror, MIT-licensed).

Every claim in this report is backed by a concrete artifact in the repository or by a GitHub Actions run on real Apple infrastructure (macos-15 runners, Xcode 16, Metal/MetalFX frameworks). The verification loop for this port was GitHub's macOS VM fleet — compile validation, unit tests, and Metal device probes all execute there, because the port was engineered remotely from a Linux environment.

Integrity note: the Nintendo Switch repository originally suggested for this task (ryujinxemul/Ryujinx-Nintendo-Switch-Emulator) was analyzed and found to be a fake — 10 stub files with broken includes, marketing screenshots, and placeholder text in place of key files. No real key material was present. The suite instead integrates the genuine Ryujinx source (MIT, full ARMeilleure/GAL/GPU tree) via a pinned submodule, and the fake repository is flagged here so users avoid it.

---

2. Upstream architecture as received

AnyPS5 (GPL-2.0, ~91k LOC of C++20, 1.3k+ stars) is organized into three pillars:

1. Relinker (core/relinker, 9.0k LOC). Converts PS5 ELF/SELF executables into native host images: ELF for Linux, PE for Windows. It rebuilds entry stubs, program/section layouts, PLT/GOT binding, SysV dynamic sections, and Windows TLS/imports/relocations. NID symbols are resolved through an NID patcher that rewrites exported symbol names per console NID tables.
2. Shader recompiler (core/shader, 33.7k LOC). A full RDNA instruction decoder feeding an IR, an optimization pipeline (SSA, SRT descriptor walking, binding allocation, dead-code elimination), and a SPIR-V backend validated by SPIRV-Tools. The PS5's GNM/AGC shader bytecode therefore arrives on the host as portable SPIR-V.
3. System libraries (core/libs, 48.2k LOC). Implementations of PS5 prx modules (libkernel, libc, libSceAgc/AgcDriver, libSceVideoOut, libSceAudioOut, libScePad, ...) compiled as host shared libraries with NID-patched exports. libSceAgcDriver contains the PM4 command processor and the Vulkan execution engine (VulkanDevice, 871 lines) plus a presentation scaler.

The upstream presentation seam was already clean: PresentationWindow abstracts the SDL window behind function pointers (surface creation, drawable size), and PresentationScaler isolates the upscale stage. That seam is exactly where this edition's Metal/MetalFX path plugs in.

---

3. Port architecture

3.1 Backend-neutral execution interface

Execution/include/GpuDevice.hpp extracts the complete public contract of VulkanDevice into an abstract interface (Target, WaitIdle, WaitDraws, AcquireGpuMemory, ResolveMemory, Window, Resize, Presentable, PresentClear, PresentPixels, PresentDisplayBuffer, Dispatch, Draw, EnqueueDraw). GpuDeviceFactory.cpp selects the backend per host:

• macOS: ANYPS5_GPU_BACKEND=metal (default) → MetalDevice; automatic fallback to VulkanDevice (MoltenVK) when no Metal device or MetalFX is available; ANYPS5_GPU_BACKEND=vulkan forces the Vulkan path.
• Linux/Windows: unchanged Vulkan path.

Driver.cpp was refactored from std::shared_ptr<VulkanDevice> to std::shared_ptr<GpuDevice> with zero behavioral change to the Vulkan pipeline.

3.2 Native Metal backend (MetalDevice.mm, Obj-C++)

• Device/window: MTLCreateSystemDefaultDevice, MTLCommandQueue, and a CAMetalLayer acquired from the SDL Cocoa window (attached on demand, framebufferOnly=NO, triple-buffered, high-DPI drawable sizing via convertRectToBacking:).
• Presentation path (complete): PresentClear (render-pass clear), PresentPixels (staging upload + inline MSL fullscreen-triangle blit with aspect-fit viewport from upstream's own ComputeContainRect_nid_postfix), PresentDisplayBuffer (guest BGRA8/RGBA8 buffers composited to the drawable).
• MetalFX upscaling: when macOS 14+ MetalFX is available and the drawable exceeds the source extent, the present path switches from bilinear blit to an MTLFXSpatialScaler (descriptor-cached per source/target size, LDR content, output format matched to the layer pixel format) — Apple's hardware-accelerated spatial upscaler, the same technology used by native Metal game ports.
• Compute dispatch: SPIR-V produced by the upstream recompiler is translated to MSL at runtime through SPIRV-Cross (CompilerMSL, MSL 2.3, MTLLanguageVersion3.0) and executed as Metal compute pipelines. Resource kinds that would require full descriptor-ABI parity with the Vulkan backend throw precise errors, matching upstream's strict-failure philosophy.
• Guest memory: a registry keyed by guest address (ResolveMemory) mapping to shared-storage MTLBuffers, mirroring the Vulkan device's memory resolution contract.
• Draw path: intentionally throws std::runtime_error directing users to the Vulkan backend for full game execution — a documented, honest boundary rather than a silent wrong-result path (Section 6).

3.3 Mach-O relinker output

MacosMachoPatcher (537 lines) converts the relinked PS5 ELF into a loadable x86_64 Mach-O executable: MH_EXECUTE with MH_NOUNDEFS|MH_DYLDLINK|MH_TWOLEVEL, __PAGEZERO/__TEXT/__DATA/__LINKEDIT segments from ELF program headers, LC_MAIN entry, LC_LOAD_DYLIB per DT_NEEDED prx (install names under @executable_path), LC_DYLD_INFO_ONLY bind opcodes for undefined symbols (both immediate GOT binding and lazy stub binding per the existing --lazy-binding flag), LC_BUILD_VERSION (macOS 12.0 min), deterministic LC_UUID (FNV-1a over image bytes), and an rpath command when --rpath is given. The NID patcher gained a Mach-O branch (MachONidPatcher, 680 lines) that rewrites the dyld export trie and LC_SYMTAB string tables exactly as the ELF/PE patchers do.

3.4 Darwin compatibility layers

• libc unwinding: the exception-handling table resolver gained a Darwin branch — images are enumerated through dyld, the relinker's __ehmeta table (same format the Windows path emits) is located via getsectiondata and binary-searched, with a linear __eh_frame fallback, mirroring the Windows PE logic line-for-line in semantics.
• Kernel PRX: the codebase's own ABI wrappers (PthreadAttr, mmap constants, time) proved portable; the audit found only the unwind path required Darwin-specific...