effect · `scoped_play_song`

Definition

Supported scope:COUNTRY
Supported target:none

Description

Plays song from database only on in current scope's player

实战 · 配合 · 坑

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

实战用法

scoped_play_song 常用于 mod 中为特定国家触发专属配乐，例如当某国完成关键国策、宣战或发生内战时，为该国玩家播放一首氛围音乐以增强沉浸感。注意它只对当前 scope 所属国家的玩家生效，因此非常适合放在国家级 event 或 focus 完成回调中。

# 某国完成特定国策后播放专属主题曲
focus = {
    id = GER_rise_of_the_reich
    ...
    completion_reward = {
        scoped_play_song = {
            song = "GER_triumph_theme"
        }
    }
}

配合关系

[country_event](/wiki/effect/country_event) — 在触发重要事件的同时调用 scoped_play_song，为事件弹窗营造对应的音乐氛围，二者常写在同一执行块中。
[add_ideas](/wiki/effect/add_ideas) — 赋予某个国家新 idea（如战争状态、特殊政策）时同步播放主题曲，强化该时刻的叙事感。
[complete_national_focus](/wiki/effect/complete_national_focus) — 脚本强制完成国策时配合播放胜利/转折音乐，多见于大型叙事 mod 的关键剧情节点。
[has_country_flag](/wiki/trigger/has_country_flag) — 在触发条件中用标志位判断是否已播放过该曲，避免同一首歌反复触发造成体验干扰。

常见坑

Scope 写错导致无声：scoped_play_song 必须处于 COUNTRY scope 下，若不小心在 STATE 或 CHARACTER scope 内调用，游戏不会报错但音乐完全不会播放，排查时容易被忽视。
多人游戏中误以为所有玩家都能听到：该 effect 只向当前 scope 国家的本地玩家推送音乐，在多人局中其他玩家不会收到，切勿用它做"全局广播"配乐，需要广播效果应对每个目标国家分别 scope 后各自调用。

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

scoped_play_song is commonly used in mods to trigger exclusive music for specific nations, such as playing an atmospheric track when a nation completes a key focus, declares war, or enters civil war, enhancing immersion for that nation's player. Note that it only takes effect for the player controlling the current scoped nation, making it ideal for placement in nation-level events or focus completion callbacks.

# Play exclusive theme music after a nation completes a specific focus
focus = {
    id = GER_rise_of_the_reich
    ...
    completion_reward = {
        scoped_play_song = {
            song = "GER_triumph_theme"
        }
    }
}

Synergy

[country_event](/wiki/effect/country_event) — Call scoped_play_song simultaneously when triggering important events to create corresponding musical atmosphere for the event popup; both are commonly written in the same execution block.
[add_ideas](/wiki/effect/add_ideas) — Synchronize theme music playback when granting a nation new ideas (such as war status or special policies) to reinforce narrative impact at that moment.
[complete_national_focus](/wiki/effect/complete_national_focus) — Pair victory or turning-point music when script-forcing focus completion, commonly seen at key narrative nodes in large-scale story mods.
[has_country_flag](/wiki/trigger/has_country_flag) — Use flag checks in trigger conditions to determine whether the track has already been played, preventing repeated triggers of the same song that would disrupt player experience.

Common Pitfalls

Incorrect scope resulting in silent audio: scoped_play_song must operate within a COUNTRY scope. If accidentally called within a STATE or CHARACTER scope, the game will not report an error but the music will not play at all, making it easy to overlook during debugging.
Mistakenly assuming all players hear it in multiplayer: This effect only delivers music to the local player controlling the current scoped nation. Other players in multiplayer sessions will not receive it. Do not use it for "global broadcast" music; if global effect is needed, scope and call separately for each target nation.

effect · scoped_play_song