effect · play_song

Hands-On Usage

play_song is commonly used in scripted events and major decision triggers to play specific background music for the player, enhancing immersion. For example, it can switch to a dedicated theme when a country completes a unification event. It is also suitable for triggering atmospheric tracks in mod-defined special nodes (such as declarations of war or treaty signings).

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

    immediate = {
        play_song = "my_mod_victory_theme"
    }

    option = {
        name = my_mod.1.a
    }
}

Synergy

• [sound_effect](/wiki/effect/sound_effect): play_song switches background music tracks, while sound_effect plays one-time sound effects (such as explosions or horns). Used together, they can present both music and sound effect layers simultaneously in the same event.
• [hidden_effect](/wiki/effect/hidden_effect): Wrapping play_song within hidden_effect allows silent music switching without displaying any effect notifications to the player, avoiding redundant information in logs or tooltips.
• [if](/wiki/effect/if): Combined with if condition blocks, you can selectively play different songs based on current game state (such as year or faction affiliation), enabling dynamic music switching logic.

Common Pitfalls

1. Song IDs must be registered in the music database: The parameter for play_song is the id string from the song definition. If the corresponding .asset or music configuration file lacks that entry, the game will not report an error but will play nothing. Beginners often struggle to find the issue due to spelling mistakes or missing definition files.
2. Scope-independent but not globally effective: Although this effect supports any scope, the actual playback only has meaning for the current player's client. Calling play_song in events triggered by AI nations produces no auditory feedback for human players; placing it in AI logic branches constitutes an ineffective call.