调试：控制台、error.log 与 -debug_mode

看懂日志、用控制台触发事件和执行脚本、带调试参数启动游戏

日志在哪里

游戏的日志都在用户数据目录下：

代码
Documents\Paradox Interactive\Stellaris\logs\
  error.log                 ← 脚本、本地化、资源加载的错误，最常看
  game.log                  ← 脚本里 log = "..." 的输出
  script_documentation\     ← 控制台导出的脚本文档（见下文）

error.log 每次启动游戏都会重新生成。每一行的格式是 [时间][引擎源文件:行号]: 消息，例如：

代码
[18:26:33][dlc.cpp:346]: Invalid supported_version in  file: mod/dcyh.mod line: 7
[18:26:45][lexer.cpp:476]: Location: gfx/models/ships/xxx/Compellor_ship.gfx(9): Backslash followed by neither quote nor backslash, if you meant to write a single backslash, write two backslashes.

中括号里的 dlc.cpp、lexer.cpp 是引擎内部的源文件，对你没用；有用的是后面的你的文件路径和行号。

读 error.log 的习惯

  1. 先在日志里搜索自己模组的文件夹名或文件名前缀，只看和自己有关的行。
  2. 从第一条错误开始修。一个括号没闭合，后面整个文件都会解析错乱，产生一长串连带错误。
  3. 留意覆盖类提示，它们能告诉你哪份定义生效了（规则见加载顺序与覆盖规则）：
    • Object with key … already exists, using the one at …
    • an event with id [xxx] already exists!
    • Variable name … is already taken
  4. 本地化文件不带 BOM 时，会出现 Localization file '…' should be in in utf-8-bom encoding（原文就是两个 in）。

在脚本里打印信息

效果 log 会把一段文字写进 game.log，任何作用域都能用。原版 common/scripted_effects/00_scripted_effects.txt 里有一个现成的调试工具 print_scope_effect，会打印当前的 this/root/prev/from 等作用域名字：

Clausewitz 脚本
immediate = {
	log = "mymod.1 fired"
	print_scope_effect = yes
}

在脚本化效果/触发器里用本地化命令时，要写成 \\[Root.GetName] 的转义形式，原版 common/scripted_effects/99_advanced_documentation.txt 有说明。

控制台

游戏内按 ` 键（Esc 下方、数字 1 左侧）打开控制台。常用指令：

指令作用
debugtooltip开关调试提示：鼠标悬停时显示对象 ID 等内部信息
event <事件ID>立即触发一个事件，如 event mymod.1
effect <脚本>执行一段效果脚本，如 effect add_resource = { energy = 1000 }
trigger <脚本>检查一段触发器脚本是否成立，如 trigger is_ai = no
observe进入观察者模式
play <国家ID>切换到另一个国家（ID 可用 debugtooltip 查看）
research_all_technologies研究所有科技
instant_build开关瞬间建造
script_docs导出当前版本的脚本文档

提示 控制台里测试事件时，事件的 trigger 仍然会被检查；如果没反应，先用 trigger 指令逐条验证条件。

脚本文档：最权威的参考

script_docs 会把当前游戏版本支持的全部触发器、效果、作用域、修正写进 logs\script_documentation\：

代码
effects.log        所有效果及其用法
triggers.log       所有触发器
scopes.log         所有作用域切换（owner、capital_scope、root、prev……）
modifiers.log      所有修正键及其类别
localizations.log  本地化中可用的命令

网上的教程（包括本站）可能滞后于游戏版本，以这几个文件为准。比如 4.5 的文档里，every_owned_planet 已标注为 “Deprecated; use owned_colony instead”。

-debug_mode 启动参数

stellaris.exe 支持 -debug_mode 命令行参数，引擎解析到它时会打开内部的调试模式开关。它具体开放哪些功能会随版本变化，本文不展开，需要时自行对比开关前后的表现。添加方法任选其一：

  • Steam：库 → 群星 → 属性 → 启动选项，填 -debug_mode；
  • 直接运行游戏：在游戏目录下执行 stellaris.exe -debug_mode；
  • 使用 stellaris-Launcher：-- 之后的参数会原样传给游戏。
PowerShell
stl launch -- -debug_mode

一个典型的调试循环

  1. 修改脚本，保存。
  2. 重启游戏（脚本在启动时加载），用控制台 event / effect 直接验证。
  3. 退出后查看 error.log，搜索自己的前缀，从第一条修起。
  4. 不确定语法时查 script_documentation，不确定谁覆盖了谁时查 already exists 提示。