# gd-dynamic-sound

A Godot 4 audio addon for **dynamic music** (intensity-layered, seamless playlist transitions, fade in/out) and **overlapping one-shot SFX** — both built on `AudioStreamPolyphonic`.

## Installation

1. Copy the `addons/gd-dynamic-sound/` folder into your project's `addons/` directory.
2. Enable the plugin in **Project Settings → Plugins**.
3. *(Optional, recommended)* Wire up the `Music` and `FX` buses — see below.

## Audio buses

When a player enters the tree in the editor, it auto-routes to a named bus if one exists:

- `DynamicSoundPlayer` family → looks for a bus named **`Music`**
- `DynamicSoundFXPlayer` family → looks for a bus named **`FX`**

If the named bus doesn't exist, the player stays on `Master`. User-customised buses are never overridden — the auto-route only fires when `bus` is still the default `Master`.

A ready-made layout containing both buses (each routing into `Master`) ships with the addon at `addons/gd-dynamic-sound/default_bus_layout.tres`. To use it:

- **Whole-project replacement:** copy it to your project root as `default_bus_layout.tres`, or point Godot at the addon's copy via **Project Settings → General → Audio → Buses → Default Bus Layout**.
- **Merge into an existing layout:** open Godot's audio bus panel and add `Music` and `FX` buses manually, both sending to `Master`.

## Concepts

### `DynamicSound` (Resource)

A single piece of audio with up to three intensity layers that play simultaneously and are blended at runtime.

| Property | Type | Description |
| --- | --- | --- |
| `Intensity1` | `AudioStream` | Least-intense layer (e.g. ambient). Required for length tracking. |
| `Intensity2` | `AudioStream` | Mid-intensity layer. Optional. |
| `Intensity3` | `AudioStream` | Most-intense layer. Optional. |
| `ReverbTail` | `float` | Length (seconds) of the song's reverb tail, used for seamless looping. |

### `DynamicSoundPlaylist` (Resource)

An ordered list of `DynamicSound`s.

| Property | Type | Description |
| --- | --- | --- |
| `QueuedSongs` | `Array[DynamicSound]` | Songs to play in order. The continuous player pops songs off the front as each finishes. |

## Nodes

Two node families, each with three positional variants:

| Family | Non-positional | 2D | 3D |
| --- | --- | --- | --- |
| Continuous music | `DynamicSoundPlayer` | `DynamicSoundPlayer2D` | `DynamicSoundPlayer3D` |
| One-shot SFX | `DynamicSoundFXPlayer` | `DynamicSoundFXPlayer2D` | `DynamicSoundFXPlayer3D` |

The 2D variants apply distance attenuation from a 2D position. The 3D variants are fully spatialised — distance, directionality, and Doppler.

### `DynamicSoundPlayer` family — continuous music

Plays through a playlist one song at a time, blending three intensity layers per song.

#### Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `Playlist` | `DynamicSoundPlaylist` | `null` | Songs to play in order. Mutated as songs finish. |
| `Intensity` | `float` (0–1) | `0` | Runtime mix between the three layers. `0` = layer 1 dominates, `1` = layer 3 dominates. |
| `Loop` | `bool` | `false` | When true, finished songs are re-queued at the back so the playlist cycles forever. |

When the node enters the tree in the editor, `stream` is auto-assigned an `AudioStreamPolyphonic` and `bus` is set to `"Music"` if a bus by that name exists in the project (otherwise it's left at `"Master"`). User-customised buses are not overridden.

#### Methods

| Method | Description |
| --- | --- |
| `pause()` | Pauses playback. No-op if not playing or already paused. |
| `resume()` | Resumes playback after a pause. |
| `is_song_playing() -> bool` | True iff a song's layers are active and not paused. Distinct from `is_playing()`, which stays true between songs because the polyphonic playback session itself is still live. |
| `fade_in(duration: float)` | Starts playback (if needed), unpauses, and ramps volume from silent to `volume_db` over `duration` seconds. |
| `fade_out(duration: float)` | Ramps volume from current level to silent over `duration` seconds, then stops the polyphonic session. A subsequent `fade_in` reinitialises. |

#### Behaviour

- **Autoplay.** On `_ready`, plays the front song of the playlist.
- **Advancement.** When a song's `Intensity1` length elapses, the player pops it from the queue and plays the next. With `Loop = true`, the popped song is re-appended to the back.
- **Volume.** `volume_db` is honoured; the fade adjustment is layered on top internally, so manual volume changes during a fade still work correctly.
- **Editor.** All scripts are `@tool`, but `_ready` and `_process` early-return in the editor so audio doesn't play in the inspector.

### `DynamicSoundFXPlayer` family — overlapping one-shot SFX

Each `play_fx()` call fires a fresh trigger of the assigned `DynamicSound`. Triggers overlap freely — the underlying `AudioStreamPolyphonic` cleans up each trigger when its audio ends.

#### Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `Sound` | `DynamicSound` | `null` | The sound to trigger. Layers with intensity blending if all three are set. |
| `Intensity` | `float` (0–1) | `0` | Volume mix between layers. Only blended when all three layers are present; otherwise the first non-null layer plays at full volume. |
| `PitchMode` | enum | `Constant` | `Constant` plays each trigger at pitch `1.0`. `Random` picks a fresh pitch per trigger via `1.0 + randf_range(RandomMinPitchScale, RandomMaxPitchScale)`. |
| `RandomMinPitchScale` | `float` | `-0.5` | Minimum pitch offset (added to `1.0`) when `PitchMode = Random`. Hidden in the inspector when `PitchMode = Constant`. |
| `RandomMaxPitchScale` | `float` | `0.5` | Maximum pitch offset (added to `1.0`) when `PitchMode = Random`. Hidden in the inspector when `PitchMode = Constant`. |

When the node enters the tree in the editor, `stream` is auto-assigned an `AudioStreamPolyphonic` and `bus` is set to `"FX"` if a bus by that name exists in the project (otherwise it's left at `"Master"`). User-customised buses are not overridden.

For a *constant non-1.0* pitch, set the player's built-in `pitch_scale` property — that multiplies with whatever `PitchMode` produces, so e.g. `pitch_scale = 0.8` + `PitchMode = Random` with default range gives an effective pitch in `[0.4, 1.2]`.

#### Methods

| Method | Description |
| --- | --- |
| `play_fx()` | Triggers a fresh play of `Sound`. Pitch is sampled at trigger time per `PitchMode`. Volumes are computed at trigger time and locked in — later changes to `Intensity` or `volume_db` don't affect already-playing triggers. |

#### Example: collision SFX

```gdscript
@onready var fire_fx : DynamicSoundFXPlayer2D = $FireFX

func _on_body_entered(body) -> void:
    fire_fx.play_fx()
```

## Architecture

The six player classes are thin wrappers (~70 lines each) around two shared `RefCounted` cores:

- `DynamicSoundPlayerCore` — continuous-music logic (advancement, fades, pause, intensity blending).
- `DynamicSoundFXPlayerCore` — one-shot trigger logic.

Each wrapper declares its exports, sets up a core in `_ready`, and forwards public methods. The cores access their owner via duck-typed property lookups (`_player.Playlist`, `_player.volume_db`, etc.), which is what lets the same core drive non-positional, 2D, and 3D wrappers without inheritance.

## Honourable mentions

This addon was heavily inspired by the Ovani Plugin 1.4. Please consider supporting [OvaniSound](https://ovanisound.com) — these players are designed to drive their dynamic sounds.