Som

O áudio de script do MTAX roda inteiramente do lado do jogador. Você toca um arquivo do próprio resource ou uma URL de streaming, recebe de volta um elemento do tipo sound e usa esse elemento em todas as outras funções desta página.

São dois modos de reprodução. O 2D toca sempre no mesmo volume, direto nos alto-falantes — é o que você quer para música de menu, avisos e efeitos de interface. O 3D ancora o som num ponto do mundo: o ouvinte é a câmera, e o volume cai conforme ela se afasta desse ponto.

Quase toda função desta página recebe um som como primeiro argumento. Se você passar algo que não é um som vivo, ou um argumento do tipo errado, a função devolve false e registra um aviso no console de debug — ela não interrompe o script. As exceções são setSoundLooped, isSoundLooped e showSound, que levantam um erro Lua para um argumento inválido.

Muitas dessas funções também aceitam um jogador no lugar do som: elas passam a agir sobre o chat de voz que você ouve desse jogador. O jogador local sempre tem voz; um jogador remoto, só enquanto o chat de voz está ligado. Para um jogador sem voz a função devolve false.

Estas 42 funções existem somente no cliente. Chamá-las de um script de servidor resulta em erro de valor nulo.

O ciclo de vida de um som

Todo som segue o mesmo caminho: uma função play* cria, as funções set* controlam e stopSound destrói. O arquivo precisa estar declarado em files no manifesto para chegar até o jogador.

-- criar
local musica = playSound("sons/tema.mp3", true)   -- em loop

if not musica then
    outputDebugString("nao consegui tocar o tema")
    return
end

-- controlar
setSoundVolume(musica, 0.4)

addCommandHandler("pausar", function()
    setSoundPaused(musica, not isSoundPaused(musica))
end)

addCommandHandler("recomecar", function()
    setSoundPosition(musica, 0)
end)

-- destruir
addCommandHandler("parar", function()
    stopSound(musica)
    musica = nil
end)

Nota

Um som que não está em loop é destruído sozinho quando chega ao fim, junto com o elemento que o representa. Guarde o elemento numa variável se precisar dele depois, mas confira com isElement antes de reutilizá-lo. Todos os sons de um resource são interrompidos quando ele para, e destroyElement sobre um elemento de som tem o mesmo efeito que stopSound.

Reprodução em 2D

playSound Toca um arquivo de áudio do resource ou uma URL de streaming, sem posição no mundo.

playSFX Toca um som dos bancos de áudio do jogo.

getSFXStatus Verifica se um container de áudio do jogo está utilizável.

stopSound Para um som e destrói o elemento correspondente.

Reprodução em 3D

Num som 3D o ouvinte é sempre a câmera. Dentro da distância mínima o som toca no volume cheio; entre a mínima e a máxima ele decai progressivamente; além da máxima fica em silêncio. A direção da câmera também distribui o som entre os canais esquerdo e direito, a menos que você desligue isso com setSoundPanningEnabled.

playSound3D Toca um arquivo de áudio do resource ou uma URL de streaming num ponto fixo do mundo.

playSFX3D Toca um som dos bancos de áudio do jogo num ponto fixo do mundo.

setSoundMinDistance Define o raio dentro do qual um som 3D toca no volume cheio.

getSoundMinDistance Devolve o raio de volume cheio de um som 3D.

setSoundMaxDistance Define a distância a partir da qual um som 3D deixa de ser ouvido.

getSoundMaxDistance Devolve a distância de corte de um som 3D.

setSoundPanningEnabled Liga ou desliga o posicionamento estéreo automático de um som 3D.

isSoundPanningEnabled Verifica se o posicionamento estéreo automático está ligado.

Controle de reprodução

setSoundPaused Pausa ou retoma um som.

isSoundPaused Verifica se um som está pausado.

setSoundLooped Define se um som recomeça sozinho ao terminar.

isSoundLooped Verifica se um som está em loop.

setSoundPosition Salta para um ponto do som, em segundos.

getSoundPosition Devolve quanto do som já foi tocado, em segundos.

getSoundLength Devolve a duração total do som, em segundos.

Volume, pan e pitch

setSoundVolume Define o volume de um som.

getSoundVolume Devolve o volume configurado de um som.

setSoundPan Distribui um som 2D entre os canais esquerdo e direito.

getSoundPan Devolve o pan de um som 2D.

setSoundSpeed Define a velocidade de reprodução.

getSoundSpeed Devolve a velocidade de reprodução.

setSoundProperties Ajusta taxa de amostragem, tempo, tom e sentido da reprodução de uma só vez.

getSoundProperties Devolve as quatro propriedades ajustadas por setSoundProperties.

Efeitos

Cada som tem nove espaços de efeito, um por nome. Ligue o efeito com setSoundEffectEnabled e só depois ajuste os parâmetros dele — ler ou escrever parâmetros de um efeito desligado devolve false.

Nomes de efeito

Nome
"chorus"
"compressor"
"distortion"
"echo"
"flanger"
"gargle"
"i3dl2reverb"
"parameq"
"reverb"

setSoundEffectEnabled Liga ou desliga um efeito num som.

getSoundEffects Lista o estado de todos os efeitos de um som.

setSoundEffectParameter Ajusta um parâmetro de um efeito já ligado.

getSoundEffectParameters Devolve todos os parâmetros de um efeito ligado.

Parâmetros dos efeitos

Nas tabelas abaixo, decimal aceita qualquer número, inteiro aceita qualquer número e descarta a parte fracionária, e bool aceita apenas true ou false. Passar um booleano para um parâmetro numérico, ou um número para um booleano, devolve false.

chorus

Parâmetro	Tipo
wetDryMix	decimal
depth	decimal
feedback	decimal
frequency	decimal
waveform	inteiro
delay	decimal
phase	inteiro

compressor

Parâmetro	Tipo
gain	decimal
attack	decimal
release	decimal
threshold	decimal
ratio	decimal
predelay	decimal

distortion

Parâmetro	Tipo
gain	decimal
edge	decimal
postEQCenterFrequency	decimal
postEQBandwidth	decimal
preLowpassCutoff	decimal

echo

Parâmetro	Tipo
wetDryMix	decimal
feedback	decimal
leftDelay	decimal
rightDelay	decimal
panDelay	bool

flanger

Parâmetro	Tipo
wetDryMix	decimal
depth	decimal
feedback	decimal
frequency	decimal
waveform	inteiro
delay	decimal
phase	inteiro

gargle

Parâmetro	Tipo
rateHz	inteiro
waveShape	inteiro

i3dl2reverb

Parâmetro	Tipo
room	inteiro
roomHF	inteiro
roomRolloffFactor	decimal
decayTime	decimal
decayHFRatio	decimal
reflections	inteiro
reflectionsDelay	decimal
reverb	inteiro
reverbDelay	decimal
diffusion	decimal
density	decimal
HFReference	decimal

parameq

Parâmetro	Tipo
center	decimal
bandwidth	decimal
gain	decimal

reverb

Parâmetro	Tipo
inGain	decimal
reverbMix	decimal
reverbTime	decimal
highFreqRTRatio	decimal

Streams

Um som criado a partir de uma URL é um stream. A conexão acontece em segundo plano, então logo após playSound o som ainda pode não ter dados: getSoundLength devolve 0 por alguns instantes e o áudio começa quando o buffer enche.

Streams têm algumas limitações próprias — não aceitam setSoundProperties, e um stream ao vivo sem duração conhecida não pode ser posicionado com setSoundPosition. getSoundBPM só responde depois que tocou o bastante do stream para medir.

getSoundBufferLength Devolve quanto de um stream já foi baixado, em segundos.

Análise e metadados

getSoundFFTData Devolve o espectro de frequências do som naquele instante.

getSoundWaveData Devolve uma janela da forma de onda do som naquele instante.

getSoundLevelData Devolve o nível atual de cada canal.

getSoundBPM Devolve as batidas por minuto de um som.

getSoundMetaTags Lê as tags de um arquivo ou de um stream.

Rádio

setRadioChannel Troca a estação de rádio do jogador.

getRadioChannel Devolve a estação de rádio atual.

getRadioChannelName Devolve o nome de uma estação.

Diagnóstico

showSound Liga ou desliga o modo de depuração de som.

isShowSoundEnabled Verifica se o modo de depuração de som está ligado.