Feature: client SFX playback for unit animations

- SFX.gd autoload: fire-and-forget CDN audio player with 8-slot pool,
  session-level stream cache, OGG/MP3 support via HTTPRequest download,
  uses Settings BUS_SFX so volume/mute work automatically
- Register SFX in project.godot autoloads
- game_screen.gd:
  - _sfx_for_unit(iid, key) helper — looks up CardDefinition SFX URL
    from ContentCache using the unit's def ID
  - Attack sound: played when player initiates attack + counter-attack
  - Damaged sound: played at all damage animation sites (immediate,
    delayed bystander, post-attack callback, counter-chain)
  - Death sound: played when dying animation fires
  - Move sound: played when movement animation starts

Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>
This commit is contained in:
dingo
2026-03-17 13:30:39 -04:00
co-authored by Claude Happy
parent c105120dc6
commit ea3293e9c5
3 changed files with 108 additions and 2 deletions
+84
View File
@@ -0,0 +1,84 @@
extends Node
## SFX autoload — fire-and-forget sound effects from CDN URLs.
##
## Usage:
## SFX.play("https://cdn.sor.gg/sfx/attack.ogg") # fire-and-forget
##
## 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 # max simultaneous SFX
var _pool : Array[AudioStreamPlayer] = []
var _cache : Dictionary = {} # url → AudioStream
# ── Lifecycle ─────────────────────────────────────────────────────────────────
func _ready() -> void:
for _i in POOL_SIZE:
var p := AudioStreamPlayer.new()
p.bus = Settings.BUS_SFX
add_child(p)
_pool.append(p)
# ── Public API ────────────────────────────────────────────────────────────────
## Play [param url] asynchronously (fire-and-forget).
## No-ops if url is empty or the download fails.
func play(url: String) -> void:
if url.is_empty():
return
_play_async(url)
# ── Internal ──────────────────────────────────────────────────────────────────
func _play_async(url: String) -> void:
var stream : AudioStream = _cache.get(url, null)
if stream == null:
stream = await _load_stream(url)
if stream == null:
return
_cache[url] = stream
var player := _get_free_player()
player.stream = stream
player.play()
func _get_free_player() -> AudioStreamPlayer:
for p : AudioStreamPlayer in _pool:
if not p.playing:
return p
# All slots busy — steal the oldest (index 0, round-robin would be nicer
# but overkill for 8-slot game SFX).
return _pool[0]
func _load_stream(url: String) -> AudioStream:
if url.begins_with("res://") or url.begins_with("user://"):
return load(url) as AudioStream
var http := HTTPRequest.new()
add_child(http)
http.request(url)
var result : Array = await http.request_completed
http.queue_free()
var response_code : 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)
elif ext == "mp3":
var s := AudioStreamMP3.new()
s.data = body
return s
push_warning("SFX: unsupported format '%s' — use OGG or MP3." % ext)
return null
+1
View File
@@ -26,6 +26,7 @@ Settings="*res://autoloads/Settings.gd"
Game="*res://autoloads/Game.gd"
ModelCache="*res://autoloads/ModelCache.gd"
Music="*res://autoloads/Music.gd"
SFX="*res://autoloads/SFX.gd"
[display]
@@ -1106,6 +1106,16 @@ func _play_unit_anim(iid: String, action: String, loop: bool = false) -> void:
_oneshot_callbacks[iid] = os_cb
## Returns the SFX CDN URL for a given unit and sound key, or "" if none assigned.
## [param sfx_key] is the camelCase DTO field name, e.g. "attackSoundUrl".
func _sfx_for_unit(iid: String, sfx_key: String) -> String:
var def_id : String = _unit_def_ids.get(iid, "")
if def_id.is_empty():
return ""
var def := ContentCache.get_definition(def_id)
return str(def.get(sfx_key, ""))
## Returns true if the AnimationPlayer's current track is an "attack" animation.
func _is_attack_track(full_name: String) -> bool:
var s := full_name.get_slice("/", full_name.get_slice_count("/") - 1)
@@ -1137,12 +1147,14 @@ func _play_counter_attack(defender_iid: String, attacker_iid: String) -> void:
if not _unit_bodies.has(defender_iid): return
if not is_instance_valid(_unit_bodies.get(defender_iid) as Node): return
_play_unit_anim(defender_iid, "attack", false)
SFX.play(_sfx_for_unit(defender_iid, "attackSoundUrl"))
# After the counter-attack finishes: defender → idle, attacker → damaged.
_override_oneshot(defender_iid, func(_n: String) -> void:
_play_unit_anim(defender_iid, "idle", true)
if _unit_bodies.has(attacker_iid) and \
is_instance_valid(_unit_bodies.get(attacker_iid) as Node):
_play_unit_anim(attacker_iid, "damaged", false)
SFX.play(_sfx_for_unit(attacker_iid, "damagedSoundUrl"))
)
@@ -1155,6 +1167,7 @@ func _play_counter_chain(defender_iid: String, attacker_iid: String, delay: floa
not is_instance_valid(_unit_bodies.get(defender_iid) as Node):
return
_play_unit_anim(defender_iid, "damaged", false)
SFX.play(_sfx_for_unit(defender_iid, "damagedSoundUrl"))
_override_oneshot(defender_iid, func(_n: String) -> void:
_play_counter_attack(defender_iid, attacker_iid)
)
@@ -1244,6 +1257,7 @@ func _play_damage_animations(state: Dictionary) -> bool:
if _unit_bodies.has(hit_iid) and \
is_instance_valid(_unit_bodies.get(hit_iid) as Node):
_play_unit_anim(hit_iid, "damaged")
SFX.play(_sfx_for_unit(hit_iid, "damagedSoundUrl"))
).set_delay(attack_remaining)
else:
for iid: String in damaged_iids:
@@ -1258,7 +1272,9 @@ func _play_damage_animations(state: Dictionary) -> bool:
ap.animation_finished.disconnect(old_cb)
_oneshot_callbacks.erase(iid)
var cap_iid := iid
var dmg_cb := func(_n: String) -> void: _play_unit_anim(cap_iid, "damaged", false)
var dmg_cb := func(_n: String) -> void:
_play_unit_anim(cap_iid, "damaged", false)
SFX.play(_sfx_for_unit(cap_iid, "damagedSoundUrl"))
ap.animation_finished.connect(dmg_cb, CONNECT_ONE_SHOT)
_oneshot_callbacks[iid] = dmg_cb
elif attack_remaining > 0.0:
@@ -1269,12 +1285,15 @@ func _play_damage_animations(state: Dictionary) -> bool:
if _unit_bodies.has(hit_iid) and \
is_instance_valid(_unit_bodies.get(hit_iid) as Node):
_play_unit_anim(hit_iid, "damaged")
SFX.play(_sfx_for_unit(hit_iid, "damagedSoundUrl"))
).set_delay(attack_remaining)
else:
_play_unit_anim(iid, "damaged")
SFX.play(_sfx_for_unit(iid, "damagedSoundUrl"))
for iid: String in dying_iids:
_play_unit_anim(iid, "dying")
SFX.play(_sfx_for_unit(iid, "deathSoundUrl"))
return true
@@ -1350,8 +1369,9 @@ func _animate_unit_move(iid: String, from_coord: Vector2i, to_coord: Vector2i,
# Cancel any existing move tween for this unit.
if _move_anims.has(iid) and _move_anims[iid] != null:
(_move_anims[iid] as Tween).kill()
# Play the looping move animation.
# Play the looping move animation and its SFX.
_play_unit_anim(iid, "moving", true)
SFX.play(_sfx_for_unit(iid, "moveSoundUrl"))
# Pre-compute per-step facing angles so the closures capture the correct values.
var base_angle := float(_model_base_angles.get(iid, 0.0))
var prev_coord := from_coord
@@ -1730,6 +1750,7 @@ func _handle_board_click(mouse_pos: Vector2) -> void:
if _is_enemy_unit(unit_id):
_last_attack_target_iid = unit_id
_play_unit_anim(_sel_unit_id, "attack")
SFX.play(_sfx_for_unit(_sel_unit_id, "attackSoundUrl"))
Game.send_attack(_sel_unit_id, unit_id)
_set_mode(Mode.NONE)
elif unit_id == _sel_unit_id: