effect · `set_power_balance_gfx`

Definition

Supported scope:any
Supported target:none

Description

sets gfx for power balance side

Example:
set_power_balance_gfx = {
	id = power_balance_id
	side = power_balance_side_id
	gfx = gfx_name
}

实战 · 配合 · 坑

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

实战用法

set_power_balance_gfx 主要用于在 mod 中自定义权力平衡（Power Balance）系统各方阵营的视觉图标，例如为意识形态对立、派系争斗等场景的权力天平两侧设置专属图形。当你的 mod 创建了新的权力平衡条时，需要用此 effect 为每一个 side 分别指定对应的 GFX，使界面显示正确的阵营图标而非空白或默认图形。

# 在一个事件或 focus 完成后，为自定义权力平衡设置双方图标
set_power_balance_gfx = {
    id = my_mod_power_balance
    side = my_mod_side_progressive
    gfx = GFX_my_mod_progressive_icon
}
set_power_balance_gfx = {
    id = my_mod_power_balance
    side = my_mod_side_conservative
    gfx = GFX_my_mod_conservative_icon
}

配合关系

[add_power_balance_value](/wiki/effect/add_power_balance_value)：在设置好 GFX 之后，往往需要立即给权力平衡赋初始值，两者通常出现在同一初始化块中。
[add_power_balance_modifier](/wiki/effect/add_power_balance_modifier)：为权力平衡的某一侧附加持续影响修正，与 GFX 设置共同构成一个完整的权力平衡初始化流程。
[is_power_balance_side_active](/wiki/trigger/is_power_balance_side_active)：在执行 GFX 设置之前，可用此触发器检查对应的 side 是否已激活，避免对无效 side 执行操作。
[remove_all_power_balance_modifiers](/wiki/effect/remove_all_power_balance_modifiers)：重置权力平衡场景时，先清除所有修正器，再重新设置 GFX，是一种常见的"重置再初始化"模式。

常见坑

id 与 side 必须与定义文件中完全一致：id 对应 common/power_balance/ 中定义的权力平衡 ID，side 对应其下具体的阵营 ID，任何拼写错误都会导致静默失败（游戏不报错但图形不生效），新手容易忽略大小写或下划线差异。
GFX 名称未在 .gfx 文件中注册就直接引用：gfx 字段指向的图形名称必须事先在 interface/ 目录的 .gfx 文件中通过 spriteType 声明，否则游戏会显示空白或报错，不能直接填写图片文件路径。

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

set_power_balance_gfx is primarily used to customize the visual icons for each faction in the Power Balance system within your mod. For example, you can set exclusive graphics for opposing ideologies or factional struggles on either side of the power balance scale. When your mod introduces a new power balance bar, use this effect to specify the corresponding GFX for each side separately, ensuring the UI displays the correct faction icons instead of blank spaces or default graphics.

# After an event or focus completes, set icons for both sides of a custom power balance
set_power_balance_gfx = {
    id = my_mod_power_balance
    side = my_mod_side_progressive
    gfx = GFX_my_mod_progressive_icon
}
set_power_balance_gfx = {
    id = my_mod_power_balance
    side = my_mod_side_conservative
    gfx = GFX_my_mod_conservative_icon
}

Synergy

[add_power_balance_value](/wiki/effect/add_power_balance_value): After setting the GFX, you typically need to assign an initial value to the power balance immediately. These two effects usually appear together in the same initialization block.
[add_power_balance_modifier](/wiki/effect/add_power_balance_modifier): Apply persistent modifier effects to a particular side of the power balance. Combined with GFX setup, this forms a complete power balance initialization workflow.
[is_power_balance_side_active](/wiki/trigger/is_power_balance_side_active): Before executing GFX setup, use this trigger to verify that the corresponding side is already activated, preventing operations on invalid sides.
[remove_all_power_balance_modifiers](/wiki/effect/remove_all_power_balance_modifiers): When resetting a power balance scenario, clear all modifiers first, then reapply the GFX. This "reset then reinitialize" pattern is common practice.

Common Pitfalls

The id and side must match the definition file exactly: id corresponds to the power balance ID defined in common/power_balance/, while side refers to the specific faction ID beneath it. Any spelling error will cause silent failure—the game won't report an error, but the graphics won't apply. Beginners often overlook case sensitivity or underscore differences.
Referencing a GFX name without registering it in a .gfx file first: The graphics name specified in the gfx field must be declared beforehand in .gfx files within the interface/ directory using a spriteType definition. Otherwise, the game will display a blank space or report an error. You cannot directly input image file paths.

effect · set_power_balance_gfx