DR-89/fear-vr

# F.E.A.R. VR 开源的、可本地构建的 VR mod，适用于 **《F.E.A.R. 1.08》单机基础版本**（`FEAR.exe`，LithTech Jupiter EX，Direct3D 9）。 ## 演示 [](https://youtu.be/QTsNeLT8Pn8) ## 功能 此处列出的所有功能均已实现并已在实际游戏中运行。某些已构建但尚未在游戏中验证的功能会特别注明。 ### 渲染 - **原生立体世界渲染。** LithTech 相机每帧使用各自独立的视矩阵渲染两次——而不是复制的单色图像。加载后自动激活；随时可按 F8 切换。 - **相对头部追踪。** HMD 旋转会相对于中立姿态旋转游戏相机；俯仰和翻滚得以保留。按 F9 或右摇杆点击可将当前注视方向设为中立姿态。 - **可选的 HMD 平移**，最高 25 厘米（`-Translation`）。由于没有世界物理碰撞，此功能需刻意手动开启。 - **立体 HUD。** 弹药、生命值和提示信息会叠加到双眼，而不是平铺在左眼图像上。HUD 向屏幕中心均匀压缩（5/4），以便让边缘元素保持在舒适的视野范围内。 - **全屏 UI 的平面屏幕模式。** 菜单、加载界面、影片和任务简报会以世界锁定的 2.4 × 1.8 米面板形式出现在 2 米距离处。检测基于零售版游戏状态 `CInterfaceMgr::m_eGameState`，而不是像素启发式算法。右摇杆点击可将面板重新锚定到当前注视方向。 - **舒适屏幕 (F10)。** 用于相机震动和过场动画的世界锁定渲染，使得强制性的相机移动不会牵扯玩家头部。 - **静默相机。** 武器摆动和相机后坐力已禁用；默认关闭头部摆动，且只能通过 `fearvr.ini` 切换。 - **第一人称身体修正。** 上臂和下臂被隐藏；手部和武器保持可见。经典准星已关闭，因为红色瞄准激光接管了它的作用。 ### 动态控制 - **通过 OpenXR 控制器进行完整的游戏控制** —— 移动、转向、跳跃、蹲下、冲刺、切换武器、装弹、手雷、慢动作、使用、瞄准、射击、暂停和重置视角。鼠标、键盘和手柄可同时并行使用。 - **武器跟随右手。** 射击原点和射击向量来自枪口变换，而不是注视方向。 - **来自枪口的红色瞄准激光**，可开启/关闭。 - **指向而非注视。** 激活和拾取跟随武器激光（约 1.5 米范围），而不是头部方向。 - **左手手持手电筒。** 它跟随手部位置和瞄准方向，并通过点击左扳机切换。零售版中第二个无法关闭的手电筒已被移除。 - **通过手部倾斜进行侧身。** 向侧面倾斜左手即可在角落侧身；支持反转和悬垂手部姿态。 - **每次射击的触觉反馈**，包括全自动射击——在零售版射击时触发，而不是在扣动扳机边缘时触发。弹匣为空 = 无震动。 ### 菜单与设置 - **ESC 菜单中的原生 VR 设置页面**（“VR SETTINGS”），支持控制器操作：立体渲染、立体 HUD、转向速度、红色瞄准引导、控制器震动、重置视角、恢复 VR 默认设置。 - **在 `fearvr.ini` 中持久化保存**，包含未在菜单中公开的设置：HMD 平移、头部摆动和舒适屏幕。 - **F11 校准** 用于玩家身体部件，以防默认手臂部件不合适。结果会立即保存。 ### 运行机制 - **按位数区分的两个进程：** x64 OpenXR 主机和 x86 D3D9 桥接通过带有帧环形缓冲区和心跳监测的版本化共享内存协议进行通信。如果主机崩溃，游戏会继续以平面模式运行。 - **启动时选择运行时：** 已确认支持 SteamVR 和 VirtualDesktopXR；`-Runtime` 仅为宿主进程设置 `XR_RUNTIME_JSON`。 - **SteamVR Desktop Theater** 会自动禁用并进行监测；在 VDXR 下此步骤会完全跳过。 - **结构化的 JSON 日志**，用于主机和桥接并带有性能计数器；每次运行都会写入 `logs\` 下自己的目录中。 - **版本绑定与故障安全。** 所有零售版 hook 都会检查时间戳、映像大小和预期的字节模式。如果不匹配，该 hook 将保持禁用状态，游戏继续运行。提供 `-fearvr-safe`、`-fearvr-no-interaction` 或 `-fearvr-no-gamestate` 等诊断开关。 - **可分发的软件包**（`tools\make-release.ps1`），包含安装程序、桌面快捷方式和卸载程序。它仅包含我们自己基于 MIT 许可证的二进制文件；专有模块从本地 Public Tools 安装中提取。 ## 核心原则 - **零售版文件保持原样。** 不会向 Steam 安装目录写入任何内容，也不会覆盖任何原始的 EXE/DLL/存档文件。所有工作都在项目根目录（`stage/`）下的隔离暂存区进行，并使用其专用的 `-userdirectory`。 - **Git 中不包含零售版/SDK/资产文件。** 请参阅 `.gitignore`。 - **按位数区分的独立进程：** x64 OpenXR 主机拥有 OpenXR 会话；x86 `FEAR.exe` 通过 `d3d9.dll` 桥接和本地重编译的 GameClient 模块进行渲染。原因：本机缺少 32 位 OpenXR 运行时注册表项（参见 `docs/ENVIRONMENT.md`）。 ## 架构（概述） ``` SteamVR / OpenXR (x64) ^ OpenXR + XR_KHR_D3D11_enable fearvr-host.exe (x64, D3D11) ^ versioned IPC (poses, FOV, shared texture handles) FEAR.exe (x86, D3D9) + d3d9.dll bridge + GameClient module (x86) v LithTech RenderCamera, twice per frame ``` 详情：`docs/ARCHITECTURE.md`。 ## 仓库结构 | 路径 | 内容 | |---|---| | `docs/` | 环境、架构、坐标、立体研究、测试 | | `src/common/` | 共享的 IPC 合约 (`protocol.h`) + 数学运算 | | `src/host64/` | x64 OpenXR 主机 (`fearvr-host.exe`) | | `src/proxy32/` | x86 D3D9 代理/桥接 | | `src/gameclient_loader/` | 用于真实 `archcfg` 阶段的中立 ABI 加载器 | | `src/launcher/` | 启动器（启动主机，然后是隔离的 `FEAR.exe`） | | `game-source-overlay/` | 仅包含**新编写的** GameClient 项目文件 | | `patches/` | 最小的、经过许可证检查的 diff / 转换脚本 | | `shaders/` | 主机全屏/合成着色器 | | `tests/` | 自动化测试（协议、数学、状态机……） | | `tools/` | `verify-install.ps1`, `prepare-m5-stage.ps1`, `launch-m5-fear.ps1` …… | | `vendor-local/`, `build/`, `stage/`, `logs/` | 本地文件，**不**在 Git 中 | ## 前置条件 请参阅 `docs/ENVIRONMENT.md` 了解已验证的当前状态以及仍然缺失的组件。简而言之： - 《F.E.A.R. 1.08》（终极射击版），已合法安装 - Visual Studio 2022 及其“使用 C++ 的桌面开发”（+ 用于编译/源码分析的 v141 工具集；运行时 Public Tools 模块需要 VC7.1） - CMake, Git - SteamVR 作为活动的 OpenXR 运行时 + 头显 - 本地官方 Public Tools 安装程序 1.08 ## 快速开始（验证环境） ``` pwsh -File tools/verify-install.ps1 ``` 检查零售版路径、`FEAR.exe` 哈希值/版本、OpenXR 运行时、注册表和可用的构建工具，并报告缺失的组件——不进行任何更改。 ## 构建 一条命令即可检查固定依赖项、构建 x86 和 x64 版本、运行两个测试套件，并写入包含所有构件 SHA-256 校验和的 `stage\build-manifest.json`： ``` pwsh -File tools\build-all.ps1 ``` 依然可以进行单独构建；x86 (proxy) 和 x64 (host) 是**分开**构建的： ``` pwsh -File tools\prepare-dependencies.ps1 cmake -S . -B build\x86 -A Win32 -DFEARVR_BUILD_PROXY=ON -DFEARVR_BUILD_HOST=OFF cmake --build build\x86 --config RelWithDebInfo cmake -S . -B build\x64 -A x64 -DFEARVR_BUILD_PROXY=OFF -DFEARVR_BUILD_HOST=ON cmake --build build\x64 --config RelWithDebInfo ``` `-G "Visual Studio 17 2022"` 是其中的一部分：如果没有 `-G`，CMake 会选择最新安装的 Visual Studio，而 x86 模块必须保持与 v141/VC7.1 的兼容性。`build-all.ps1` 会检测使用不同生成器创建的构建树并重新创建它。 这些构件是**进程可复现的，而非位完全相同**：MSVC 会嵌入时间戳和 PDB GUID，因此相同源码的两次构建会产生不同的哈希值。清单会记录 Git 状态，并在工作树状态不干净（dirty）时发出警告。 针对活动的 OpenXR 运行时验证 M1 主机： ``` build\x64\src\host64\RelWithDebInfo\fearvr-host.exe --validate-only build\x64\src\host64\RelWithDebInfo\fearvr-host.exe --max-frames 120 ``` M2 桥接与真实阶段： ``` pwsh -File tools\test-m2-bridge.ps1 pwsh -File tools\test-m2-bridge.ps1 -ClassicD3D9 pwsh -File tools\test-m2-bridge.ps1 -AbortHost pwsh -File tools\prepare-m2-stage.ps1 pwsh -File tools\launch-m2-fear.ps1 ``` 可玩的 M4 版本： ``` pwsh -File tools\prepare-m4-stage.ps1 pwsh -File tools\launch-m4-fear.ps1 ``` 带有动态控制的 M5： ``` pwsh -File tools\prepare-m5-stage.ps1 pwsh -File tools\launch-m5-fear.ps1 ``` ## VR 运行时：SteamVR 或 Virtual Desktop 该 mod 不绑定任何特定的运行时——x64 主机仅使用 OpenXR。**SteamVR** 和 **VirtualDesktopXR (VDXR)** 已确认支持。 ``` pwsh -File tools\launch-m5-fear.ps1 # active runtime pwsh -File tools\launch-m5-fear.ps1 -Runtime vdxr # Virtual Desktop pwsh -File tools\launch-m5-fear.ps1 -Runtime steamvr # SteamVR ``` `-Runtime` **仅为主机进程**设置 `XR_RUNTIME_JSON`。 `HKLM\SOFTWARE\Khronos\OpenXR\1\ActiveRuntime` 下的系统全局设置不会被更改；如果要永久更改，请分别在 Virtual Desktop Streamer 或 SteamVR 中进行。 `tools\verify-install.ps1` 会显示当前活动的运行时以及已安装的运行时。 仅在 SteamVR 下才会执行 SteamVR 特定的步骤（禁用 `autoShowGameTheater`、影院 watchdog）。在 VDXR 下这些步骤会被完全跳过，且不会触碰任何 SteamVR 文件。 **仍然需要 Steam** —— 但仅作为商店：《F.E.A.R.》官方通过 `steam.exe -applaunch 21090` 启动。这与哪个 VR 运行时渲染无关。在 VDXR 下，SteamVR 本身不需要运行。 按键绑定：左摇杆移动，左侧手柄（Grip）冲刺；左摇杆点击保持自由。右摇杆转向；达到 80% 偏移时执行跳跃和蹲下，摇杆点击重置视角。A 键切换武器，B 键装弹（短按）或投掷手雷（长按），X 键切换慢动作，Y 键打开暂停。右侧手柄（Grip）执行使用，扳机执行瞄准和射击。向侧面倾斜左手可在角落侧身。手电筒位于左手，跟随其位置和瞄准方向，通过点击左扳机切换。每次射击都会震动。鼠标、键盘和手柄可同时并行使用。详情：`docs/OPENXR-INPUT.md`。 在第一人称视角下，只有手和武器可见；上臂和下臂被隐藏。 M5 启动时会默认启用已确认的立体 HUD，并自动关闭 SteamVR 延迟的 F.E.A.R. Desktop Theater。选项： - `-Translation`：有限的 HMD 平移，最高 25 厘米，无世界物理碰撞； - 头部摆动默认关闭；在 `fearvr.ini` 中设置 `HeadBob=1` 仅启用相机移动，同时武器保持稳定以实现稳定瞄准； - `-NoHeadBob`：强制关闭头部摆动，即使 INI 启用了它； - `-NoStereoHud`：仅用于对比/故障排除。 游戏内按键： - F8：开启/关闭原生立体世界渲染； - F9：重置当前 HMD 朝向； - F10：开启/关闭用于相机震动和过场动画的世界锁定舒适屏幕； - F11：逐个隔离玩家身体部位以重新校准手臂部件。仅在默认设置不合适时需要使用。 M5 的 ESC 菜单在紧接“Options”之后包含英文标记的“VR SETTINGS”条目。该页面被刻意保持简短的单页形式：立体渲染、立体 HUD、转向速度、红色瞄准引导、控制器震动、重置视角、恢复 VR 默认设置和 BACK。HMD 平移、头部摆动和舒适屏幕依然可以在 `fearvr.ini` 中进行配置，避免使原生菜单变得杂乱。选择会保存到 `stage/userdata-m5/fearvr.ini`。摇杆进行导航，A 或扳机确认，B 返回。 ## 卸载 在项目根目录之外，该 mod 仅写入 **一个** 文件：`steamvr.vrsettings`，并且仅涉及 `steamvr.autoShowGameTheater` 键。没有注册表更改，没有向零售版安装目录写入，项目文件夹之外也没有任何文件。 ``` pwsh -File tools\uninstall-fearvr.ps1 # dry run, changes nothing pwsh -File tools\uninstall-fearvr.ps1 -Apply # actually remove ``` 移除stage\`、`build\`、`dist\`、`local-runtime\` 和 `logs\`。 在执行此操作前，会专门从最旧的备份中还原 `autoShowGameTheater` —— 仅限该一个键，因此后续自定义的 SteamVR 设置会被保留。 **游戏存档不会被移除。** `stage\userdata-*` 是游戏的 `-userdirectory`，包含存档、配置和截图。这些属于用户数据，而非 mod 文件；它们仅在使用 `-IncludeUserData` 时被移除。 其他开关：`-KeepLogs`、`-IncludeVendor` 和 `-Scope SteamVrOnly|ProjectOnly`。 不需要进行 Steam 文件完整性检查，因为从未向零售版文件写入任何内容。脚本会在卸载前后验证 `FEAR.exe` 的 SHA-256。 在卸载过程中应关闭 SteamVR：它会在关闭时重写其配置，否则会覆盖还原的内容。如果脚本检测到 SteamVR 正在运行，将会发出警告。 ## 已知限制 - 经典的 D3D9 路径需要每帧进行 CPU 回读（`FEARVR_BF_CPU_FALLBACK`），立体 HUD 合成器也是如此。两者均被标记为概念验证，并非正式发布的性能优化路径。 - HMD 平移没有世界物理碰撞，因此依然保持可选状态（`-Translation`）。 - 依赖版本的 hook 适用于 **F.E.A.R. 1.08.282.0**。如果哈希值或签名不匹配，它们将保持禁用状态，游戏继续以平面模式运行。 - 左侧系统/菜单按钮无法绑定：SteamVR 会将其捕获用于自身的系统菜单。 - 上楼梯时的武器跳动问题尚未得到彻底解决，因此被刻意推迟处理。 - “动态控制瞄准”已通过瞄准激光和命中点进行验证；未宣称支持通用的“6DoF 武器”。 ## 许可证 自主编写的组件基于 **MIT License**（见 `LICENSE`）。 有关依赖项以及官方 F.E.A.R. Client 和 Public Tools 组件的许可边界，请参见 `THIRD_PARTY_NOTICES.md`。 ## 法律声明 此 mod **不**包含任何零售版文件、专有 SDK 源代码和提取的资产。构建和运行它需要您自己合法购买的《F.E.A.R.》安装版本以及官方 Public Tools 安装程序。“VR 可玩”的声明最早从 M4 开始，“动态控制”从 M5 开始。

标签：AI合规, Bash脚本, Direct3D 9, OpenXR, VR模组, 动作控制, 头动追踪, 游戏Mod, 立体渲染, 虚拟现实