---
title: "Audio sound effects music and positional feedback"
description: "The game needs to be heard: a coin chime, a footstep, a hit thud, looping ambience, or background music. `AudioEmitterComponent` is the one audio primitive; scripts trigger and control it."
engineVersion: v1.0.234
date: 2026-09-28
license: "(c) Gessa, proprietary. Cite with attribution to https://gessa.ai/docs/. Terms: https://gessa.ai/terms/."
canonical: https://gessa.ai/docs/knowledge/playbooks/audio-feedback/
---

# Audio sound effects music and positional feedback

## When to use

The game needs to be heard: a coin chime, a footstep, a hit thud, looping
ambience, or background music. `AudioEmitterComponent` is the one audio
primitive; scripts trigger and control it.

## The recipe

1. Attach `AudioEmitterComponent` to the sounding entity with
   `project_add_component` (`project.entity.component.set`):
   `{ "type":"AudioEmitterComponent", "soundAssetId": <audio asset id>,
   "volume": 1, "pitch": 1, "loop": false, "spatial": true, "rolloff":"inverse",
   "refDistance": 1, "maxDistance": 32, "playOnStart": false, "enabled": true }`.
2. Positional vs global: `spatial: true` makes the sound attenuate with distance
   (`rolloff` is `linear`, `inverse`, or `exponential`; `refDistance` and
   `maxDistance` shape falloff). `spatial: false` is a flat UI/music sound.
3. Play on spawn with `playOnStart: true` (looping ambience), or trigger from a
   script. In a GessaScript body (`replaceScriptFromGessaScript`) call
   `ctx.audio.play` (one-shot on this entity), `ctx.audio.playSpatial` (at a
   world point), `ctx.audio.setBackgroundMusic` (the music bed),
   `ctx.audio.setVolume`, and `ctx.audio.stop`.
4. Event-driven SFX: give a pickup or hazard its emitter, and fire
   `ctx.audio.play` from the trigger/action handler that already runs the
   gameplay effect (see collectibles-and-scoring, combat-damage-and-respawn).
5. Target another entity's emitter with `targetEntityId` when one controller
   should sound off a different source.

## Pitfalls

- `soundAssetId` is optional in the schema but nothing plays without it; set a
  real audio asset id (prefer the catalog first, see asset-acquisition-strategy).
- `volume` is 0..1, `pitch` and `refDistance`/`maxDistance` are `> 0`
  (min 0.01); values outside the range fail validation.
- The default `enabled` is `false` and `playOnStart` is `false`; set both true
  for ambient loops that should start on their own.
- Audio is not the renderer: a silent emitter is usually a missing asset or a
  worker-host audio gap, not a render issue. Confirm the asset id resolves.
- There is no `AudioListenerComponent` to attach; it is a roadmap name, not a
  shipped component.

## Verify

- `engine_get_component_schema` on `AudioEmitterComponent` for the `rolloff`
  enum and numeric bounds.
- `simulation_run` (`qa.run.start`) to confirm the emitter triggers on the
  intended event.