# FreeWorld Mod 开发指引（给 AI Agent）

本文档供 AI 编码代理在为游戏 FreeWorld（Unity，地面殖民 + 星系航行的太空沙盒）开发 Mod 时阅读。它是自包含的：只读这一份就能写出能加载的 Mod。需要查某张配置表的字段或某个接口的签名时，再按第 11 节读取同站的数据文件。

- 本文档与站点部署在同一目录，文中的相对链接都相对于本文档的 URL。
- 规则按游戏代码核对。标注“未验证”的内容没有在游戏内实测，使用时要告诉用户。
- 对应的游戏版本与代码提交见 `data/meta.js`（`window.FW_API_META`）。游戏仍在更新，以用户实际安装的版本为准。

## 0. 工作方式

1. 先确定用户要的效果，再按第 2 节选**能力最低**的 Mod 类型。能用 XML 做就不要写程序，能用 Lua 做就不要写 DLL。
2. 不要编造表名、字段名、ID 或 C# 接口。它们都能在第 11 节的数据文件里查到；查不到就告诉用户，不要猜。
3. 写完按第 13 节自检，再把第 14 节中与本次 Mod 有关的限制和未验证项告诉用户。
4. 你无法替用户启动游戏时，明确说明“已生成，未在游戏内运行”，并给出第 12 节的验证步骤。

## 1. 必须遵守的规则

- 一个 Mod 是 `mods/` 下的一个文件夹，必须有 `Manifest/manifest.xml`。
- `packageId` 全局唯一，**不能包含下划线 `_`**（存档按 `_` 拆分 Mod 记录）。发布后不要改。
- 所有内容放在版本目录里，统一用 `v_common/`。
- XML 新增的行，ID 会变成 `<packageId>_<ID>`。**XML 只能新增行，不能覆盖或修改原版行**，也不能修改原版文本。
- 引用 Mod 新增的行时写完整 ID（`<packageId>_<ID>`）；`DependID` 写的是原版行的 ID，不带前缀。
- `def.xml` 里写错的字段名会被**静默忽略**，不报错。字段名区分大小写，必须对照数据文件核对。
- `def.xml` 只能给字符串、数字、布尔字段赋值。列表、枚举、对象类型的字段不能从 XML 赋值。
- 同一个版本目录里，程序只能是 Lua 或 DLL 之一。`Assemblies/` 下只要有 `.dll`，整个 Mod 就被当作 DLL Mod，**手机上整个 Mod 被跳过**（连数据和资源一起）。
- Mod 只在游戏启动时加载。改了启用列表或 Mod 文件都要重启游戏。
- Lua 和 DLL 都是可执行代码，不是沙箱。不要读写 Mod 目录以外的用户文件，不要联网，除非用户明确要求。
- 显示给玩家的文字走语言表（`LanguageDef` 行），不要把中文直接写进物品的 `Name` 字段。

## 2. 选哪种 Mod

| 需求 | 类型 | 平台 | 章节 |
| --- | --- | --- | --- |
| 新增物品、建筑、文本等配置行 | 数据 Mod（`def.xml`） | PC + 手机 | 4 |
| 新物品图标、替换战舰贴图、角色外观 | 资源 Mod | PC + 手机 | 5 |
| 修改原版数值、每帧读取状态做表现 | Lua 程序 Mod | PC；手机受限 | 6 |
| 自定义开局、引导、剧情演出 | 剧本 Mod（数据行 + 剧情 Lua + 地图） | PC + 手机（手机未验证） | 7 |
| 在游戏方法前后插入逻辑、新增 C# 类、改内部规则 | C# DLL Mod（可配合 Harmony） | 仅 PC | 8 |

一个 Mod 可以同时包含数据、资源和一种程序。

## 3. 目录与清单

```
mods/
└─ MyMod/                          文件夹名随意
   ├─ Manifest/
   │  ├─ manifest.xml              必需
   │  ├─ icon.png                  可选，列表图标
   │  └─ preview.jpg               可选，详情预览图
   └─ v_common/
      ├─ Resources/
      │  ├─ Def/def.xml            配置行
      │  ├─ Textures/              图标、贴图、role-customize.xml
      │  └─ Map/                   关卡地图 .nsmt
      ├─ Lua/                      Lua 程序入口与剧情脚本
      └─ Assemblies/               DLL（只有 DLL Mod 才放）
```

`mods/` 的位置：

| 平台 | 位置 |
| --- | --- |
| Windows | 游戏安装目录下的 `mods/`，与 exe 同级 |
| Android | `Android/data/<包名>/files/mods/` |
| iOS | 应用沙盒 `Documents/mods/` |
| Unity 编辑器（开发仓库） | 工程根目录的 `mods/` |

`Manifest/manifest.xml` 模板：

```xml
<?xml version="1.0" encoding="utf-8"?>
<ModXmlManifest>
  <packageId>author.modname</packageId>
  <name>My Mod</name>
  <author>Author</author>
  <icon>icon.png</icon>
  <previewImage>preview.jpg</previewImage>
  <desc>一句话说明这个 Mod 做什么。</desc>
  <versions>
    <ModMetaVersion>
      <version>v_common</version>
      <!-- 依赖：可重复，每个写一个 packageId。只用于界面提示和自动排序，加载时不强制检查 -->
      <!-- <dependencies>other.mod</dependencies> -->
      <!-- Lua 程序 Mod：相对 v_common/Lua/ -->
      <!-- <luaMain>main.lua</luaMain> -->
      <!-- DLL Mod：相对 v_common/Assemblies/，lib 先于 main 加载，main 只用第一个 -->
      <!-- <lib>0Harmony.dll</lib> -->
      <!-- <main>MyMod.dll</main> -->
    </ModMetaVersion>
  </versions>
</ModXmlManifest>
```

- `packageId` 和至少一个 `ModMetaVersion` 必填，缺少时该文件夹不会出现在 Mod 列表。
- 版本目录的匹配顺序：与游戏完整版本号同名的目录，其次 `v_common`。“主版本.次版本”目录当前不生效。都不匹配时该 Mod 被跳过，只写日志，不弹窗。
- 加载顺序等于启用列表的顺序。

## 4. 数据 Mod

位置：`v_common/Resources/Def/def.xml`。每张配置表对应一个 C# 类，`ModDefRow` 的 `Name` 写的是**类名**（如 `T_FoodDef`），不是表文件名。

```xml
<?xml version="1.0" encoding="utf-8"?>
<ModXmlDef>
  <files />
  <rows>
    <!-- 文本：Key = id_ + 引用处填写的字符串。语言行的 Key 不会加包前缀，自己加前缀避免冲突 -->
    <ModDefRow Name="LanguageDef">
      <Item Name="Key">id_author_modname_tomato_name</Item>
      <Item Name="CN">太空番茄</Item>
      <Item Name="EN">Space Tomato</Item>
    </ModDefRow>
    <ModDefRow Name="LanguageDef">
      <Item Name="Key">id_author_modname_tomato_desc</Item>
      <Item Name="CN">在低重力温室中培育的番茄。</Item>
      <Item Name="EN">A tomato grown in a low-gravity greenhouse.</Item>
    </ModDefRow>

    <!-- 新物品：DependID 先深拷贝原版 ID 为 3 的食物，再用下面的字段覆盖 -->
    <ModDefRow Name="T_FoodDef" DependID="3">
      <Item Name="ID">tomato</Item>
      <Item Name="Name">author_modname_tomato_name</Item>
      <Item Name="Desc">author_modname_tomato_desc</Item>
      <Item Name="RawIcon">tomato.png</Item>
      <Item Name="Price">12.5</Item>
    </ModDefRow>
  </rows>
</ModXmlDef>
```

规则：

- **始终使用 `DependID`**，以一行同类原版数据为模板。不写 `DependID` 时新行只有代码默认值（`Type` 为 `-1`），多数游戏逻辑无法正常使用。可用的原版 ID 见 `data/def-samples.js` 中该表的 `ids`。
- 上例的最终 ID 是 `author.modname_tomato`。
- `Name` / `Desc` 填文本 Key 去掉 `id_` 的部分。界面上显示出 Key 本身，说明语言行的 Key 漏了 `id_` 或两边不一致。
- 语言行字段：`Key`、`CN`、`EN`、`CNTW`（繁体，留空时显示 `CN`）。Key 已存在时先加载的生效，原版先于所有 Mod 加载。
- `RawIcon`：相对 `v_common/Resources/Textures/` 的 PNG 文件名。64×64 的 PNG 实测可用。不写则沿用模板的图标。
- 小数写成 `12.5`。数值转换失败时日志有错误，该字段保持模板值，行仍会加入。
- 类名带命名空间时写完整名；`data/api-data.js` 里每张表的 `xmlName` 就是应填的值。
- 新行加入了表，不代表它会出现在商人货单、配方、科技树里。那些列表在别的表里按 ID 引用；需要时再新增对应表的行（同样只能新增），或用程序 Mod 修改原版行。
- `.fwr` 整表文件（`<files>` 节）由官方导表工具生成，工具不随游戏提供。不要尝试手写。

存档兼容：存档按完整 ID 保存引用。发布后不要改 `packageId` 和行 ID。玩家停用 Mod 后读取含有其内容的存档，这些引用会找不到定义，游戏只提示缺少 Mod，不做清理。

## 5. 资源 Mod

资源放在 `v_common/Resources/Textures/`。游戏只读取下面这些位置：

| 用途 | 写法 |
| --- | --- |
| 新增行的图标 | 行的 `RawIcon` 字段 |
| 新增地板 / 平台 | `F_StrcutDef` 行的 `RawIcon`（必填）；平台另读同名的 `*_additive.png` |
| 替换战舰贴图 | `Textures/ShipTextureOverrides/ShipTextures.xml` |
| 角色外观 / 武器 | `Textures/role-customize.xml` |
| 关卡地图 | `M_StarMapPath_Def.Path` → `Resources/Map/*.nsmt`（见第 7 节） |
| 自定义界面的 AssetBundle | `Resources/AssetBundle/`，由 Mod 自己的 DLL 加载，仅 PC |

`Resources/Audio/` 目前没有加载逻辑，不要往里放东西并期望生效。

战舰贴图（不需要程序）：

```xml
<?xml version="1.0" encoding="utf-8"?>
<ShipTextures>
  <Ship id="B-07" image="MyShip/BaseColor.png">
    <Secondary name="_NormalMap" image="MyShip/Normal.png" />
    <Secondary name="_ORM"       image="MyShip/ORM.png" />
    <Secondary name="_MaskTex"   image="MyShip/Emission.png" />
    <Secondary name="_ShadowMap" image="MyShip/Shadow.png" />
  </Ship>
</ShipTextures>
```

- `id` 必须是 `G_AirShip` 表中已有的 ID，同一文件内不重复。
- `image` 为相对该 XML 的 PNG/JPG，不允许绝对路径和 `..`，单张不超过 32 MiB。
- `Secondary` 可选，名称区分大小写，只有上面四种。
- 出错只跳过那艘船或那个通道，写入 `<persistentDataPath>/ModReports/ShipTextures/LoadReport.txt`；同目录 `AirShipIds.tsv` 列出全部可用 ID。

角色外观（`role-customize.xml`）的结构见 [resource-mods.html](resource-mods.html#spine)。新皮肤如何被角色配置引用的完整流程未验证，做这类 Mod 时要告诉用户。

## 6. Lua 程序 Mod

清单的版本节点加 `<luaMain>main.lua</luaMain>`，入口放在 `v_common/Lua/main.lua`。入口脚本必须 `return` 一个表：

```lua
local TAG = '[author.modname] '

local M = {}

-- 必需。Mod 安装时调用，此时游戏配置表还是空的。只在这里注册事件、初始化自己的状态。
function M.onLoad(ctx)
    print(TAG .. 'loaded, version=' .. ctx.version)
end

-- 可选。所有原版行和 Mod XML 行已读入、尚未建立 ID 索引。在这里修改配置数据。
-- 此时只能遍历 beans；getDataID 会返回 nil。
function M.onDefLoaded(ctx)
    local beans = CS.T_FoodDef.beans
    for i = 0, beans.Count - 1 do
        local row = beans[i]
        if row.ID == '3' then
            row.Price = row.Price * 2
            return
        end
    end
    error('T_FoodDef ID=3 not found')
end

-- 可选。onDefLoaded 之后每帧调用。不要每帧打印日志、分配大量对象或扫描全图。
function M.onUpdate(ctx, deltaTime)
end

-- 必需。退出游戏或加载失败时调用。必须撤销 onLoad 做过的所有注册，即使 onLoad 只执行了一半。
function M.onUnload(ctx)
end

return M
```

- `ctx` 只有三个字段：`packageId`、`version`（版本目录名）、`rootPath`（本 Mod `Lua/` 目录的绝对路径）。
- `require('helpers.defs')` 加载 `Lua/helpers/defs.lua`。模块名只能用字母、数字、下划线和点，只在本 Mod 的 `Lua/` 内查找。
- 每个 Lua Mod 有独立的 Lua 环境，全局变量不与其他 Mod 共享。
- 顶层代码不要注册事件或修改游戏状态，放进 `onLoad`。
- 四个回调都在主线程上调用。

时机与可用数据：

| 回调 | 时机 | 配置表 |
| --- | --- | --- |
| `onLoad` | 安装 Mod 时 | 空 |
| `onDefLoaded` | 行已读入，未初始化 | 只能遍历 `CS.<表类>.beans` |
| `onUpdate` | 之后每帧 | `CS.<表类>.getDataID(id)` 可用 |
| `onUnload` | 退出 / 加载失败 | — |

出错时：

- 入口脚本或 `onLoad` 报错：游戏先调用 `onUnload`，该 Mod 不安装，弹出“加载Mod … 失败”提示，玩家可选继续（跳过该 Mod）或清除所有 Mod 并重启。
- `onDefLoaded` 报错：配置表加载中止，加载画面停在“启动失败”。**这会让游戏无法启动**，所以在这里要先判空再改，找不到目标行时写日志并跳过通常比 `error` 更合适，除非继续运行会产生错误数据。
- `onUpdate` 报错：记录一次，之后不再调用该 Mod 的 `onUpdate`，游戏继续运行。
- 日志格式：`Lua Mod failed: packageId=… stage=…`。

Lua 调用 C#（xLua）：

| C# | Lua |
| --- | --- |
| 静态方法 / 字段 | `CS.MapTools.isCellInMapRect(x, y)`（点号） |
| 实例方法 | `node:isInFog()`（冒号） |
| 实例字段 | `row.Price = 10` |
| 命名空间类型 | `CS.UnityEngine.Vector2Int(1, 2)` |
| `List<T>` | `for i = 0, list.Count - 1 do local x = list[i] end`（下标从 0 开始） |
| Unity 对象判空 | `obj ~= nil and not obj:Equals(nil)` |

事件：游戏对 Mod 开放的 C# 事件只有 `ModDelegateDispatch` 的两个建筑生成事件。

```lua
local handler = function(buildType, buildId, cellX, cellY, buildDir)
    return nil   -- 返回 nil 表示不处理；返回 FWBuildBean 则接管创建
end
function M.onLoad(ctx)   CS.ModDelegateDispatch.generator_BuildBean('+', handler) end
function M.onUnload(ctx) CS.ModDelegateDispatch.generator_BuildBean('-', handler) end  -- 必须是同一个函数对象
```

其他“某件事发生时通知我”的需求，Lua 只能在 `onUpdate` 里轮询：缓存上次结果，只在变化时处理。

手机（IL2CPP）：只有打包时生成了桥接代码的类型能可靠调用，当前只有 `ModDelegateDispatch`。本文的 `CS.T_FoodDef.beans`、字段读写、事件订阅在编辑器（Mono）中实测可用，在手机正式包中未验证。面向手机的 Lua Mod 要告诉用户这一点。

`xlua.hotfix`（替换 C# 方法）需要基础包启用 `HOTFIX_ENABLE`，当前未启用。不要使用。

## 7. 剧本 Mod（剧情脚本与地图）

数据 Mod 的行可以引用 Mod 自带的剧情 Lua 和关卡地图。这**不是** Lua 程序 Mod：不声明 `luaMain`，脚本在引导节点被触发时才运行，运行在游戏共用的剧情 Lua 环境里，接口是 `mission` 对象。

查找规则（只对来自 Mod 的行生效）：

| 字段 | 先在 Mod 内找 | Mod 内没有时 |
| --- | --- | --- |
| `GuideMissionDef.script` | `v_common/Lua/<script>.lua` | 游戏自己的脚本目录；都没有则该节点失败 |
| `M_StarMapPath_Def.Path` | `v_common/Resources/Map/<Path>.nsmt` | 游戏自己的地图目录；都没有则开档报错，不回退 |

路径必须是相对路径，不能含 `..`。

`def.xml`：

```xml
<ModDefRow Name="GuideMissionDef">
  <Item Name="ID">Start</Item>
  <Item Name="Name">示例开局</Item>
  <Item Name="script">ModStart</Item>       <!-- v_common/Lua/ModStart.lua -->
  <Item Name="scriptfun">start</Item>       <!-- 入口函数，留空为 start -->
  <Item Name="Nextscript">-1</Item>         <!-- 下一个引导节点 ID，-1 为无 -->
  <Item Name="EventTrigger">-1</Item>       <!-- 关联事件 ID，| 分隔，-1 为无 -->
</ModDefRow>
```

脚本必须定义全局函数 `call(mission, entry)` 和入口函数。需要等待玩家或界面时用协程。下面的结构取自官方脚本，这份模板本身没有在游戏内运行过；`'Nora'` 是官方脚本使用的头像 ID：

```lua
local mission, co2

function call(m, entry)
    mission = m
    co2 = coroutine.create(entry)          -- 游戏随后恢复 co2 来启动入口
    mission:registerCleanup(function() co2 = nil end)
    return co2
end

function start(m)
    mission = m
    mission:disableCamearDrag()            -- 脚本结束时游戏自动恢复
    mission:pauseGame()

    local rect = CS.UnityEngine.Rect(0, 0, 2400, 1080)
    local headPos = CS.UnityEngine.Vector2Int(-770, 282)
    local textPos = CS.UnityEngine.Vector2Int(-320, 323)
    mission:introduceRect_Avatar(rect, 'Nora', '引导文字', headPos, textPos, false, true)
    coroutine.yield()                      -- 等玩家点击；界面结束后游戏恢复协程

    mission:endScript('ModStart')          -- 每条路径都必须以 endScript 或 failScript 结束
end
```

规则：

- 同一时刻只运行一个剧情脚本。已有脚本在运行时，新的触发不会启动。
- 缺少 `call` 或入口函数：`Lua 入口无效`。`call` 没有创建 `co2`、入口里也没结束：`Lua coroutine is missing`。
- 协程返回却没调用 `endScript`，且没有界面在等待：判失败 `Lua coroutine ended without endScript`。
- `mission:endScript(label)` 为完成；`mission:failScript(reason)` 或 Lua 报错为失败；读档、退出为取消。只有完成才把节点记为已完成。
- 无论怎样结束，游戏都会逆序调用 `registerCleanup` 登记的函数，并把脚本通过 `mission` 改过的镜头、输入、暂停、速度、界面栏、音乐状态恢复为开始前的值。
- 剧情 Lua 环境全游戏共用：除 `call` 和入口函数外都用 `local`。
- 会等待的接口（调用后要 `coroutine.yield()`）：`introduceRect_Avatar`、`introduceRect`、`showWord`、`clickButton`、`locationCell(…, true)`。
- `mission` 的全部方法（270 多个）见 `data/script-api.js`，每个方法带官方脚本的调用次数 `uses`。优先用 `uses` 高的方法；分组名带 `Legacy`、`old`、`暂时不用了` 的不要用。

地图行的风险：`M_StarMapPath_Def` 不随启动加载（停在封面时是 0 行），而 Mod 的 XML 行在启动阶段转换。给它写 `DependID`（例如官方示例的 `PresetMap1`）时，按代码会找不到模板，该行被跳过并记录 `class or dependID not found`。这是按代码和导出数据推断的，未在游戏内实测；做地图类 Mod 时要让用户先看日志确认该行是否加入，并说明这一点。

示例 Mod 的完整验收尚未在游戏内进行：自定义开局界面是否列出 Mod 追加的初始组合行、手机真机读取都未验证。

## 8. C# DLL Mod（仅 PC）

```xml
<ModMetaVersion>
  <version>v_common</version>
  <lib>0Harmony.dll</lib>     <!-- 可选，可重复 -->
  <main>MyMod.dll</main>
</ModMetaVersion>
```

主程序集中必须有一个**无命名空间**、名为 `ModPluginLauncher`、继承 `BaseModLauncher`、带无参构造函数的公共类：

```csharp
using System;

public sealed class ModPluginLauncher : BaseModLauncher
{
    // 安装时调用，配置表尚未加载。
    public override void launcher()
    {
        base.launcher();
        setDefLoader(new MyDefLoader(config));   // config 是本 Mod 的 ModXmlManifest
    }
}

sealed class MyDefLoader : BaseModDefLoader
{
    public MyDefLoader(ModXmlManifest config) : base(config) { }

    // 行已读入、尚未初始化。只能用 beans，不能用 beansDict / getDataID。
    public override void initModDef()
    {
        T_FoodDef target = null;
        foreach (T_FoodDef row in T_FoodDef.beans)
            if (row.ID == "3") { target = row; break; }
        if (target == null)
            throw new InvalidOperationException("T_FoodDef ID=3 not found");

        target.Price *= 2;                                 // 修改原版行

        T_FoodDef added = T_FoodDef.getTemplateDef("3");   // 深拷贝
        added.ID = "dll_tomato";                           // 最终 ID：<packageId>_dll_tomato
        addRow(added);
    }
}
```

- 引用游戏目录 `<游戏>_Data/Managed/` 下的 `Assembly-CSharp.dll` 和需要的 `UnityEngine*.dll`，目标框架 .NET Framework 4.x 或 .NET Standard 2.x。
- 只能使用 `public` 成员。`ModPluginManager` 是 `internal`。
- `initModDef` 写成可重复执行（新增前先查重）。
- DLL Mod **没有卸载回调**，Harmony 补丁一直生效到游戏退出。
- 内容完全相同的程序集只加载一次，多个 Mod 可以带同一份库。
- 游戏更新后必须重新编译并测试。
- 自定义建筑：订阅 `ModDelegateDispatch.generator_BuildBean`（返回 `FWBuildBean`）和 `generator_BuildClass`（返回 `BaseBuild`）；第一个返回非 `null` 的订阅者生效。它只覆盖常规建筑的生成路径。
- Harmony 补丁可能在非主线程被调用，访问 Unity 对象或界面前用 `MainThread.post` / `MainThread.invoke` 转到主线程。

## 9. 加载时序

1. 读取启用列表 `<persistentDataPath>/mod.dat`，扫描 Mod（Steam 创意工坊优先，再本地 `mods/`）。
2. 按启用顺序安装每个 Mod：选版本目录 → Lua `onLoad` / DLL `launcher()` → 解析 `def.xml` 与 `role-customize.xml`。某个 Mod 失败只影响它自己（弹提示，可继续）。
3. 加载配置表：读全部原版表 → 追加各 Mod 的 XML 行 → **Lua `onDefLoaded` / DLL `initModDef()`** → 初始化每一行并建立 ID 索引 → 读战舰贴图 → 打包图标图集。
4. 合并角色外观，显示封面。之后每帧调用 Lua `onUpdate`。
5. 退出时调用 Lua `onUnload`。

## 10. 常用游戏 API

这些是游戏内部的公开成员，不是为 Mod 设计的稳定接口，游戏更新可能改动。签名从源码抄录。

配置表（`T` 为任意表类）：

```csharp
static List<T> T.beans                       // 所有行
static T T.getDataID(string id)              // 按 ID 取行，索引建好后才可用
static T T.getTemplateDef(string id)         // 深拷贝一行
void BaseModDefLoader.addRow<T>(T row)       // DLL：新增行，自动加包前缀
```

文本、提示、日志：

```csharp
static string LanguageDef.getTextByID(string key)                    // key 不带 id_；找不到返回 key
static string LanguageDef.getTextByID(string key, string fallback)
static bool LanguageDef.HasText(string key)
static UIToast FairyUIDispatcher.showToast(string content, bool waitLine = false)
static TipPoolDat FairyUIDispatcher.showTip(string text, string confirmText, string centleText, TipDelegate dele, bool isCanClose = true, int tipType = TipPoolDat.TIP_TYPE_TIP)
static void Logger.LogEngine(string str)
static void Logger.LogWarningEngine(string str)
static void Logger.LogErrorEngine(string str)
```

地面地图：

```csharp
static MapManager MapManager.getInstance()   // 不在地面场景时为 null；成员 planManager、roomManage、camearControl、heroManager
static bool MapManager.isInitFinish
static bool MapManager.isRuning
static float MapManager.getNowSpeed()
static bool MapTools.isCellInMapRect(int cellX, int cellY)
static GridNode MapGrid.getGridNode(int cellx, int celly)   // 成员 build、floor、platform、electricLine、floorLamp、roomBean、isInFog()
static bool PassableHandler.isPersonPassable(int cellx, int celly, SpriteObject role = null)
static bool UIUntils.isGameSceneLoading()
const int MapGlobal.cellWidth = 32, MapGlobal.cellHeight = 32
```

玩家与存档：

```csharp
static UserBean UserBean.tryGetInstance()    // 没有时返回 null。不要用会新建实例的 getInstance()
FWGameData UserBean.gameData
UserFWStarSpread UserBean.curStarMap
long FWGameData.elapsedMM                    // 游戏内已过毫秒
List<ET_RecordBean> FWGameData.ET_LuaRecords // 随存档保存的键值记录：key + longValue / floatValue / boolValue
object FWGameData.ArchiveSyncRoot            // DLL 读写存档数据前 lock
```

游戏没有专门的 Mod 存档接口。需要持久化时把状态拆成数值写进 `ET_LuaRecords`，Key 以自己的包名为前缀。不要把 Mod DLL 里定义的类型挂到存档对象上，它们不会被保存。

线程：

```csharp
static bool MainThread.onMain
static void MainThread.post(Action action)      // 排到主线程，不等待
static void MainThread.invoke(Action action)    // 在主线程执行并等待
```

地面指令（计划）：

```csharp
static BasePlanGraph LocalCoreHandle.Plan_addNewPlan_LN(FWPlanBean newPlan)
static void LocalCoreHandle.Plan_removePlan_LN(RolePlan plan)
static void LocalCoreHandle.Plan_DoPrior_LN(BasePlanGraph graph, bool flag)
static void LocalCoreHandle.Plan_CacheUpdate_LN(bool gmEnable = false)
static BasePlanGraph ViewBuild_Fctions_Base.createBuildsPlan(BaseBuild zoneBuild, short planType)
```

Lua 做不到、只能用 DLL 的事：在游戏方法执行前后插入逻辑、改变内部调用的结果、定义或继承 C# 类。

## 11. 查表、查字段、查接口

站点的数据文件都是 `window.X = <JSON>;` 形式的脚本。取第一个 `= ` 之后的内容，去掉结尾分号，就是严格的 JSON。

| 文件 | 变量 | 内容 |
| --- | --- | --- |
| [data/meta.js](data/meta.js) | `FW_API_META` | 游戏版本、代码提交、导出时间 |
| [data/api-data.js](data/api-data.js) | `FW_API_DATA` | 全部配置表与字段、Mod 相关 C# 类型的签名、XML 结构、Lua 绑定配置。约 570 KB |
| [data/def-samples.js](data/def-samples.js) | `FW_DEF_SAMPLES` | 每张表的中文分类、表文件、行数、原版 ID 示例、首行各字段的值 |
| [data/script-api.js](data/script-api.js) | `FW_SCRIPT_API` | 剧情脚本 `mission` 对象的全部方法 |

结构：

```
FW_API_DATA.defTables[]  { name, xmlName, typeId, source, fields[], constants[], enums[] }
  fields[]               { name, type, xml, declaredIn, default }     xml=true 才能在 def.xml 赋值
FW_API_DATA.types[]      { name, kind, base, source, members[] { kind, name, signature, key } }
FW_API_DATA.xml[]        { id: manifest | def | spine, root, path, tree }
FW_API_DATA.lua          { luaCallCSharp[], csharpCallLua[], hotfixTypes[], hotfixEnabled }
FW_DEF_SAMPLES.tables{}  表类名 → { category, file, rows, ids[], template{} }   template 是首行的字段值
FW_SCRIPT_API.methods[]  { name, ret, params[] { type, name, default, doc }, summary, group, file, line, uses }
```

读取示例（Node.js）：

```js
const fs = require('fs');
function load(file) {
  const text = fs.readFileSync(file, 'utf8');
  return JSON.parse(text.slice(text.indexOf('= ') + 2).trim().replace(/;$/, ''));
}
const api = load('data/api-data.js');
const samples = load('data/def-samples.js');

// 按中文分类或类名找表
const hits = api.defTables.filter(t =>
  /Food/i.test(t.name) || (samples.tables[t.name]?.category || '').includes('食物'));

// 列出一张表里能在 def.xml 赋值的字段，以及原版首行的值
const table = api.defTables.find(t => t.name === 'T_FoodDef');
const first = samples.tables[table.name].template;
for (const f of table.fields.filter(f => f.xml))
  console.log(f.name, f.type, 'default=' + f.default, 'sample=' + first[f.name]);

// 可用作 DependID 的原版 ID
console.log(samples.tables[table.name].ids);
```

查不到网络上的数据文件时，请用户提供表名和字段，不要凭记忆填写。

表名前缀的大致含义：`T_*` 物品，`F_*` 设施与结构，`Map_*` 地图物，`Role_*` 角色，`TK_*` 任务与事件，`G_*` 星系层（战舰 `G_AirShip`、船插 `G_HullMod`、势力 `G_ForceFaction`），`Trade_*` 交易，`LanguageDef` 文本。

## 12. 验证与排错

让用户做的验证步骤：

1. 把 Mod 文件夹放进 `mods/`。
2. 启动游戏，封面点“模组管理”，把 Mod 从“未启用”移到“已启用”，点“保存并使用”，游戏重启。
3. 查看日志中是否有 `mod install success: <name>`。
4. 进入游戏确认效果。

日志位置：PC 为 `%USERPROFILE%\AppData\LocalLow\CatStudio\Outer Space\Player.log`，Android 为 `adb logcat -s Unity`。PC 上该目录即 `<persistentDataPath>`。

| 日志 | 含义 |
| --- | --- |
| `[ModPluginManager] scan root=… scannedMods=N` | 扫描的目录和找到的 Mod 数量。先看这一行确认目录放对了 |
| `Invalid Mod manifest: …` | 清单缺少 `packageId` 或 `versions` |
| `Mod manifest load failed: config=…` | 清单 XML 解析失败 |
| `Mod version mismatch, skipped: packageId=…` | 没有匹配的版本目录，用 `v_common` |
| `Mod install failed: packageId=…, error=…` | 安装失败，`error=` 后是完整异常 |
| `Mod cannot declare both Lua and DLL programs` | 同一版本同时有 `luaMain` 和 DLL |
| `class not found:X` | `ModDefRow` 的 `Name` 不是有效类名 |
| `class or dependID not found: X Y` | `DependID` 指向的行不存在，该行被跳过 |
| `class not found： ModPluginLauncher` | DLL 中没有无命名空间的 `ModPluginLauncher` |
| `Lua Mod failed: packageId=… stage=…` | Lua 回调出错，`stage` 指出是哪一步 |
| `Lua 入口无效` / `Lua 演出失败` / `Lua 文件不存在` | 剧情脚本的问题，见第 7 节 |
| `Mobile Mod skipped: …` | 手机上跳过了含 DLL 的 Mod |

常见现象：

| 现象 | 原因 |
| --- | --- |
| Mod 不在列表中 | 清单不在 `Manifest/manifest.xml`；XML 格式错误；`packageId` 与别的 Mod 重复 |
| 已启用但完全没效果，也没有弹窗 | 版本目录不匹配 |
| 新物品不存在 | `def.xml` 路径不对；类名错；`DependID` 不存在；查找时没带包前缀 |
| 界面显示 Key 而不是文字 | 语言行 Key 漏了 `id_` |
| 某个字段没生效 | 字段名拼错（静默忽略）；字段类型不能从 XML 赋值 |
| 读档提示缺少 Mod，但其实已启用 | `packageId` 含下划线 |

## 13. 交付前自检

- [ ] `Manifest/manifest.xml` 存在，`packageId` 不含下划线，有 `v_common` 版本节点。
- [ ] 所有内容都在 `v_common/` 下，路径大小写与本文一致（`Resources/Def/def.xml`、`Resources/Textures/`、`Lua/`、`Assemblies/`）。
- [ ] 每个 `ModDefRow` 的 `Name` 是 `data/api-data.js` 中存在的 `xmlName`。
- [ ] 每个 `Item Name` 是该表存在的字段，且 `xml` 为 `true`。
- [ ] 每个 `DependID` 是该表的原版 ID。
- [ ] 每个 `Name` / `Desc` 都有对应的 `LanguageDef` 行，Key 为 `id_` + 该值，至少有 `CN` 和 `EN`。
- [ ] `RawIcon` 指向的文件真实存在于 `Resources/Textures/`。
- [ ] 非 DLL Mod 的 `Assemblies/` 下没有任何 `.dll`。
- [ ] Lua 程序 Mod：入口返回表，含 `onLoad` 与 `onUnload`；`onUnload` 撤销了全部注册；`onDefLoaded` 里没有用 `getDataID`。
- [ ] 剧情脚本：有全局 `call` 与入口函数；每条路径以 `endScript` 或 `failScript` 结束；等待接口后有 `coroutine.yield()`。
- [ ] XML 文件是 UTF-8，格式良好。
- [ ] 已向用户说明：未在游戏内运行、涉及的未验证项、存档依赖。

## 14. 已知限制与未验证事项

限制：

- XML 不能覆盖原版行和原版文本。
- 写错的 XML 字段名不报错。
- 依赖关系不在加载时检查。
- “主版本.次版本”版本目录不生效。
- `Resources/Audio/` 没有加载逻辑。
- 不支持运行中热加载 / 卸载；DLL Mod 没有卸载回调。
- 对 Mod 开放的 C# 事件只有两个建筑生成事件。
- 没有专门的 Mod 存档接口。

未验证：

- Lua 程序 Mod 在手机正式包（IL2CPP）中调用 `CS.*` 的可用范围。
- 剧本 Mod 示例的游戏内完整流程，以及手机真机读取 Mod 的脚本和地图。
- 角色外观 Mod 中新皮肤被角色配置引用的完整流程。
- OpenHarmony 平台的 Mod 行为。

## 15. 站点页面

| 页面 | 内容 |
| --- | --- |
| [index.html](index.html) | 概览 |
| [getting-started.html](getting-started.html) | 第一个数据 Mod，逐步说明 |
| [manifest.html](manifest.html) | 清单字段、版本目录、启用顺序 |
| [data-mods.html](data-mods.html) | `def.xml` 规则、文本、图标、存档兼容 |
| [resource-mods.html](resource-mods.html) | 图标、地板、战舰贴图、角色外观 |
| [lua-mods.html](lua-mods.html) | Lua 程序 Mod |
| [scenario-mods.html](scenario-mods.html) | 剧本 Mod 与剧情脚本 |
| [dll-mods.html](dll-mods.html) | C# DLL Mod 与 Harmony |
| [game-api.html](game-api.html) | 常用游戏 API |
| [lifecycle.html](lifecycle.html) | 加载流程与时机 |
| [troubleshooting.html](troubleshooting.html) | 排错与已知限制 |
| [reference.html](reference.html) | 可搜索的配置表、类型、剧情脚本接口参考 |

可直接复制的示例 Mod：

- [examples/ExampleDataMod/](examples/ExampleDataMod/Manifest/manifest.xml)：`Manifest/manifest.xml`、`v_common/Resources/Def/def.xml`、`v_common/Resources/Textures/space_tomato.png`。已在游戏中实测加载。
- [examples/ExampleLuaMod/](examples/ExampleLuaMod/Manifest/manifest.xml)：`Manifest/manifest.xml`、`v_common/Lua/main.lua`、`v_common/Lua/helpers/defs.lua`。已在游戏中实测加载。
