Guía de diseño de audio

Un conjunto de patrones para el sonido de una carta: música de fondo que arranca sola, música que sigue a la escena, efectos de sonido con palabras clave, bucles de ambiente, música que la IA elige según la historia y una gramola en tu propio código de interfaz. Coge los que necesites; se pueden combinar.

Resumen

Hay varios sitios desde donde controlar el sonido:

Forma de control	Dónde se configura	Cómo es
Playlist por defecto	Página Audio → Configuración de BGM	La música arranca cuando entra el jugador y va pasando por tus pistas
BGM condicional	Página Audio → Configuración de BGM → BGM condicional	Cambia de pista cuando lo dice una variable, una palabra clave, la cuenta de turnos o el inicio de sesión. Sin comportamientos
Dejar que elija la IA	Dejar que la IA ponga esta pista / Dejar que la IA ponga este sonido en una pista	Escribes una frase diciendo cuándo encaja; la IA la pone cuando la historia coincide
Comportamientos	Efectos Reproducir música, Reproducir efecto de sonido, Detener audio	El sonido como un paso más entre otros (cambiar una variable, abrir lore, soltar un golpe de sonido)
Botones de la interfaz del jugador	Pasos Reproducir audio / Detener audio	Un botón que pone o para una pista, sin código
Código de interfaz	`api.playAudio()` / `api.stopAudio()`	Control total, para cosas como una gramola

La página Audio se abre desde el bloque de audio del lienzo (si la carta todavía no tiene, pulsa ＋ Audio en la fila Puedes añadir) o desde Paneles → Audio.

Patrón 1: Música de fondo que arranca sola

Paso 1: Añade pistas

En la página Audio, pulsa Agregar pista y rellena:

Campo	Valor	Por qué
Título	Tema principal	Para que tú la reconozcas
Fuente de audio	Sube un `.mp3` o un `.ogg`, o usa Explorar recursos
Tipo de pista	BGM	Música de fondo
Reproducir en bucle	Activado	La BGM suele ir en bucle
Volumen por defecto	`0.7`	Deja hueco para los efectos y el ambiente
Fundido de entrada (s)	`2`	Entra poco a poco en lugar de empezar de golpe

Cada pista tiene un ID de pista que no se puede editar y que no cambia aunque le cambies el nombre. Solo lo necesitas para el código de interfaz (al lado tienes Copiar ID).

Si quieres más de una pieza, añade más pistas: exploración, combate, pueblo.

Paso 2: Configura la playlist por defecto

Pulsa Configuración de BGM (Playlist + reglas de activación):

Campo	Valor	Por qué
Playlist por defecto	Elige Tema principal (y cualquier otra pista de BGM)	Las pistas de la lista suenan una detrás de otra
Modo de reproducción	Bucle, Aleatorio o Secuencial	Bucle repite la lista en orden; Aleatorio la baraja
Reproducción automática	Activado	La música arranca cuando el jugador entra en la carta
Esperar al primer mensaje	Desactivado (o activado)	Activado: la música espera a que el jugador envíe su primer mensaje
Pausa entre pistas (s)	`0` (o `2`)	Con `0`, una pista enlaza directamente con la siguiente

Resultado

El jugador abre la carta → la música entra con un fundido de 2 segundos → cuando termina una pista empieza la siguiente → después de la última, la lista vuelve a empezar.

¿Solo una pista?

Activa Reproducir en bucle y ponla sola en la playlist.

Patrón 2: Música que sigue a una variable

Lo que vas a construir

Cuando el jugador va del pueblo a la mazmorra, la música del pueblo se apaga poco a poco y entra la de la mazmorra. Cuando la Salud baja de 20, entra una música tensa; cuando se recupera, vuelve la música normal. Nada de esto necesita un comportamiento.

Cómo funciona

Una regla de BGM condicional con el disparador Condición de variable se comprueba después de cada cambio. Cuando se cumplen sus condiciones, pone su pista. Cuando dejan de cumplirse, Al terminar decide qué suena después: Volver a la playlist por defecto, Volver a la pista anterior o una pista concreta.

Paso a paso

Asegúrate de tener una variable de Texto Ubicación (con valor inicial village) y las pistas Pueblo y Mazmorra. Luego, Configuración de BGM → BGM condicional → Agregar regla condicional:

Campo	Valor	Por qué
CUANDO	Condición de variable	Lo decide el valor de una variable
Condición	Ubicación es `dungeon`
Reproducir	Mazmorra
Prioridad	`10`	Si coinciden varias reglas a la vez, gana el número más alto
Fundido de entrada (s)	`2`	La pista nueva entra poco a poco
Fundido de salida (s)	`2`	La pista anterior se apaga poco a poco
Detener BGM anterior	Activado	La música del pueblo se para en lugar de seguir sonando por debajo
Al terminar	Volver a la playlist por defecto	Vuelve la música del pueblo cuando el jugador sale de la mazmorra

Una segunda regla para cuando la salud está baja:

Campo	Valor
CUANDO	Condición de variable
Condición	Salud es menor que `20`
Reproducir	Crisis
Prioridad	`20` (más alta que la de la ubicación, así que también gana dentro de la mazmorra)
Detener BGM anterior	Activado
Al terminar	Volver a la pista anterior

El jugador está explorando y suena la playlist
  → La Salud baja de 30 a 15
  → La regla de crisis coincide; la playlist se apaga y entra Crisis
El jugador se bebe una poción y la Salud vuelve a 35
  → La regla deja de coincidir; Al terminar recupera lo que sonaba antes

Varias condiciones

Una regla puede tener más de una condición. Elige TODAS las condiciones cumplidas para «Salud por debajo de 20 y Ubicación es dungeon», o CUALQUIER condición cumplida para que baste con una de las dos.

¿Quién cambia la Ubicación?

Cualquier cosa que cambie la variable: la IA (con las Reglas de comportamiento de la variable), un botón de la interfaz del jugador (Cambiar una variable) o un comportamiento. A la regla de música le da igual cómo cambió. En Mapa y navegación de escenas se montan los botones.

Patrón 3: Efectos de sonido con palabras clave

Lo que vas a construir

Una explosión cuando la IA escribe «explosión» y una puerta que chirría cuando el jugador dice «abrir la puerta». Se configura en la página Audio, sin comportamientos.

Paso 1: Añade pistas de SFX

Campo	Explosión	Puerta
Título	Explosión	Puerta abriéndose
Tipo de pista	SFX	SFX
Reproducir en bucle	Desactivado	Desactivado
Volumen por defecto	`0.9`	`0.8`

Paso 2: Añade reglas de BGM condicional

Aunque se llame así, una regla de BGM condicional puede poner cualquier tipo de pista, SFX incluidos.

Regla: la IA dice «explosión»

Campo	Valor
CUANDO	Palabra clave de la IA
Palabras clave	`explosión`, `estallido`, `detonar` (escribe cada una y pulsa Enter; cualquiera de ellas la dispara)
Reproducir	Explosión
Detener BGM anterior	Desactivado, para que la música siga sonando debajo del efecto

Regla: el jugador dice «abrir la puerta»

Campo	Valor
CUANDO	Palabra clave del jugador
Palabras clave	`abrir la puerta`, `empujar la puerta`
Reproducir	Puerta abriéndose
Detener BGM anterior	Desactivado

Coincidir solo palabras completas evita que «estallido» coincida dentro de «estallidos»; déjalo desactivado si quieres que valgan las dos.

Patrón 4: Bucles de ambiente

Lo que vas a construir

Lluvia, viento o el murmullo de una taberna sonando bajito por debajo de la música.

Cómo funciona

Ambiente es el tercer tipo de pista. Suena a la vez que la BGM, así que puedes tener una pista de BGM y una de ambiente al mismo tiempo. Mantenla en bucle y con poco volumen.

Paso 1: Añade una pista de ambiente

Campo	Valor
Título	Bosque
Tipo de pista	Ambiente
Reproducir en bucle	Activado
Volumen por defecto	`0.3` (más bajo que la música)
Fundido de entrada (s)	`3`
Fundido de salida (s)	`3`

Paso 2: Ponla donde toca

Usa una regla de BGM condicional como en el Patrón 2: Condición de variable Ubicación es forest, Reproducir Bosque, Al terminar Volver a la playlist por defecto.

Detener BGM anterior tiene que estar desactivado en las reglas de ambiente. El ambiente va encima de la música; con el interruptor activado, al empezar la lluvia se pararía la música.

También puedes hacerlo en un comportamiento que ya se encargue de un cambio de escena: añade Reproducir efecto de sonido o Reproducir música para la pista de ambiente, y Detener audio para la anterior.

Niveles de volumen

La BGM, entre 0.5 y 0.7; el ambiente, entre 0.2 y 0.4; los efectos de sonido, entre 0.7 y 1.0. Con niveles distintos, las tres capas no se tapan unas a otras.

Patrón 5: Que la IA elija la música

Lo que vas a construir

Música animada de taberna cuando la historia entra en una taberna, música de combate cuando estalla una pelea, un choque de espadas cuando alguien desenvaina, sin que tengas que escribir una regla para cada caso.

Cómo funciona

Abre una pista y rellena Dejar que la IA ponga esta pista (en una pista de BGM) o Dejar que la IA ponga este sonido (en una pista de SFX). Las pistas de ambiente no se eligen así; llévalas con reglas (Patrón 4).

Pista	Campo	Qué escribir
Taberna (BGM)	Cuándo sonar	`alegre y animada: tabernas, mercados, fiestas`
Combate (BGM)	Cuándo sonar	`estalla una pelea o empieza una persecución`
Choque de espadas (SFX)	Sonar una vez cuando ocurra esto	`alguien desenvaina o se cruzan las espadas`

En cuanto una pista tiene su nota, pone Activado: la IA la pone cuando la historia encaja. Después de cada respuesta, la carta compara la historia con las notas y cambia la música o pone el sonido. Esto funciona dentro del Seguimiento inteligente (en Ajustes de la carta), así que va igual use el jugador el modelo que use. Si dejas una nota vacía, esa pista solo sigue la playlist y tus reglas.

Cuando al menos una pista tiene nota, la zona de Configuración de BGM te hace unas cuantas preguntas sobre cómo se llevan lo que elige la IA y tus reglas. Cada una sale solo cuando de verdad puede darse:

Cuando la IA quiere cambiar pero una regla condicional está poniendo su propia pista: Reglas primero (la regla sigue sonando y la IA espera) o IA primero
Después de una pista elegida por la IA: seguir en bucle hasta que la IA cambie o devuelva la música, o sonar una vez y volver a la playlist por defecto
Baja la música de fondo mientras suena un efecto elegido por la IA y luego la restaura

Apartar una pista de la IA

Desactiva Permitir control por IA en una pista y la IA no podrá ponerla, pararla ni cambiarla. Tu playlist, tus reglas, tus comportamientos y tu código de interfaz sí pueden. Úsalo para el tema del menú o para una pista que maneja tu código.

Directivas de audio

La IA de la historia también puede escribir directivas de audio directamente en su respuesta. El motor le pasa a la IA por su cuenta la lista de pistas que puede controlar (ID, tipo y título) y el formato de las directivas, así que no te hace falta una entrada de lore que las enumere. Las directivas se quitan del texto antes de que lo vea el jugador:

You push open the tavern's heavy door, and warm air hits your face. [audio: <tavern track ID> crossfade 2]

Directiva	Efecto
`[audio: trackId play]`	Reproducir (con el Fundido de entrada propio de la pista)
`[audio: trackId stop]`	Detener (con el Fundido de salida propio de la pista)
`[audio: trackId crossfade 2]`	Detener la otra BGM que controla la IA y hacer entrar esta en 2 segundos
`[audio: trackId volume 0.5]`	Cambiar el volumen
`[audio: trackId play chain:nextTrackId]`	Cuando termine esta pista, empezar la siguiente

chain va bien para una entrada: un cuerno de guerra que da paso a la música de combate cuando termina.

La IA no siempre se acuerda de escribir directivas, sobre todo en conversaciones largas. Las notas de arriba (Cuándo sonar) y las reglas de BGM condicional son las vías fiables; las directivas son un extra.

Patrón 6: Botones que suenan

Sin código: botones de la interfaz del jugador

En Interfaz, selecciona un Botón y, en Al pulsar, en orden, añade Reproducir audio (eliges la pista) o Detener audio (una pista, o Detener todo). Los efectos Reproducir música, Reproducir efecto de sonido y Detener audio de un comportamiento hacen lo mismo desde el lienzo, y un botón puede ejecutar ese comportamiento con Activar un comportamiento.

Ruta con código propio: una gramola

useYumina() le da a tu código de interfaz estas llamadas de audio (todas las duraciones van en segundos):

api.playAudio(trackId, opts): pone una pista. opts puede incluir volume (de 0 a 1), fadeDuration, chainTo, maxDuration, duckBgm y loop (sustituye el ajuste de bucle de la pista solo para esta reproducción)
api.stopAudio(trackId?, fadeDuration?): para una pista, o todo si no pones el ID. Descarta la posición de la pista; usa pauseAudio si quieres retomarla
api.pauseAudio(trackId) / api.resumeAudio(trackId): pausan y retoman en el mismo punto
api.onAudioEnded(cb): llama a cb(trackId) cuando termina una pista que no va en bucle, y devuelve una función para darse de baja

playAudio no para la otra música por sí sola. Para cambiar entre pistas de BGM, para primero las demás.

Copia el ID de pista de cada pista desde la página Audio y, en Paneles → Código de frontend → index.tsx, sustituye el return <Chat /> que viene por defecto:

tsx

export default function MyWorld() {
  const api = useYumina();
  const msgs = api.messages || [];

  // Paste the Track IDs from the Audio page
  const tracks = [
    { id: "PASTE-JAZZ-TRACK-ID", label: "Jazz", color: "#7c3aed" },
    { id: "PASTE-ROCK-TRACK-ID", label: "Rock", color: "#dc2626" },
    { id: "PASTE-CLASSICAL-TRACK-ID", label: "Classical", color: "#0891b2" },
  ];
  const [nowPlaying, setNowPlaying] = React.useState("");

  const play = (t) => {
    // Fade out the other jukebox tracks, then fade this one in
    tracks.forEach((other) => {
      if (other.id !== t.id) api.stopAudio(other.id, 1.5);
    });
    api.playAudio(t.id, { fadeDuration: 1.5 });
    setNowPlaying(t.id);
  };

  const stop = () => {
    api.stopAudio();
    setNowPlaying("");
  };

  return (
    <Chat renderBubble={(msg) => {
      const isLastMsg = msg.messageIndex === msgs.length - 1;
      return (
        <div>
          <div
            style={{ color: "#e2e8f0", lineHeight: 1.7 }}
            dangerouslySetInnerHTML={{ __html: msg.contentHtml }}
          />

          {isLastMsg && (
            <div style={{
              marginTop: "12px",
              padding: "12px",
              background: "rgba(30,41,59,0.5)",
              borderRadius: "8px",
              border: "1px solid #334155",
            }}>
              <div style={{ fontSize: "12px", color: "#94a3b8", marginBottom: "8px" }}>
                Jukebox
              </div>
              <div style={{ display: "flex", gap: "8px", flexWrap: "wrap" }}>
                {tracks.map((t) => (
                  <button
                    key={t.id}
                    onClick={() => play(t)}
                    style={{
                      padding: "8px 16px",
                      background: t.color,
                      border: "none",
                      borderRadius: "6px",
                      color: "#fff",
                      fontSize: "13px",
                      cursor: "pointer",
                    }}
                  >
                    {nowPlaying === t.id ? "♪ " + t.label : t.label}
                  </button>
                ))}
                <button
                  onClick={stop}
                  style={{
                    padding: "8px 16px",
                    background: "#475569",
                    border: "none",
                    borderRadius: "6px",
                    color: "#e2e8f0",
                    fontSize: "13px",
                    cursor: "pointer",
                  }}
                >
                  Stop
                </button>
              </div>
            </div>
          )}
        </div>
      );
    }} />
  );
}

Qué hace el código:

<Chat renderBubble={...} /> conserva la lista de mensajes, el cuadro de texto y el desplazamiento de la plataforma; tú solo dibujas cada burbuja
play() apaga en 1,5 segundos las demás pistas de la gramola y hace entrar la elegida
api.stopAudio() sin argumentos para todo lo que esté sonando
nowPlaying vive solo en la interfaz, así que se reinicia al recargar la página. Para que la elección quede en la partida guardada, guárdala en una variable con api.setVariable("Now playing", t.id) y léela con api.variables["Now playing"]
La gramola solo aparece debajo del último mensaje

Para recorrer una playlist propia, escucha el final de cada pista:

tsx

React.useEffect(() => api.onAudioEnded((endedId) => {
  if (endedId === nowPlaying) playNext();
}), [nowPlaying]);

(Esto solo salta con pistas que no van en bucle.)

Referencia rápida

Tipos de pista

Tipo	Para qué	Ajustes típicos
BGM	Música de fondo	Bucle activado, volumen de 0.5 a 0.7
SFX	Efectos de sonido que suenan una vez	Bucle desactivado, volumen de 0.7 a 1.0
Ambiente	Bucles de ambiente por debajo de la música	Bucle activado, volumen de 0.2 a 0.4

Qué método para qué

Lo que quieres	Método	Dónde
Música al entrar el jugador	Playlist por defecto + Reproducción automática	Audio → Configuración de BGM
Cambiar de pista según una variable	BGM condicional, Condición de variable	Audio → BGM condicional
SFX cuando la IA escribe una palabra	BGM condicional, Palabra clave de la IA	Audio → BGM condicional
SFX cuando el jugador escribe una palabra	BGM condicional, Palabra clave del jugador	Audio → BGM condicional
Cambiar de pista en un turno concreto	BGM condicional, Cuenta de turnos (En el turno o Cada N turnos)	Audio → BGM condicional
Una pista fija al empezar cada partida	BGM condicional, Inicio de sesión	Audio → BGM condicional
Que decida la historia	Cuándo sonar / Sonar una vez cuando ocurra esto en la pista	Ajustes de la pista
Que la IA no toque una pista	Desactiva Permitir control por IA	Ajustes de la pista
Sonido como parte de un comportamiento	Reproducir música, Reproducir efecto de sonido, Detener audio	Efectos del comportamiento
Un botón que pone una pista	Paso Reproducir audio / Detener audio	Interfaz
Control total desde código	`api.playAudio()` / `api.stopAudio()`	Paneles → Código de frontend

Campos de BGM condicional

Campo	Qué hace
CUANDO	Condición de variable, Palabra clave de la IA, Palabra clave del jugador, Cuenta de turnos, Inicio de sesión
Reproducir	La pista que suena
Prioridad	Si coinciden varias reglas, gana la más alta
Fundido de entrada (s) / Fundido de salida (s)	Los fundidos del cambio de esta regla
Detener BGM anterior	Activado para música que sustituye a otra música; desactivado para SFX y ambiente
Al terminar	Qué suena cuando la condición deja de cumplirse: Volver a la playlist por defecto, Volver a la pista anterior o una pista concreta

API de audio del código de interfaz

Método	Descripción
`api.playAudio(trackId, opts)`	Pone una pista. `opts`: `volume`, `fadeDuration` (segundos), `chainTo`, `maxDuration`, `duckBgm`, `loop`
`api.stopAudio(trackId?, fadeDuration?)`	Para una pista, o todo si no hay ID
`api.pauseAudio(trackId)` / `api.resumeAudio(trackId)`	Pausan y retoman en el mismo punto
`api.onAudioEnded(cb)`	Ejecuta `cb(trackId)` cuando termina una pista que no va en bucle; devuelve una función para darse de baja
`api.setAudioVolume("bgm" \| "sfx", v)` / `api.getAudioVolume(...)`	El volumen del jugador para la música o para los efectos

Problemas habituales

Síntoma	Causa probable	Solución
No suena nada	El navegador bloquea el audio hasta que el jugador interactúa con la página	Activa Esperar al primer mensaje, o deja que el primer clic ponga la música
Suenan dos músicas a la vez	Una regla o un comportamiento puso una pista de BGM sin parar la anterior	Activa Detener BGM anterior en las reglas de música; en los comportamientos, añade Detener audio para la pista anterior; en código, para las demás antes de `playAudio`
Los efectos de sonido cortan la música	Detener BGM anterior está activado en una regla de SFX	Desactívalo en las reglas de SFX y de ambiente
La IA nunca elige una pista	La pista no tiene nota, o el Seguimiento inteligente está desactivado	Rellena Cuándo sonar y revisa el Seguimiento inteligente en Ajustes de la carta
La IA pone una pista que no debería	Permitir control por IA está activado	Desactívalo en esa pista
El ambiente suena demasiado fuerte	Volumen demasiado alto	Ambiente de 0.2 a 0.4, música de 0.5 a 0.7
Una regla de variable nunca se dispara	La condición compara un tipo de valor equivocado	Los números necesitan comparaciones numéricas; el texto tiene que coincidir exactamente
Las reglas se pelean entre sí	Tienen la misma prioridad	Dales valores de Prioridad distintos; gana el más alto

Esta es la receta n.º 14: guía de diseño de audio

Empieza con una playlist. Añade reglas de BGM condicional cuando la música tenga que seguir al juego, notas cuando quieras que elija la historia, y código solo para cosas como una gramola. Para ver más a fondo cómo decide el sistema de audio qué suena, mira Avanzado: diseño de audio.

Guía de diseño de audio ​

Resumen ​

Patrón 1: Música de fondo que arranca sola ​

Paso 1: Añade pistas ​

Paso 2: Configura la playlist por defecto ​

Resultado ​

Patrón 2: Música que sigue a una variable ​

Lo que vas a construir ​

Cómo funciona ​

Paso a paso ​

Patrón 3: Efectos de sonido con palabras clave ​

Lo que vas a construir ​

Paso 1: Añade pistas de SFX ​

Paso 2: Añade reglas de BGM condicional ​

Patrón 4: Bucles de ambiente ​

Lo que vas a construir ​

Cómo funciona ​

Paso 1: Añade una pista de ambiente ​

Paso 2: Ponla donde toca ​

Patrón 5: Que la IA elija la música ​

Lo que vas a construir ​

Cómo funciona ​

Apartar una pista de la IA ​

Directivas de audio ​

Patrón 6: Botones que suenan ​

Sin código: botones de la interfaz del jugador ​

Ruta con código propio: una gramola ​

Referencia rápida ​

Tipos de pista ​

Qué método para qué ​

Campos de BGM condicional ​

API de audio del código de interfaz ​

Problemas habituales ​

Guía de diseño de audio

Resumen

Patrón 1: Música de fondo que arranca sola

Paso 1: Añade pistas

Paso 2: Configura la playlist por defecto

Resultado

Patrón 2: Música que sigue a una variable

Lo que vas a construir

Cómo funciona

Paso a paso

Patrón 3: Efectos de sonido con palabras clave

Lo que vas a construir

Paso 1: Añade pistas de SFX

Paso 2: Añade reglas de BGM condicional

Patrón 4: Bucles de ambiente

Lo que vas a construir

Cómo funciona

Paso 1: Añade una pista de ambiente

Paso 2: Ponla donde toca

Patrón 5: Que la IA elija la música

Lo que vas a construir

Cómo funciona

Apartar una pista de la IA

Directivas de audio

Patrón 6: Botones que suenan

Sin código: botones de la interfaz del jugador

Ruta con código propio: una gramola

Referencia rápida

Tipos de pista

Qué método para qué

Campos de BGM condicional

API de audio del código de interfaz

Problemas habituales