Files
2026-04-14 16:02:24 -04:00

133 lines
3.3 KiB
GDScript

extends Node
## SFX autoload - fire-and-forget sound effects from local assets or CDN URLs.
##
## Usage:
## SFX.play("https://cdn.example.com/sfx/attack.wav")
##
## Volume and mute are applied globally through the "SFX" AudioServer bus
## (managed by Settings.sfx_volume / Settings.sfx_muted).
## Downloaded streams are cached in memory for the session so each URL
## only hits the network once.
const POOL_SIZE := 8
var _pool: Array[AudioStreamPlayer] = []
var _cache: Dictionary = {}
var _in_flight: Dictionary = {}
func _ready() -> void:
for _i in POOL_SIZE:
var player := AudioStreamPlayer.new()
player.bus = Settings.BUS_SFX
add_child(player)
_pool.append(player)
func play(url: String) -> void:
url = url.strip_edges()
if not _is_supported_url(url):
return
_play_async(url)
func prime(url: String) -> void:
url = url.strip_edges()
if not _is_supported_url(url):
return
if _cache.has(url) or _in_flight.has(url):
return
_prime_async(url)
func _play_async(url: String) -> void:
var stream: AudioStream = _cache.get(url, null)
if stream == null:
if _in_flight.has(url):
await _in_flight[url]
stream = _cache.get(url, null)
else:
stream = await _load_and_cache(url)
if stream == null:
return
var player := _get_free_player()
player.stream = stream
player.play()
func _prime_async(url: String) -> void:
await _load_and_cache(url)
func _get_free_player() -> AudioStreamPlayer:
for player: AudioStreamPlayer in _pool:
if not player.playing:
return player
return _pool[0]
func _load_stream(url: String) -> AudioStream:
if url.begins_with("res://") or url.begins_with("user://"):
return load(url) as AudioStream
if not (url.begins_with("http://") or url.begins_with("https://")):
return null
var request_url := _normalize_remote_url(url)
var http := HTTPRequest.new()
add_child(http)
var err := http.request(request_url)
if err != OK:
http.queue_free()
push_warning("SFX: request failed for %s (err %d)" % [request_url, err])
return null
var result: Array = await http.request_completed
http.queue_free()
var response_code: int = int(result[1])
var body: PackedByteArray = result[3]
if response_code != 200 or body.is_empty():
push_warning("SFX: failed to download %s (HTTP %d)" % [url, response_code])
return null
var ext := url.get_extension().to_lower()
if ext == "ogg":
return AudioStreamOggVorbis.load_from_buffer(body)
if ext == "mp3":
var mp3 := AudioStreamMP3.new()
mp3.data = body
return mp3
if ext == "wav":
return AudioStreamWAV.load_from_buffer(body)
push_warning("SFX: unsupported format '%s' - use OGG, MP3, or WAV." % ext)
return null
func _normalize_remote_url(url: String) -> String:
return url.replace(" ", "%20")
func _is_supported_url(url: String) -> bool:
if url.is_empty() or url == "null":
return false
return url.begins_with("http://") or url.begins_with("https://") \
or url.begins_with("res://") or url.begins_with("user://")
func _load_and_cache(url: String) -> AudioStream:
if _cache.has(url):
return _cache[url] as AudioStream
if _in_flight.has(url):
while _in_flight.has(url):
await get_tree().process_frame
return _cache.get(url, null) as AudioStream
_in_flight[url] = true
var stream := await _load_stream(url)
_in_flight.erase(url)
if stream != null:
_cache[url] = stream
return stream