Sons

Aprenda como adicionar sons à sua cena.

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

📔 Nota: Tenha em mente que os sons são ouvidos apenas pelos jogadores que estão parados dentro dos terrenos (parcels) que compõem a cena onde o som foi gerado, mesmo que, de outra forma, estivessem dentro do alcance auditivo. Os jogadores também podem optar por desligar todos os sons nas configurações.

Os formatos de som suportados variam conforme o navegador, mas é recomendado usar .mp3.

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

Tocar sons

A maneira mais fácil de tocar um som é adicionar um Audio Source componente visualmente no Scene Editor in Creator Hub e configurá-lo para Start Playing e Loop. Veja Add Components.

Você também pode acionar a reprodução de um som de forma no-code via Actions, veja Make any item smart.

Para tocar um som via código, use a função AudioSource.playSound function.

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

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

O arquivo de som deve estar dentro da pasta do projeto. No exemplo acima, o arquivo de áudio está localizado em uma assets/sounds pasta, que está localizada no nível raiz da pasta do projeto da cena.

📔 Nota: O AudioSource componente deve ser importado via

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

Veja Imports para saber como lidar com isso facilmente.

A AudioSource.playSound() função aceita os seguintes argumentos:

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

• src: A localização do arquivo de som dentro do seu projeto.

💡 Dica: Para maior clareza, recomendamos manter seus arquivos de som separados em uma assets/sounds pasta dentro da sua cena.

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

Outra maneira de tocar sons é criar manualmente um componente AudioSource em uma entidade. Use essa abordagem para ter mais controle sobre o som, por exemplo, para fazê-lo em loop ou ajustar o volume.

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

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

As seguintes propriedades podem ser definidas:

• audioClipUrl: A localização do arquivo de som dentro do seu projeto.

• playing: Se true, o som começa a tocar. Você pode criar um som com playing set to false, and then set it to true at a later time.

• volume: (optional) O volume do arquivo de som. 1 por padrão, que é volume total.

• pitch: (optional) Modifica o pitch (altura) de um som. 1 é o padrão; diminua para um som mais grave e aumente para um som mais agudo.

💡 Dica: Para evitar que um efeito sonoro se torne muito repetitivo durante um jogo, é útil randomizar pequenas variações no pitch do som a cada vez que ele toca.

• currentTime: (optional) 0 por padrão. Defina esse valor para evitar começar desde o início do arquivo de som.

Cada entidade pode ter apenas um único AudioSource componente, que só pode reproduzir um único clipe por vez. Essa limitação pode ser facilmente contornada modificando a fonte de áudio no momento de reproduzir um novo som, ou incluindo múltiplas entidades filhas invisíveis, cada uma com seu próprio som.

📔 Nota: Os sons são reproduzidos na instância local de cada jogador. Outros jogadores próximos não ouvirão os mesmos sons a menos que a cena local deles também os reproduza explicitamente.

Pré-carregando um som

Se uma entidade usa um som, mas ele não é reproduzido imediatamente em tempo de execução da cena, pode levar algum tempo para fazer o download. Ele pode estar disponível em tempo de execução da cena usando o AssetLoad componente.

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

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

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

Parando sons

Para interromper a reprodução de som de uma entidade, use a função AudioSource.stopSound() . Você só precisa especificar a entidade, já que cada entidade tem um único AudioSource componente, e cada AudioSource componente reproduz um único arquivo por vez.

AudioSource.stopSound(sourceEntity)

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

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

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

// Define a simple function
function stopSound(entity: Entity) {
	// fetch mutable version of audio source component
	const audioSource = AudioSource.getMutable(entity)

	// modify its playing value
	audioSource.playing = false
}

// call function
stopSound(sourceEntity)

Looping

Para manter um som tocando em loop contínuo, defina o campo loop do AudioSource componente para true antes de começar a reproduzi-lo.

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

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

Sons em loop são especialmente úteis para adicionar música de fundo ou outros sons de ambientação.

Ajustar volume

Você pode definir a propriedade volume do AudioSource componente para alterar o volume de um som.

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

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

// Create AudioSource component
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 jogador à fonte de áudio. À medida que o jogador se afasta, o volume será menor.

Sons globais

Por padrão, todos os sons de um AudioSource são posicionais. Isso significa que eles parecem originar-se da posição do componente Transform , e soarão mais altos à medida que o jogador se aproxima. Mas você também pode configurar um som para ser global, de modo que o volume seja constante, não importando onde o jogador esteja parado. Isso é ideal para música de fundo, sons de notificação e outros sons não posicionais.

📔 Nota: Global Sounds é um recurso suportado apenas no cliente desktop DCL 2.0.

Para tornar um som global, defina a propriedade global 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 arquivo de som mais longo, use o playSoundSegment() na biblioteca SDK Utils. Veja SDK7 Utils.

Você também pode conseguir isso definindo explicitamente a propriedade currentTime em um AudioSource componente, e então parando-o após aguardar um período de tempo.

Streaming de áudio

Veja Streaming de áudio para saber como você pode reproduzir uma transmissão de áudio ao vivo a partir de uma fonte externa.