> For the complete documentation index, see [llms.txt](https://studio-docs.sandbox.game/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://studio-docs.sandbox.game/the-editor/how-to-set-up-sound.md).

# How to set up sound

Audio in the scene is a **file**, then a **Sound Node**. Import a clip under `assets/sounds/`. Add a **Sound Node** (`ENGINE.SoundNode`). Point a sound resource on that node at the file with a fully qualified path: `@project/assets/sounds/...`.

That is the same pattern as VFX: the file is not in the world until a node plays it. See [How to set up VFX](/the-editor/how-to-set-up-vfx.md).

Pickups can play a clip without a Sound Node. Set `pickupSoundUrl` (and optional `pickupVolume`, `pickupMaxDistance`) on the pickup. See [Doors, switches, pickups and triggers](/the-editor/doors-switches-pickups-and-triggers.md).

Keep logical extensions in paths (for example `.wav`). The [Asset Compiler](/the-editor/how-to-use-asset-compiler.md) can compress audio for Play (engine remap example: WAV → OGG). Do not retarget those paths by hand.

## File vs Sound Node

| Thing                      | What it is                                  | How you get one                            |
| -------------------------- | ------------------------------------------- | ------------------------------------------ |
| Audio file                 | A clip on disk (`assets/sounds/`)           | Import into the Asset panel                |
| Sound resource on the node | Name, `audioPath`, volume, spatial falloff  | Entries on the Sound Node (`sounds`)       |
| Sound Node                 | Scene node that loads and plays those clips | Outliner plus → Component → **Sound Node** |

`positional` **off** — the clip is global (UI, music bed on a node).\
`positional` **on** — the clip is 3D. Place or parent the node; `refDistance`, `maxDistance`, `distanceModel`, and `rolloffFactor` on the resource control falloff.

`loop` — repeat.\
`autoPlay` — play when Play mode starts (`beginPlay`). Uses the first resource, or `autoPlayClipKey` if that name exists.\
`bus` — defaults to `SFX`.

Music, voice-over, and pooled combat one-shots in a large game often run from TypeScript against `@project/assets/sounds/...` instead of many Sound Nodes. That is a code catalog, not this placement workflow.

{% stepper %}
{% step %}

## Import the clip

In the Asset panel, open or create `sounds/`, then add your file. Convention is `assets/sounds/`.
{% endstep %}

{% step %}

## Add a Sound Node

Select the plus button in the Outliner, choose Component, and add **Sound Node**.
{% endstep %}

{% step %}

## Add a sound resource and set the path

Select the Sound Node. Add an entry to its sounds list. Set `name` (the key you play in code). Set `audioPath` to `@project/assets/sounds/your-clip.wav` (or the file you imported).

Set `volume` between 0 and 1.
{% endstep %}

{% step %}

## Choose global or 3D

Leave `positional` off for a global clip.

Turn `positional` on for a world source. Move the node (or parent it to a mesh). Tune Spatial fields on the resource: `refDistance`, `maxDistance`, `distanceModel` (`inverse`, `linear`, or `exponential`), `rolloffFactor`.
{% endstep %}

{% step %}

## Autoplay or play from code

Turn `loop` on for a repeating bed. Turn `autoPlay` on to start in Play mode.

To start a clip from gameplay, find the node and call `play` with the resource `name`:

```typescript
const sound = this.getNode(ENGINE.SoundNode);
await sound?.play('your-clip-key');
```

The browser may keep the audio context suspended until the player clicks or taps. Play after that interaction if a clip is silent on first load.
{% endstep %}
{% endstepper %}

## Common mistakes

| What went wrong                             | What to do                                                                                                                                      |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Imported a file and heard nothing           | Add a **Sound Node** and set `audioPath`. The file is not a scene object.                                                                       |
| Expected a pickup to use the Sound Node     | Pickups use `pickupSoundUrl` on the pickup.                                                                                                     |
| 3D clip plays at full volume everywhere     | Turn `positional` on and set `maxDistance` / `refDistance`.                                                                                     |
| Path points at a baked `.ogg` after compile | Keep the logical source path (`.wav` or whatever you imported).                                                                                 |
| Changed the `.genesys-scene` to add audio   | Place the node in the editor, or ask the agent through [Sandbox Studio MCP](/working-efficiently-with-ai/set-up-and-use-sandbox-studio-mcp.md). |

## What You've Done

You can import a clip, attach it to a Sound Node, play it globally or in 3D, and autoplay in Play mode. Next: [How to set up VFX](/the-editor/how-to-set-up-vfx.md) for the same file-then-node pattern, or [How to Set Up a Prefab](/the-editor/how-to-set-up-a-prefab.md) if the sound should travel with a mesh.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://studio-docs.sandbox.game/the-editor/how-to-set-up-sound.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.