排错与已知限制Troubleshooting & known limits

日志与报告在哪里Where logs and reports are

内容What位置Where
PC 运行日志PC log%USERPROFILE%\AppData\LocalLow\CatStudio\Outer Space\Player.log
Android 运行日志Android logadb 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 startupLua 与 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 existdef.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 mobileAssemblies/ 下有 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 enabledpackageId 包含下划线 _。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 version
Mod 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 YDependID 指向的行不存在,该行被跳过。The DependID row doesn't exist; the row is skipped.
class not found:XModDefRow/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:Xrole-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 or v_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 不能包含下划线。packageId must 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.