Sounds

Aprenda a adicionar sounds à sua cena.

O som é uma ótima maneira de fornecer feedback às ações e eventos do jogador; sons de fundo também podem dar mais contexto à tua scene e melhorar a imersão do jogador nela.

📔 Nota: Tem em mente que os sons só são ouvidos pelos players que estiverem dentro dos parcels que compõem a scene onde o som foi gerado, mesmo que de outra forma estivessem dentro do alcance de audição. Os players também podem optar por desativar todos os sons nas suas settings.

Os formatos de som suportados variam consoante o browser, mas é recomendável usar .mp3.

.wav ficheiros também são suportados, mas geralmente não são recomendados, pois são significativamente mais pesados.

Tocar sons

A forma mais fácil de tocar um som é adicionar um Audio Source component visualmente no Scene Editor no Creator Hub e defini-lo para Start Playing e Loop. Vê Add Components.

Também podes acionar a reprodução de um som de forma no-code através de Actions, vê Torne qualquer item smart.

Para tocar um som via code, usa a AudioSource.playSound function.

// Criar entity
const sourceEntity = engine.addEntity()

// Tocar som
AudioSource.playSound(sourceEntity, 'assets/sounds/sound-effect.mp3')

O ficheiro de som deve estar dentro da pasta do projeto. No exemplo acima, o ficheiro de áudio está localizado numa pasta assets/sounds que se encontra ao nível da raiz da pasta do projeto da scene.

📔 Nota: O AudioSource component deve ser importado através de

import { AudioSource } from "@dcl/sdk/ecs"

Veja Imports para saber como lidar facilmente com estes casos.

O AudioSource.playSound() function recebe os seguintes argumentos:

• entity: Em que entity aplicar o som. O som será ouvido a partir da posição desta entity, o que significa que fica mais alto à medida que o player se aproxima.

• src: A localização do ficheiro de som dentro do teu projeto.

💡 Dica: Para maior clareza, recomendamos manter os teus ficheiros de som separados numa pasta assets/sounds dentro da tua scene.

• resetCursor: (opcional) Se for true, o som começa sempre do início. Caso contrário, continua a partir da posição atual do cursor. Útil para pausar e retomar.

Outra forma de tocar sons é criar manualmente um AudioSource component numa entity. Usa esta abordagem para teres mais controlo sobre o som, por exemplo para o fazer em loop ou definir o volume.

// Criar entity
const sourceEntity = engine.addEntity()

// Criar componente AudioSource
AudioSource.create(sourceEntity, {
	audioClipUrl: 'sounds/sound-effect.mp3',
	loop: true,
	playing: true,
})

As seguintes propriedades podem ser definidas:

• audioClipUrl: A localização do ficheiro de som dentro do teu projeto.

• playing: Se for true, o som começa a tocar. Podes criar um som com playing definido para false e, mais tarde, defini-lo para true.

• volume: (opcional) O volume do ficheiro de som. Por predefinição é 1, que corresponde ao volume máximo.

• pitch: (opcional) Modifica o pitch de um som. 1 é o valor predefinido; diminui-o para um som mais grave e aumenta-o para um som mais agudo.

💡 Dica: Para evitar que um efeito sonoro se torne demasiado repetitivo durante um jogo, é útil aleatorizar pequenas variações no pitch do som sempre que ele toca.

• currentTime: (opcional) 0 por predefinição. Define este valor para evitar começar do início do ficheiro de som.

Cada entity só pode ter um único AudioSource component, que só pode tocar um único clip de cada vez. Esta limitação pode ser facilmente contornada modificando a fonte de áudio no momento de tocar um novo som, ou incluindo múltiplas entities-filhas invisíveis, cada uma com o seu próprio som.

📔 Nota: Os sons são reproduzidos na instância local de cada player. Outros players próximos não ouvirão os mesmos sons, a menos que a sua scene local também os reproduza explicitamente.

Pré-carregar um Som

Se uma entity usar um som, mas este não for tocado imediatamente no runtime da scene, pode demorar algum tempo a transferir. Ele pode ficar disponível no runtime da scene usando o AssetLoad componente.

import { AssetLoad } from "@dcl/sdk/ecs"

AssetLoad.create(engine.RootEntity, {
  assets: [
    "assets/scene/bundle1/explosionSound.mp3",
  ],
})

Para mais informações, consulta a documentação de Pre Load Resources .

Parar sons

Para impedir que uma entity reproduza o seu som, usa a AudioSource.stopSound() function. Só precisas de especificar a entity, uma vez que cada entity tem um único AudioSource component, e cada AudioSource component reproduz um único ficheiro de cada vez.

AudioSource.stopSound(sourceEntity)

Outra forma de parar um som é definir a playing propriedade para false.

// Criar entity
const sourceEntity = engine.addEntity()

// Criar componente AudioSource
AudioSource.create(sourceEntity, {
	audioClipUrl: 'sounds/explosion.mp3',
	playing: true,
})

// Definir uma function simples
function stopSound(entity: Entity) {
	// obter a versão mutável do componente de fonte de áudio
	const audioSource = AudioSource.getMutable(entity)

	// modificar o seu valor playing
	audioSource.playing = false
}

// chamar function
stopSound(sourceEntity)

Looping

Para manter um som a tocar num loop contínuo, define o loop campo do AudioSource component para true antes de começares a reproduzi-lo.

// Criar entity
const sourceEntity = engine.addEntity()

// Criar componente AudioSource
AudioSource.create(sourceEntity, {
	audioClipUrl: 'sounds/sound-effect.mp3',
	playing: true,
	loop: true,
})

Tocar sons em loop é especialmente útil para adicionar música de fundo ou outros sons de fundo.

Definir volume

Podes definir a volume propriedade do AudioSource component para alterar o volume de um som.

O volume é expresso como um número de 0 a 1.

// Criar entity
const sourceEntity = engine.addEntity()

// Criar componente AudioSource
AudioSource.create(sourceEntity, {
	audioClipUrl: 'sounds/sound-effect.mp3',
	playing: true,
	volume: 0.5,
})

📔 Nota: Claro, o volume de um som também é afetado pela distância do player à fonte de áudio. À medida que o player se afasta, o volume será menor.

Sons globais

Por predefinição, todos os sons de um AudioSource são posicionais. Isto significa que parecem ser gerados a partir da posição do Transform component, e soarão mais alto à medida que o player se aproxima. Mas também podes configurar um som como global, para que o volume seja constante, independentemente de onde o player esteja. Isto é ideal para usar em música de fundo, sons de notificação e outros sons não posicionais.

📔 Nota: Global Sounds é uma feature apenas suportada no cliente desktop DCL 2.0.

Para tornar um som global, define a global propriedade para true.

AudioSource.create(sourceEntity, {
	audioClipUrl: 'sounds/music.mp3',
	playing: true,
	global: true,
})

Tocar um segmento de um som

Para tocar um segmento de um ficheiro de som mais longo, usa o playSoundSegment() na biblioteca SDK Utils. Vê SDK7 Utils.

Também podes conseguir isto ao definir explicitamente a currentTime propriedade num AudioSource component, e depois pará-lo após esperar um período de tempo.

Streaming de áudio

Veja Streaming de áudio para aprender como podes reproduzir um stream de áudio em direto a partir de uma source externa.

Análise de áudio

Veja Análise de áudio para aprender a ler dados de amplitude e frequência em tempo real a partir de um AudioSource e criar visuais reativos a partir disso, como cubos que pulsam com o baixo ou visualizadores de barras ao estilo equalizador.