Cave: Guia de Introdução

O áudio no Cave é feito para ser muito direto: você importa um arquivo de áudio, pré-visualiza-o no editor e o toca em seu jogo quando algo acontece.

Neste ensinamento, você aprenderá:

• Como os ativos de áudio funcionam no Navegador de Ativos.
• Como pré-visualizar um arquivo de áudio.
• Como exportar ou substituir áudio como .ogg.
• Como tocar áudio a partir do Python.
• O que significam volume e altura.
• Para que o identificador de áudio retornado pode ser usado.
• Como a aba do Monitor de Áudio ajuda a depurar o áudio.

Você não precisa de uma configuração complexa para começar. Se você pode importar um som e tocá-lo quando um botão, porta, coleta ou ação de personagem acontece, você já entende o fluxo de trabalho principal.

Importando Áudio

O Cave pode importar arquivos de áudio para o projeto como ativos de áudio. Como você viu na seção Importando Ativos, o cave suporta arquivos de áudio .ogg.

Uma vez que o áudio é importado, ele aparece no Navegador de Ativos assim como seu outro conteúdo do projeto. De lá, você pode usá-lo em scripts, callbacks de UI, Logic Bricks, eventos de linha do tempo, ou qualquer outro sistema que precise tocar um som.

Por exemplo, seu projeto pode ter ativos de áudio como:

• Clique no Botão
• Porta Abrindo
• Coletar Moeda
• Passo
• Ambiente da Floresta

Nomes legíveis são muito úteis aqui porque o áudio é frequentemente referenciado pelo nome no Python.

Pré-visualizando Ativos de Áudio

Após importar um arquivo de áudio, você pode pré-visualizá-lo diretamente dentro do Cave.

Existem duas maneiras simples de fazer isso:

• Clique duas vezes no ativo de áudio no Navegador de Ativos para tocar rapidamente uma pré-visualização.
• Clique uma vez para selecioná-lo e mostrar suas propriedades, onde você pode usar os controles de pré-visualização para tocá-lo.

A visualização de propriedades é útil porque oferece mais controle durante a pré-visualização. Por exemplo, você pode testar como o áudio soa com diferentes valores de altura antes de usar esse som no jogo.

Isso é especialmente útil para efeitos como passos, impactos, cliques de UI e sons de criaturas. Uma pequena mudança de altura pode fazer sons repetidos parecerem menos idênticos.

Exportando ou Substituindo Áudio

Os ativos de áudio também podem ser exportados de volta como arquivos .ogg. Isso é útil quando você deseja editar o áudio em uma ferramenta externa, por exemplo.

Você também pode substituir o ativo de áudio por outro arquivo .ogg. Isso é prático quando a lógica já referencia um nome de ativo, mas você deseja mudar o som real.

Por exemplo, seu jogo pode já usar um ativo chamado Porta Abrindo. Se você substituir o áudio dentro desse ativo, scripts que tocam Porta Abrindo podem continuar funcionando sem precisar ser renomeados.

Tocando Áudio usando o Componente de Áudio

Às vezes, você quer tocar um som de looping simples para um ambiente, uma música para o menu principal, etc. Nesse caso, o componente de áudio será o suficiente:

Ele tocará incessantemente o áudio que você especificar e permite que você controle o volume, a altura, se o som é 3D, e a distância máxima. Note que ele não expõe mais opções, como quantas vezes queremos repetir o áudio, etc. Se você precisar de mais personalização, você precisa tocar o áudio através do código.

Tocando Áudio a partir do Python

A maneira mais simples de tocar um ativo de áudio a partir do Python é com cave.playSound().

cave.playSound("Clique no Botão")

Isso toca o ativo de áudio chamado Clique no Botão.

Você também pode passar um valor de volume:

cave.playSound("Porta Abrindo", volume=0.8)

O volume padrão é 1.0, o que significa volume normal. Valores mais baixos tornam o som mais silencioso.

Por exemplo:

Na maioria das vezes, você começará com 1.0 e ajustará a partir daí.

Volume e Altura

• Volume controla quão alto o som está.
• Altura controla quão alta ou baixa a sensação do som. Também muda a velocidade de reprodução, então alturas mais altas soam mais rápidas e afiadas, enquanto alturas mais baixas soam mais lentas e profundas.

O valor padrão para ambos volume e altura é 1.0.

Por exemplo:

Ao usar cave.playSound(), o volume é passado diretamente quando o som começa. A altura geralmente é alterada através do identificador de áudio retornado pela função.

O Identificador de Áudio

Quando você chama cave.playSound(), o Cave retorna um identificador de áudio.

Esse identificador representa a instância do som que está atualmente sendo tocada.

sound = cave.playSound("Passo na Pedra", volume=0.8)
sound.pitch = 1.0

Você pode usar esse identificador para controlar o som após ele começar.

Por exemplo:

sound = cave.playSound("Ambiente da Caverna", volume=0.6, loop=True)

# Alternativamente, você pode usar o getter e o setter:
sound.setPitch(0.9)
sound.setVolume(0.4)

O identificador pode ser usado para coisas como:

• Mudar volume.
• Mudar altura.
• Pausar o som.
• Retomar o som.
• Parar o som.
• Verificar o progresso.
• Fazer o som vir de uma entidade 3D.

Por exemplo, se o som da porta deve vir da entidade porta:

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

Você não precisa desse identificador para cada som. Se você só quer tocar um rápido clique de botão, isso é suficiente:

cave.playSound("Clique no Botão")

Use o identificador quando precisar de controle extra.

É até possível aleatorizar um pouco o passo, dando mais variedade sem exigir mais sons:

sd = cave.playSound("Passo na Pedra")

# Definindo sua fonte 3D para ser a entidade que o toca:
sd.setSource3D(entity, 20)

# Aleatorizando altura e volume:
sd.pitch  = cave.random.uniform(0.5, 1.5)
sd.volume = cave.random.uniform(0.1, 0.3)

O código acima é muito semelhante ao que você encontrará no callback de animação Caminhar e Correr do Proto Character padrão, ao criar um novo Projeto Cave.

A Aba do Monitor de Áudio

O Cave também inclui uma aba Monitor de Áudio para depurar o áudio enquanto seu jogo está rodando.

Você pode abri-la pelo menu Tabs no canto superior esquerdo do editor.

O Monitor de Áudio mostra informações sobre o áudio atualmente sendo tocado, incluindo o progresso de reprodução. Você pode expandir entradas para inspecionar mais detalhes, o que é muito útil quando um projeto começa a ter muitos sons tocando ao mesmo tempo.

Por exemplo, o Monitor de Áudio pode ajudar você a responder perguntas como:

• Este som está realmente sendo tocado?
• O mesmo som está tocando muitas vezes?
• Um ambiente em loop ainda está ativo?
• Quão longe no som está?

Você provavelmente não precisará do Monitor de Áudio constantemente em um pequeno protótipo, mas ele se torna muito útil ao depurar cenas mais complexas.

O Que Você Deve Lembrar

O áudio no Cave é simples: importe um arquivo de áudio, pré-visualize-o no Navegador de Ativos e toque-o a partir do Python com cave.playSound().

Use volume para controlar o volume, altura para controlar quão alta ou baixa a sensação do som, e mantenha o identificador retornado quando você precisar controlar o som após ele começar.

Quando o áudio se torna mais difícil de rastrear, abra a aba do Monitor de Áudio a partir do menu Tabs e inspecione o que está sendo tocado.