---
title: "综述"
description: "XBase 是 GTA SA / VC / III 的轻量基础库。大道至简。"
---

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

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

当前版本后端状态：

| 库 | 游戏 | 状态 |
|---|---|---|
| `XBaseSA.lib` | GTA San Andreas | 16 个领域全部有实现。Player / Vehicle / Weapon / Visual / Teleport / Camera / Cheats / VehicleEffects / Hooks / Ui / WebView 为 Supported；Ped / World / Scene / Overlay / BulletAssist 为 Partial |
| `XBaseVC.lib` | GTA Vice City | Hooks / Ui / WebView 为 Supported；Player / Ped / Vehicle / Weapon / World / Visual / Teleport / BulletAssist / Cheats / Scene / Overlay 为 Partial；Camera 未支持，VehicleEffects 为 SA 专属 |
| `XBaseIII.lib` | GTA III | Hooks / Ui / WebView 为 Supported；Player / Ped / Vehicle / Weapon / World / Visual / Teleport / Cheats / Scene / Overlay / BulletAssist 为 Partial；Camera 未支持，VehicleEffects 为 SA 专属 |

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

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

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

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

<Callout type="info" title="设计哲学">
一行 `#include <XBase/XBase.h>`，通过 `XBase::` 命名空间直接调用全部功能。
</Callout>

## 控制器一览

### 基础设施

| 控制器 | 命名空间 | 职责 |
|---|---|---|
| **Log** | `XBase::Log` | 线程安全日志，文件输出+内存环缓存 |
| **Json** | `XBase::Json` | 递归下降 JSON 解析/序列化 |
| **Config** | `XBase::Config` | JSON 持久化配置，点号嵌套键 |
| **I18n** | `XBase::I18n` | 多语言翻译，目录扫描+fallback 链 |
| **Hooks** | `XBase::Hooks` | kiero D3D9 钩子 + ImGui 集成 |
| **Hotkey** | `XBase::Hotkey` | 按键绑定、Toggle/Hold/Once 模式与持久化 |
| **Platform** | `XBase::Platform` | 文件、模块目录、剪贴板、外部打开、时钟 |
| **Runtime** | `XBase::Runtime` | 当前游戏目标检测与运行环境校验 |
| **Host** | `XBase::Host` | 宿主事件安装、消息提示与版本运行时保护 |

### 控制器

| 控制器 | 命名空间 | 职责 |
|---|---|---|
| **Core** | `XBase::Core` | 初始化、领域所有权、世界就绪检测、全局 Process 分发 |
| **Player** | `XBase::Player` | 血量/护甲/金钱/通缉/皮肤/技能/无敌/隐身/硬核/自由飞行 |
| **Ped** | `XBase::Ped` | Ped 生成、Elvis/武装/暴动等作弊、帮派控制 |
| **Vehicle** | `XBase::Vehicle` | 修复/生成/引擎/灯光/锁定/防护/车门/速度锁定/巡航 |
| **World** | `XBase::World` | 天气/时间/游戏速度/重力/Pickup/物理控制 |
| **Weapon** | `XBase::Weapon` | 给予/清空/丢弃/无限弹药/快速装填/技能 |
| **Teleport** | `XBase::Teleport` | 坐标/标记点/地图传送 |
| **Scene** | `XBase::Scene` | 动画/粒子/过场动画/任务控制/战斗行走风格 |
| **Visual** | `XBase::Visual` | HUD/雷达显示控制、后处理滤镜 |
| **BulletAssist** | `XBase::BulletAssist` | 子弹追踪、坐标透视、强锁与开火抑制 |
| **Overlay** | `XBase::Overlay` | 屏幕信息覆盖层（FPS/坐标/面板） |
| **Camera** | `XBase::Camera` | 自由视角与俯视相机 |
| **Cheats** | `XBase::Cheats` | 飞车/氮气/完美操控/绿灯/暴动/随机作弊 |
| **VehicleEffects** | `XBase::VehicleEffects` | 载具霓虹等渲染期特效 |

### UI 层

| 模块 | 命名空间 | 职责 |
|---|---|---|
| **Theme** | `XBase::Theme` | 主题配色、样式预设、字体管理 |
| **UI** | `XBase::UI` | 窗口管理、Tab 系统、MenuSurface 与基础组件封装 |
| **WebView** | `XBase::WebView` | 通过系统 WebView2 在游戏窗口内渲染网页 |

### 其他

| 控制器 | 命名空间 | 职责 |
|---|---|---|
| **Version** | `XBase` | 游戏版本检测 |
| **Types** | `XBase::Types` | 共享数据结构（ProofState/PedSpawnOptions 等） |

## 版本能力查询

```cpp
#include <XBase/XBase.h>

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

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

## 宿主生命周期

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

```cpp
#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` 消费）。

## 用法

```cpp
#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`，每个模组的配置与日志在 `Runtime\<模组名>\` 下。取路径与初始化统一用 `Platform::Mod*`、`Log::InitForMod`、`Config::InitForMod`，细节见 [数据目录](/docs/xbase/data-layout)。随包提供的 `XBase.exe` 用来查看这些配置与日志。

硬约束：

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