zhen469891/gbfr-ultrawide

# GBFRUltrawide 针对**碧蓝幻想：Relink v2.0.2**（Granblue Fantasy: Relink v2.0.2）的带鱼屏/非 16:9 比例修复补丁，以 x64 ASI 插件形式提供。它能在 21:9 / 32:9（以及更窄的）显示器上恢复自定义分辨率、正确的宽高比以及合适的 HUD。 ## 这是什么（以及为什么会有这个项目） 本项目是对 [Lyall's GBFRelINKFix](https://github.com/Lyall/GBFRelinkFix)（MIT 许可证）的 **v2.0.2 重写版**。GBFRelinkFix 是为游戏 v1.x 版本编写的；当 Relink 更新到 v2.0 时，编译器重新生成了每个 hook 站点周围的代码，导致**所有原始内存特征码都失效了**。上游仓库现在已被归档且不再维护。 GBFRUltrawide 保留了上游的 hook *设计* 和 ini 布局，但针对游戏 **v2.0.2** 对每个特征码都进行了重新寻找、反汇编和指令级别的验证。它还放弃了 spdlog 依赖，转而使用极简的内置记录器，将模块重命名为 `GBFRUltrawide`，并为每次扫描记录了明确的 `HIT` / `MISS` / `FIRED` 行，这样在未来的游戏更新中，就可以清楚地看出是*哪个*单独的功能损坏了。 完整的工程细节故事——包括每个特征码是如何被重新定位的，以及当游戏再次更新时如何重新操作——请参阅 [`docs/PATTERNS.md`](docs/PATTERNS.md)。 ## 功能 | 功能 | ini 节 | 备注 | | --- | --- | --- | | 自定义分辨率 / 带鱼屏 | `[Custom Resolution]` | 任意 WxH，或填 `0` 使用桌面分辨率。修补预设及质量表，以及所有应用路径。 | | 宽高比修复 | `[Fix Aspect Ratio]` | 在任何比例下修正 3D 投影宽高比（修复画面拉伸/侧边黑边问题）。 | | HUD 锁定并居中至 16:9 | `[Fix HUD]` | 保持 HUD 清晰易读且居中，而不是拉伸铺满整个屏幕宽度。 | | 拉伸 HUD | `[Span HUD]` | 可选地将游戏主界面 HUD 拉伸至所选比例（`SpanAllHUD`，`SpanAllBackgrounds`）。 | | 拉伸背景 | `[Fix HUD]` / `[Span HUD]` | 淡入淡出、菜单和全屏背景将填满整个屏幕。 | | 画面破损修复 | (自动) | 在奇数宽度（例如 3440）下向上取整内部渲染缩放值，以防止画面破损。 | | 阴影质量 | `[Shadow Quality]` | 覆盖阴影贴图分辨率（例如 4096/8192）。 | | 细节级别 | `[Level of Detail]` | 倍率，用于推迟物体 LOD 突现（pop-in）的距离。**中等可信度** —— 见下文。 | | 禁用 TAA | `[Disable TAA]` | 关闭时域抗锯齿。 | | 将 FPS 上限提高至 240 | `[Raise Framerate Cap]` | 实验性功能；超过 30 fps 时物理效果可能会出现异常。 | | 相机距离倍率 | `[Gameplay Camera Distance]` | 将游戏主相机向后/向前拉。 | ### v2.0.2 上的已知限制 - **不支持游戏主 FOV 倍率。** 在 v2.0.2 中，游戏相机消息不再带有 FOV 值——以前用于保存 FOV 的位置现在保存的是俯仰角（pitch）。对其进行 hook 会导致相机倾斜而不是缩放，因此我们刻意没有安装 FOV hook。任何 `[Gameplay FOV]` 的值（以及 `[Fix FOV]` 中针对 `<16:9` 的 FOV 补偿）都会在日志中标记为 *NOT SUPPORTED* 并被忽略。宽高比修正不受影响，在所有分辨率下均可正常工作。 - **LOD 距离**和 **UI 标记**属于**中等可信度**的定位。它们已经在指令级别上得到了验证，但最好能在游戏内进一步确认；如果它们表现异常，`docs/PATTERNS.md` 中记录了备选的回退候选位置。 ## 安装说明 游戏必须为 **v2.0.2** 版本（参见[兼容性](#compatibility)）。 ### 选项 A —— 安装程序（推荐） 运行 **`GBFRUltrawideSetup.exe`**。它会： - 自动检测 Steam 平台安装的 Relink（读取 Steam 的 `libraryfolders.vdf`、Steam App ID `881020`，以及常见的库目录），或者让你手动浏览找到它； - 将所有需要覆盖的文件备份到 `GBFRUltrawide_backup` 文件夹中，并提供选项备份并移除旧版 GBFRelinkFix 安装遗留的文件； - 将 `winmm.dll`（Ultimate ASI Loader）部署到游戏根目录，并将 `GBFRUltrawide.asi` + `GBFRUltrawide.ini` 部署到 `scripts\` 目录中； - 为 ini 提供图形化设置编辑器（分辨率、HUD、微调等）。 ### 选项 B —— 手动安装 1. 将 **`winmm.dll`**（捆绑的 Ultimate ASI Loader, x64）复制到游戏根目录中，与 `granblue_fantasy_relink.exe` 放在一起。 2. 将 **`GBFRUltrawide.asi`** 和 **`GBFRUltrawide.ini`** 复制到游戏的 `scripts\` 文件夹中（如果不存在则创建它）。 3. 启动游戏。日志将写入 `scripts\GBFRUltrawide.log`。 ## 配置 设置保存在 **`scripts\GBFRUltrawide.ini`** 中。节和键名与上游的 GBFRelinkFix 保持完全一致，以便现有的配置可以直接继承使用。核心选项： - `[Custom Resolution] Enabled / Width / Height` —— 设置你的分辨率，或者将 `Width`/`Height` 留空为 `0` 以继承桌面分辨率。 - `[Fix HUD] Enabled` —— 将 HUD 锁定为 16:9 并拉伸背景。 - `[Span HUD] Enabled / AspectRatio / SpanAllHUD / SpanAllBackgrounds` —— `AspectRatio = 0` 匹配你的屏幕；`1.7778` = 16:9，`2.3888` = 21:9，`3.5537` = 32:9。 - `[Fix Aspect Ratio] Enabled` —— 3D 宽高比修正。 - `[Shadow Quality] Enabled / Value` —— 例如 `2048`/`4096`/`8192`。 - `[Level of Detail] Multiplier` —— `>1` 可推迟 LOD 突现（pop-in）。 - `[Disable TAA] Enabled`，`[Raise Framerate Cap] Enabled`（240 fps，实验性功能）。 - `[GBFRelinkFix Parameters] InjectionDelay` —— 在应用非分辨率 hook 之前等待的毫秒数（默认 `1000`）。 ## 兼容性 专门为游戏 **v2.0.2** 构建 and 验证（模块时间戳 `1782470458`）。每个特征码都锚定在 v2.0.2 编译器生成的代码上，因此**未来的游戏更新极有可能破坏部分或所有特征码** —— 就像 v2.0 破坏了原版模组一样。当这种情况发生时，日志会将受影响的功能标记为 `MISS`，并*仅*禁用这些功能；其余功能将继续正常工作。重新寻找特征码的说明请见 [`docs/PATTERNS.md`](docs/PATTERNS.md)。 ## 从源码构建 要求：**Visual Studio 2022 Build Tools**，包含 MSVC **v14.4x** 工具集、**C++23**、**x64** 架构，以及 CMake 3.21+。 ``` .\build.ps1 ``` 这将使用 `Visual Studio 17 2022` 生成器 (`-A x64`) 进行配置，构建 Release 版本，并将产出文件收集到 `dist\` 目录中（包含 `GBFRUltrawide.asi` 和 `GBFRUltrawide.ini`）。 在 `build.ps1` 生成 `dist\` 后，（重新）构建安装程序： ``` powershell -ExecutionPolicy Bypass -File installer\build_installer.ps1 ``` 它会使用 .NET Framework 4.x 的 `csc.exe` 编译 `GBFRUltrawideSetup.exe`，并在 `installer\out\` 下组装发布布局（包含 exe + `payload\`，其中含有 `winmm.dll`、`.asi`、`.ini`）。 ## 故障排除 日志文件位于 **`scripts\GBFRUltrawide.log`**。对于每个特征码，它会记录以下状态之一： - **`HIT`** —— 特征码已找到；该行包含了安装 hook/补丁的模块相对偏移量（`granblue_fantasy_relink.exe+0x…`）。 - **`MISS`** —— 特征码*未*找到。仅该单个功能会被禁用；模组继续运行。游戏更新后出现 `MISS` 意味着该特征码需要重新寻找。 - **`FIRED`** —— 已安装的 hook 确实在运行时被执行了（每个 hook 记录一次）。出现了 `HIT` 但没有匹配的 `FIRED` 意味着 hook 虽然安装了，但游戏从未运行该代码路径 —— 这是一个有用的信号，表明特征码找到了错误（无效）的代码副本。 如果带鱼屏效果未生效：请确认游戏版本是 v2.0.2，`winmm.dll` 位于游戏根目录下，`.asi`/`.ini` 位于 `scripts\` 目录下，并检查日志中是否有 `MISS` 行。 ## 许可证与致谢 MIT —— 关于 **Lyall** 的原始工作，请参阅上游的 [GBFRelinkFix](https://github.com/Lyall/GBFRelinkFix)。 - [Lyall / GBFRelinkFix](https://github.com/Lyall/GBFRelinkFix) —— 原版模组、hook 设计及 ini 布局 (MIT)。 - [ThirteenAG / Ultimate ASI Loader](https://github.com/ThirteenAG/Ultimate-ASI-Loader) —— 通过 `winmm.dll` 进行 ASI 加载 (MIT)。 - [safetyhook](https://github.com/cursey/safetyhook) —— 内联/函数中部 hook，与 Zydis 一起 amalgamated (MIT)。 - [inipp](https://github.com/mcmtroffaes/inipp) —— ini 解析 (MIT)。

标签：ASI插件, Bash脚本, C++, 云资产清单, 内存Hook, 带鱼屏适配, 数据擦除, 游戏Mod, 逆向工程