Audio

Las pistas de audio proporcionan música de fondo, efectos de sonido y sonidos ambientales. Pueden ser activadas por directivas de IA, reglas o listas de reproducción automáticas.

Esquema AudioTrack

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

Campo	Tipo	Descripción
id	string	ID único en kebab-case
name	string	Nombre visible
type	"bgm" | "sfx" | "ambient"	Tipo de pista
url	string	Fuente de audio — @asset:{id} o URL directa
loop	boolean	Si se debe repetir (típico: true para BGM/ambient, false para SFX)
volume	number	0.0 a 1.0
fadeIn	number | null	Duración del fade-in en segundos
fadeOut	number | null	Duración del fade-out en segundos
maxDuration	number | null	Auto-detener después de N segundos

Directivas de Audio de la IA

La IA activa el audio mediante directivas entre corchetes:

[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]

Acción	Descripción
play	Iniciar reproducción de la pista
stop	Detener la pista
crossfade <seconds>	Crossfade del BGM actual a esta pista
volume <0-1>	Cambiar el volumen de la pista
play chain:<trackId>	Reproducir esta pista, luego reproducir automáticamente la siguiente

Lista de reproducción BGM

Reproducir automáticamente una secuencia de pistas BGM:

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

Campo	Tipo	Descripción
tracks	string[]	Array de IDs de pistas para ciclar
playMode	"loop" | "shuffle" | "sequential"	Modo de orden de reproducción
gapSeconds	number	Silencio entre pistas (predeterminado: 0, máx: 30)
autoPlay	boolean	Empezar a reproducir automáticamente (predeterminado: true)
waitForFirstMessage	boolean	No empezar hasta que el jugador envíe su primer mensaje

BGM Condicional

Reproducir pistas específicas cuando se cumplen las condiciones. Soporta verificaciones de variables, coincidencia de palabras clave, conteo de turnos y disparadores de inicio de sesión.

{
  "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"
    }
  ]
}

Campo	Tipo	Descripción
id	string	Identificador único
name	string	Nombre visible
targetTrackId	string	Pista a reproducir cuando se activa
triggerType	"variable" | "ai-keyword" | "keyword" | "turn-count" | "session-start"	Qué activa el BGM condicional
conditions	Condition[]	Condiciones de variables a verificar
conditionLogic	"all" | "any"	Cómo se combinan múltiples condiciones (predeterminado: "all")
keywords	string[]	Palabras clave a coincidir (para disparadores keyword / ai-keyword)
matchWholeWords	boolean	Coincidir solo palabras completas (para disparadores de palabras clave)
atTurn	number	Disparar en un turno específico (para disparador turn-count)
everyNTurns	number	Disparar cada N turnos (para disparador turn-count)
priority	number	La prioridad más alta gana cuando coinciden múltiples disparadores
fadeInDuration	number	Duración del fade-in en segundos
fadeOutDuration	number	Duración del fade-out en segundos
stopPreviousBGM	boolean	Detener primero el BGM que se está reproduciendo
fallback	"default" | "previous" | trackId string	Qué reproducir cuando la condición se vuelve falsa

Los operadores de condición usan la forma corta: eq, neq, gt, lt, gte, lte, contains.

Cuando la condición se vuelve verdadera, la pista inicia. Cuando es falsa, se detiene (con fade-out si está configurado) y vuelve según la configuración de fallback.