# Custom Game Adapter

> 为未支持的游戏创建自定义适配配置。用户只给出游戏目录时，探测引擎类型，并使用 3DM Mods MCP 获取 GlossGameId 和游戏封面，生成并写入 Expands JSON；也用于查看、编辑和删除已有的自定义游戏适配。

- Skill: `glossmod/custom-game-adapter` (Agent Skill)
- Install (CLI): `npx skillmds@latest add glossmod/custom-game-adapter`
- Raw SKILL.md: https://api.skillmd.com/api/skills/glossmod/custom-game-adapter/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: glossmod (https://skillmd.com/u/glossmod)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/glossmod/custom-game-adapter

---


# Gloss Mod Manager: Custom Game Adapter Workflow

## 作用

这个 skill 用来给 Gloss Mod Manager 尚未内置支持的游戏创建适配配置。用户通常只提供一个游戏安装目录，你需要自己探测目录特征、补齐缺失字段、生成 JSON 并写入 Expands 目录，让这个游戏出现在游戏选择列表里。

它同时负责自定义适配的读取、编辑和删除。它不负责安装 Mod，也不负责把游戏添加到管理器（那是 gloss-mod-manager skill 的职责）。

## 什么时候使用

- 用户发来一个游戏目录，说想让 Gloss 支持这个游戏。
- 用户想给某个游戏手写或修改 Mod 类型规则。
- 用户要查看、修改或删除之前创建的自定义适配。
- 支持游戏列表里没有目标游戏，需要先做适配再管理。

## 核心规则

- 先探测，再生成。不要凭游戏名猜目录结构和引擎类型。
- GlossGameId 和 gameCoverImg 必须优先从 3DM Mods MCP 获取，不要猜测或使用未经验证的值。
- 3DM Mods MCP 不可用、搜索不到游戏或游戏没有封面时，分别使用 0 或空字符串，并把原因告知用户。
- gameName 是配置的唯一标识和文件名，用英文、不带特殊字符。
- 写入前必须先校验。校验不通过就修配置，不要硬写。
- 覆盖已有配置必须先读出来看一眼，并向用户确认，`overwrite` 不要默认传 true。
- 删除是不可逆操作，执行前必须向用户确认。
- 能用内置模板就不要手写 modType。手写只用于模板都不适用的游戏。

## 推荐流程

1. 调用 mcp_gloss-mod-man_get-supported-games-list，确认这个游戏是否已经受支持。已支持就不需要适配，转去用 gloss-mod-manager skill。
2. 调用 mcp_gloss-mod-man_list-custom-games，确认是否已经存在同名的自定义适配。存在就走「编辑已有适配」分支。
3. 调用 mcp_gloss-mod-man_inspect-game-directory，传入用户给的目录，拿到 engine、exeCandidates、unity/unrealEngine 信息和 notes。
4. 使用 3DM Mods MCP 搜索游戏并获取 ID 与封面：
    - 调用 `mcp_3mod-mcp_get-game-list`，传入 `search` 为游戏中文名、英文名或用户提供的名称，查看候选结果。
    - 如果返回多个相近候选，把候选的 `id`、`game_name` 和 `game_ename` 列给用户确认，不要自行选择。
    - 对用户确认的候选调用 `mcp_3mod-mcp_get-game-detail`，传入候选的 `id` 获取权威详情。
    - 将详情的 `id` 写入 `GlossGameId`，将 `game_cover_imgUrl` 写入 `gameCoverImg`。如果封面值是以 `/` 开头的相对路径，拼成 `https://mod.3dmgame.com` 开头的绝对 URL；已有绝对 URL 原样保留。
    - 搜索不到、MCP 不可用或详情没有 `game_cover_imgUrl` 时，不要猜测：分别将 `GlossGameId` 设为 0 或将 `gameCoverImg` 留空，并在结果中说明。
5. 根据探测结果和 3DM Mods MCP 详情组装配置（见下面「配置生成规则」）。
6. 调用 mcp_gloss-mod-man_validate-custom-game 校验。有 errors 就按提示改，直到通过。warnings 可以接受，但要在最后告知用户。
7. 调用 mcp_gloss-mod-man_save-custom-game 写入。
8. 调用 mcp_gloss-mod-man_get-supported-games-list 确认新游戏已经出现在列表里。
9. 向用户说明适配已生效，并提示可以继续把游戏添加到管理器。

## 配置生成规则

### 必填字段

- `gameName`: 英文游戏名，无特殊字符。作为文件名和唯一标识。
- `GlossGameId`: 从 `mcp_3mod-mcp_get-game-detail` 返回的 `id` 拿。搜索不到或无法调用 3DM Mods MCP 时填 0。
- `steamAppID`: Steam 游戏填真实 AppId，非 Steam 游戏填 0。
- `gameExe`: 取 exeCandidates 第一项。若该项 `inRoot` 为 true，直接用文件名字符串；否则用数组形式 `[{ name, rootPath }]`，rootPath 用探测结果里给的值。
- `modType` 和 `checkModType`: 按引擎选模板，见下。

### 按引擎选模板

探测结果的 `engine` 字段直接决定模板选择：

- `Unity`: `"modType": "UnityGame.modType"`，`"checkModType": "UnityGame.checkModType"`
- `UnityIL2CPP`: `"modType": "UnityGameILCPP2.modType"`，`"checkModType": "UnityGameILCPP2.checkModType"`
- `UnrealEngine`: `"modType": "UnrealEngine.modType"`，`"checkModType": "UnrealEngine.checkModType"`，并且必须带上 `unrealEngineData`，其中 `bassPath` 和 `useUE4SS` 用探测结果里的值。
- `Unknown`: 需要手写 modType 数组和 checkModType 数组。

### 建议补充的字段

- `installdir`: Steam 游戏填从 Steam common 目录到游戏主程序的相对路径，可参考探测结果的 folderName。
- `startExe`: 有 steamAppID 时建议给两个启动方式，一个 `steam://rungameid/<steamAppID>`，一个直接指向 exe 的相对路径。
- `gameCoverImg`: 从 `mcp_3mod-mcp_get-game-detail` 返回的 `game_cover_imgUrl` 获取。相对路径要转换为以 `https://mod.3dmgame.com` 开头的绝对 URL；没有就留空，并告知用户列表里不会有封面。

### 手写 modType 的规则

只在 `engine` 为 `Unknown`，或者用户明确要求自定义时才手写。

每个类型对象需要 `id`、`name`、`installPath`、`install`、`uninstall`。install 和 uninstall 都是对象，`UseFunction` 从下面选，且都必须带 `inGameStorage`：

- `generalInstall` / `generalUninstall`: 把 Mod 内容整体复制到 installPath。最常用。配合 `keepPath` 决定是否保留 Mod 内部目录结构。
- `installByFile`: 只处理匹配 `fileName` 的文件。`isExtname` 为 true 时 fileName 按扩展名匹配。
- `installByFileSibling`: 匹配到 `fileName` 后，连同它的同级文件一起装。适合「认标志文件、装整个目录」的场景。可用 `pass` 跳过指定文件。
- `installByFolder`: 处理名为 `folderName` 的目录。`include` 控制是否包含该目录本身。
- `installByFolderParent`: 处理 `folderName` 的父目录。
- `Unknown`: 兜底占位，不执行实际安装。用于 id 99 的「未知」类型。

务必保留一个 `id` 为 99、名为「未知」的兜底类型，install 和 uninstall 都用 `Unknown`，否则无法归类的 Mod 会没有归属。

checkModType 数组里每条规则需要 `UseFunction`、`Keyword`、`TypeId`：

- `extname`: 按扩展名匹配，Keyword 形如 `[".pak"]`。
- `basename`: 按完整文件名匹配。
- `inPath`: 按路径片段匹配，要求 Keyword 里的每一项都出现在路径中。

每条规则的 `TypeId` 必须对应 modType 里真实存在的 id。

## 编辑已有适配

1. 调用 mcp_gloss-mod-man_read-custom-game 读出当前配置。
2. 向用户确认要改哪些字段，只改这些字段，其余原样保留。
3. 调用 mcp_gloss-mod-man_validate-custom-game 校验改后的完整配置。
4. 调用 mcp_gloss-mod-man_save-custom-game，传 `overwrite: true`。

## 删除适配

1. 调用 mcp_gloss-mod-man_read-custom-game 确认目标存在，并把配置内容展示给用户。
2. 明确告知用户这会同时删掉该游戏的自定义类型文件，且不可恢复。
3. 得到用户确认后再调用 mcp_gloss-mod-man_delete-custom-game。

## 分支处理

- 如果游戏已在内置支持列表里：不要创建自定义适配，内置适配会覆盖同名自定义配置。
- 如果目录不存在：要求用户提供正确的安装根目录，不要自己补路径。
- 如果 exeCandidates 为空：目录很可能不是游戏根目录，要求用户确认。
- 如果 engine 是 Unknown：先询问用户这个游戏的 Mod 通常是什么格式、装在哪个目录，再手写 modType，不要凭空编造路径。
- 如果 3DM Mods MCP 返回多个相近游戏：把 `id`、中文名和英文名列给用户选，不要自己挑。
- 如果 3DM Mods MCP 未启用或鉴权失败：告知用户先启用 3DM Mods MCP 并配置 Key；在用户允许继续的情况下，GlossGameId 使用 0、gameCoverImg 留空。
- 如果校验反复不通过：把 errors 原文告诉用户，说明缺什么，不要绕过校验。

## 完成标准

- 配置已通过 validate-custom-game 校验。
- 已成功写入，save-custom-game 返回 state 为 true。
- 新游戏已出现在 get-supported-games-list 结果中。
- 已把遗留的 warnings（例如 GlossGameId 为 0、没有封面图）告知用户。

## 参考工具

- mcp_gloss-mod-man_inspect-game-directory: 探测目录，拿引擎类型和候选主程序。
- mcp_3mod-mcp_get-game-list: 按中文名、英文名或描述搜索 3DM 游戏候选。
- mcp_3mod-mcp_get-game-detail: 按游戏 ID 获取权威游戏信息和 `game_cover_imgUrl`。
- mcp_gloss-mod-man_list-custom-games: 列出已有的自定义适配。
- mcp_gloss-mod-man_read-custom-game: 读取单个自定义适配的完整配置。
- mcp_gloss-mod-man_validate-custom-game: 写入前校验，返回 errors 和 warnings。
- mcp_gloss-mod-man_save-custom-game: 写入配置并刷新支持游戏列表。
- mcp_gloss-mod-man_delete-custom-game: 删除配置及其自定义类型文件。

## 示例

Unreal 游戏，套模板：

```json
{
    "tool": "mcp_gloss-mod-man_save-custom-game",
    "arguments": {
        "definition": {
            "GlossGameId": 0,
            "steamAppID": 2358720,
            "installdir": "BlackMythWukong",
            "gameName": "Black Myth Wukong",
            "gameExe": [{ "name": "b1.exe", "rootPath": "../../.." }],
            "startExe": [
                { "name": "Steam 启动", "exePath": "steam://rungameid/2358720" }
            ],
            "modType": "UnrealEngine.modType",
            "unrealEngineData": { "bassPath": "b1", "useUE4SS": false },
            "checkModType": "UnrealEngine.checkModType"
        }
    }
}
```

引擎未知，手写 modType：

```json
{
    "tool": "mcp_gloss-mod-man_save-custom-game",
    "arguments": {
        "definition": {
            "GlossGameId": 344,
            "steamAppID": 2420110,
            "gameName": "Horizon Forbidden West",
            "gameExe": "HorizonForbiddenWest.exe",
            "modType": [
                {
                    "id": 1,
                    "name": "stream",
                    "installPath": "LocalCacheWinGame/package/mods",
                    "install": {
                        "UseFunction": "installByFileSibling",
                        "fileName": ".stream",
                        "isExtname": true,
                        "inGameStorage": true,
                        "pass": []
                    },
                    "uninstall": {
                        "UseFunction": "installByFileSibling",
                        "fileName": ".stream",
                        "isExtname": true,
                        "inGameStorage": true,
                        "pass": []
                    }
                },
                {
                    "id": 99,
                    "name": "未知",
                    "installPath": "/",
                    "install": { "UseFunction": "Unknown", "inGameStorage": true },
                    "uninstall": { "UseFunction": "Unknown", "inGameStorage": true }
                }
            ],
            "checkModType": [
                { "UseFunction": "extname", "Keyword": [".stream"], "TypeId": 1 }
            ]
        }
    }
}
```