---
title: "Package"
---


`include/XBase/Package.h` · `XBase::Package`

## 清单文件

每个 mod 在自己的数据目录放一份 `XBase\Mods\<模组名>\package.json`，声明身份信息与运行环境约束。`Bootstrap` 挂载 mod 时读取并校验；文件不存在视为无约束，旧目录照常挂载。

```json
{
  "name": "XMenu",
  "version": "v0.1.0-alpha1",
  "author": "鼠子(YuiNijika)",
  "description": "XMenu 模组菜单",
  "homepage": "https://gtamodx.com/mods/xmenu",
  "engines": {
    "xbase": ">=0.1.0"
  },
  "dependencies": {
    "SomeMod": "^1.0.0"
  }
}
```

| 字段 | 说明 |
|---|---|
| `name` | mod 名称，缺省用目录名 |
| `version` | mod 自身版本，mod 的版本号以这里为唯一真源 |
| `author` / `description` / `homepage` | 展示信息，宿主界面的关于页直接取用 |
| `engines.xbase` | 对 XBase 运行库的版本约束 |
| `dependencies` | 对其它 mod 的版本约束，键是对方目录名，值是版本区间 |

## 版本区间语法

对齐 npm 的 node-semver 子集：

- 比较符 `>=` `>` `<=` `<` `==` 与精确版本
- 脱字符 `^1.2.3` 锁定最左非零分量（`^0.2.3` 只允许补丁位变化）
- 波浪号 `~1.2.3` 只允许补丁位变化
- 连字符区间 `1.2.3 - 2.0.0`
- 通配 `1.x` / `1.2.x` / `*`
- `||` 分隔的组任一满足，组内空格分隔的条件同时满足
- 版本号前缀 `v` 忽略，预发布后缀（如 `alpha1`）不参与数字比较

## 校验行为

挂载时依次校验：

1. `engines.xbase` 不满足 → 拒绝挂载，弹窗列出所需版本与已装版本
2. `dependencies` 里每个依赖按名字找 `Mods\<依赖名>\package.json` 的 `version`，依赖缺失或版本不符 → 拒绝挂载并列出全部问题
3. JSON 解析失败 → 拒绝挂载并指出清单路径

## C++ 接口

```cpp
namespace XBase::Package {

struct Info {
    bool valid;
    std::string name, version, author, description, homepage;
    std::string xbaseRequirement;
    std::vector<std::pair<std::string, std::string>> dependencies;
};

bool Load(const std::string& modName, Info& out);
bool Satisfies(const std::string& requirement, std::uint32_t runtimeNumber);
bool ParseVersion(const std::string& text, std::uint32_t& number);
bool Validate(const std::string& modName, std::string& failureReason);

} // namespace XBase::Package
```

宿主要展示 mod 的名称版本作者时走 `Load()` 取字段，不要在源码里再写一份；版本判定用 `Satisfies()` 配合 `Version.h` 的 `kVersionNumber`，不要解析字符串。