@icon("icon.png") class_name SpatialAudio3D extends AudioStreamPlayer3D ## A Godot 4 plugin that brings physically-informed 3D audio to your scenes ## - with distance-based delay, raycast-driven reverb, and dynamic occlusion, all derived from your level geometry at runtime. ## ## It consists of three components: ## * Soundsource ## * Reverber ## * Soundplayer ## ## The *Soundsource* is the original audio emitter, it has a delay based on the player's distance to it. ## Soundsource also shoots raycasts in 8 different directions + up to determine where to create the Reverbers, ## and it measures the room size using additional measurement raycasts. ## ## The *Reverber* is a sound that is reflected on a wall, it has a delay and reverb effect, based on player's distance and room size. ## ## The *Soundplayer* is the entity that actually plays the audio. Why do I need an additional Soundplayer and not playing directly on Soundsource and Reverber? ## During development, I figured that setting the delay while playing sound generates audible cracks. ## To mitigate this, each Soundsource has two *Soundplayers*; one active playing a sound, and one in standby where I set delays. ## Every 10 meters, Soundsource does a crossfade between the active and inactive Soundplayer. ## ## A similar problem arises with the Reverber: Imagine it plays a sound in a big room with long reverb. ## Suddenly, you exit the room. The Reverber with the long reverb is repositioned 1m at the door, and the still playing reverb suddenly abrupts. ## To mitigate this, each Reverber also has two Soundplayers; one active playing a sound, and one in standby. ## If the player moves around and the reverber would be placed more than 10m away to it's former position, the standby Soundplayer is placed instead, ## letting the former reverber hall and fade out. @export_category("Sound Properties") @export var reverb_enabled: bool = true ## Enable reverb-effects with all its computations.[br][br]Disable if you just need it for occlusion detection, for example fading ambient rain when entering a house. @export_range(-81, +80, 3.0, "suffix:dB") var reverb_volume_db: float = -6 ## Maximum volume of the reverbs. @export_range(-1, 5, 0.05, "or_greater", "suffix:s") var reverb_fadeintime: float = 2.0 ## Fade-in time when a reverb is added at a wall.[br][br]The default of 2s is a good value where changes in environment merge well into the overall sound mix.[br]If you have small areas with little changes of distances, set this value to low (0.2s) so that repositioned reverbs don't get stuck for too long in a position. In a large area, when the raycast suddenly hits a close wall, the sudden appearing reverb can sound unnatural.[br][br]Set to -1 for dynamic fade time (based on wetness). @export_range(-1, 8, 0.05, "or_greater", "suffix:s") var reverb_fadeouttime: float = 2.0 ## Fade-out time when a reverb is removed.[br][br]The default of 2s is a good value where changes in environment merge well into the overall sound mix.[br]If you have small areas with little changes of distances, set this value to low (0.2s) so that repositioned reverbs don't get stuck for too long in a position.[br][br]Set to -1 for dynamic fade time (based on wetness). @export_range(1, 20_000, 0.1, "suffix:Hz") var occlusion_lp_cutoff: int = 600 ## Frequency when soundsource is occluded behind walls. @export_range(0, 5, 0.05, "or_greater", "suffix:s") var occlusion_fadetime: float = 0.5 ## Fadetime when occlusion changes. @export_range(0, 100, 0.1, "or_greater", "suffix:m") var bass_proximity: int = 50 ## The closer you are to a wall, the more bass you will hear.[br][br]The effect starts at this value (distance to the wall).[br][br]0 to disable. @export_category("Physics") @export_range(1, 100, 1, "or_greater", "suffix:m") var max_raycast_distance: int = 100 ## Maximum distance for the reverb raycasts. @export_flags_3d_physics var collision_mask: int = 1 ## Mask for the raycast where to add reverb. @export var roomsize_multiplicator: float = 6.0 ## How much hall to add compared to room size.[br]Sometimes you have a small room but you need a long reverb. @export_range(1, 340, 1, "or_greater", "suffix:m/s") var speed_of_sound: int = 340 ## How fast sound travels through the air. @export var prox_reduction: float = 0.0 ## How much proximity reduces the reverb @export_range(4,32,1) var reverb_raycast_count: int = 8 ##how many reverb raycasts to shoot out horizontally @export_category("System") @export_range(1, 60, 0.1, "or_greater", "suffix:per second") var audiophysics_ticks: int = 10 ## The number of audio physics calculations per second.[br]Tied to _physics_process().[br][br]Use 30-60 for fast moving sounds like a motorcycle passing by.[br][br]Default: 10. @export var loop: bool = false ## Loop audio indefinitely. @export var shut_up: bool = false ## Mute output. @export var debug: bool = false ## Visualize raycasts, measurement rays and reverb-audioplayers. @onready var player_camera: Camera3D = get_viewport().get_camera_3d() # store reference to camera so that global_position is always up to date #@onready var raycasts_coords: Array = [ #Vector3(0, 0, max_raycast_distance), # N #Vector3(max_raycast_distance, 0, max_raycast_distance), # NW #Vector3(max_raycast_distance, 0, 0), # W #Vector3(max_raycast_distance, 0, -max_raycast_distance), # SW #Vector3(0, 0, -max_raycast_distance), # S #Vector3(-max_raycast_distance, 0, -max_raycast_distance), # SE #Vector3(-max_raycast_distance, 0, 0), # E #Vector3(-max_raycast_distance, 0, max_raycast_distance), # NE #Vector3(0, max_raycast_distance, 0), # U # Vector3(0, max_raycast_distance, max_raycast_distance), # U 45° # Vector3(0, -max_raycast_distance, 0), # D #] var raycasts_coords: Array[Vector3] = [] # this is the soundsource audioplayer. var soundsource: Soundsource # internal vars var do_update: bool = false var tick_interval: int var _tick_counter: int = -1 # initialize the counter with enough time for the engine to initialize var _debug: Dictionary var debugsphere: Node3D var fade_tween: Tween var lowpass_tween: Tween var xfadetime: float = 1.000 enum fx {delay, reverb, reverb_hipass, lowpass} func _ready(): # add soundsource soundsource = Soundsource.new() # @export variables are overridden on _init, so we pass them right after to have the actual values # @export vars soundsource.loop = loop soundsource.shut_up = shut_up soundsource.debug = debug soundsource.audiophysics_ticks = audiophysics_ticks soundsource.speed_of_sound = speed_of_sound soundsource.max_raycast_distance = max_raycast_distance soundsource.roomsize_multiplicator = roomsize_multiplicator soundsource.collision_mask = collision_mask soundsource.reverb_enabled = reverb_enabled soundsource.reverb_volume_db = reverb_volume_db soundsource.bass_proximity = bass_proximity soundsource.reverb_fadeintime = reverb_fadeintime soundsource.reverb_fadeouttime = reverb_fadeouttime soundsource.occlusion_lp_cutoff = occlusion_lp_cutoff soundsource.occlusion_fadetime = occlusion_fadetime soundsource.reverb_raycast_count = reverb_raycast_count # module vars soundsource.name = name soundsource.stream = stream soundsource.volume_db = volume_db soundsource.max_polyphony = max_polyphony soundsource.doppler_tracking = doppler_tracking soundsource.soundsource = soundsource add_child(soundsource) # this calls _ready(), so vars needs to be set before add_child() # but position can only be set when node is in tree, e.g. after add_child() # calculate how often (physics-frames) we run tick_interval = max(0, roundi(Engine.physics_ticks_per_second / max(1, audiophysics_ticks))) # start playing on autoplay if autoplay: stop() await get_tree().create_timer(0.1).timeout # reverbers aren't ready. soundsource.do_play() func _physics_process(_delta): # keep rotation locked global_rotation = Vector3(0, 0, 0) if _tick_counter >= tick_interval: soundsource.update_run() _tick_counter = 0 # update tick _tick_counter += 1 func do_play(): soundsource.do_play() func do_stop(): soundsource.do_stop() func do_set_stream(sound: AudioStream): soundsource.do_set_stream(sound) func create_raycast(name_p, target_position) -> RayCast3D: var r = RayCast3D.new() r.name = name_p r.target_position = target_position r.collision_mask = collision_mask r.enabled = false return r func create_raycast_sector(start_angle: int = 0, width_factor: float = 1.5, bearing_raycount: int = 20, heading_count: int = 7) -> Array[RayCast3D]: var rays: Array[RayCast3D] = [] var i = 0 for heading: float in range(0, heading_count, 1): # 0: ground, 7: above heading = heading/PI for bearing: float in range((bearing_raycount/2.0 * -1), (bearing_raycount/2.0)): # -7: right, 7: left bearing = bearing / bearing_raycount * width_factor var mr = RayCast3D.new() mr.name = "mray" + str(i) add_child(mr) mr.target_position = Vector3(max_raycast_distance, 0, 0) mr.collision_mask = collision_mask mr.debug_shape_custom_color = Color("#ff0") mr.debug_shape_thickness = 1 mr.rotation = Vector3(0, bearing, heading) + Vector3(0, deg_to_rad(-start_angle), 0) mr.enabled = false if debug: var dray = Debugray.new() dray.visibility_range_end = max_raycast_distance dray.visibility_range_end_margin = max_raycast_distance / 10.0 dray.visibility_range_fade_mode = GeometryInstance3D.VISIBILITY_RANGE_FADE_SELF mr.add_child(dray) rays.append(mr) i += 1 return rays func create_soundplayer(name_p: String, with_reverb_fx: bool = true) -> Soundplayer: var soundplayer := Soundplayer.new() # @export vars soundplayer.loop = loop soundplayer.shut_up = shut_up soundplayer.debug = debug soundplayer.audiophysics_ticks = audiophysics_ticks soundplayer.speed_of_sound = speed_of_sound soundplayer.max_raycast_distance = max_raycast_distance soundplayer.roomsize_multiplicator = roomsize_multiplicator soundplayer.reverb_enabled = reverb_enabled soundplayer.reverb_volume_db = reverb_volume_db soundplayer.bass_proximity = bass_proximity soundplayer.reverb_fadeintime = reverb_fadeintime soundplayer.reverb_fadeouttime = reverb_fadeouttime soundplayer.occlusion_lp_cutoff = occlusion_lp_cutoff soundplayer.occlusion_fadetime = occlusion_fadetime # module vars soundplayer.name = name_p soundplayer.stream = stream soundplayer.volume_db = volume_db soundplayer.max_polyphony = max_polyphony # BUG: Doppler-tracking interferes with set_delay. # The delay only grows bigger and bigger when doppler-tracking is used, so we won't use it for now. soundplayer.doppler_tracking = AudioStreamPlayer3D.DOPPLER_TRACKING_DISABLED soundplayer.with_reverb_fx = with_reverb_fx soundplayer.soundsource = soundsource return soundplayer func create_audiobus(bus_name, vol_db = 0): var a = AudioServer.bus_count AudioServer.add_bus(a) AudioServer.set_bus_name(a, bus_name) AudioServer.set_bus_volume_db(a, vol_db) AudioServer.set_bus_send(a, "Master") func remove_audiobus(bus_name: String): #print("removing bus ", bus_name) var a = AudioServer.get_bus_index(bus_name) AudioServer.remove_bus(a) ## sets the volume. ## if you provide fadetime, it will fade to volume using an internal tweener. ## if you need to fade more than one value at a time in this player, you can provide a tweener. func set_audiobus_volume(bus_name, vol_db, fadetime: float = 0, tweenvar: Tween = null): #if debug: print("set_audiobus_volume(%s, %f, %f)" % [bus_name, vol_db, fadetime]) var a = AudioServer.get_bus_index(bus_name) if fadetime == 0: AudioServer.set_bus_volume_db(a, vol_db) else: var current_volume = AudioServer.get_bus_volume_db(a) if tweenvar: tweenvar.play() tweenvar.tween_method(tweensetvol.bind(a), current_volume, vol_db, fadetime) else: if fade_tween: fade_tween.kill() fade_tween = create_tween() fade_tween.tween_method(tweensetvol.bind(a), current_volume, vol_db, fadetime) # this is a little helper method for tweening. # tween_method always tweens the first value. # but the first value in set_bus_volume_db() is bus index, so we provide volume as the first value for tween_method. func tweensetvol(vol, bus_index): AudioServer.set_bus_volume_db(bus_index, vol) func add_audioeffect(bus_name, effect_type: fx): var a = AudioServer.get_bus_index(bus_name) match effect_type: fx.delay: var delay = AudioEffectDelay.new() delay.dry = 0 delay.tap1_delay_ms = 0 delay.tap1_level_db = 0 delay.tap1_pan = 0 delay.tap2_active = false AudioServer.add_bus_effect(a, delay, 0) fx.reverb: var reverb = AudioEffectReverb.new() reverb.dry = 0 reverb.spread = 0 reverb.hipass = 0.2 reverb.dry = 0 reverb.wet = 1 reverb.predelay_feedback = 0 AudioServer.add_bus_effect(a, reverb, 1) fx.lowpass: var lowpass = AudioEffectLowPassFilter.new() lowpass.cutoff_hz = 20500 AudioServer.add_bus_effect(a, lowpass, 2) func set_audioeffect(bus_name, effect_type: fx, params): #if debug: print("set_audioeffect(%s, %s, %s)" % [bus_name, effect_type, JSON.stringify(params)]) var a = AudioServer.get_bus_index(bus_name) match effect_type: fx.delay: var delay_fx = AudioServer.get_bus_effect(a, 0) delay_fx.tap1_delay_ms = params.delay fx.reverb: var reverb_fx = AudioServer.get_bus_effect(a, 1) reverb_fx.room_size = params.room_size reverb_fx.wet = params.wetness reverb_fx.dry = 1 - params.wetness fx.reverb_hipass: var reverb_hipass_fx = AudioServer.get_bus_effect(a, 1) reverb_hipass_fx.hipass = params.hipass fx.lowpass: var lowpass_fx = AudioServer.get_bus_effect(a, 2) if params.fadetime == 0: lowpass_fx.cutoff_hz = params.lowpass else: if params.fadetime > 0: if lowpass_tween: lowpass_tween.kill() lowpass_tween = create_tween() # fading in higher frequencies (20'000 - 6'000) is less noticeable than fading in the lower frequencies. if params.lowpass < lowpass_fx.cutoff_hz: # fade fast through the higher frequencies lowpass_tween.set_ease(Tween.EASE_OUT) else: lowpass_tween.set_ease(Tween.EASE_IN) # we are low, start slowly lowpass_tween.set_trans(Tween.TRANS_QUINT) lowpass_tween.tween_property(lowpass_fx, "cutoff_hz", params.lowpass, float(params.fadetime)).from_current() else: push_error("ERROR: fadetime not set in SpatialAudioStreamPlayer3D --> set_audioeffect --> fx.lowpass!") func toggle_audioeffect(bus_name, effect_type: fx, enabled): var a = AudioServer.get_bus_index(bus_name) match effect_type: fx.delay: AudioServer.set_bus_effect_enabled(a, 0, enabled) fx.reverb: AudioServer.set_bus_effect_enabled(a, 1, enabled) fx.lowpass: AudioServer.set_bus_effect_enabled(a, 2, enabled) func calculate_delay(distance: float): return round(distance / speed_of_sound * 1000) # Soundsource: # responsible for: positions and distances # room size and wetness (calc_reverb) # performs calculations over all raycasts/reverbers every X (0.5) seconds # reverber.update_position() # spawns reverbers class Soundsource extends SpatialAudio3D: var raycasts: Array[RayCast3D] var reverbers: Array[Reverber] var measurement_rays: Array[RayCast3D] var distances: Array[float] var distance_to_player: float var distance_to_player_since_last_delay_update: float var delay_ms: set(v): if delay_ms != v: delay_ms = v var _soundplayer_active := soundplayer_active var _soundplayer_standby := soundplayer_standby if soundplayer_active.state == soundplayer_active.ss.active: soundplayer_standby.delay_ms = v soundplayer_active.set_inactive(xfadetime) soundplayer_standby.set_active(xfadetime) soundplayer_active = _soundplayer_standby soundplayer_standby = _soundplayer_active var room_size = 0.0 var wetness = 1.0 var soundplayer_active: Soundplayer var soundplayer_standby: Soundplayer var _is_playing_starting: bool = false func _ready(): if debug: #print("spawning soundsource: ", name) var ds = Debugsphere.new() ds.max_raycast_distance = max_raycast_distance ds.size = 0.0 ds.label_offset = Vector3(0, 3, 0) ds.name = "Debugsphere " + name add_child(ds) debugsphere = ds ds.line1 = "☼ " + name # create soundplayers for delay-crossfading soundplayer_active = create_soundplayer(name + "-A", false) soundplayer_standby = create_soundplayer(name + "-B", false) add_child(soundplayer_active) add_child(soundplayer_standby) # set one active soundplayer_active.set_active() soundplayer_standby.set_inactive() # Only create raycasts, reverbers and measurement rays when reverb is enabled if reverb_enabled: var angle_step = TAU / float(reverb_raycast_count) for i in range(reverb_raycast_count): var angle = i * angle_step # Calculate points in a circle around the Y axis var target = Vector3(sin(angle), 0, cos(angle)) * max_raycast_distance raycasts_coords.append(target) # Add the ceiling (UP) raycast raycasts_coords.append(Vector3(0, max_raycast_distance, 0)) # create raycasts var raycast_index = 0 for c in raycasts_coords: var rc = create_raycast("ray " + name + "#" + str(raycast_index), c) var dray = Debugray.new() dray.visibility_range_end = max_raycast_distance * 1.3 dray.visibility_range_end_margin = max_raycast_distance / 10.0 dray.visibility_range_fade_mode = GeometryInstance3D.VISIBILITY_RANGE_FADE_SELF rc.add_child(dray) var dray_normal = Debugray.new() rc.add_child(dray_normal) add_child(rc) raycasts.append(rc) # create reverbers raycast_index = 0 for rc in raycasts: var reverber = create_reverber(name, raycast_index) get_tree().get_root().add_child.call_deferred(reverber) reverbers.append(reverber) raycast_index += 1 # create measurement rays measurement_rays = create_raycast_sector(0, 2*PI, 12, 3) for mr in measurement_rays: distances.append(-1) func _physics_process(_delta): if debug: dump_debug() debugsphere.update_label() func _exit_tree(): for r in reverbers: r.queue_free() for c in get_children(): remove_child(c) func create_reverber(name_p, raycast_index: int) -> Reverber: var reverber := Reverber.new() # @export vars reverber.loop = loop reverber.shut_up = shut_up reverber.debug = debug reverber.audiophysics_ticks = audiophysics_ticks reverber.speed_of_sound = speed_of_sound reverber.max_raycast_distance = max_raycast_distance reverber.roomsize_multiplicator = roomsize_multiplicator reverber.reverb_enabled = reverb_enabled reverber.reverb_volume_db = reverb_volume_db reverber.bass_proximity = bass_proximity reverber.reverb_fadeintime = reverb_fadeintime reverber.reverb_fadeouttime = reverb_fadeouttime reverber.occlusion_lp_cutoff = occlusion_lp_cutoff reverber.occlusion_fadetime = occlusion_fadetime # module vars reverber.name = name_p reverber.stream = stream reverber.volume_db = volume_db reverber.max_polyphony = max_polyphony reverber.soundsource = soundsource # reverber vars reverber.raycast_index = raycast_index return reverber func do_set_stream(s: AudioStream): stream = s soundplayer_active.stream = s soundplayer_standby.stream = s if reverb_enabled: for r in reverbers: if r != null: r.soundplayer_active.stream = s r.soundplayer_standby.stream = s func do_play(): if shut_up: return # when playing finishes, signals from all soundplayers are being emitted at the same time. # we just want to trigger ONE do_play() when looping is enabled. if _is_playing_starting: return _is_playing_starting = true call_deferred("_clear_play_lock") if reverb_enabled: for r in reverbers: r.do_play() # start play on both soundplayer_active.do_play() soundplayer_standby.do_play() func _clear_play_lock(): _is_playing_starting = false func do_stop(): if reverb_enabled: for r in reverbers: r.do_stop() soundplayer_active.do_stop() soundplayer_standby.do_stop() func update_run(): distance_to_player = global_position.distance_to(player_camera.global_position) # only update delay when moved >5m since last update if abs(distance_to_player - distance_to_player_since_last_delay_update) > 5: delay_ms = calculate_delay(distance_to_player) distance_to_player_since_last_delay_update = distance_to_player # calculate my occlusion soundplayer_active.update_effect_params() if reverb_enabled: # update distances for all reverbers calculate_all_distances() # calculate room_size and wetness for reverbers calculate_reverb() func calculate_all_distances(): var raycast_index = 0 for reverber in reverbers: var rc := raycasts[raycast_index] var target_position: Vector3 var colliding = false var dray: Debugray = rc.get_child(0) var dray_normal: Debugray = rc.get_child(1) # if raycast is colliding and the angle between raycast and normal is "over 2.5 radians" (3.14 == exact 180° reflection; 2.5 == somewhat 30° tolerance) rc.force_raycast_update() if rc.is_colliding() and (rc.get_collision_normal().angle_to(rc.target_position) > 1.5): # position reverber 10cm away from the collision/wall, otherwise occlusion detection doesn't work target_position = rc.get_collision_point() + rc.get_collision_normal() * 0.1 colliding = true if debug: dray.draw(position, to_local(target_position), "#f00") if debug: dray_normal.draw(to_local(rc.get_collision_point() + rc.get_collision_normal() * 0.1), to_local(rc.get_collision_point() + rc.get_collision_normal()), "#0f0") else: target_position = rc.target_position * 100 # move the inactive point far far away if debug: dray.clear() if debug: dray_normal.clear() reverber.update_position(target_position, colliding) raycast_index += 1 # measure room using measurement rays var ri = 0 for mr in measurement_rays: mr.force_raycast_update() if mr.is_colliding(): distances[ri] = global_position.distance_to(mr.get_collision_point()) #if debug: #@warning_ignore("unsafe_method_access") #mr.get_child(0).draw(position, to_local(mr.target_position) + global_position, "#00f3") else: distances[ri] = -1 #if debug: #@warning_ignore("unsafe_method_access") #mr.get_child(0).draw(position, to_local(mr.target_position) + global_position, "#ff01") ri += 1 func calculate_reverb(): # Find the reverb params var _room_size = 0.0 var _wetness = 1.0 var total_rays = distances.size() for distance in distances: if distance >= 0: # find the average room size based on the raycast distances that are valid _room_size += (distance / (max_raycast_distance / roomsize_multiplicator)) / float(total_rays) _room_size = snappedf(_room_size, 0.001) _room_size = min(_room_size, 1.0) _room_size = max(_room_size, .4) else: # if a raycast did not hit anything we will reduce the reverb effect, almost no raycasts should hit when outdoors nowhere near buildings _wetness -= 1.0 / float(distances.size()) _wetness = snappedf(_wetness, 0.001) _wetness = max(_wetness, 0.0) room_size = _room_size wetness = _wetness if debug: debugsphere.line2 = "Room size: %.3f" % room_size debugsphere.line3 = "Wetness: %.3f" % wetness # Reverber: # responsible for playing and positioning Soundplayers class Reverber extends SpatialAudio3D: var raycast_index: int var distance_to_soundsource: float var distance_to_player: float var soundplayer_active: Soundplayer var soundplayer_standby: Soundplayer func _ready(): name = name + "#" + str(raycast_index) # create reverb-soundplayers for AB-reverb soundplayer_active = create_soundplayer(name + "-A") soundplayer_standby = create_soundplayer(name + "-B") get_tree().get_root().add_child(soundplayer_active) get_tree().get_root().add_child(soundplayer_standby) func _exit_tree(): soundplayer_active.queue_free() soundplayer_standby.queue_free() # don't inherit this from SpatialAudio3D func _physics_process(_delta): pass func do_play(): soundplayer_active.do_play() soundplayer_standby.do_play() func do_stop(): soundplayer_active.do_stop() soundplayer_standby.do_stop() func update_position(target_position: Vector3, colliding: bool): var _soundplayer_active := soundplayer_active var _soundplayer_standby := soundplayer_standby var fadeintime = 1 * soundsource.wetness if reverb_fadeintime < 0 else reverb_fadeintime var fadeouttime = 3 * soundsource.wetness if reverb_fadeouttime < 0 else reverb_fadeouttime # make sure inactive soundplayers stay silent soundplayer_standby.set_inactive() if global_position.distance_to(target_position) > 10: global_position = target_position soundplayer_active.set_inactive(fadeouttime) soundplayer_standby.target_position = target_position if colliding: soundplayer_standby.set_active(fadeintime) soundplayer_active = _soundplayer_standby soundplayer_standby = _soundplayer_active elif global_position.distance_to(target_position) > 0.3: global_position = target_position soundplayer_active.update_effect_params() soundplayer_active.target_position = target_position # update effects on colliding (active) soundplayers if colliding: soundplayer_active.update_effect_params() # Soundplayer is the actual player that plays a sound. # This is because the Soundsource as well as the reverbers need two players and fade between them, # e.g. for letting the reverb hall playing out and not stopping abruptly, or for crossfading between different delays. # responsible for setup and teardown audio bus, volume, effect parameters and occlusion detection. class Soundplayer extends SpatialAudio3D: var ds = {0: "active", 1: "inactive", 2: "fading_to_active", 3: "fading_to_inactive"} enum ss {active, inactive, fading_to_active, fading_to_inactive} var with_reverb_fx: bool var state: ss: set(v): if state != v: state = v #if debug: debugsphere.line4 = ds[v] #if debug: print("%s: %s --> %s" % [name, ds[state], ds[v]]) var distance_to_soundsource: float var distance_to_player: float var target_position: Vector3: set(v): if target_position != v: if state != ss.fading_to_inactive: target_position = v global_position = v var delay_ms: int: set(v): if abs(delay_ms - v) > 10 and (Time.get_ticks_msec() - delay_updated_at) > 1000: delay_ms = v delay_updated_at = Time.get_ticks_msec() if debug: debugsphere.line2 = "%s ms" % delay_ms if state != ss.fading_to_inactive: set_audioeffect(audiobus_name, fx.delay, {"delay": delay_ms}) var delay_updated_at: int var room_size: float: set(v): if room_size != v: room_size = v if state != ss.fading_to_inactive: set_audioeffect(audiobus_name, fx.reverb, {"room_size": room_size, "wetness": wetness}) var wetness: float: set(v): if wetness != v: wetness = v # audioeffect is already set together with room_size var proximity_volume: float: set(v): if abs(proximity_volume - v) > 0.1: proximity_volume = v if debug: debugsphere.line3 = "%d dB" % v if state == ss.active: set_audiobus_volume(audiobus_name, proximity_volume) var proximity_bass: float: set(v): if proximity_bass != v: proximity_bass = v if state != ss.fading_to_inactive: set_audioeffect(audiobus_name, fx.reverb_hipass, {"hipass": proximity_bass}) var lp_cutoff: int: set(v): if abs(lp_cutoff - v) > 20: lp_cutoff = v if debug: debugsphere.line4 = "occluded" if v != 20500 else "" set_audioeffect(audiobus_name, fx.lowpass, {"lowpass": lp_cutoff, "fadetime": occlusion_fadetime}) var occlusion_raycast: RayCast3D var audiobus_name: String var _fade_generation: int = 0 var _is_valid: bool = true func _ready(): if debug: #print("spawning soundplayer: ", name) debugsphere = Debugsphere.new() debugsphere.max_raycast_distance = max_raycast_distance debugsphere.name = "Debugsphere " + name debugsphere.line1 = "♬" add_child(debugsphere) debugsphere.visible = false # ensure unique name for the mixer audiobus_name = "%s-%s" % [name, get_instance_id()] # create bus and add effects to it create_audiobus(audiobus_name) add_audioeffect(audiobus_name, fx.delay) add_audioeffect(audiobus_name, fx.reverb) if with_reverb_fx == false: toggle_audioeffect(audiobus_name, fx.reverb, false) add_audioeffect(audiobus_name, fx.lowpass) # set initial state to inactive and mute state = ss.inactive set_audiobus_volume(audiobus_name, -80) # set volume according to AudioStreamPlayer3D param proximity_volume = volume_db # set my bus to this newly created bus. bus = audiobus_name # create raycast for occlusion test occlusion_raycast = create_raycast("occray for " + name, position) add_child(occlusion_raycast) # connect signal (used to restart playing if loop is enabled) finished.connect(_on_finished) func _on_finished(): if loop: soundsource.do_play() func _physics_process(_delta): if debug: dump_debug() debugsphere.update_label() func _exit_tree(): _is_valid = false if fade_tween: fade_tween.kill() if lowpass_tween: lowpass_tween.kill() remove_audiobus(audiobus_name) for c in get_children(): remove_child(c) func do_play(): #if debug: printerr(str(Time.get_ticks_msec()) + ": start playing on " + name + ", stream: " + str(stream)) play() func do_stop(): #if debug: printerr(str(Time.get_ticks_msec()) + ": stop playing on " + name + ", stream: " + str(stream)) stop() func set_active(fadetime: float = 0, easing: Tween.EaseType = Tween.EASE_OUT, transition: Tween.TransitionType = Tween.TRANS_QUART): #if debug: print("SET ACTIVE: %s (state: %s, fadetime: %s)" % [name, ds[state], fadetime]) if state == ss.inactive: if debug: debugsphere.visible = true update_effect_params() if fadetime > 0: # stamp this coroutine's generation before yielding. # If set_inactive (or another set_active) is called while we await, # it will increment _fade_generation, and we will bail on resume # instead of overwriting the new state with ss.active. _fade_generation += 1 var my_generation := _fade_generation state = ss.fading_to_active if fade_tween: fade_tween.kill() fade_tween = create_tween() fade_tween.stop() fade_tween.set_ease(easing) fade_tween.set_trans(transition) set_audiobus_volume(audiobus_name, proximity_volume, fadetime, fade_tween) await fade_tween.finished # bail if we were superseded or the node is being freed. if _fade_generation != my_generation or not _is_valid: return else: set_audiobus_volume(audiobus_name, proximity_volume) state = ss.active func set_inactive(fadetime: float = 0, easing: Tween.EaseType = Tween.EASE_IN, transition: Tween.TransitionType = Tween.TRANS_QUINT): #if debug: print("SET INACTIVE: %s (state: %s, fadetime: %s)" % [name, ds[state], fadetime]) if state == ss.active or state == ss.fading_to_active: if fadetime > 0: # increment generation to invalidate any concurrent set_active coroutine. _fade_generation += 1 var my_generation := _fade_generation state = ss.fading_to_inactive if fade_tween: fade_tween.kill() fade_tween = create_tween() fade_tween.stop() fade_tween.set_ease(easing) fade_tween.set_trans(transition) set_audiobus_volume(audiobus_name, -80, fadetime, fade_tween) await fade_tween.finished # bail if we were superseded or the node is being freed. if _fade_generation != my_generation or not _is_valid: return else: set_audiobus_volume(audiobus_name, -80) state = ss.inactive if debug: debugsphere.visible = false func update_effect_params(): # update distance vars distance_to_soundsource = global_position.distance_to(soundsource.global_position) distance_to_player = global_position.distance_to(player_camera.global_position) # occlusion lp_cutoff = calculate_occlusion_lowpass() # only calculate reverb effects on reverbers, not soundsource soundplayers. # soundsource will set delay on soundsource-soundplayers. if with_reverb_fx: # calculate and set delay delay_ms = calculate_delay(distance_to_soundsource) + calculate_delay(distance_to_player) # roomsize & wetness room_size = soundsource.room_size wetness = soundsource.wetness # set volume. further away = louder. # (without tuning, in small rooms, reverb is overwhelming, but you can't hear echo far away) proximity_volume = calculate_proximity_volume() # set proximity bass # more bass if closer to the wall, effect begins at 50m to a wall # hipass = 0.2 proximity_bass = calculate_proximity_bass() # turn down reverb volume by [reduction] dB when closer to the wall func calculate_proximity_volume(): var proximity_reduction = prox_reduction var max_volume = reverb_volume_db + volume_db # calculate reduction based on the ratio player-to-max_raycast_distance and player-to-soundsource. # the closer you are to a wall, the less reverb should be heard. the further away you are, the more it should be audible. # the further away the soundsource is, the less reverb should be heard. var ratio_player_rc = min(1, distance_to_player / max_raycast_distance) var ratio_player_ss = min(1, distance_to_player / distance_to_soundsource) var prox_volume = (proximity_reduction * ratio_player_rc + proximity_reduction * ratio_player_ss) / 2 - proximity_reduction # add soundsource max_volume prox_volume = prox_volume + max_volume # limit maximum volume to max_volume prox_volume = min(prox_volume, max_volume) return prox_volume func calculate_proximity_bass(): return snappedf(min(0.2 * distance_to_player / max(bass_proximity, 0.001), 0.2), 0.001) func calculate_occlusion_lowpass(): var limited_distance_to_player = clamp(distance_to_player, 0, max_raycast_distance) occlusion_raycast.target_position = global_position.direction_to(player_camera.global_position) * max_raycast_distance * 10 var _cutoff = 20500 occlusion_raycast.force_raycast_update() if occlusion_raycast.is_colliding(): var collision_point = occlusion_raycast.get_collision_point() var ray_distance = collision_point.distance_to(global_position) var wall_to_player_ratio = ray_distance / max(distance_to_player, 0.001) if ray_distance < distance_to_player: _cutoff = snappedf(occlusion_lp_cutoff * wall_to_player_ratio, 0.001) return _cutoff class Debugsphere extends Node3D: var color: Color = "00f" var size: float = 0.5 var max_raycast_distance: int var label = Label3D var line1: String var line2: String var line3: String var line4: String var label_offset: Vector3 func _ready(): # size 0 means label-only: a degenerate SphereMesh floods "Vector3 cannot be normalized" warnings per vertex if size > 0: var meshinstance = MeshInstance3D.new() var spheremesh = SphereMesh.new() var mat = StandardMaterial3D.new() mat.albedo_color = color #mat.shading_mode = BaseMaterial3D.SHADING_MODE_UNSHADED #mat.fixed_size = true spheremesh.material = mat #meshinstance.cast_shadow = false spheremesh.radius = size / 2 spheremesh.height = size meshinstance.mesh = spheremesh meshinstance.visibility_range_end = max_raycast_distance * 1.3 meshinstance.visibility_range_end_margin = max_raycast_distance / 10.0 meshinstance.visibility_range_fade_mode = GeometryInstance3D.VISIBILITY_RANGE_FADE_SELF add_child(meshinstance) # create second sphere without depth-test, displayed when occluded var occluded_meshinstance = MeshInstance3D.new() var occluded_spheremesh = SphereMesh.new() var occluded_mat = StandardMaterial3D.new() occluded_mat.albedo_color = Color(color, 0.2) #occluded_mat.fixed_size = true occluded_mat.no_depth_test = true occluded_mat.transparency = BaseMaterial3D.TRANSPARENCY_ALPHA occluded_spheremesh.material = occluded_mat occluded_meshinstance.cast_shadow = false occluded_spheremesh.radius = size / 2 occluded_spheremesh.height = size occluded_meshinstance.mesh = occluded_spheremesh occluded_meshinstance.visibility_range_end = max_raycast_distance * 1.3 occluded_meshinstance.visibility_range_end_margin = max_raycast_distance / 10.0 occluded_meshinstance.visibility_range_fade_mode = GeometryInstance3D.VISIBILITY_RANGE_FADE_SELF add_child(occluded_meshinstance) # create label3d label = Label3D.new() label.position = label_offset label.billboard = BaseMaterial3D.BILLBOARD_ENABLED label.fixed_size = true label.no_depth_test = true label.pixel_size = 0.0005 label.font_size = 50 label.text = "" label.visibility_range_end = max_raycast_distance * 1.3 label.visibility_range_end_margin = max_raycast_distance / 10.0 label.visibility_range_fade_mode = GeometryInstance3D.VISIBILITY_RANGE_FADE_SELF add_child(label) func update_label(): label.text = line1 + "\n" + line2 + "\n" + line3 + "\n" + line4 class Debugray extends MeshInstance3D: var immediate_mesh: ImmediateMesh var material: ORMMaterial3D func _ready(): immediate_mesh = ImmediateMesh.new() material = ORMMaterial3D.new() material.shading_mode = BaseMaterial3D.SHADING_MODE_UNSHADED mesh = immediate_mesh cast_shadow = GeometryInstance3D.SHADOW_CASTING_SETTING_OFF func draw(pos1: Vector3, pos2: Vector3, color: Color): clear() immediate_mesh.surface_begin(Mesh.PRIMITIVE_LINES, material) immediate_mesh.surface_add_vertex(pos1) immediate_mesh.surface_add_vertex(pos2) immediate_mesh.surface_end() material.albedo_color = color material.transparency = BaseMaterial3D.TRANSPARENCY_ALPHA func clear(): immediate_mesh.clear_surfaces() func dump_debug(): var _s = "" for key in _debug: _s += "%s: %s\n" % [key, JSON.stringify(_debug[key], " ")] if _s != "": var ad = get_tree().get_root().find_child("AudioDebug") if ad: ad.text = _s func print_r(obj): if obj is Object: obj = inst_to_dict(obj) print(JSON.stringify(obj, " "))