trigger · `phase`

Definition

Supported scope:COMBATANT
Supported target:none

Description

check if we are in this combat phase

实战 · 配合 · 坑

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

实战用法

phase 常用于自定义战斗事件或决策中，根据当前战斗所处的阶段（如突破阶段、持续战斗阶段等）触发不同的效果或加成。例如可以在 mod 中实现"只有在特定战斗阶段才触发某种士气崩溃事件"的逻辑：

COMBATANT = {
    limit = {
        phase = preparation
        is_attacker = yes
    }
    # 在准备阶段且为进攻方时触发某逻辑
}

配合关系

is_attacker / is_defender：战斗阶段往往需要区分攻守方，进攻方在突破阶段与防守方在僵持阶段的行为逻辑通常不同，两者组合能精确定位触发条件。
is_winning：在某个战斗阶段同时检查己方是否占优，可用于实现"势如破竹"类的特殊增益效果。
has_combat_modifier：常与 phase 搭配确认某阶段是否已存在特定战斗加成，避免重复叠加同类修正。
night：夜战触发逻辑经常需要结合当前战斗阶段来判断，确保特定夜战事件只在合适的阶段生效。

常见坑

阶段枚举值拼写错误：phase 接受的具体阶段名称必须与游戏内部定义完全一致（区分大小写），新手容易凭直觉猜写，导致条件永远不满足却没有任何报错提示，建议直接参考官方脚本中已有用例确认合法值。
在非 COMBATANT scope 下使用：phase 只在战斗双方（COMBATANT）scope 下有效，若误用在 country 或 unit_leader 等 scope 中，游戏不会报错但条件始终返回 false，排查时容易被忽视。

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

phase is commonly used in custom battle events or decisions to trigger different effects or bonuses based on the current stage of combat (such as breakthrough phase, sustained combat phase, etc.). For example, you can implement logic in a mod like "trigger a morale collapse event only during a specific combat phase":

COMBATANT = {
    limit = {
        phase = preparation
        is_attacker = yes
    }
    # Triggers certain logic when in preparation phase and as the attacker
}

Synergy

is_attacker / is_defender: Battle phases typically require distinguishing between attacker and defender roles. The behavioral logic of an attacker during breakthrough phase differs from a defender during stalemate phase. Combining both triggers allows precise targeting of activation conditions.
is_winning: Checking whether your side has the advantage during a specific battle phase enables implementation of special bonuses like "overwhelming momentum" effects.
has_combat_modifier: Frequently paired with phase to confirm whether a specific combat bonus already exists during that stage, preventing unwanted stacking of similar modifiers.
night: Night combat logic often needs to combine with the current battle phase for proper evaluation, ensuring specific night battle events only apply during appropriate stages.

Common Pitfalls

Misspelled phase enumeration values: The specific phase names accepted by phase must exactly match the in-game definitions (case-sensitive). Beginners often guess based on intuition, resulting in conditions that never trigger with no error messages. It is recommended to directly reference existing examples in official scripts to confirm valid values.
Using outside COMBATANT scope: phase is only valid within the COMBATANT scope (the two sides in combat). If mistakenly used in scopes like country or unit_leader, the game will not report an error but the condition will always return false, making it easy to overlook during troubleshooting.

trigger · phase