排错与已知限制Troubleshooting & known limits
日志与报告在哪里Where logs and reports are
| 内容What | 位置Where |
|---|---|
| PC 运行日志PC log | %USERPROFILE%\AppData\LocalLow\CatStudio\Outer Space\Player.log |
| Android 运行日志Android log | adb logcat -s Unity |
| 战舰贴图加载报告Warship texture report | <persistentDataPath>/ModReports/ShipTextures/LoadReport.txt同目录的 AirShipIds.tsv 列出全部可用战舰 ID。AirShipIds.tsv next to it lists every valid warship ID. |
| 启用列表Enabled list | <persistentDataPath>/mod.dat(删除即清空启用列表) (delete to clear the list) |
PC 上 <persistentDataPath> 即上面日志所在的目录。游戏每次启动和打开 Mod 管理界面时会记录一行 [ModPluginManager] scan root=… scannedMods=N,可以先确认扫描目录和数量。On PC, <persistentDataPath> is the folder holding the log above. Each launch and each opening of the mod manager logs [ModPluginManager] scan root=… scannedMods=N — check the folder and count first.
按症状排查By symptom
| 现象Symptom | 常见原因Usual cause |
|---|---|
| Mod 不在列表中Mod missing from the list | 清单不在 Manifest/manifest.xml;XML 格式错误;缺少 packageId 或 versions;与另一个 Mod(含工坊)packageId 重复,只保留先扫描到的。Manifest not at Manifest/manifest.xml; malformed XML; missing packageId or versions; duplicate packageId with another mod (incl. Workshop) — only the first scanned is kept. |
| 启动时弹出“加载Mod … 失败”“Failed to load mod …” prompt at startup | Lua 与 DLL 同时存在;Lua 入口或 onLoad 出错;DLL 加载失败;def.xml / role-customize.xml 解析失败。在日志里搜 Mod install failed: packageId=… 看异常。提示中选“继续”只跳过这个 Mod。Both Lua and DLL present; error in the Lua entry or onLoad; DLL failed to load; def.xml / role-customize.xml failed to parse. Search the log for Mod install failed: packageId=…. “Continue” in the prompt skips only this mod. |
| Mod 已启用,但完全没生效,也没有弹窗Mod is enabled but does nothing, with no prompt | 没有匹配的版本目录:日志有 Mod version mismatch, skipped。把内容放进 v_common,见版本目录如何选择。No matching version folder: the log shows Mod version mismatch, skipped. Put the content in v_common; see How a version folder is chosen. |
| 加载画面停在“启动失败”Loading screen stuck on “startup failed” | 配置表阶段出错,常见于 onDefLoaded / initModDef 抛出异常。Failure while loading definitions, typically an exception in onDefLoaded / initModDef. |
| 新物品不存在New item doesn't exist | def.xml 不在 <version>/Resources/Def/;Name 类名错误;DependID 不存在;查找时没有带包 ID 前缀。def.xml not in <version>/Resources/Def/; wrong class in Name; unknown DependID; looked up without the package prefix. |
| 界面显示的是 Key 而不是文字UI shows the key instead of text | 语言行 Key 漏了 id_ 前缀,或 Key 与引用处不一致。见文本与多语言。Language Key is missing the id_ prefix or doesn't match the reference. See Text & localisation. |
| 某个字段没生效A field has no effect | 字段名拼错(静默忽略);该字段类型无法从 XML 赋值;值格式转换失败(日志有错误)。Misspelled field (silently ignored); the field's type can't be set from XML; value conversion failed (logged). |
| 手机上 Mod 不生效Mod does nothing on mobile | Assemblies/ 下有 DLL(整个 Mod 被跳过,会有提示);Lua 调用了没有生成桥接的 C# API;放错目录(见快速开始)。A DLL in Assemblies/ (whole mod skipped, with a notice); Lua calls a C# API without generated bridges; wrong folder (see Getting started). |
| 读档时提示缺少 Mod,但其实已启用Save says a mod is missing although it's enabled | packageId 包含下划线 _。packageId contains an underscore _. |
日志原文对照Log messages
| 日志Message | 含义Meaning |
|---|---|
Invalid Mod manifest: … | 清单缺少 packageId 或 versions。Manifest lacks packageId or versions. |
Mod manifest load failed: config=… | 清单 XML 解析失败。Manifest XML could not be parsed. |
not found the matching versionMod version mismatch, skipped: packageId=… | 没有匹配当前游戏版本或 v_common 的目录,该 Mod 被跳过。No folder matching the game version or v_common; the mod is skipped. |
Mod install failed: packageId=…, folder=…, error=… | 该 Mod 安装失败并弹出提示;error= 后是完整异常。The mod failed to install and the prompt was shown; the full exception follows error=. |
Mod cannot declare both Lua and DLL programs | 同一版本同时有 luaMain 与 DLL。The version has both luaMain and a DLL. |
class not found: ModPluginLauncher | 主程序集中没有无命名空间的 ModPluginLauncher。(该提示里的 BaseModPluginLauncher 是旧名称,实际应继承 BaseModLauncher。)No global-namespace ModPluginLauncher in the main assembly. (The message mentions BaseModPluginLauncher, an old name; derive from BaseModLauncher.) |
class or dependID not found: X Y | DependID 指向的行不存在,该行被跳过。The DependID row doesn't exist; the row is skipped. |
class not found:X | ModDefRow/ModDefFwr 的 Name 不是有效类名。Name on ModDefRow/ModDefFwr isn't a valid class. |
file not exist:… | <files> 引用的 .fwr 不存在。A .fwr referenced in <files> is missing. |
Lua Mod failed: packageId=… stage=… | Lua 回调出错,stage 指出是哪一步。A Lua callback failed; stage says which. |
Lua 文件不存在: X(Mod packageId) | 剧情脚本在该 Mod 的 Lua/ 与游戏脚本目录中都找不到,见剧本 Mod。A story script was found neither in the mod's Lua/ nor in the game's script folder; see Scenario mods. |
Lua 入口无效: X.lua, entry=… | 剧情脚本缺少全局函数 call,或缺少 scriptfun 指定的入口函数。The story script lacks the global call function or the entry function named by scriptfun. |
Lua 演出失败 [N] X.lua: … | 剧情脚本运行出错或调用了 mission:failScript;冒号后是原因,行尾带地图与游戏内时间。A story script raised an error or called mission:failScript; the reason follows the colon, with map and in-game time at the end. |
Mod 资源路径非法(…) | 数据行引用的脚本或地图路径是绝对路径、含 .. 或越出 Mod 目录。A script or map path in a data row is absolute, contains .., or escapes the mod folder. |
Mod 开局地图未找到:templateName=… | Mod 行的 M_StarMapPath_Def.Path 在该 Mod 的 Resources/Map/ 与游戏地图目录中都找不到;不会回退到默认地图。The M_StarMapPath_Def.Path of a mod row was found neither in the mod's Resources/Map/ nor in the game's map folder; there is no fallback map. |
Mobile Mod skipped: … | 手机上跳过了含 DLL 的 Mod。A mod with DLLs was skipped on mobile. |
ModSpineDef not found:X | role-customize.xml 中的部件 Key 不在 S_CharacterSpinePartsDef。A part key in role-customize.xml is not in S_CharacterSpinePartsDef. |
… 图片不存在。 此飞船覆盖未应用,保留原贴图。 | 战舰贴图报告:image 指向的文件不存在。报告内容为中文。Warship report: the image file doesn't exist. The report text is in Chinese. |
已知限制(当前版本)Known limits (this build)
- 版本目录的“主版本.次版本”匹配不生效,只能用完整版本号或
v_common。“major.minor” version folders don't match; use the full version orv_common. - XML 只能新增行,不能覆盖原版行或原版文本。XML can only add rows; it can't replace built-in rows or text.
- XML 中写错的字段名不报错。Misspelled field names in XML are not reported.
- 列表、枚举、对象类型的字段不能从 XML 赋值。List, enum and object fields can't be set from XML.
- 依赖关系不在加载时检查。Dependencies are not enforced at load.
packageId不能包含下划线。packageIdmust not contain underscores.- 配置表在同一次运行中被重新加载时(仅出现在编辑器/测试工具中),XML 行的 ID 会再次加前缀。正式游戏只在启动时加载一次。If definitions are reloaded within one session (only editor/test tools do this), XML row IDs get prefixed twice. The shipped game loads them once at startup.
Resources/Audio/目录目前没有加载逻辑。Resources/Audio/has no loader yet.- Mod 不支持运行中热加载/卸载;DLL Mod 没有卸载回调。No hot reload/unload while running; DLL mods have no unload callback.