effect · `sound_effect`

Definition

Supported scope:any
Supported target:none

Description

Plays sound effect

实战 · 配合 · 坑

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

实战用法

sound_effect 常用于事件触发时播放音效以增强沉浸感，例如在战争爆发事件中播放爆炸声，或在科技研究完成的隐藏效果中播放提示音。它适用于任何需要为玩家提供音频反馈的场景，如决策触发、国策完成等关键节点。

country_event = {
    id = my_mod.1
    title = my_mod.1.t
    desc = my_mod.1.d

    option = {
        name = my_mod.1.a
        sound_effect = "event:/SFX/Events/military/declaration_of_war"
        add_war_support = 0.10
    }
}

配合关系

[hidden_effect](/wiki/effect/hidden_effect)：将 sound_effect 包裹在 hidden_effect 中，可以在不向玩家显示多余 tooltip 的情况下静默播放音效，避免音效触发条件出现在事件日志里。
[custom_effect_tooltip](/wiki/effect/custom_effect_tooltip)：当音效触发逻辑复杂时，配合 custom_effect_tooltip 向玩家展示一个可读的说明文字，弥补 sound_effect 本身不生成 UI 提示的缺陷。
[if](/wiki/effect/if)：通过 if 条件块控制音效仅在特定情况下播放，例如只对人类玩家触发音效，避免 AI 执行时产生无意义的音频调用。
[play_song](/wiki/effect/play_song)：两者同为音频类命令，sound_effect 用于短促的一次性音效，play_song 用于切换背景音乐，常搭配使用以营造完整的音频氛围。

常见坑

音效路径填写错误：sound_effect 的值必须是游戏内已定义的音效事件路径（通常以 event:/ 开头），直接填写文件名或自创路径会导致静默失败且不报错，新手应优先参考原版事件脚本中的路径写法进行复用。
对 AI 国家重复触发：在 every_country 等批量 scope 循环中使用 sound_effect 时，每个 scope 切换都会尝试触发音效，AI 国家的触发虽不可闻但仍会造成不必要的开销，建议用 [is_ai](/wiki/trigger/is_ai)（即 if = { limit = { NOT = { is_ai = yes } } }）限制仅对人类玩家生效。

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

sound_effect is commonly used to play audio cues when events trigger, enhancing immersion—for example, explosion sounds during war declaration events or notification chimes in hidden effects when technology research completes. It applies to any scenario requiring audio feedback for the player, such as decision triggers, focus completions, and other critical moments.

country_event = {
    id = my_mod.1
    title = my_mod.1.t
    desc = my_mod.1.d

    option = {
        name = my_mod.1.a
        sound_effect = "event:/SFX/Events/military/declaration_of_war"
        add_war_support = 0.10
    }
}

Synergy

[hidden_effect](/wiki/effect/hidden_effect): Wrapping sound_effect inside hidden_effect allows silent audio playback without generating unnecessary tooltips for the player, preventing audio trigger conditions from appearing in the event log.
[custom_effect_tooltip](/wiki/effect/custom_effect_tooltip): When audio trigger logic is complex, pair it with custom_effect_tooltip to display readable descriptive text to the player, compensating for the lack of UI feedback that sound_effect itself produces.
[if](/wiki/effect/if): Use conditional if blocks to control audio playback only under specific circumstances—for example, triggering sound effects only for human players and avoiding meaningless audio calls when AI executes the code.
[play_song](/wiki/effect/play_song): Both are audio commands; sound_effect handles short, one-time sound effects while play_song switches background music. They are often used together to create a complete audio atmosphere.

Common Pitfalls

Incorrect sound effect path: The sound_effect value must be a sound event path already defined in the game (typically starting with event:/). Directly using filenames or custom paths will fail silently without errors. Beginners should prioritize referencing path conventions from vanilla event scripts for reuse.
Repeated triggering for AI countries: When using sound_effect in batch scope loops like every_country, each scope switch attempts to trigger the sound. Although audio from AI countries is inaudible, it still causes unnecessary overhead. Use [is_ai](/wiki/trigger/is_ai) (i.e., if = { limit = { NOT = { is_ai = yes } } }) to restrict execution to human players only.

effect · sound_effect