# playSound3D (Cliente)

> Toca um som numa posição do mundo, só neste cliente. O volume cai com a distância entre `setSoundMinDistance` (5 m) e `setSoundMaxDistance` (20 m). Dispara `onClientSoundStarted` com `play`.

- **Plataforma**: MY Multiplayer (MYMP)
- **Tipo**: Função Lua
- **Lado**: Cliente
- **Categoria**: Som
- **URL**: https://wiki.mymp.gg/pt/playSound3D-client
- **Contraparte**: Também existe no servidor, com outra implementação: [playSound3D (Servidor)](https://wiki.mymp.gg/pt/playSound3D-server.md)

## Sintaxe

```lua
sound|false playSound3D(string sound, float x, y, z [, bool looped = false, bool throttled = true])
```

## Parâmetros

| Nome | Tipo | Descrição |
| --- | --- | --- |
| `sound` | `string` | Um nome registrado com `engineAddSound`, o caminho de um arquivo do recurso (`@outro/arquivo.mp3` para outro recurso) ou os próprios bytes de um arquivo de áudio. |
| `x, y, z` | `float` | Posição do som no mundo, em três números ou um `vec3`. |
| `looped` | `bool` | Repetir o som quando ele chega ao fim. *(padrão: `false`)* |
| `throttled` | `bool` | Aceito por compatibilidade com o MTA e ignorado. *(padrão: `true`)* |

## Retorno

O elemento `sound` criado, ou `false` se o som não pôde ser aberto.

O som sai de alcance (`onClientElementStreamOut`) quando a câmera fica a mais de 40 m além da distância máxima ou quando está em outra dimensão, e volta (`onClientElementStreamIn`) a menos de 20 m dela.

## Exemplo

```lua
local pos = getElementPosition(localPlayer)
local radio = playSound3D("sounds/radio.ogg", pos, true)
setSoundMaxDistance(radio, 40)
```

### Vindo do MTA

Endereços de internet (`http`, `ftp`) não são aceitos. Outro recurso é indicado com `@recurso/`, e não com `:recurso/`.

## Veja também

- [playSound (Cliente)](https://wiki.mymp.gg/pt/playSound-client.md): Toca um som sem posição no mundo, só neste cliente. Dispara onClientSoundStarted com o motivo play.
- [setSoundMaxDistance (Compartilhado)](https://wiki.mymp.gg/pt/setSoundMaxDistance.md): Define a partir de que distância um som 3D fica mudo. O padrão é 20 m. No servidor, a mudança é enviada a todos os clientes.
- [setSoundSpeaker (Cliente)](https://wiki.mymp.gg/pt/setSoundSpeaker.md): Faz um ped falar um som: a boca dele se mexe com o volume do som e, se o som é 3D, ele sai da cabeça do ped a cada quadro.
- [playSound3D (Servidor)](https://wiki.mymp.gg/pt/playSound3D-server.md): Cria um som numa posição do mundo que todos os clientes tocam juntos. As mudanças feitas nele no servidor chegam a todos.