Initial commit

addons/resonate/docs/getting-started.md

@@ -0,0 +1,78 @@
+# Getting started
+
+Godot provides a simple and functional audio engine with all the raw ingredients. However, it leaves it up to you to decide how to organise, manage and orchestrate audio in your projects.
+
+**Resonate** is an *audio manager* designed to fill this gap, providing both convenient and flexible ways to implement audio more easily in Godot. 
+
+## Installation
+
+Once you have downloaded Resonate into your project `addons/` directory, open **Project > Project Settings** and go to the **Plugins** tab. Click on the **Enable** checkbox to enable the plugin.
+
+It's good practice to reload your project to ensure freshly installed plugins work correctly. Go to **Project > Reload Current Project**.
+
+Resonate has two core systems: the **SoundManager** and the **MusicManager** which are available as global singletons (Autoload). You can confirm if these are available and enabled under **Project > Project Settings > Autoload**.
+
+The `SoundManager` and `MusicManager` will now be available from any GDScript file. However, Resonate needs to initialise and load properly, so you should be aware of the [script execution order](#script-execution-order).
+
+## Concepts
+
+The following concepts explain how the various components of Resonate work together.
+
+**Sound** (one-shots, sound effects, dialogue) is managed differently compared to **Music.** This is why Resonate comprises of two core systems: the `SoundManager` and `MusicManager`.
+
+### Sound
+
+A **SoundEvent** is any sound that can be triggered, controlled and stopped from code. Anything in your game that produces a sound will need an equivalent SoundEvent. Instead of playing an AudioStream directly, you trigger events in response to gameplay and Resonate takes care of the rest. Events are made up of one or more AudioStreams which are treated as variations to be played at random when the event is triggered, e.g. triggering a "footsteps" event plays one of several pre-recorded variations to add variety and realism to your sound design. You can add as many variations to an event as you need. Using an event name means you have a consistent reference used to trigger sounds, but can easily update the AudioStream files associated with each event independently.
+
+A **SoundBank** is a collection of SoundEvents. As your project grows, SoundBanks help you organise related sound events such as "dialogue" or "impacts" sound effects into groups. You can have as many SoundBanks as you want or need to keep your project organised in a way that suits your game's architecture. Banks also act a little bit like a namespace, e.g. creating separate "player" and "npc" SoundBanks allows you to trigger a "death" dialogue sound event from either bank without name collisions.
+
+### Music
+
+A **MusicTrack** is a piece of music comprised of one or more **Stems**. By default, tracks will fade in/out when played or stopped, and this fade time can be configured. If you play a MusicTrack when another is already playing, the two tracks will be cross-faded so that the new track takes over.
+
+Layers of a MusicTrack are called **Stems**, which typically represent different instruments or mix busses, e.g. "drums", "bass", "melody". This allows for stems to be enabled and disabled independently. By default, stems fade in/out and this fade time can be configured. Care should be taken to ensure Stems are set to loop (see import settings) and that they are either all of the same length or a measure division that enables them to loop in sync with each other. Stems can be used like layers in order to create a dynamic and changing composition. In the context of sound design for games this is sometimes referred to as *vertical composition*. As an example, you could enable a "drums" stem in response to an increase in gameplay tension, then disable it when the tension dissipates.
+
+A **MusicBank** is a collection of MusicTracks. As your project grows, MusicBanks help you organise related music tracks into groups. You can have as many MusicBanks as you want or need to keep your project organised in a way that suits your game's architecture. Banks also act a little bit like a namespace, e.g. creating separate MusicBanks for distinct levels or areas in your game world allows you to name and trigger an "ambient" or "combat" music track from either bank without name collisions. This can help you standardise how you integrate with other game systems, or simply organise audio with a consistent labelling schema.
+
+## Script execution order
+
+Resonate needs to initialise `PooledAudioStreamPlayers` and search the entire scene/node tree for every `SoundBank` and `MusicBank`. This process requires at least one game tick to complete.
+
+Therefore, to immediately trigger sounds or music upon your game's launch, you need to subscribe to the relevant `loaded` signal. The following concepts apply to both the `SoundManager` and `MusicManager`:
+
+```GDScript
+func _ready() -> void:
+	MusicManager.loaded.connect(on_music_manager_loaded)
+	
+func on_music_manager_loaded() -> void:
+	MusicManager.play("boss_fight")
+```
+
+You can also perform a safety check to ensure `MusicManager.has_loaded` is true before a function call.
+
+## Scene changes & runtime node creation
+
+Resonate will scan the scene tree for all music and sound banks when your game launches, which it uses internally to create lookup tables. It will also automatically update those tables whenever a node is inserted or removed from the scene tree. If you load a script at runtime attempting to use either the MusicManager or SoundManager, you can leverage the `updated` signal to ensure you're ready to play music or trigger sound events without issues:
+
+```GDScript
+var _instance_jump: PooledAudioStreamPlayer = SoundManager.null_instance()
+
+func _ready():
+	SoundManager.updated.connect(on_sound_manager_updated)
+
+func _input(p_event: InputEvent) -> void:
+	if p_event.is_action_pressed("jump"):
+		_instance_jump.trigger()
+
+func on_sound_manager_updated() -> void:
+	if SoundManager.should_skip_instancing(_instance_jump):
+		return
+	
+	_instance_jump = SoundManager.instance("player", "jump")
+
+	SoundManager.release_on_exit(self, _instance_jump)
+```
+
+## Digging deeper
+
+To understand the music or sound managers in more detail, view examples of setting up banks, or inspect their corresponding APIs, check out the dedicated [MusicManager](music-manager.md) or [SoundManager](sound-manager.md) documentation.

addons/resonate/docs/images/add-music-bank-node.jpg.import

@@ -0,0 +1,34 @@
+[remap]
+
+importer="texture"
+type="CompressedTexture2D"
+uid="uid://decojxomfjk5j"
+path="res://.godot/imported/add-music-bank-node.jpg-420caf2d73871ff53dd1cbab494345dc.ctex"
+metadata={
+"vram_texture": false
+}
+
+[deps]
+
+source_file="res://addons/resonate/docs/images/add-music-bank-node.jpg"
+dest_files=["res://.godot/imported/add-music-bank-node.jpg-420caf2d73871ff53dd1cbab494345dc.ctex"]
+
+[params]
+
+compress/mode=0
+compress/high_quality=false
+compress/lossy_quality=0.7
+compress/hdr_compression=1
+compress/normal_map=0
+compress/channel_pack=0
+mipmaps/generate=false
+mipmaps/limit=-1
+roughness/mode=0
+roughness/src_normal=""
+process/fix_alpha_border=true
+process/premult_alpha=false
+process/normal_map_invert_y=false
+process/hdr_as_srgb=false
+process/hdr_clamp_exposure=false
+process/size_limit=0
+detect_3d/compress_to=1

addons/resonate/docs/images/add-sound-bank-node.jpg.import

@@ -0,0 +1,34 @@
+[remap]
+
+importer="texture"
+type="CompressedTexture2D"
+uid="uid://dyf0vqo1r1frq"
+path="res://.godot/imported/add-sound-bank-node.jpg-a91f65b0a3eac2a6a1735380945abe73.ctex"
+metadata={
+"vram_texture": false
+}
+
+[deps]
+
+source_file="res://addons/resonate/docs/images/add-sound-bank-node.jpg"
+dest_files=["res://.godot/imported/add-sound-bank-node.jpg-a91f65b0a3eac2a6a1735380945abe73.ctex"]
+
+[params]
+
+compress/mode=0
+compress/high_quality=false
+compress/lossy_quality=0.7
+compress/hdr_compression=1
+compress/normal_map=0
+compress/channel_pack=0
+mipmaps/generate=false
+mipmaps/limit=-1
+roughness/mode=0
+roughness/src_normal=""
+process/fix_alpha_border=true
+process/premult_alpha=false
+process/normal_map_invert_y=false
+process/hdr_as_srgb=false
+process/hdr_clamp_exposure=false
+process/size_limit=0
+detect_3d/compress_to=1

addons/resonate/docs/images/music-banks.png.import

@@ -0,0 +1,34 @@
+[remap]
+
+importer="texture"
+type="CompressedTexture2D"
+uid="uid://coy730qpivrbt"
+path="res://.godot/imported/music-banks.png-4f6ff10409b2687d87395d8da36bde62.ctex"
+metadata={
+"vram_texture": false
+}
+
+[deps]
+
+source_file="res://addons/resonate/docs/images/music-banks.png"
+dest_files=["res://.godot/imported/music-banks.png-4f6ff10409b2687d87395d8da36bde62.ctex"]
+
+[params]
+
+compress/mode=0
+compress/high_quality=false
+compress/lossy_quality=0.7
+compress/hdr_compression=1
+compress/normal_map=0
+compress/channel_pack=0
+mipmaps/generate=false
+mipmaps/limit=-1
+roughness/mode=0
+roughness/src_normal=""
+process/fix_alpha_border=true
+process/premult_alpha=false
+process/normal_map_invert_y=false
+process/hdr_as_srgb=false
+process/hdr_clamp_exposure=false
+process/size_limit=0
+detect_3d/compress_to=1

addons/resonate/docs/images/music-manager.png.import

@@ -0,0 +1,34 @@
+[remap]
+
+importer="texture"
+type="CompressedTexture2D"
+uid="uid://c33xlcqiwygve"
+path="res://.godot/imported/music-manager.png-94b69d2e104f7db933ca8f29270624b8.ctex"
+metadata={
+"vram_texture": false
+}
+
+[deps]
+
+source_file="res://addons/resonate/docs/images/music-manager.png"
+dest_files=["res://.godot/imported/music-manager.png-94b69d2e104f7db933ca8f29270624b8.ctex"]
+
+[params]
+
+compress/mode=0
+compress/high_quality=false
+compress/lossy_quality=0.7
+compress/hdr_compression=1
+compress/normal_map=0
+compress/channel_pack=0
+mipmaps/generate=false
+mipmaps/limit=-1
+roughness/mode=0
+roughness/src_normal=""
+process/fix_alpha_border=true
+process/premult_alpha=false
+process/normal_map_invert_y=false
+process/hdr_as_srgb=false
+process/hdr_clamp_exposure=false
+process/size_limit=0
+detect_3d/compress_to=1

addons/resonate/docs/images/set-soundbank-label.jpg.import

@@ -0,0 +1,34 @@
+[remap]
+
+importer="texture"
+type="CompressedTexture2D"
+uid="uid://cn3ojlclw1u8i"
+path="res://.godot/imported/set-soundbank-label.jpg-f96dc62be961f04105aa7359942e993a.ctex"
+metadata={
+"vram_texture": false
+}
+
+[deps]
+
+source_file="res://addons/resonate/docs/images/set-soundbank-label.jpg"
+dest_files=["res://.godot/imported/set-soundbank-label.jpg-f96dc62be961f04105aa7359942e993a.ctex"]
+
+[params]
+
+compress/mode=0
+compress/high_quality=false
+compress/lossy_quality=0.7
+compress/hdr_compression=1
+compress/normal_map=0
+compress/channel_pack=0
+mipmaps/generate=false
+mipmaps/limit=-1
+roughness/mode=0
+roughness/src_normal=""
+process/fix_alpha_border=true
+process/premult_alpha=false
+process/normal_map_invert_y=false
+process/hdr_as_srgb=false
+process/hdr_clamp_exposure=false
+process/size_limit=0
+detect_3d/compress_to=1

addons/resonate/docs/images/sound-banks.png.import

@@ -0,0 +1,34 @@
+[remap]
+
+importer="texture"
+type="CompressedTexture2D"
+uid="uid://b1q8c8jsyx4xs"
+path="res://.godot/imported/sound-banks.png-7e9fa46409d6d7a2c4374ffb9307d714.ctex"
+metadata={
+"vram_texture": false
+}
+
+[deps]
+
+source_file="res://addons/resonate/docs/images/sound-banks.png"
+dest_files=["res://.godot/imported/sound-banks.png-7e9fa46409d6d7a2c4374ffb9307d714.ctex"]
+
+[params]
+
+compress/mode=0
+compress/high_quality=false
+compress/lossy_quality=0.7
+compress/hdr_compression=1
+compress/normal_map=0
+compress/channel_pack=0
+mipmaps/generate=false
+mipmaps/limit=-1
+roughness/mode=0
+roughness/src_normal=""
+process/fix_alpha_border=true
+process/premult_alpha=false
+process/normal_map_invert_y=false
+process/hdr_as_srgb=false
+process/hdr_clamp_exposure=false
+process/size_limit=0
+detect_3d/compress_to=1

addons/resonate/docs/images/sound-manager.png.import

@@ -0,0 +1,34 @@
+[remap]
+
+importer="texture"
+type="CompressedTexture2D"
+uid="uid://mg8fvg6efg77"
+path="res://.godot/imported/sound-manager.png-03f9b96b4f719aeb1dde3ec2d85c4f0f.ctex"
+metadata={
+"vram_texture": false
+}
+
+[deps]
+
+source_file="res://addons/resonate/docs/images/sound-manager.png"
+dest_files=["res://.godot/imported/sound-manager.png-03f9b96b4f719aeb1dde3ec2d85c4f0f.ctex"]
+
+[params]
+
+compress/mode=0
+compress/high_quality=false
+compress/lossy_quality=0.7
+compress/hdr_compression=1
+compress/normal_map=0
+compress/channel_pack=0
+mipmaps/generate=false
+mipmaps/limit=-1
+roughness/mode=0
+roughness/src_normal=""
+process/fix_alpha_border=true
+process/premult_alpha=false
+process/normal_map_invert_y=false
+process/hdr_as_srgb=false
+process/hdr_clamp_exposure=false
+process/size_limit=0
+detect_3d/compress_to=1

addons/resonate/docs/music-manager.md

@@ -0,0 +1,58 @@
+# MusicManager
+
+## Introduction
+
+The **MusicManager** is responsible for playing music tracks. It does so through a **StemmedMusicStreamPlayer** (SMSP), which extends Godot's **AudioStreamPlayer**. The core feature of SMSPs, as the name suggests, is the management and playback of ***stems***.
+
+![MusicManager](images/music-manager.png)
+
+Stems are music tracks split horizontally. For example, a music track may be split into pad, melody, and drum stems. Each of these stems can be played in isolation or in-sync with any or all of the other stems. This feature (while not required) allows you to craft more dynamic in-game music. For example, while the player is far enough away from a boss, only the pad stem plays. Then when the player gets closer, the melody stem gets added in. Finally, when the player is within the boss's detection distance, the drum stem gets added in. This helps you form a music track that grows in intensity without having to swap music tracks in and out entirely. It's a more organic and seamless transition.
+
+### MusicBanks
+
+The way you configure music is through the use of **MusicBanks**. Each MusicBank contains one or more music tracks, each of which contains one or more stems. Each stem contains one audio stream.
+
+![MusicBanks](images/music-banks.png)
+
+**MusicBanks** are automatically discovered by the **MusicManager** when your game starts, and can be located anywhere in your active scene(s).
+
+### Fading & crossfading
+
+Whenever you start or stop either an entire music track or a single stem, you can provide a (cross)fade time. If you want either of those to start immediately, just provide a (cross)fade time of zero seconds.
+
+## Usage
+
+### Creating MusicBanks
+
+#### Step 1
+
+Add a new MusicBank node to your scene.
+
+![MusicBankNode](images/add-music-bank-node.jpg)
+
+#### Step 2
+
+Give your new MusicBank a label and then create a new MusicTrackResource. A MusicTrackResource represents one track in your music bank. Each track requires a name, which you will use to start it from your script(s).
+
+![AddMusicResource](images/add-music-resource.gif)
+
+#### Step 3
+
+Create as many MusicStemResources as you track requires. Each stem requires a name, which you will use to enable or disable it from your script(s). If you mark a stem as enabled at the resource level, it will automatically be started for you when you play the music track. If often makes sense to have you core stem enabled by default.
+
+![AddMusicStemResource](images/add-music-stem-resources.gif)
+
+### Playing music
+
+To start a new music track, just call the `play` method on the MusicManager with the name of the bank and track you want to play.
+
+```GDScript
+MusicManager.play("combat", "boss_fight")
+```
+
+To enable or disable stems on the currently playing track, just call `enabled_stem` or `disable_stem`.
+
+```GDScript
+MusicManager.enable_stem("melody")
+MusicManager.disable_stem("drums")
+```

addons/resonate/docs/sound-manager.md

@@ -0,0 +1,107 @@
+# SoundManager
+
+## Introduction
+
+The **SoundManager** is responsible for triggering sounds. It does so through **PooledAudioStreamPlayers** (PASPs), which extend Godot's native **AudioStreamPlayers** (ASPs). PASPs, like ASPs, support audio playback in 1D, 2D, and 3D space, making them useful for any game sound effect.
+
+![SoundManager](images/sound-manager.png)
+
+Sound events can be configured with multiple variations (audio streams) which are chosen at random when played. This can help create organic-sounding events such as footsteps, gunshots, collisions, etc.
+
+### SoundBanks
+
+The way you configure sound events and their variations is through the use of **SoundBanks**. Each **SoundBank** you create has a name and several associated events, among other configuration options.
+
+![SoundManager](images/sound-banks.png)
+
+**SoundBanks** are automatically discovered and loaded by the **SoundManager** when your game starts. This allows you to co-locate your **SoundBanks** with the entities or systems they belong to.
+
+All registered sound events can be triggered in three ways: uniformly, at a fixed position, or attached to a node. Uniformly triggered sound events always play in 1D space and, therefore, will be heard as if coming from all directions (no stereo or 3D panning). Sound events triggered at a fixed position (Vector2/Vector3) or attached to a node (Node2D/Node3D) will automatically be positioned in 2D or 3D space. They will be heard accordingly through the use of panning.
+
+When you trigger a sound event, the **SoundManager** will retrieve a free PASP from one of its appropriate 1D, 2D, or 3D pools. After the event, the PASP will be freed and returned to the pool, available for the next event. Using pools means you do not have to insert ASPs into your scenes manually. For performance reasons, however, the **SoundManager** will limit how many PASPs it creates in each pool. This limit can be configured under `Audio/Manager/Sound` in your project settings.
+
+When you want to play a particular event consistently, you can request exclusive use of a PASP from the **SoundManager**. When doing so, it will not be automatically returned to its pool when an event has finished playing. It can be manually released if you wish to return it to its pool.
+
+### Polyphony
+
+By default, every PASP, when told to trigger an event, will play the event once. If instructed to trigger the event again while a previous variation is still playing, it will stop playback and immediately begin playing a new random variation. Polyphonic playback can be enabled in situations where this is undesirable, for instance, playing rapid gunshots. When told to trigger, polyphonic playback will start playing a random variation concurrently with all other variations already playing. The maximum number of concurrent variations a PASP can play can be configured under `Audio/Manager/Sound` in your project settings.
+
+## Usage
+
+### Creating SoundBanks
+
+#### Step 1
+
+Add a new **SoundBank** node to your scene.
+
+![SoundBankNode](images/add-sound-bank-node.jpg)
+
+#### Step 2
+
+Set the label for your new **SoundBank**. **SoundBanks** are flexible in that they allow you to group your sounds however you want. The label in this case is the group name. Example labels could be "player", "UI", "gunshots", etc. The name you provide here is what you will use when calling the play or instance functions from your script(s).
+
+![SoundBankNode](images/set-soundbank-label.jpg)
+
+#### Step 3
+
+Create a new **SoundEventResource**. Each **SoundEventResource** is a single **event** in a **SoundBank**. The name you provide here is what you will use when calling the play or instance functions from your script(s).
+
+![SoundBankNode](images/add-sound-event-resource.gif)
+
+#### Step 4
+
+Add as many streams (variations) to the event as you need. These variations, chosen at random, are played when you trigger the event from your script(s).
+
+![SoundBankNode](images/add-sound-event-resource-streams.gif)
+
+You are now ready to trigger the event from your script(s).
+
+### Triggering events
+
+#### Simple
+
+There are two ways to trigger events with the **SoundManager**. The first way is to automatically trigger the event and have the **SoundManager** handle everything for you. 
+
+```GDScript
+SoundManager.play("player", "footsteps")
+```
+
+Using this approach (any **SoundManager** method starting with `play`) will cause the **SoundManager** to pick a free player from the pool, trigger your event on it, and immediately return it to the pool once the sound has finished playing.
+
+#### Advanced
+
+The second way is to manually trigger events. To manually trigger an event, you need to first `instance` a sound event. When a sound event is instanced, the **SoundManager** will return a reserved **PooledAudioStreamPlayer**. You can save a reference to this player and call the `trigger` method on it whenever you want to trigger the reserved event.
+
+`trigger() -> void`
+
+See the following example below:
+
+```GDScript
+var instance = SoundManager.instance_poly("player", "footsteps")
+
+instance.trigger()
+```
+
+When using an instanced sound event, its your duty to release it back to the pool if you're done using it. This can be achieved by calling the `release` method.
+
+```GDScript
+instance.release()
+```
+
+However, it's often the case that an instanced sound event will be used indefinitely by the calling script, in which case you do not need to call `release`.
+
+#### Automatic space detection
+
+When calling the `play` or `instance` methods, the **SoundManager** will use a 1D space **PooledAudioStreamPlayer**. If you require an event to be played in 2D or 3D space, you'll need to use one of the extended `play` or `instance` methods (see the API references below.)
+
+#### Polyphonic playback
+
+The `instance` method also offers a further extension which allows you to reserve a **PooledAudioStreamPlayer** in a polyphonic configuration (see the API references below.)
+
+#### Varying pitch and volume
+
+As it's quite common to want to vary the pitch and/or volume of an event, we've added an extended version of the `trigger` method called `trigger_varied`:
+
+`trigger_varied(p_pitch: float = 1.0, p_volume: float = 0.0) -> void`
+
+The `trigger_varied` method works for both polyphonic and non-polyphonic events.