effect · `play_song`

Definition

Supported scope:any
Supported target:none

Description

Plays song from database

实战 · 配合 · 坑

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

实战用法

play_song 常用于剧情事件、重大决策触发时为玩家播放特定背景音乐，以增强沉浸感，例如在某国完成统一事件时切换专属主题曲。它也适合用在 mod 定义的特殊节点（如宣战、签署和约）中触发情绪渲染音轨。

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
    }
}

配合关系

[sound_effect](/wiki/effect/sound_effect)：play_song 负责切换背景音乐轨道，而 sound_effect 用于播放一次性音效（如爆炸、号角），两者配合可在同一事件中同时呈现音乐层与音效层。
[hidden_effect](/wiki/effect/hidden_effect)：将 play_song 包裹在 hidden_effect 中，可以在不向玩家显示任何效果提示的情况下静默切换音乐，避免日志或工具提示中出现多余信息。
[if](/wiki/effect/if)：配合 if 条件块，可以根据当前游戏状态（如年份、阵营归属）有选择性地播放不同歌曲，实现动态音乐切换逻辑。

常见坑

歌曲 ID 必须在 music 数据库中注册：play_song 的参数是歌曲定义的 id 字符串，若对应的 .asset 或 music 配置文件中没有该条目，游戏不会报错但也不会播放任何内容，新手常因拼写错误或漏写定义文件而找不到问题所在。
不区分 scope 但并非全局生效：虽然该 effect 支持任意 scope，但实际播放效果仅对当前操作的玩家客户端有意义；在 AI 国家触发的事件中调用 play_song 不会对人类玩家产生任何听觉反馈，放在 AI 逻辑分支里属于无效调用。

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

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

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

effect · play_song