| name | creating-godot-procedural-audio |
| description | Designs and implements procedural audio for Godot games. Use when creating runtime SFX with Godot built-in audio APIs, mapping game events to timbre, or avoiding external audio assets. |
Use this skill for Godot game audio that is synthesized or generated inside the project.
Default artifacts:
- If a project directory is known, put the full audio plan in
<PROJECT_DIR>/SOUND_DESIGN.md.
- If the project README has a
Visual And Audio Direction or Required sounds section, keep it as a short summary and update it only when the audio direction changes.
- Implement through a small project-specific module such as
<PROJECT_DIR>/audio_controller.gd; keep main.gd as orchestration.
- Reuse
.agents/skills/creating-godot-procedural-audio/assets/audio_synth.gd or the template's existing audio_synth.gd primitives. Copy the helper into the project only if it is missing or materially different.
- If visual tags are project-specific or concept-derived rather than exact guide entries, map them by nearest material, geometry, motion, or atmosphere family and record that mapping in
SOUND_DESIGN.md.
- Continuous sounds should expose a minimal control surface:
start_<sound>(), update_<sound>(params), release_<sound>(), and stop_<sound>(). Headless/no-op handles must preserve the same calls so tests can verify state transitions without playback.
Core rules:
- Use Godot built-in audio only; avoid external audio files unless the project explicitly allows them.
- Keep event families semantically stable within a game: score, danger, damage, and state change should have distinct timbral identities.
- Vary waveform, pitch range, envelope, modulation, rhythm, and density between games instead of reusing a global beep vocabulary.
- Continuous sounds need explicit start, stop, and release behavior.
- Prefer simple generated sample streams when possible; use
AudioStreamGenerator when real-time synthesis is required.
Workflow:
- Derive sound character from the visual direction and mechanics.
- Choose 1-2 base waveforms plus a modulation method.
- Define event-to-timbre mappings.
- Link dynamic parameters (combo / speed / danger / difficulty) so they audibly modulate at least one event, not just the score number.
- Implement through a small audio responsibility module.
Read references/sound-design-guide.md for event catalogues, procedural audio patterns, and design checklists.
Reusable primitives are in assets/audio_synth.gd.
Companion skills
directing-game-visuals produces <PROJECT_DIR>/VISUAL_DESIGN.md, which sound character should derive from.scaffolding-godot-mini-games ships the template audio_synth.gd referenced above; copy this skill's assets/audio_synth.gd only when no template copy exists in the project.
