effect · scoped_play_song

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

1. 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.
2. 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.