III.VC.SA.WebView2

在 GTA III / Vice City / San Andreas 游戏内显示一个由系统 WebView2 渲染的网页面板，热键开关，页面地址与窗口模式由配置决定。

这个项目做什么

• 游戏内显示网页：面板是一个独立窗口，页面由系统 WebView2 渲染，不依赖任何菜单
• 独占全屏下改用抓帧贴图呈现，并提示切换到无边框窗口以获得原生速度与文字输入
• 页面加载失败时给出重新加载入口

不属于本项目的内容：

• 不提供菜单、作弊、传送等游戏功能，这些属于 XMenu
• 不内置网页内容，页面由配置里的地址决定

安装

1. 安装 Ultimate ASI Loader（若已装 Widescreen Fix 则自带）
2. 把 III.VC.SA.WebView2.asi 与同级的 WebView2\ 目录一起放进游戏目录或 scripts\ 目录
3. 目录结构保持如下，载荷 DLL 与 WebView2Loader.dll 必须和 ASI 在同一层目录下

游戏目录\
├─ III.VC.SA.WebView2.asi
└─ WebView2\
   ├─ WebView2III.dll
   ├─ WebView2VC.dll
   ├─ WebView2SA.dll
   └─ WebView2Loader.dll

运行时要求：Windows 10/11 自带 WebView2 运行时；缺失时面板不会出现，日志会记录原因。

支持的游戏

配置

首次运行会在载荷目录生成 WebView2\config.json，改动后重启游戏生效。

{
  "webview": {
    "url": "https://gtamodx.com/",
    "hotkey": "F8",
    "zoom": 1.0,
    "width": 1000,
    "height": 640,
    "windowMode": 2
  }
}

窗口模式说明：独占全屏时 DWM 不合成游戏窗口，面板只能以抓帧预览显示，帧率受限且不支持文字输入；把 windowMode 设为 2 并重启游戏后，游戏以无边框窗口运行，面板恢复原生渲染。

构建

依赖 XBase SDK。先构建 XBase，它会把头文件与静态库暂存到本项目的 include\XBase 与 lib：

XBase\Build.bat Release --no-pause
III.VC.SA.WebView2\Build.bat Release --no-pause

产物：

build\bin\III.VC.SA.WebView2.asi
build\bin\WebView2\WebView2SA.dll
build\bin\WebView2\WebView2VC.dll
build\bin\WebView2\WebView2III.dll
build\bin\WebView2\WebView2Loader.dll

代码结构

加载链路：

III.VC.SA.WebView2.asi
└─ XBase Bootstrap 检测游戏版本
   └─ 载入 WebView2\WebView2<游戏>.dll
      └─ XBasePayloadAttach
         ├─ Runtime::ValidateEnvironment
         ├─ Config::Init 并准备窗口模式
         └─ Host::Install

面板每帧流程：

OnProcess
├─ Panel::Process   同步可见性、菜单关闭时隐藏
├─ Core::Process    WebView 域创建/抓帧/光标
└─ Hooks::MaintainInputState
Draw 回调
└─ Panel::Draw
   ├─ WebView::SetBounds
   ├─ WebView::DrawPanel        仅抓帧模式
   └─ WebView::ForwardPanelInput 仅抓帧模式

与 XBase 的关系

本项目不包含任何游戏地址，全部能力来自 XBase 公共 API：

完整 API、能力矩阵与边界说明见 XBase 文档：https://gtadev.miomoe.cn/docs/xbase/

排查路径

1. 游戏目录下确认 III.VC.SA.WebView2.asi 与 WebView2\ 同级存在，且载荷 DLL 名与游戏匹配
2. 查看 XBase\logs\xbase.log，正常启动应出现 WebView2: Host 注册通过 与 WebView2: 渲染后端就绪
3. 提示 Failed to detect supported GTA runtime 表示游戏版本不在支持列表
4. 提示找不到载荷文件时，按日志里的期望路径核对目录与文件名
5. 面板出现但没有画面：确认 WebView2Loader.dll 在载荷目录内，且系统已安装 WebView2 运行时
6. 面板帧率低或不支持文字输入：当前是独占全屏抓帧预览，按配置章节切换到无边框窗口模式
7. 热键无效：确认 webview.hotkey 写法正确，日志会记录解析失败并回退到默认值