boykopovar/AnyPS5 — PS5 可执行文件自动移植工具

研究将 PS5 可执行文件移植到 Linux 和 Windows。
本周新增 Star 12,389 ｜ 仓库 Star 总数 47,176 ｜ Forks 4,378

▲ 图 0：AnyPS5 官方拼图（官方截图）

官方项目进度图（系统库与着色器覆盖率，随 main 分支实时更新）

▲ 图 1：AnyPS5 官方进度图（官方截图）

进度看板：https://boykopovar.github.io/AnyPS5/progress.html ｜ 历史记录：https://boykopovar.github.io/AnyPS5/history.html

指标含义：系统库的百分比指 项目已知函数 的占比（在 core/libs/prx 中声明的），而非 PS5 全部系统函数。总数会随更多函数被声明而增长。

一、它的工作原理

AnyPS5 包含：

• 一个 relinker：把可执行文件转换为目标系统的原生格式（Linux ELF / Windows PE / macOS Mach-O）
• 一套 系统 prx 库实现（core/libs/prx）：用于动态链接

没有模拟器，也没有单独的运行时进程。 这意味着性能接近原生，但需要为每个目标平台编译对应的系统库。

着色器重编译器（core/shader/recompiler/Recompiler.cpp）能成功产出 SPIR-V（构建时启用 ANYPS5_ENABLE_SPIRV_TOOLS 会用 Spirv-Tools 校验）。

二、环境要求

依赖矩阵

Windows 编译器选择警告：Scoop 的独立 GCC 15.2.0 包 无法 构建完整运行时 —— 禁用 SEH 会选中 SjLj 异常，其 SEH 后端无法编译 System V ABI 的 catch 处理器。请用 MSYS2 UCRT64 或具备 DWARF 能力的 WinLibs 发行版。此限制不适用于仅 relinker 构建。

三、部署方式

方式 A：网页转换器（零安装，强烈推荐先试这个）

打开 https://boykopovar.github.io/AnyPS5/ —— 文件不离开你的设备，转换在浏览器内完成。

单个应用转 Linux 输出：
- 选择或拖入一个应用 ZIP
- 转换器保存为未压缩文件夹（需浏览器支持）
- 不会覆盖已存在的目标文件夹；若转换失败或被取消，会中止当前文件并尝试删除新建的输出文件夹；若浏览器阻止清理，错误信息会指出可能含不完整文件的文件夹名

批量转换：
- 拖入多个应用 ZIP → 合并为一个 ZIP 包
- 转换器 分别检查 每个应用，把其可执行文件、库与 app0/ 文件放入 编号文件夹，因此同名压缩包不会互相覆盖
- 批量输出使用 ZIP 模式；未压缩文件夹模式仅对单个 Linux 应用可用
- 整个包受 256 MiB 内存下载上限限制，更大的批次请用 Save ZIP to disk
- 批次被取消或任一应用失败 → 中止不完整的包；清理失败会被报告而非当作成功结果交付

方式 B：仅构建 relinker（最简单，推荐）

无需初始化子模块，无需配置 SDL / Vulkan / FFmpeg / FreeType 或着色器重编译器。只需 CMake + C++20 编译器 + 构建工具；Python 3.9+ 可启用 Python 回归测试。

cmake -S . -B build-relinker -G Ninja -DCMAKE_BUILD_TYPE=Release -DANYPS5_RELINKER_ONLY=ON -DBUILD_TESTING=ON
cmake --build build-relinker --parallel
ctest --test-dir build-relinker --output-on-failure

• CMake 配置阶段需能找到 Python 才会注册 Python 测试
• 用 ctest --test-dir build-relinker -N 列出已注册测试，应看到 input_magic（一个 Python 驱动的 relinker 测试）
• 自动发现失败时，显式指定：-DPython3_EXECUTABLE="C:/path/to/python.exe"
• 产物：build-relinker/core/relinker/relinker（Windows + Ninja 下为 relinker.exe）
• 此模式 不构建 系统库，官方 release 归档仅随附 Linux 与 Windows 的库

方式 C：完整构建（可运行游戏）

# 1. 初始化子模块
git submodule update --init --recursive

# 2. 配置
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++
cmake --build build --parallel

# 3. 单独构建系统库（重要！）
cmake --build build --target libs --parallel

libs 是必须单独执行的自定义目标。 core/libs/prx 下的每个库都以 EXCLUDE_FROM_ALL 构建。默认 BUILD_TESTING=OFF 时，默认构建 不会 生成它们，必须显式执行 --target libs。开启 BUILD_TESTING=ON 时默认完整构建会通过 patched_libraries_tests 依赖一并构建 libs。

改了库之后没重建 libs 就运行游戏，测的是旧二进制，会看起来"完全没效果"。

Windows（PowerShell）环境准备：

$env:PATH = "C:\tools\winlibs\mingw64\bin;C:\Program Files\Git\cmd;C:\Program Files\Git\usr\bin;$env:PATH"

# 若 CMake 报 Could NOT find Python3
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DPython3_EXECUTABLE="C:/path/to/python.exe"

# 构建后把运行时 DLL 拷到库目录
$toolchainBin = "C:\tools\winlibs\mingw64\bin"
foreach ($runtimeName in @("libgcc_s_seh-1.dll", "libstdc++-6.dll", "libwinpthread-1.dll")) {
    Copy-Item -LiteralPath (Join-Path $toolchainBin $runtimeName) -Destination "build/core/libs/libs"
}

Windows 的运行时加载器 不搜索 PATH 找这些依赖 —— 缺 DLL 会报 error 126（找不到指定模块），即使 .prx 文件就在那里。

Linux 补充： 若 CMake 报 Could NOT find Threads，执行 sudo dnf install glibc-static libstdc++-static 后重新配置（项目启用静态可执行文件链接，FFmpeg 的线程检查需要这些库）。

FFmpeg 下载： 配置期间会自动下载 FFmpeg 二进制（除非设置了 FFMPEG_PREBUILT_DIR）。用 WinLibs CMake 时若下载失败（status 60，SSL 证书错误），需设置 SSL_CERT_FILE 指向 CA bundle，例如 C:\Program Files\Git\ucrt64\etc\ssl\certs\ca-bundle.crt（Git for Windows 2.56+；之前版本用 mingw64 而非 ucrt64）。

四、使用方法

4.1 输入目录结构

使用 干净的 ELF 可执行文件。把随附的 ELF 模块放在输入可执行文件的同级 sce_module/、sce_modules/ 或 prx/ 目录中，或用 --sce-module-path 指定的父目录下：

source/
    input.elf
    sce_module/

规则：

• --sce-module-path 接受绝对路径与相对当前工作目录的路径；不要包含 sce_module 这一层目录名
• 只处理模块目录 直接内 的文件
• SELF/fSELF 容器会被 跳过并给出警告 —— 需要纳入请先解包
• sce_module/ 与 sce_modules/ 同时存在是错误
• 三者全缺失是错误，除非显式提供 --module-dir
• prx/ 可以与 sce_module/ 或 sce_modules/ 共存
• 用 tools/unwrap_self.py 解包已解密的 SELF 容器（把段放到 SELF 段记录的偏移处，恢复 p_offset % p_align == p_vaddr % p_align；若所有加载段看起来都是加密的则拒绝）

4.2 基本转换命令

relinker [options]  

# Linux 输出
relinker source/input.elf app.elf

# Windows 输出
relinker --windows source/input.elf app.exe

# macOS 输出（x86-64 Mach-O，Apple Silicon 上通过 Rosetta 运行）
relinker --macos source/input.elf eboot

重要：输出格式 默认是 Linux ELF，与文件名无关。单靠 .exe 后缀 不会 选中 Windows 格式。

Intel / Rosetta 转换：

relinker --to-intel source/input.elf app.elf          # Intel 主机
relinker --macos --to-rosetta source/input.elf eboot    # Apple Silicon + Rosetta

--to-intel 会重写可执行文件与随附模块中的 AMD 专属指令，但 无法 翻译游戏运行时动态生成的 AMD 指令 —— 这类游戏需要 AMD 主机。--to-rosetta 在 --to-intel 基础上还降级 Rosetta 缺少的指令：ANDN 变标量 NOT/AND，RDSEED 变 RDRAND，CLWB 变 NOP，RDPID 与 RDTSCP 的 ECX 返回处理器 0。

4.3 运行时目录布局

app.elf (Linux) 或 app.exe (Windows)
libs/
    *.prx
app0/

    eboot.bin
    sce_module/
        <已转换的模块>

• libs/ 放 AnyPS5 的系统库，不是原始 PS5 的 .prx 文件
• 把构建好的系统库从 build/core/libs/libs/*.prx 复制到 libs/（用目标 OS 对应的版本）
• 应用资源单独放在 app0/，包括游戏原本的 eboot.bin —— 游戏会测试 /app0/eboot.bin 来定位自身目录（主机上它总是存在）
• 也可以把资源打包成 app0.zar（ZArchive 格式，根目录就是 app0/）
• 某些应用还需要原始的 app0/sce_sys/param.json：必须含非空 titleId 字符串与非空 localizedParameters 对象（含一个带非空 titleName 的语言项）。启动时若存在该文件会创建 data/；非零的 downloadDataSize 还会创建 download0/

4.4 运行

Linux：

./app.elf

relinker 会给 app.elf 及其列出的每个 Executable file: 加上可执行权限。若权限丢失（如浏览器下载），先 chmod +x。

Windows（PowerShell）：

.\app.exe

--windows-gui 构建在没有标准输出句柄时（如从资源管理器启动），输出写入同目录的 anyps5.log，覆盖上一次运行的文件。

4.5 常用选项

--skip-sce-module、--exclude-sce-module、--skip-syscall-check、--lazy-binding 已废弃。 官方明确说明：启用这些标志的应用会 极不稳定，不适合一般使用，仅供调试。

4.6 游戏补丁（Game patches）

补丁文件在转换前修改输入可执行文件或随附模块的字节，用于应对硬编码了主机无法满足的数值。relinker 会检查它要替换的字节，因此针对另一版本的补丁会失败而不是损坏文件。

输入可执行文件目录下的 relinker-patches.toml 会 自动加载 并打印 Patches:。

format = 1

[[patch]]
name        = "pool_size"
target      = "eboot.elf"
va          = 0x1234
type        = "i32"
expected    = 0x10000000
value       = 0x18000000
max         = 0x7f000000
align       = 0x1000
description = "pool size"

x86 注意事项： mov r/m64, imm32 与 add/sub/cmp r/m64, imm32 会对立即数做符号扩展。要通过 imm32 修补 64 位字段，请用 type = "i32" 并加 min 以排除负值。

校验模式：

relinker --verify-patches patches.toml source/input.elf
relinker --verify-output --verify-patches patches.toml app.elf

4.7 输入映射（手柄与键鼠）

支持 SDL 映射的游戏手柄，含摇杆与扳机。键鼠可用 anyps5-input.ini 配置。支持设备与配置格式见 docs/user/INPUT_MAPPING.md。

4.8 Linux 特殊权限

当 Vulkan 驱动导入 dma-buf 内存（非 NVIDIA 专有驱动）时，共享直接内存通过 /dev/udmabuf 导入，运行游戏的用户需对其有读写权限。很多发行版创建它为 root:kvm 模式 0660：

sudo usermod -aG kvm $USER   # 然后重新登录
# 或（重启前有效）
sudo setfacl -m u:$USER:rw /dev/udmabuf

无权限时启动会打印 [gpu] open /dev/udmabuf: Permission denied，这些范围会被复制而非导入，通过 FLAT/GLOBAL 地址的 GPU 写入会失败并报 BDA access failed。

4.9 Windows 直通内存

直接内存（sceKernelAllocateDirectMemory，每游戏最高 13824 MiB）在 游戏映射时 才提交，而不是游戏分配或首次使用页面时。系统提交上限（已装内存 + 页面文件大小，即任务管理器"已提交"的第二个值）必须覆盖映射的直接内存与其他所有已提交内存。否则 sceKernelMapDirectMemory 抛 replace guest placeholder with resident direct memory。解决：扩大页面文件或关闭其他应用。

五、常见问题

Q：为什么游戏启动就停？
多半是 CPU 扩展缺失（AVX2 / FMA / F16C / BMI1 / BMI2 / LZCNT / MOVBE）。程序会在运行任何游戏代码前打印主机 CPU 扩展并指名缺失项。

Q：dlopen: was not relinked 错误？
游戏运行时加载的某个模块没有被转换（可能所在目录没传给 --module-dir）。用 --module-dir 重新转换该目录。

Q：Windows 报 error 193？
你把原始 PS5 的 .prx 放进了 libs/ —— Windows 会尝试把它当 DLL 加载。libs/ 只放 AnyPS5 系统库。

Q：Windows 报 error 126，但 .prx 明明在？
缺 libgcc_s_seh-1.dll / libstdc++-6.dll / libwinpthread-1.dll。Windows 加载器不搜 PATH，必须把 DLL 放在 libs/ 里。

Q：改了库但游戏行为没变？
没执行 cmake --build build --target libs --parallel，测的还是旧二进制。

Q：SELF 文件被跳过？
SELF/fSELF 容器会被跳过并警告。先用 tools/unwrap_self.py 解包。

六、免责声明

本项目用于 互操作性、研究、保存与兼容性 目的。不包含、不分发、也不需要 受版权保护的软件、固件、加密密钥或专有库。用户需自行确保所用二进制文件的获取与使用符合适用法律与其各自许可条款。

AnyPS5 是独立项目，与 Sony Interactive Entertainment 无任何隶属、授权或认可关系。"PlayStation" 与 "PS5" 是 Sony Interactive Entertainment Inc. 的商标。

参考链接

• 仓库：https://github.com/boykopovar/AnyPS5
• 网页转换器：https://boykopovar.github.io/AnyPS5/
• 使用文档：https://github.com/boykopovar/AnyPS5/blob/main/docs/user/USAGE.md
• 构建文档：https://github.com/boykopovar/AnyPS5/blob/main/docs/dev/BUILD.md
• 架构文档：https://github.com/boykopovar/AnyPS5/blob/main/docs/dev/ARCHITECTURE.md
• 输入映射：https://github.com/boykopovar/AnyPS5/blob/main/docs/user/INPUT_MAPPING.md
• Discord：https://discord.gg/BHFztBPUe