音频

音频音轨提供背景音乐、音效和环境音。它们可以通过 AI 指令、规则或自动播放列表触发。

AudioTrack Schema

{
  "id": "bgm-tavern",
  "name": "Tavern Theme",
  "type": "bgm",
  "url": "@asset:uuid-here",
  "loop": true,
  "volume": 0.4,
  "fadeIn": 2,
  "fadeOut": 1.5,
  "maxDuration": null
}

字段	类型	描述
id	string	唯一的 kebab-case ID
name	string	显示名称
type	"bgm" | "sfx" | "ambient"	音轨类型
url	string	音频来源 — @asset:{id} 或直接 URL
loop	boolean	是否循环播放（通常：BGM/环境音为 true，音效为 false）
volume	number	0.0 到 1.0
fadeIn	number | null	淡入时长，单位秒
fadeOut	number | null	淡出时长，单位秒
maxDuration	number | null	N 秒后自动停止

AI 音频指令

AI 通过方括号指令触发音频：

[audio: bgm-tavern play]
[audio: sfx-sword play]
[audio: bgm-tavern stop]
[audio: bgm-battle crossfade 2.5]
[audio: ambient-rain volume 0.3]
[audio: sfx-magic play chain:bgm-ambient]

动作	描述
play	开始播放音轨
stop	停止音轨
crossfade <seconds>	从当前 BGM 交叉淡入到此音轨
volume <0-1>	更改音轨音量
play chain:<trackId>	播放此音轨，然后自动播放下一首

BGM 播放列表

自动播放一系列 BGM 音轨：

{
  "bgmPlaylist": {
    "tracks": ["bgm-explore-1", "bgm-explore-2", "bgm-explore-3"],
    "playMode": "shuffle",
    "gapSeconds": 0,
    "autoPlay": true,
    "waitForFirstMessage": true
  }
}

字段	类型	描述
tracks	string[]	要循环播放的音轨 ID 数组
playMode	"loop" | "shuffle" | "sequential"	播放顺序模式
gapSeconds	number	音轨之间的静音间隔（默认：0，最大：30）
autoPlay	boolean	是否自动开始播放（默认：true）
waitForFirstMessage	boolean	等到玩家发送第一条消息后再开始播放

条件 BGM

当条件满足时播放特定音轨。支持变量检查、关键词匹配、回合计数和会话开始触发器。

{
  "conditionalBGM": [
    {
      "id": "combat-music",
      "name": "Combat Music",
      "targetTrackId": "bgm-battle",
      "triggerType": "variable",
      "conditions": [
        { "variableId": "in-combat", "operator": "eq", "value": true }
      ],
      "conditionLogic": "all",
      "priority": 10,
      "fadeInDuration": 1,
      "fadeOutDuration": 2,
      "stopPreviousBGM": true,
      "fallback": "default"
    }
  ]
}

字段	类型	描述
id	string	唯一标识符
name	string	显示名称
targetTrackId	string	触发时播放的音轨
triggerType	"variable" | "ai-keyword" | "keyword" | "turn-count" | "session-start"	触发条件 BGM 的事件类型
conditions	Condition[]	要检查的变量条件
conditionLogic	"all" | "any"	多个条件的组合方式（默认："all"）
keywords	string[]	要匹配的关键词（用于 keyword / ai-keyword 触发器）
matchWholeWords	boolean	仅匹配完整单词（用于关键词触发器）
atTurn	number	在特定回合触发（用于 turn-count 触发器）
everyNTurns	number	每隔 N 回合触发（用于 turn-count 触发器）
priority	number	多个触发器匹配时，优先级高的胜出
fadeInDuration	number	淡入时长，单位秒
fadeOutDuration	number	淡出时长，单位秒
stopPreviousBGM	boolean	是否先停止当前播放的 BGM
fallback	"default" | "previous" | trackId 字符串	条件变为 false 时播放什么

条件运算符使用缩写形式：eq、neq、gt、lt、gte、lte、contains。

当条件变为 true 时，音轨开始播放。当条件变为 false 时，音轨停止（如果配置了淡出则带淡出效果），并根据 fallback 设置回退。