综述

XBase 是一个按游戏版本隔离的 静态库，为 GTA SA、GTA Vice City 和 GTA III 分别生成 XBaseSA.lib、XBaseVC.lib、XBaseIII.lib。

除静态库外，XBase 还提供进程内共享运行时 XBase{SA,VC,III}.dll（见 共享运行时方案）：多个 mod 可共用一份 Hooks / ImGui / Core 状态。运行时二进制统一安装于 <游戏根目录>\XBase\Library\，公共 API 形状保持一致，但每个库仅允许使用对应游戏的 plugin-sdk ABI；每个模组自身的载荷与数据则位于 Mods\<模组名>\。

当前版本后端状态：

VehicleEffects 是 SA 独有的能力，VC 与 III 不提供，这是设计如此而不是尚未实现。

公共符号可链接不等于功能已实现。页面必须使用 FeatureCapability 判断细粒度支持；能力返回 Unsupported 时，宿主必须禁用对应入口，不能因 XBase 提供兼容桩而启用。

VC/III 库不会复用 SA 地址或 SA 类布局。尚未实现的域通过 XBase::HasCapability() 返回 false，而不是伪造成功。

控制器一览

基础设施

控制器

UI 层

其他

版本能力查询

#include <XBase/XBase.h>

if (XBase::HasCapability(XBase::FeatureCapability::VehicleBasic)) {
    XBase::Vehicle::Repair();
}

能力查询属于当前静态库的编译目标，不是运行时猜测。宿主必须链接与游戏目标对应的库；禁止将 XBaseSA.lib 链接到 VC 或 III。

宿主生命周期

XBase 作为 XMenu 等宿主的静态库时，由宿主负责驱动生命周期：

#include <XBase/XBase.h>

void OnGameInit() {
    XBase::Core::NotifyGameInit();
}

void OnProcess() {
    XBase::Core::Process();
}

// 安装宿主回调；同时启用当前版本的运行时保护
XBase::Host::Install({OnGameInit, OnProcess});

// 显式移交领域；掩码会过滤当前库不支持的领域
XBase::Core::Init(XBase::Core::AllDomains);

// 卸载前恢复状态并清理领域
XBase::Core::Shutdown();
XBase::Host::Shutdown();

Host::Install() 会同时安装版本相关的运行时保护：VC 增加剧情资源目录纠正与空文件句柄保护，SA/VC 增加剧情期间的对象访问安全门（由 BulletAssist 消费）。

用法

#include <XBase/XBase.h>

XBase::Player::Heal();
XBase::Player::GiveMoney(100000);
XBase::Vehicle::Spawn(411);       // Infernus
XBase::Vehicle::Repair();
XBase::World::SetWeather(0, true); // 锁定晴天
XBase::Weapon::GiveAll();

构建

• C++20 / Win32 (x86) / MBCS / static runtime
• Premake5 生成 VS2022 解决方案
• XBaseSA.lib 使用 plugin_sa
• XBaseVC.lib 使用 plugin_vc，当前未实现域通过能力查询拒绝调用
• XBaseIII.lib 使用 plugin_III，当前未实现域通过能力查询拒绝调用
• Setup.bat 生成项目文件，Build.bat 编译三个目标

数据目录

接入 XBase 的模组共用 <游戏根目录>\XBase\：自身日志为 debug.log，共享加载器为 WebView2Loader.dll，每个模组的配置与日志在 Mods\<模组名>\ 下。取路径与初始化统一用 Platform::Mod*、Log::InitForMod、Config::InitForMod，细节见 数据目录。随包提供的 XBase.exe 用来查看这些配置与日志。

硬约束：

• asi 只放 plugins\ / scripts\，载荷与数据一律在 <游戏根目录>\XBase\Mods\<宿主名>\
• 不要自建 XBase\ 路径，也不要随包携带 WebView2Loader.dll 或 XBase.exe
• 配置与日志只能用 Config::InitForMod / Log::InitForMod 初始化，路径由 Platform::Mod* 提供
• 外部入口（Web UI、命令、热键）改宿主持有的状态，由控制器每帧推送，禁止直接调会被覆盖的独立开关