effect · `set_building_level`

Definition

Supported scope:STATE
Supported target:none

Description

Sets specific level of a building construction for amount of levels in specified state or province

实战 · 配合 · 坑

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

实战用法

set_building_level 常用于 mod 中的事件或决策，直接将某州的建筑等级设定为固定值，适合初始化地图、触发特殊事件后重建基础设施、或通过决策一次性拉满特定建筑。例如，在一个"工业援助"决策中，将目标州的民用工厂直接设置到指定等级：

# 在 STATE scope 内执行
set_building_level = {
    building = industrial_complex
    level = 5
    instant_build = yes
}

配合关系

[non_damaged_building_level](/wiki/trigger/non_damaged_building_level)：在执行 set_building_level 前先检测当前建筑的未受损等级，避免重复设置或逻辑矛盾。
[damage_building](/wiki/effect/damage_building)：可先用 damage_building 将建筑破坏至特定状态，再用 set_building_level 重建，模拟"先摧毁后重建"的剧情演出。
[add_extra_state_shared_building_slots](/wiki/effect/add_extra_state_shared_building_slots)：建筑等级提升后可能超出可用槽位上限，配合此命令提前扩充共享建筑槽以确保数值合法。
[free_building_slots](/wiki/trigger/free_building_slots)：在设置建筑前校验剩余空闲槽位是否充足，防止因槽位不足导致效果静默失败。

常见坑

忽略建筑槽位上限：set_building_level 直接设定等级，但若目标等级超过该州当前的可用建筑槽位，效果可能被截断或静默失败，务必先确认槽位充足或配合 add_extra_state_shared_building_slots 预留空间。
与 add_building_construction 混淆：set_building_level 是立即到位的硬设置，不经过施工队排队流程；若不加 instant_build = yes 字段（部分版本/建筑类型需要），可能出现意料之外的行为，需注意与 add_building_construction（走正常建造队列）的本质区别。

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_building_level is commonly used in mod events or decisions to directly set a state's building level to a fixed value. It's ideal for map initialization, rebuilding infrastructure after triggering special events, or using decisions to instantly max out specific buildings. For example, in an "Industrial Aid" decision, you can directly set the target state's civilian factory to a specified level:

# Executed within STATE scope
set_building_level = {
    building = industrial_complex
    level = 5
    instant_build = yes
}

Synergy

[non_damaged_building_level](/wiki/trigger/non_damaged_building_level): Check the current undamaged building level before executing set_building_level to avoid redundant assignments or logical conflicts.
[damage_building](/wiki/effect/damage_building): You can first use damage_building to destroy a building to a specific state, then use set_building_level to rebuild it, simulating a "destroy then rebuild" narrative sequence.
[add_extra_state_shared_building_slots](/wiki/effect/add_extra_state_shared_building_slots): After increasing building levels, you may exceed the available slot limit. Combine this command to preemptively expand shared building slots and ensure valid values.
[free_building_slots](/wiki/trigger/free_building_slots): Validate that sufficient free slots remain before setting a building level to prevent silent failures due to insufficient slots.

Common Pitfalls

Ignoring building slot limits: set_building_level directly sets the level, but if the target level exceeds the state's current available building slots, the effect may be truncated or silently fail. Always verify sufficient slots exist or use add_extra_state_shared_building_slots to reserve space in advance.
Confusing with add_building_construction: set_building_level is an immediate hard set that bypasses the construction queue process. Without the instant_build = yes field (required in certain versions/building types), unexpected behavior may occur. Pay attention to the fundamental difference from add_building_construction (which follows the normal construction queue).

effect · set_building_level