Skip to content

Commit

Permalink
Documentation for audio and interface classes (#167)
Browse files Browse the repository at this point in the history 
* Finish documentation for some audio classes

Finished PopochiuAudioCue, AudioCueSound and AudioCueMusic.

* Progress on AudioManager documentation

Minor updates to PopochiuAudioCue documentation.
[upd] Removed preload of audio_cue.gd to use PopochiuAudioCue directly in AudioManager class.

* Finish documentation for AudioManager

Improved grammar in all documentation comments for audio classes.

[upd] Minor style update for comment about queue methods.

* Add documentation for IAudio, ICharacter and IDialog

Minor updates to documentation in PopochiuCharacter and Popochiu.

[upd] Now semitone_to_pitch in PopochiuAudioManager is a private method.

* Finish documentation for IDialog and IInventory

Create PopochiuIInventory class.

[upd] Minor updates for PopochiuInventoryItem

* Finish documentation for PopochiuIRoom

Update long description styles for PopochiuICharacter, PopochiuIDialog, PopochiuIInventory.

[fix] Fix old calls to I.set_active_item()

* Finish documentation for PopochiuIGraphicInterface
  • Loading branch information
@mapedorr
mapedorr authored Mar 4, 2024
1 parent fd9ba51 commit 83e583b
Show file tree
Hide file tree
Showing 20 changed files with 684 additions and 400 deletions.
157 changes: 80 additions & 77 deletions addons/popochiu/engine/audio_manager/audio_cue.gd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,57 +3,57 @@ 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. Whether it loops or not, or
## whether it is 2D positioned.
## 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
## Indicates if the audio can be played simultaniously with other instances of
## itself. Specially useful for audio cues in loop.
## 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 := 1.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
@export var attenuation := 1.0 # (float, EASE)
@export var bus := 'Master'
## The audio bus in which the audio file will be played.
@export var bus := "Master"


# ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ PUBLIC ░░░░
# Plays immediately this audio cue with a fade that will last `duration` seconds.
# You can specify the starting volume with `from` and the target volume with `to`.
#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
duration := 1.0, wait_to_end := false, from := -80.0, to := INF, position_2d := Vector2.ZERO
) -> void:
if wait_to_end:
await E.am.play_fade_cue(
resource_name,
duration,
from,
to,
position_2d,
true
)
await E.am.play_fade_cue(resource_name, duration, from, to, position_2d, true)
else:
E.am.play_fade_cue(resource_name, duration, from, to, position_2d)


# Queue the call to play this audie cue with a fade that will last `duration`
# seconds. You can specify the starting volume with `from` and the target volume
# with `to`.
# (!) This is intended to run in queued instructions: E.queue([]).
## 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
duration := 1.0, wait_to_end := false, from := -80.0, to := INF, position_2d := Vector2.ZERO
) -> Callable:
return func ():
if wait_to_end:
Expand All @@ -63,59 +63,36 @@ func queue_fade(
await E.get_tree().process_frame


# Stops the audio cue. Can use a fade that will last `fade_duration`
# seconds.
## Stops the audio cue, with an optional fade effect lasting [param fade_duration] seconds.
func stop(fade_duration := 0.0) -> void:
E.am.stop(resource_name, fade_duration)


# Queue the call to stop the audio cue.
# Can use a fade that will last `fade_duration` seconds.
# (!) This is intended to run in queued instructions: E.queue([]).
## 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 E.get_tree().process_frame


# Changes the pitch_scale of the AudioStreamPlayer(2D) that is playing the audio
# file of this cue
## 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:
E.am.change_cue_pitch(resource_name, pitch)


# Changes the volume_db of the AudioStreamPlayer(2D) that is playing the audio
# file of this cue
## 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:
E.am.change_cue_volume(resource_name, volume)


# ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ SET & GET ░░░░
func set_loop(value: bool) -> void:
loop = value

if not audio: return

match audio.get_class():
'AudioStreamOggVorbis', 'AudioStreamMP3':
audio.loop = value
'AudioStreamWAV':
if (audio as AudioStreamWAV).get_loop_end() == 0 && value:
PopochiuUtils.print_warning(
"[b]%s[/b]" % resource_name +\
" does not have the correct metadata to loop, please check" +\
" AudioStreamWAV documentation"
)
else:
(audio as AudioStreamWAV).loop_mode =\
AudioStreamWAV.LOOP_FORWARD if value\
else AudioStreamWAV.LOOP_DISABLED

notify_property_list_changed()


# Returns the `pitch_scale` to apply to the audio stream player that will play
# the audio of this audio cue.
## 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 := A.semitone_to_pitch(pitch)

Expand All @@ -125,15 +102,13 @@ func get_pitch_scale() -> float:
return p


# Returns the playback position of the AudioCue identified by `cue_name`.
# If not found, returns -1.0.
## Returns the playback position of this audio cue.
func get_cue_playback_position() -> float:
return E.am.get_cue_playback_position(resource_name)


# Maps the values in `values` to the properties of this audio cue.
# Used by TabAudio when changing the script of the audio cue to one of the types:
# AudioCueSound or AudioCueMusic (in projects prior to v1.9.0)
## 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
Expand All @@ -144,13 +119,11 @@ func set_values(values: Dictionary) -> void:
rnd_pitch = values.rnd_pitch
rnd_volume = values.rnd_volume
max_distance = values.max_distance
attenuation = values.attenuation
bus = values.bus


# Returns the properties of this audio cue as a Dictionary.
# Used by TabAudio when changing the script of the audio cue to one of the types:
# AudioCueSound or AudioCueMusic (in projects prior to v1.9.0)
## 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,
Expand All @@ -162,12 +135,39 @@ func get_values() -> Dictionary:
rnd_pitch = rnd_pitch,
rnd_volume = rnd_volume,
max_distance = max_distance,
attenuation = attenuation,
bus = bus
}


# ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ PRIVATE ░░░░
#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':
if (audio as AudioStreamWAV).get_loop_end() == 0 && value:
PopochiuUtils.print_warning(
"[b]%s[/b]" % resource_name +\
" does not have the correct metadata to loop, please check" +\
" AudioStreamWAV documentation"
)
else:
(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 A.semitone_to_pitch(pitch + randf_range(rnd_pitch.x, rnd_pitch.y))
Expand All @@ -176,3 +176,6 @@ func _get_rnd_pitch() -> float:
func _get_rnd_volume() -> float:
randomize()
return volume + randf_range(rnd_volume.x, rnd_volume.y)


#endregion
20 changes: 11 additions & 9 deletions addons/popochiu/engine/audio_manager/audio_cue_music.gd
View file
Original file line number Diff line number Diff line change
@@ -1,21 +1,23 @@
@tool
extends PopochiuAudioCue
class_name AudioCueMusic
extends PopochiuAudioCue
## A specific type of [PopochiuAudioCue] designed for playing music.


# ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ PUBLIC ░░░░
# Plays immediately this cue's music track.
# It can fade for `fade_duration` seconds.
# You can change the track starting position in seconds with `music_position`.
#region Public #####################################################################################
## Plays this audio cue. It can fade for [param fade_duration] seconds, and you can change the track
## starting position in seconds with [param music_position].
func play(fade_duration := 0.0, music_position := 0.0) -> void:
E.am.play_music_cue(resource_name, fade_duration, music_position)


# Queue the call to play this cue's music track.
# It can fade for `fade_duration` seconds.
# You can change the track starting position in seconds with `music_position`.
# (!) This is intended to run in queued instructions: E.queue([]).
## Plays this audio cue. It can fade for [param fade_duration] seconds, and you can change the track
## starting position in seconds with [param music_position].[br][br]
## [i]This method is intended to be used inside a [method Popochiu.queue] of instructions.[/i]
func queue_play(fade_duration := 0.0, music_position := 0.0) -> Callable:
return func ():
await play(fade_duration, music_position)
await E.get_tree().process_frame


#endregion
24 changes: 13 additions & 11 deletions addons/popochiu/engine/audio_manager/audio_cue_sound.gd
View file
Original file line number Diff line number Diff line change
@@ -1,29 +1,31 @@
@tool
extends PopochiuAudioCue
class_name AudioCueSound
extends PopochiuAudioCue
## A specific type of [PopochiuAudioCue] designed for playing sounds.


# ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ PUBLIC ░░░░
# Plays immediately this cue's sound.
# If `wait_to_end` is `true` the function will pause until the audio clip finishes.
# You can play the clip from a specific `position_2d` in the scene if `is_2d` is
# `true`.
#region Public #####################################################################################
## Plays this audio cue. If [param wait_to_end] is set to [code]true[/code], the function will pause
## until the audio clip finishes. You can play the file from a specific [param position_2d] in the
## scene if [member PopochiuAudioCue.is_2d] is [code]true[/code].
func play(wait_to_end := false, position_2d := Vector2.ZERO) -> void:
if wait_to_end:
await E.am.play_sound_cue(resource_name, position_2d, true)
else:
E.am.play_sound_cue(resource_name, position_2d)


# Queue the call to play this cue's sound.
# If `wait_to_end` is `true` the function will pause until the audio clip finishes
# You can play the clip from a specific `position_2d` in the scene if `is_2d` is
# `true`.
# (!) This is intended to be used in queued instructions: E.queue([]).
## Plays this audio cue. If [param wait_to_end] is set to [code]true[/code], the function will pause
## until the audio clip finishes. You can play the file from a specific [param position_2d] in the
## scene if [member PopochiuAudioCue.is_2d] is [code]true[/code].[br][br]
## [i]This method is intended to be used inside a [method Popochiu.queue] of instructions.[/i]
func queue_play(wait_to_end := false, position_2d := Vector2.ZERO) -> Callable:
return func ():
if wait_to_end:
await play(true, position_2d)
else:
play(false, position_2d)
await E.get_tree().process_frame


#endregion
Loading

0 comments on commit 83e583b

Please sign in to comment.