feat(sprint-19): AudioManager, floor music cross-fade, and SFX system

2026-05-10 20:19:55 +02:00
parent 2c0c8b3c42 2e0cd18b6e
commit 1d65bf21dc
18 changed files with 289 additions and 38 deletions
@@ -0,0 +1,65 @@
+# Audio Assets — Sprint 19
+
+Download these files manually from freesound.org and replace the empty placeholders under `assets/audio/`.
+
+All picks are CC0 (Public Domain) unless noted as CC-BY. CC-BY files require attribution in the game's credits / README.
+
+---
+
+## Music tracks
+
+| Target file | Freesound ID | Title | Author | License | Duration | URL |
+|---|---|---|---|---|---|---|
+| `assets/audio/music/floor_0.ogg` | 725019 | Kids Background - Happy Children (loop ver.2) | AudioCoffee | CC0 | ~60s loop | https://freesound.org/people/AudioCoffee/sounds/725019/ |
+| `assets/audio/music/floor_0.ogg` *(alt)* | 720612 | Kids - Children Background (loop) | AudioCoffee | CC0 | ~60s loop | https://freesound.org/people/AudioCoffee/sounds/720612/ |
+| `assets/audio/music/floor_1.ogg` | 387588 | Piano Ambiance 4 (120bpm) — Ambient Piano Loop 37 | Erokia | CC0 | loop | https://freesound.org/people/Erokia/sounds/387588/ |
+| `assets/audio/music/floor_1.ogg` *(alt)* | 384934 | Soft Piano Loop #1 | ispeakwaves | CC-BY 3.0 | loop | https://freesound.org/people/ispeakwaves/sounds/384934/ |
+| `assets/audio/music/floor_2.ogg` | 684511 | Simple Game Music Loop | Seth_Makes_Sounds | CC0 | loop | https://freesound.org/people/Seth_Makes_Sounds/sounds/684511/ |
+| `assets/audio/music/floor_2.ogg` *(alt)* | 387588 | Piano Ambiance 4 — use if floor_1 already taken | Erokia | CC0 | loop | https://freesound.org/people/Erokia/sounds/387588/ |
+| `assets/audio/music/floor_3.ogg` | 723913 | Forest birds - ambient seamless loop | Magnesus | CC0 | seamless loop | https://freesound.org/people/Magnesus/sounds/723913/ |
+| `assets/audio/music/floor_3.ogg` *(alt)* | 798842 | Morning Birds in a Quiet Urban Garden | WhisperingEarth | check page | field recording | https://freesound.org/people/WhisperingEarth/sounds/798842/ |
+
+> **floor_2.ogg note:** The nursery/lullaby track is the hardest to find as a pure CC0 loop. `Seth_Makes_Sounds/684511` is a gentle, simple game loop that works for a calm nursery atmosphere. If you want a proper lullaby feel, `ispeakwaves/384934` (Soft Piano Loop, CC-BY 3.0) is a better fit — just add attribution.
+
+---
+
+## SFX
+
+| Target file | Freesound ID | Title | Author | License | Duration | URL |
+|---|---|---|---|---|---|---|
+| `assets/audio/sfx/chest_tap.ogg` | 679772 | Knocking on Wood | ominouswhoosh | CC0 | ~0.3s | https://freesound.org/people/ominouswhoosh/sounds/679772/ |
+| `assets/audio/sfx/chest_tap.ogg` *(alt)* | 617056 | Tapping Wood 1 | F.M.Audio | CC0 | short | https://freesound.org/s/617056/ |
+| `assets/audio/sfx/item_spawn.ogg` | 683096 | Woosh | florianreichelt | CC0 | short | https://freesound.org/people/florianreichelt/sounds/683096/ |
+| `assets/audio/sfx/item_spawn.ogg` *(alt)* | 460473 | VS_Short Whoosh 8 | Vilkas_Sound | CC0 | short | https://freesound.org/people/Vilkas_Sound/sounds/460473/ |
+| `assets/audio/sfx/item_drag_start.ogg` | 411177 | Pick up Item 1 | SilverIllusionist | CC0 | short | https://freesound.org/people/SilverIllusionist/sounds/411177/ |
+| `assets/audio/sfx/item_drag_start.ogg` *(alt)* | 133280 | game pick up object | Leszek_Szary | CC0 | short | https://freesound.org/people/Leszek_Szary/sounds/133280/ |
+| `assets/audio/sfx/item_drop_hand.ogg` | 448086 | Normal click | Breviceps | CC0 | <0.2s | https://freesound.org/people/Breviceps/sounds/448086/ |
+| `assets/audio/sfx/item_drop_hand.ogg` *(alt)* | 580780 | Flashlight clicking sound | StrikeWhistler | CC0 | <0.2s | https://freesound.org/people/StrikeWhistler/sounds/580780/ |
+| `assets/audio/sfx/item_drop_outfit.ogg` | 161415 | cape-swoosh | CosmicEmbers | CC-BY 3.0 | short | https://freesound.org/people/CosmicEmbers/sounds/161415/ |
+| `assets/audio/sfx/item_drop_outfit.ogg` *(alt)* | 683096 | Woosh (florianreichelt) — softer pick | florianreichelt | CC0 | short | https://freesound.org/people/florianreichelt/sounds/683096/ |
+| `assets/audio/sfx/item_return_chest.ogg` | 740266 | soft button click 1 | FOSSarts | CC0 | <0.2s | https://freesound.org/people/FOSSarts/sounds/740266/ |
+| `assets/audio/sfx/item_return_chest.ogg` *(alt)* | 677860 | UI Button Click Snap | el_boss | CC0 | <0.2s | https://freesound.org/people/el_boss/sounds/677860/ |
+| `assets/audio/sfx/item_drop_floor.ogg` | 449955 | Wooden Thud (Mono) | Breviceps | CC0 | <0.3s | https://freesound.org/people/Breviceps/sounds/449955/ |
+| `assets/audio/sfx/item_drop_floor.ogg` *(alt)* | 342530 | Light Thud 4 | sgrowe | CC0 | <0.3s | https://freesound.org/people/sgrowe/sounds/342530/ |
+
+---
+
+## Download instructions
+
+1. Open each URL in a browser while logged in to freesound.org (free account required for download).
+2. Click "Download" and choose OGG format where available (or download as WAV and convert with Audacity/ffmpeg).
+3. Rename the file to match the "Target file" column and drop it into the repo, replacing the empty placeholder.
+4. For CC-BY files, add an entry to `docs/credits-audio.md` (create if it does not exist yet) with: `Author — Title — CC-BY 3.0 — URL`.
+
+## ffmpeg conversion (WAV to OGG)
+
+```
+ffmpeg -i input.wav -c:a libvorbis -q:a 4 output.ogg
+```
+
+## Notes
+
+- All CC0 picks require no attribution, but you may credit anyway.
+- Prefer the primary pick; use the alt only if the primary is unavailable or unsuitable on preview.
+- Keep music loops between 30–60 s to minimize file size on mobile.
+- SFX should be trimmed with a short (~5 ms) fade-out to avoid clicks.
@@ -1,63 +1,132 @@
-## AudioManager — music playback with cross-fade, SFX playback, volume control.
+## AudioManager — floor music with cross-fade and SFX for player interactions.
+## Autoload registered in project.godot. No class_name (Godot 4 autoload conflict).
 extends Node

-const DEFAULT_MUSIC_VOLUME: float = 0.6
-const CROSSFADE_DURATION: float = 1.0
+const CROSSFADE_DURATION: float = 0.8

-var _music_player_a: AudioStreamPlayer
-var _music_player_b: AudioStreamPlayer
+const _MUSIC_MAP: Dictionary = {
+	0: "res://assets/audio/music/floor_0.ogg",
+	1: "res://assets/audio/music/floor_1.ogg",
+	2: "res://assets/audio/music/floor_2.ogg",
+	3: "res://assets/audio/music/floor_3.ogg",
+}
+
+const _SFX_MAP: Dictionary = {
+	"chest_tap":         "res://assets/audio/sfx/chest_tap.ogg",
+	"item_spawn":        "res://assets/audio/sfx/item_spawn.ogg",
+	"item_drag_start":   "res://assets/audio/sfx/item_drag_start.ogg",
+	"item_drop_hand":    "res://assets/audio/sfx/item_drop_hand.ogg",
+	"item_drop_outfit":  "res://assets/audio/sfx/item_drop_outfit.ogg",
+	"item_return_chest": "res://assets/audio/sfx/item_return_chest.ogg",
+	"item_drop_floor":   "res://assets/audio/sfx/item_drop_floor.ogg",
+}
+
+var _current_floor: int = -1
+var _is_crossfading: bool = false
 var _active_player: AudioStreamPlayer
+var _last_room: String = ""
+
+var _music_a: AudioStreamPlayer
+var _music_b: AudioStreamPlayer
 var _sfx_player: AudioStreamPlayer
-var _music_volume: float = DEFAULT_MUSIC_VOLUME
-var _sfx_volume: float = 1.0
-var _is_fading: bool = false


 func _ready() -> void:
-	_music_player_a = AudioStreamPlayer.new()
-	_music_player_b = AudioStreamPlayer.new()
+	_music_a = AudioStreamPlayer.new()
+	_music_b = AudioStreamPlayer.new()
 	_sfx_player = AudioStreamPlayer.new()
-	add_child(_music_player_a)
-	add_child(_music_player_b)
+	add_child(_music_a)
+	add_child(_music_b)
 	add_child(_sfx_player)
-	_active_player = _music_player_a
-	_apply_music_volume()
+	_active_player = _music_a
+	_music_a.volume_db = linear_to_db(GameState.music_volume)
+	_music_b.volume_db = linear_to_db(0.0)
+	_sfx_player.volume_db = linear_to_db(GameState.sfx_volume)
+	GameState.state_changed.connect(_on_game_state_changed)
+	_last_room = GameState.current_room
+	var initial_floor: int = _derive_floor_from_room(GameState.current_room)
+	if initial_floor != -1:
+		play_floor_music(initial_floor)


-func play_music(stream: AudioStream) -> void:
-	if _active_player.stream == stream and _active_player.playing:
+func play_floor_music(floor: int) -> void:
+	if AudioServer.get_driver_name() == "Dummy":
 		return
-	var next_player: AudioStreamPlayer = _music_player_b if _active_player == _music_player_a else _music_player_a
-	next_player.stream = stream
-	next_player.volume_db = linear_to_db(0.0)
-	next_player.play()
-	var prev_player: AudioStreamPlayer = _active_player
-	_active_player = next_player
-	var tween: Tween = create_tween()
-	tween.set_parallel(true)
-	tween.tween_property(prev_player, "volume_db", linear_to_db(0.0), CROSSFADE_DURATION)
-	tween.tween_property(next_player, "volume_db", linear_to_db(_music_volume), CROSSFADE_DURATION)
-	tween.chain().tween_callback(prev_player.stop)
+	if floor == _current_floor:
+		return
+	if not _MUSIC_MAP.has(floor):
+		return
+	if _is_crossfading:
+		return
+	_is_crossfading = true
+	_current_floor = floor
+	var inactive: AudioStreamPlayer = _music_b if _active_player == _music_a else _music_a
+	var path: String = _MUSIC_MAP[floor]
+	if not ResourceLoader.exists(path):
+		_is_crossfading = false
+		return
+	var stream: AudioStream = load(path) as AudioStream
+	if stream == null:
+		_is_crossfading = false
+		return
+	inactive.stream = stream
+	inactive.volume_db = linear_to_db(0.0)
+	inactive.play()
+	var tween: Tween = create_tween().set_parallel(true)
+	tween.tween_property(inactive, "volume_db", linear_to_db(GameState.music_volume), CROSSFADE_DURATION)
+	tween.tween_property(_active_player, "volume_db", linear_to_db(0.0), CROSSFADE_DURATION)
+	await tween.finished
+	_active_player.stop()
+	_active_player = inactive
+	_is_crossfading = false


-func play_sfx(stream: AudioStream) -> void:
+func play_sfx(event: String) -> void:
+	if AudioServer.get_driver_name() == "Dummy":
+		return
+	if not _SFX_MAP.has(event):
+		return
+	var path: String = _SFX_MAP[event]
+	if not ResourceLoader.exists(path):
+		return
+	var stream: AudioStream = load(path) as AudioStream
+	if stream == null:
+		return
 	_sfx_player.stream = stream
-	_sfx_player.volume_db = linear_to_db(_sfx_volume)
 	_sfx_player.play()


-func set_music_volume(value: float) -> void:
-	_music_volume = clampf(value, 0.0, 1.0)
-	_apply_music_volume()
+func set_music_volume(vol: float) -> void:
+	GameState.music_volume = vol
+	_active_player.volume_db = linear_to_db(vol)


-func set_sfx_volume(value: float) -> void:
-	_sfx_volume = clampf(value, 0.0, 1.0)
+func set_sfx_volume(vol: float) -> void:
+	GameState.sfx_volume = vol
+	_sfx_player.volume_db = linear_to_db(vol)


-func get_music_volume() -> float:
-	return _music_volume
+func get_current_floor() -> int:
+	return _current_floor


-func _apply_music_volume() -> void:
-	_active_player.volume_db = linear_to_db(_music_volume)
+func _on_game_state_changed() -> void:
+	if GameState.current_room == _last_room:
+		return
+	_last_room = GameState.current_room
+	var floor: int = _derive_floor_from_room(GameState.current_room)
+	if floor != -1:
+		play_floor_music(floor)
+
+
+func _derive_floor_from_room(room: String) -> int:
+	match room:
+		"reception", "giftshop", "restaurant", "emergency":
+			return 0
+		"xray", "pharmacy", "lab", "patient_rooms":
+			return 1
+		"ultrasound", "delivery_room", "nursery":
+			return 2
+		"garden_party":
+			return 3
+	return -1
@@ -24,6 +24,7 @@ func _ready() -> void:
 func _on_drag_picked_up(_pos: Vector2) -> void:
 	if is_in_hand_slot():
 		_detach_from_hand_slot()
+	AudioManager.play_sfx("item_drag_start")
 	item_picked_up.emit(self)


@@ -35,6 +36,9 @@ func _on_drag_released(_pos: Vector2) -> void:
 		var character: Character = result[0] as Character
 		var hand: String = result[1] as String
 		character.attach_item(hand, self)
+		AudioManager.play_sfx("item_drop_hand")
+	else:
+		AudioManager.play_sfx("item_drop_floor")
 	item_placed.emit(self)


@@ -46,6 +50,7 @@ func _try_return_to_chest() -> bool:
 	var chest: RoomChest = home_chest as RoomChest
 	if chest == null:
 		return false
+	AudioManager.play_sfx("item_return_chest")
 	chest.receive_item(self)
 	return true

@@ -15,6 +15,7 @@ func _on_drag_released(_pos: Vector2) -> void:
 	var character: Character = _find_nearest_character()
 	if character != null:
 		character.apply_outfit_item(outfit_layer, item_id, outfit_sprite, self)
+		AudioManager.play_sfx("item_drop_outfit")
 		return
 	super._on_drag_released(_pos)

@@ -8,6 +8,7 @@ signal item_received(chest: RoomChest, item_id: String)
 const SPAWN_TWEEN_DURATION: float = 0.3

@export var chest_id: String = ""
+@export var tap_radius: float = 50.0

 var _spawned_items: Array[HoldableItem] = []
 var _item_configs: Array[ChestItemData] = []
@@ -21,9 +22,22 @@ func _ready() -> void:
 			call_deferred("spawn_items")


+func _unhandled_input(event: InputEvent) -> void:
+	var press_pos: Vector2 = _get_press_position(event)
+	if press_pos == Vector2.INF:
+		return
+	var canvas_pos: Vector2 = get_viewport().get_canvas_transform().affine_inverse() * press_pos
+	if canvas_pos.distance_to(global_position) > tap_radius:
+		return
+	get_viewport().set_input_as_handled()
+	AudioManager.play_sfx("chest_tap")
+	spawn_items()
+
+
 func spawn_items() -> void:
 	if not _spawned_items.is_empty():
 		return
+	AudioManager.play_sfx("item_spawn")
 	var parent: Node = get_parent()
 	for config: ChestItemData in _item_configs:
 		var item: HoldableItem = _create_item(config)
@@ -71,6 +85,14 @@ func get_spawned_item(index: int) -> HoldableItem:
 	return _spawned_items[index]


+func _get_press_position(event: InputEvent) -> Vector2:
+	if event is InputEventScreenTouch and event.pressed:
+		return event.position
+	if event is InputEventMouseButton and event.pressed and event.button_index == MOUSE_BUTTON_LEFT:
+		return event.position
+	return Vector2.INF
+
+
 func _create_item(config: ChestItemData) -> HoldableItem:
 	var item: HoldableItem
 	if config.item_type == ChestItemData.ItemType.OUTFIT:
@@ -0,0 +1,71 @@
+## Tests for AudioManager — floor derivation, no-op guard, SFX key validation.
+extends GutTest
+
+
+func before_each() -> void:
+	AudioManager._current_floor = -1
+	AudioManager._is_crossfading = false
+
+
+func test_derive_floor_floor0_reception() -> void:
+	assert_eq(AudioManager._derive_floor_from_room("reception"), 0)
+
+
+func test_derive_floor_floor0_all_rooms() -> void:
+	assert_eq(AudioManager._derive_floor_from_room("giftshop"), 0)
+	assert_eq(AudioManager._derive_floor_from_room("restaurant"), 0)
+	assert_eq(AudioManager._derive_floor_from_room("emergency"), 0)
+
+
+func test_derive_floor_floor1_all_rooms() -> void:
+	assert_eq(AudioManager._derive_floor_from_room("xray"), 1)
+	assert_eq(AudioManager._derive_floor_from_room("pharmacy"), 1)
+	assert_eq(AudioManager._derive_floor_from_room("lab"), 1)
+	assert_eq(AudioManager._derive_floor_from_room("patient_rooms"), 1)
+
+
+func test_derive_floor_floor2_all_rooms() -> void:
+	assert_eq(AudioManager._derive_floor_from_room("ultrasound"), 2)
+	assert_eq(AudioManager._derive_floor_from_room("delivery_room"), 2)
+	assert_eq(AudioManager._derive_floor_from_room("nursery"), 2)
+
+
+func test_derive_floor_garden() -> void:
+	assert_eq(AudioManager._derive_floor_from_room("garden_party"), 3)
+
+
+func test_derive_floor_unknown_returns_minus_one() -> void:
+	assert_eq(AudioManager._derive_floor_from_room("unknown_room"), -1)
+	assert_eq(AudioManager._derive_floor_from_room(""), -1)
+
+
+func test_get_current_floor_starts_at_minus_one() -> void:
+	assert_eq(AudioManager.get_current_floor(), -1)
+
+
+func test_play_floor_music_same_floor_is_noop() -> void:
+	AudioManager._current_floor = 0
+	AudioManager.play_floor_music(0)
+	assert_eq(AudioManager.get_current_floor(), 0)
+
+
+func test_play_sfx_unknown_key_does_not_crash() -> void:
+	AudioManager.play_sfx("nonexistent_event_xyz")
+	pass
+
+
+func test_sfx_map_has_all_seven_keys() -> void:
+	assert_true(AudioManager._SFX_MAP.has("chest_tap"))
+	assert_true(AudioManager._SFX_MAP.has("item_spawn"))
+	assert_true(AudioManager._SFX_MAP.has("item_drag_start"))
+	assert_true(AudioManager._SFX_MAP.has("item_drop_hand"))
+	assert_true(AudioManager._SFX_MAP.has("item_drop_outfit"))
+	assert_true(AudioManager._SFX_MAP.has("item_return_chest"))
+	assert_true(AudioManager._SFX_MAP.has("item_drop_floor"))
+
+
+func test_music_map_has_all_four_floors() -> void:
+	assert_true(AudioManager._MUSIC_MAP.has(0))
+	assert_true(AudioManager._MUSIC_MAP.has(1))
+	assert_true(AudioManager._MUSIC_MAP.has(2))
+	assert_true(AudioManager._MUSIC_MAP.has(3))
@@ -83,3 +83,21 @@ func test_receive_item_decrements_spawned_count() -> void:
 	var item: HoldableItem = chest.get_spawned_item(0)
 	chest.receive_item(item)
 	assert_eq(chest.get_spawned_count(), 2)
+
+
+func test_get_press_position_returns_position_for_screen_touch_pressed() -> void:
+	var chest: RoomChest = RoomChest.new()
+	add_child_autofree(chest)
+	var event: InputEventScreenTouch = InputEventScreenTouch.new()
+	event.pressed = true
+	event.position = Vector2(100.0, 200.0)
+	assert_eq(chest._get_press_position(event), Vector2(100.0, 200.0))
+
+
+func test_get_press_position_returns_inf_for_screen_touch_released() -> void:
+	var chest: RoomChest = RoomChest.new()
+	add_child_autofree(chest)
+	var event: InputEventScreenTouch = InputEventScreenTouch.new()
+	event.pressed = false
+	event.position = Vector2(100.0, 200.0)
+	assert_eq(chest._get_press_position(event), Vector2.INF)