effect · `log`

Definition

Supported scope:any
Supported target:none

Description

Print message to game.log, console (if visible) and history logger (if running. you can use category|log to specify a category), Can be localized

实战 · 配合 · 坑

实战内容由 AI 生成,并已对照 vanilla 命令词表校验 —— 请当作起点而非权威依据。上方的定义节才是游戏自带文档原文。

实战用法

log 最常用于调试复杂 mod 逻辑时追踪变量值与执行流程，例如在事件触发后输出当前国家标签与变量状态，帮助开发者确认脚本是否按预期执行。也常用于在大型 if/else 分支中标记"走了哪条路"，配合 game.log 文件快速定位问题。

country_event = {
    id = my_mod.1
    immediate = {
        log = "my_mod.1 fired for [Root.GetTag], var=[?my_variable]"
        if = {
            limit = { check_variable = { my_variable > 5 } }
            log = "debug|my_mod.1: branch A taken, my_variable=[?my_variable]"
            add_to_variable = { my_variable = 1 }
        }
    }
}

配合关系

[if](/wiki/effect/if) — 在条件分支的入口和出口各写一条 log，可精确追踪哪个分支被命中，是调试 if/else 嵌套时的标准做法。
[hidden_effect](/wiki/effect/hidden_effect) — 正式发布前将调试用的 log 包裹在 hidden_effect 里，方便统一启用或注释，避免 log 刷屏影响性能。
[set_variable](/wiki/effect/set_variable) / [add_to_variable](/wiki/effect/add_to_variable) — 修改变量前后各加一条 log，可直接在日志里对比变量变化，确认数值运算正确。
[is_debug](/wiki/trigger/is_debug) — 在 trigger 侧用 is_debug = yes 做门控，配合 log 只在调试模式下输出信息，防止正式游戏产生无用日志。

常见坑

忘记使用分类前缀导致日志难以过滤：输出量大时不加 category| 前缀，所有 log 混在 game.log 里极难搜索；应养成 log = "my_mod|..." 的命名习惯，方便用关键字过滤。
在循环或每帧触发的块里裸写 log：every_country、while_loop_effect 等循环结构中若无条件写 log，每次执行都会产生大量日志条目，严重拖慢游戏速度，务必加条件限制或仅在调试阶段保留。

Hands-On Notes

Hands-on notes are AI-generated and checked against the vanilla command vocabulary — treat them as a starting point, not authoritative reference. The definition above is the game's own documentation.

Hands-On Usage

log is primarily used for debugging complex mod logic by tracking variable values and execution flow. For example, you can output the current country tag and variable state after an event fires, helping developers confirm that scripts execute as intended. It is also commonly used to mark "which branch was taken" in large if/else structures, and combined with the game.log file to quickly locate issues.

country_event = {
    id = my_mod.1
    immediate = {
        log = "my_mod.1 fired for [Root.GetTag], var=[?my_variable]"
        if = {
            limit = { check_variable = { my_variable > 5 } }
            log = "debug|my_mod.1: branch A taken, my_variable=[?my_variable]"
            add_to_variable = { my_variable = 1 }
        }
    }
}

Synergy

[if](/wiki/effect/if) — Write one log statement at the entry and exit of each conditional branch to precisely track which branch is hit. This is standard practice when debugging nested if/else structures.
[hidden_effect](/wiki/effect/hidden_effect) — Before final release, wrap debug log statements in hidden_effect for convenient bulk enabling or commenting, preventing log spam from affecting performance.
[set_variable](/wiki/effect/set_variable) / [add_to_variable](/wiki/effect/add_to_variable) — Add one log before and after modifying variables to directly compare variable changes in the log file and confirm that numeric calculations are correct.
[is_debug](/wiki/trigger/is_debug) — Use is_debug = yes as a gate on the trigger side, combined with log to output information only in debug mode, preventing useless logs in the actual game.

Common Pitfalls

Forgetting to use category prefixes makes logs hard to filter: When output volume is large, omitting the category| prefix means all logs are mixed in game.log and extremely difficult to search. Develop the habit of naming as log = "my_mod|..." so you can filter by keyword.
Writing bare log statements in loops or per-frame triggered blocks: In loop structures like every_country and while_loop_effect, writing log without conditions generates massive log entries each execution, severely slowing down the game. Always add conditional restrictions or keep log only during the debug phase.

effect · log