First commit 🎉

addons/popochiu/engine/audio_manager/audio_cue.gd

@@ -0,0 +1,179 @@
+@tool
+class_name PopochiuAudioCue
+extends Resource
+## Used to play audio files with extra properties.
+##
+## You can set the pitch (with random values), volume, and audio bus, as well as specify whether
+## it loops, and whether it is 2D positioned.
+
+
+## The audio file to play.
+@export var audio: AudioStream
+## Whether the audio file will loop when played.
+@export var loop := false : set = set_loop
+## Whether this audio cue uses a 2D position.
+@export var is_2d := false
+## Whether the audio can be played simultaneously with other instances of itself. Especially useful
+## for audio cues set in a loop (where [member loop] is [code]true[/code]).
+@export var can_play_simultaneous := true
+## The pitch value (in semitones) to use when playing the audio file.
+@export var pitch := 0.0
+## The volume to use when playing the audio file.
+@export var volume := 0.0
+## The range of values to use for randomly changing the pitch of the audio file when played.
+@export var rnd_pitch := Vector2.ZERO
+## The range of values to use to randomly changing the volume of the audio file when played.
+@export var rnd_volume := Vector2.ZERO
+## Maximum distance from which the audio file is still hearable. This only works if [member is_2d]
+## is [code]true[/code].
+@export var max_distance := 2000
+## The audio bus in which the audio file will be played.
+@export var bus := "Master"
+
+
+#region Public #####################################################################################
+## Plays this audio cue with a fade that lasts [param duration] seconds. If [param wait_to_end] is
+## set to [code]true[/code], the function will wait for the audio to finish. You can specify the
+## starting volume with [param from] and the target volume with [param to], as well as the
+## [param position_2d] of the [AudioStreamPlayer] or [AudioStreamPlayer2D] that will play the audio
+## file.
+func fade(
+	duration := 1.0, wait_to_end := false, from := -80.0, to := INF, position_2d := Vector2.ZERO
+) -> void:
+	if wait_to_end:
+		await PopochiuUtils.e.am.play_fade_cue(resource_name, duration, from, to, position_2d, true)
+	else:
+		PopochiuUtils.e.am.play_fade_cue(resource_name, duration, from, to, position_2d)
+
+
+## Plays this audio cue with a fade that lasts [param duration] seconds. If [param wait_to_end] is
+## set to [code]true[/code], the function will wait for the audio to finish. You can specify the
+## starting volume with [param from] and the target volume with [param to], as well as the
+## [param position_2d] of the [AudioStreamPlayer] or [AudioStreamPlayer2D] that will play the audio
+## file.[br][br]
+## [i]This method is intended to be used inside a [method Popochiu.queue] of instructions.[/i]
+func queue_fade(
+	duration := 1.0, wait_to_end := false, from := -80.0, to := INF, position_2d := Vector2.ZERO
+) -> Callable:
+	return func ():
+		if wait_to_end:
+			await fade(duration, wait_to_end, from, to, position_2d)
+		else:
+			fade(duration, wait_to_end, from, to, position_2d)
+			await PopochiuUtils.e.get_tree().process_frame
+
+
+## Stops the audio cue, with an optional fade effect lasting [param fade_duration] seconds.
+func stop(fade_duration := 0.0) -> void:
+	PopochiuUtils.e.am.stop(resource_name, fade_duration)
+
+
+## Stops the audio cue, with an optional fade effect lasting [param fade_duration] seconds.[br][br]
+## [i]This method is intended to be used inside a [method Popochiu.queue] of instructions.[/i]
+func queue_stop(fade_duration := 0.0) -> Callable:
+	return func ():
+		stop(fade_duration)
+		await PopochiuUtils.e.get_tree().process_frame
+
+
+## Changes the [member AudioStreamPlayer.pitch_scale] of the [AudioStreamPlayer] playing the audio
+## file associated with this audio cue to [param pitch]. If the audio was played with a 2D position,
+## then [member AudioStreamPlayer2D.pitch_scale] will be affected.
+func change_stream_pitch(pitch := 0.0) -> void:
+	PopochiuUtils.e.am.change_cue_pitch(resource_name, pitch)
+
+
+## Changes the [member AudioStreamPlayer.volume_db] of the [AudioStreamPlayer] playing the audio
+## file associated with this audio cue to [param volume]. If the audio was played with a 2D
+## position, then [member AudioStreamPlayer2D.volume_db] will be affected.
+func change_stream_volume(volume := 0.0) -> void:
+	PopochiuUtils.e.am.change_cue_volume(resource_name, volume)
+
+
+## Returns the value of [member AudioStreamPlayer.pitch_scale] to be applied to the
+## [AudioStreamPlayer] playing the audio file associated with this audio cue. If the audio was
+## played with a 2D position, then [member AudioStreamPlayer2D.volume_db] will be affected.
+func get_pitch_scale() -> float:
+	var p := PopochiuUtils.a.semitone_to_pitch(pitch)
+	
+	if rnd_pitch != Vector2.ZERO:
+		p = _get_rnd_pitch()
+	
+	return p
+
+
+## Returns the playback position of this audio cue.
+func get_cue_playback_position() -> float:
+	return PopochiuUtils.e.am.get_cue_playback_position(resource_name)
+
+
+## Maps [param values] to the properties of this audio cue. This is used by TabAudio when changing
+## the script of the audio cue to one of the types: [AudioCueSound] or [AudioCueMusic].
+func set_values(values: Dictionary) -> void:
+	resource_name = values.resource_name
+	audio = values.audio
+	loop = values.loop
+	is_2d = values.is_2d
+	pitch = values.pitch
+	volume = values.volume
+	rnd_pitch = values.rnd_pitch
+	rnd_volume = values.rnd_volume
+	max_distance = values.max_distance
+	bus = values.bus
+
+
+## Returns the properties of this audio cue as a [Dictionary]. This is used by TabAudio when
+## changing the script of the audio cue to one of the types: [AudioCueSound] or [AudioCueMusic].
+func get_values() -> Dictionary:
+	return {
+		resource_name = resource_name,
+		audio = audio,
+		loop = loop,
+		is_2d = is_2d,
+		pitch = pitch,
+		volume = volume,
+		rnd_pitch = rnd_pitch,
+		rnd_volume = rnd_volume,
+		max_distance = max_distance,
+		bus = bus
+	}
+
+
+## Returns [code]true[/code] if playing.
+func is_playing() -> bool:
+	return PopochiuUtils.a.is_playing_cue(resource_name)
+
+
+#endregion
+
+#region SetGet #####################################################################################
+func set_loop(value: bool) -> void:
+	loop = value
+	
+	if not audio: return
+	
+	match audio.get_class():
+		'AudioStreamOggVorbis', 'AudioStreamMP3':
+			audio.loop = value
+		'AudioStreamWAV':
+			(audio as AudioStreamWAV).loop_mode = (
+				AudioStreamWAV.LOOP_FORWARD if value else AudioStreamWAV.LOOP_DISABLED
+			)
+	
+	notify_property_list_changed()
+
+
+#endregion
+
+#region Private ####################################################################################
+func _get_rnd_pitch() -> float:
+	randomize()
+	return PopochiuUtils.a.semitone_to_pitch(pitch + randf_range(rnd_pitch.x, rnd_pitch.y))
+
+
+func _get_rnd_volume() -> float:
+	randomize()
+	return volume + randf_range(rnd_volume.x, rnd_volume.y)
+
+
+#endregion