Audio sound effects music and positional feedback

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.