Cave: Guía de Inicio

El audio en Cave está diseñado para ser muy sencillo: importas un archivo de audio, lo previsualizas en el editor y lo reproduces desde tu juego cuando sucede algo.

En esta lección, aprenderás:

• Cómo funcionan los assets de audio en el Asset Browser.
• Cómo previsualizar un archivo de audio.
• Cómo exportar o reemplazar audio como .ogg.
• Cómo reproducir audio desde Python.
• Qué significan el volumen y el tono.
• Para qué se puede usar el audio handle que se devuelve.
• Cómo la pestaña Audio Monitor ayuda a depurar el audio.

No necesitas una configuración compleja para comenzar. Si puedes importar un sonido y reproducirlo cuando un botón, puerta, recogida o acción de un personaje ocurre, ya entiendes el flujo básico de trabajo.

Importar Audio

Cave puede importar archivos de audio al proyecto como assets de audio. Como viste en la sección Importing Assets, Cave soporta archivos de audio .ogg.

Una vez que el audio está importado, aparece en el Asset Browser igual que el resto del contenido de tu proyecto. Desde ahí, puedes usarlo en scripts, callbacks de UI, Logic Bricks, eventos de timeline o cualquier otro sistema que necesite reproducir un sonido.

Por ejemplo, tu proyecto podría tener assets de audio como:

• Button Click
• Door Open
• Pickup Coin
• Footstep
• Forest Ambience

Los nombres legibles son muy útiles aquí porque el audio se suele referenciar por nombre en Python.

Previsualizar Assets de Audio

Después de importar un archivo de audio, puedes previsualizarlo directamente dentro de Cave.

Hay dos formas simples de hacerlo:

• Doble clic sobre el asset de audio en el Asset Browser para reproducir una previsualización rápidamente.
• Clic izquierdo una vez para seleccionarlo y mostrar sus propiedades, donde puedes usar los controles de previsualización para reproducirlo.

La vista de propiedades es útil porque te da más control mientras previsualizas. Por ejemplo, puedes probar cómo suena el audio con diferentes valores de tono antes de usar ese sonido en el juego.

Esto es especialmente útil para efectos como pasos, impactos, clics de UI y sonidos de criaturas. Un pequeño cambio de tono puede hacer que los sonidos repetidos se sientan menos idénticos.

Exportar o Reemplazar Audio

Los assets de audio también pueden ser exportados como archivos .ogg. Esto es útil cuando quieres editar el audio con una herramienta externa, por ejemplo.

También puedes reemplazar el asset de audio con otro archivo .ogg. Esto es práctico cuando la lógica ya referencia un nombre de asset, pero quieres cambiar el sonido real.

Por ejemplo, tu juego puede usar un asset llamado Door Open. Si reemplazas el audio dentro de ese asset, los scripts que reproducen Door Open seguirán funcionando sin necesidad de renombrar.

Reproducir Audio usando Audio Component

A veces quieres reproducir un sonido simple en bucle para un ambiente, música del menú principal, etc. En este caso, el audio component es suficiente:

Reproducirá sin parar el audio que le especifiques y te permite controlar el volumen, el tono, si el sonido es 3D y la distancia máxima. Fíjate que no expone más opciones, como cuántas veces quieres que el audio se repita, etc. Si necesitas más personalización, debes reproducir el audio mediante código.

Reproducir Audio desde Python

La forma más sencilla de reproducir un asset de audio desde Python es usando cave.playSound().

cave.playSound("Button Click")

Esto reproduce el asset de audio llamado Button Click.

También puedes pasar un valor de volumen:

cave.playSound("Door Open", volume=0.8)

El volumen por defecto es 1.0, que significa volumen normal. Valores más bajos hacen el sonido más silencioso.

Por ejemplo:

La mayoría de las veces comenzarás con 1.0 y ajustarás a partir de ahí.

Volumen y Tono

• Volumen controla qué tan fuerte es el sonido.
• Tono controla qué tan agudo o grave suena el sonido. También cambia la velocidad de reproducción, por lo que un tono más alto suena más rápido y agudo, mientras que un tono más bajo suena más lento y profundo.

El valor predeterminado para volumen y tono es 1.0.

Por ejemplo:

Al usar cave.playSound(), el volumen se pasa directamente cuando empieza el sonido. El tono generalmente se cambia mediante el audio handle que devuelve la función.

El Audio Handle

Cuando llamas a cave.playSound(), Cave devuelve un audio handle.

Este handle representa la instancia del sonido que se está reproduciendo.

sound = cave.playSound("Footstep Stone", volume=0.8)
sound.pitch = 1.0

Puedes usar este handle para controlar el sonido después de que comienza.

Por ejemplo:

sound = cave.playSound("Cave Ambience", volume=0.6, loop=True)

# Alternativamente, puedes usar los getter y setter:
sound.setPitch(0.9)
sound.setVolume(0.4)

El handle se puede usar para cosas como:

• Cambiar el volumen.
• Cambiar el tono.
• Pausar el sonido.
• Reanudar el sonido.
• Detener el sonido.
• Revisar el progreso.
• Hacer que el sonido provenga de una entidad 3D.

Por ejemplo, si un sonido de puerta debería salir de la entidad puerta:

sound = cave.playSound("Door Open", volume=1.0)
sound.setSource3D(self.entity, maxDistance=20)

No necesitas este handle para todos los sonidos. Si solo quieres reproducir un clic rápido en un botón, esto es suficiente:

cave.playSound("Button Click")

Usa el handle cuando necesites un control extra.

Incluso es posible aleatorizar un poco el sonido de pasos, dando más variedad sin requerir más sonidos:

sd = cave.playSound("Footstep Stone")

# Estableciendo su fuente 3D como la entidad que lo reproduce:
sd.setSource3D(entity, 20)

# Aleatorizando tono y volumen:
sd.pitch  = cave.random.uniform(0.5, 1.5)
sd.volume = cave.random.uniform(0.1, 0.3)

El código anterior es muy similar al que encontrarás en el callback de animación Walk and Run del Proto Character por defecto, cuando creas un nuevo proyecto en Cave.

La pestaña Audio Monitor

Cave también incluye una pestaña Audio Monitor para depurar audio mientras tu juego está corriendo.

Puedes abrirla desde el menú de Tabs en la parte superior izquierda del editor.

El Audio Monitor muestra información sobre el audio que se está reproduciendo, incluyendo el progreso de reproducción. Puedes desplegar entradas para inspeccionar más detalles, lo cual es muy útil cuando un proyecto tiene muchos sonidos sonando simultáneamente.

Por ejemplo, el Audio Monitor puede ayudarte a responder preguntas como:

• ¿Se está reproduciendo realmente este sonido?
• ¿Se está reproduciendo el mismo sonido demasiadas veces?
• ¿Existe un ambiente en loop activo?
• ¿Cuánto tiempo lleva reproduciéndose el sonido?

Probablemente no necesitarás el Audio Monitor constantemente en un prototipo pequeño, pero se vuelve muy útil al depurar escenas más complejas.

Lo que debes recordar

El audio en Cave es simple: importa un archivo de audio, prévisualo en el Asset Browser y reprodúcelo desde Python con cave.playSound().

Usa el volumen para controlar la intensidad, el tono para controlar qué tan agudo o grave se siente el sonido, y conserva el handle que se devuelve cuando necesites controlar el sonido después de que comience.

Cuando el audio se vuelva más difícil de rastrear, abre la pestaña Audio Monitor desde el menú Tabs e inspecciona qué se está reproduciendo.