addons/dialogic/Modules/Audio/subsystem_audio.gd

   1 extends DialogicSubsystem
   2 ## Subsystem for managing background music and one-shot sound effects.
   3 ##
   4 ## This subsystem has many different helper methods for managing audio
   5 ## in your timeline.
   6 ## For instance, you can listen to music changes via [signal music_started].
   7
   8
   9 ## Whenever a new background music is started, this signal is emitted and
  10 ## contains a dictionary with the following keys: [br]
  11 ## [br]
  12 ## Key         |   Value Type  | Value [br]
  13 ## ----------- | ------------- | ----- [br]
  14 ## `path`      | [type String] | The path to the audio resource file. [br]
  15 ## `volume`    | [type float]  | The volume of the audio resource that will be set to the [member base_music_player]. [br]
  16 ## `audio_bus` | [type String] | The audio bus name that the [member base_music_player] will use. [br]
  17 ## `loop`      | [type bool]   | Whether the audio resource will loop or not once it finishes playing. [br]
  18 ## `channel`   | [type int]    | The channel ID to play the audio on. [br]
  19 signal music_started(info: Dictionary)
  20
  21
  22 ## Whenever a new sound effect is set, this signal is emitted and contains a
  23 ## dictionary with the following keys: [br]
  24 ## [br]
  25 ## Key         |   Value Type  | Value [br]
  26 ## ----------- | ------------- | ----- [br]
  27 ## `path`      | [type String] | The path to the audio resource file. [br]
  28 ## `volume`    | [type float]  | The volume of the audio resource that will be set to [member base_sound_player]. [br]
  29 ## `audio_bus` | [type String] | The audio bus name that the [member base_sound_player] will use. [br]
  30 ## `loop`      | [type bool]   | Whether the audio resource will loop or not once it finishes playing. [br]
  31 signal sound_started(info: Dictionary)
  32
  33
  34 var max_channels: int:
  35         set(value):
  36                 if max_channels != value:
  37                         max_channels = value
  38                         ProjectSettings.set_setting('dialogic/audio/max_channels', value)
  39                         ProjectSettings.save()
  40                         current_music_player.resize(value)
  41         get:
  42                 return ProjectSettings.get_setting('dialogic/audio/max_channels', 4)
  43
  44 ## Audio player base duplicated to play background music.
  45 ##
  46 ## Background music is long audio.
  47 var base_music_player := AudioStreamPlayer.new()
  48 ## Reference to the last used music player.
  49 var current_music_player: Array[AudioStreamPlayer] = []
  50 ## Audio player base, that will be duplicated to play sound effects.
  51 ##
  52 ## Sound effects are short audio.
  53 var base_sound_player := AudioStreamPlayer.new()
  54
  55
  56 #region STATE
  57 ####################################################################################################
  58
  59 ## Clears the state on this subsystem and stops all audio.
  60 ##
  61 ## If you want to stop sounds only, use [method stop_all_sounds].
  62 func clear_game_state(_clear_flag := DialogicGameHandler.ClearFlags.FULL_CLEAR) -> void:
  63         for idx in max_channels:
  64                 update_music('', 0.0, '', 0.0, true, idx)
  65         stop_all_sounds()
  66
  67
  68 ## Loads the state on this subsystem from the current state info.
  69 func load_game_state(load_flag:=LoadFlags.FULL_LOAD) -> void:
  70         if load_flag == LoadFlags.ONLY_DNODES:
  71                 return
  72         var info: Dictionary = dialogic.current_state_info.get("music", {})
  73         if not info.is_empty() and info.has('path'):
  74                 update_music(info.path, info.volume, info.audio_bus, 0, info.loop, 0)
  75         else:
  76                 for channel_id in info.keys():
  77                         if info[channel_id].is_empty() or info[channel_id].path.is_empty():
  78                                 update_music('', 0.0, '', 0.0, true, channel_id)
  79                         else:
  80                                 update_music(info[channel_id].path, info[channel_id].volume, info[channel_id].audio_bus, 0, info[channel_id].loop, channel_id)
  81
  82
  83 ## Pauses playing audio.
  84 func pause() -> void:
  85         for child in get_children():
  86                 child.stream_paused = true
  87
  88
  89 ## Resumes playing audio.
  90 func resume() -> void:
  91         for child in get_children():
  92                 child.stream_paused = false
  93
  94
  95 func _on_dialogic_timeline_ended() -> void:
  96         if not dialogic.Styles.get_layout_node():
  97                 clear_game_state()
  98         pass
  99 #endregion
 100
 101
 102 #region MAIN METHODS
 103 ####################################################################################################
 104
 105 func _ready() -> void:
 106         dialogic.timeline_ended.connect(_on_dialogic_timeline_ended)
 107
 108         base_music_player.name = "Music"
 109         add_child(base_music_player)
 110
 111         base_sound_player.name = "Sound"
 112         add_child(base_sound_player)
 113
 114         current_music_player.resize(max_channels)
 115
 116
 117 ## Updates the background music. Will fade out previous music.
 118 func update_music(path := "", volume := 0.0, audio_bus := "", fade_time := 0.0, loop := true, channel_id := 0) -> void:
 119
 120         if channel_id > max_channels:
 121                 printerr("\tChannel ID (%s) higher than Max Music Channels (%s)" % [channel_id, max_channels])
 122                 dialogic.print_debug_moment()
 123                 return
 124
 125         if not dialogic.current_state_info.has('music'):
 126                 dialogic.current_state_info['music'] = {}
 127
 128         dialogic.current_state_info['music'][channel_id] = {'path':path, 'volume':volume, 'audio_bus':audio_bus, 'loop':loop, 'channel':channel_id}
 129         music_started.emit(dialogic.current_state_info['music'][channel_id])
 130
 131         var fader: Tween = null
 132         if is_instance_valid(current_music_player[channel_id]) and current_music_player[channel_id].playing or !path.is_empty():
 133                 fader = create_tween()
 134
 135         var prev_node: Node = null
 136         if is_instance_valid(current_music_player[channel_id]) and current_music_player[channel_id].playing:
 137                 prev_node = current_music_player[channel_id]
 138                 fader.tween_method(interpolate_volume_linearly.bind(prev_node), db_to_linear(prev_node.volume_db),0.0,fade_time)
 139
 140         if path:
 141                 current_music_player[channel_id] = base_music_player.duplicate()
 142                 add_child(current_music_player[channel_id])
 143                 current_music_player[channel_id].stream = load(path)
 144                 current_music_player[channel_id].volume_db = volume
 145                 if audio_bus:
 146                         current_music_player[channel_id].bus = audio_bus
 147                 if not current_music_player[channel_id].stream is AudioStreamWAV:
 148                         if "loop" in current_music_player[channel_id].stream:
 149                                 current_music_player[channel_id].stream.loop = loop
 150                         elif "loop_mode" in current_music_player[channel_id].stream:
 151                                 if loop:
 152                                         current_music_player[channel_id].stream.loop_mode = AudioStreamWAV.LOOP_FORWARD
 153                                 else:
 154                                         current_music_player[channel_id].stream.loop_mode = AudioStreamWAV.LOOP_DISABLED
 155
 156                 current_music_player[channel_id].play(0)
 157                 fader.parallel().tween_method(interpolate_volume_linearly.bind(current_music_player[channel_id]), 0.0, db_to_linear(volume),fade_time)
 158
 159         if prev_node:
 160                 fader.tween_callback(prev_node.queue_free)
 161
 162
 163 ## Whether music is playing.
 164 func has_music(channel_id := 0) -> bool:
 165         return !dialogic.current_state_info.get('music', {}).get(channel_id, {}).get('path', '').is_empty()
 166
 167
 168 ## Plays a given sound file.
 169 func play_sound(path: String, volume := 0.0, audio_bus := "", loop := false) -> void:
 170         if base_sound_player != null and !path.is_empty():
 171                 sound_started.emit({'path':path, 'volume':volume, 'audio_bus':audio_bus, 'loop':loop})
 172
 173                 var new_sound_node := base_sound_player.duplicate()
 174                 new_sound_node.name += "Sound"
 175                 new_sound_node.stream = load(path)
 176
 177                 if "loop" in new_sound_node.stream:
 178                         new_sound_node.stream.loop = loop
 179                 elif "loop_mode" in new_sound_node.stream:
 180                         if loop:
 181                                 new_sound_node.stream.loop_mode = AudioStreamWAV.LOOP_FORWARD
 182                         else:
 183                                 new_sound_node.stream.loop_mode = AudioStreamWAV.LOOP_DISABLED
 184
 185                 new_sound_node.volume_db = volume
 186                 if audio_bus:
 187                         new_sound_node.bus = audio_bus
 188
 189                 add_child(new_sound_node)
 190                 new_sound_node.play()
 191                 new_sound_node.finished.connect(new_sound_node.queue_free)
 192
 193
 194 ## Stops all audio.
 195 func stop_all_sounds() -> void:
 196         for node in get_children():
 197                 if node == base_sound_player:
 198                         continue
 199                 if "Sound" in node.name:
 200                         node.queue_free()
 201
 202
 203 ## Converts a linear loudness value to decibel and sets that volume to
 204 ## the given [param node].
 205 func interpolate_volume_linearly(value: float, node: Node) -> void:
 206         node.volume_db = linear_to_db(value)
 207
 208
 209 ## Returns whether the currently playing audio resource is the same as this
 210 ## event's [param resource_path], for [param channel_id].
 211 func is_music_playing_resource(resource_path: String, channel_id := 0) -> bool:
 212         var is_playing_resource: bool = (current_music_player.size() > channel_id
 213                 and is_instance_valid(current_music_player[channel_id])
 214                 and current_music_player[channel_id].is_playing()
 215                 and current_music_player[channel_id].stream.resource_path == resource_path)
 216
 217         return is_playing_resource
 218
 219 #endregion