Defold 音频系统：Sound 组件、背景音乐、3D 音效与声音管理

Sound 组件（挂在 game object 上）
   │
   ├─ 播放/停止消息（msg.post）
   ├─ 音频分组（gain/groups）→ 音量总线
   └─ 位置属性（3D 定位）

WAV：无损，用于短音效（界面、打击）
OGG：有损压缩，用于音乐/长音效
FLAC：无损压缩（Web 兼容有限）
推荐：音效用 WAV、音乐用 OGG

Audio: 选择音频资源
Gain: 音量（0-1，默认 1）
Pan: 左右声道（-1 左 ~ 1 右）
Looping: 是否循环
Pitch: 音高倍率（变调）
Group: 所属音频分组

local sound = msg.url("#sfx_hit")   -- 引用组件
msg.post(sound, "play")             -- 播放

-- 攻击命中时触发
function on_hit(self)
    msg.post("#sfx_hit", "play")
end

-- 播放时可以设置播放参数（音量/音高变化增加变化感）
msg.post("#sfx_step", "play", { gain = 0.8, pitch = 1.0 })

-- 用 pitch 制造随机变调（让连续音效不单调）
local pitch = 0.9 + math.random() * 0.2   -- 0.9 ~ 1.1
msg.post("#sfx_jump", "play", { pitch = pitch })

一次性音效：直接 play（如命中、跳跃）
持续音效：play 一次、stop 停止（如引擎声、风声）
注意：频繁触发短音效 → 用独立组件避免抢占

-- 场景开始播 BGM
msg.post("#bgm", "play")

-- 切换场景/章节 → 换音乐
msg.post("#bgm", "stop")
msg.post("#bgm_alt", "play")

-- 淡出当前音乐：逐帧降 gain
local function fade_out(self, sound, duration, on_done)
    local start = self.bgm_gain or 1
    local t = 0
    -- 用 go.animate 或每帧推进
    go.animate(sound, "gain", go.PlaybackMode.PLAYBACK_ONCE_FORWARD,
               0, go.Easing.IN_QUAD, duration,
               function() if on_done then on_done() end end)
end

fade_out(self, "#bgm", 0.8, function()
    msg.post("#bgm_alt", "play")   -- 淡出后播新歌
end)

1. 全局单例管理 BGM（不随场景销毁）
2. 场景切换先淡出再换
3. 暂停时同时停 BGM
4. 音量尊重用户设置（分组音量）

-- 直接设音量
go.set("#sfx_hit", "gain", 0.5)

-- 用 go.animate 做淡入淡出（见 go.animate 用法）
go.animate("#sfx_hit", "gain", go.PlaybackMode.PLAYBACK_ONCE_FORWARD,
           0.8, go.Easing.IN_QUAD, 0.5)   -- 淡入到 0.8

-- 淡出（音效结束用）
go.animate("#sfx_hit", "gain", go.PlaybackMode.PLAYBACK_ONCE_FORWARD,
           0, go.Easing.OUT_QUAD, 0.3)

-- 设置整个分组的音量（0-1）
msg.post("@system:", "set_gain", { group = "music", gain = 0.6 })
msg.post("@system:", "set_gain", { group = "sfx", gain = 0.8 })

-- 读取分组音量
local g = msg.post("@system:", "get_gain", { group = "music" })

master（总音量）→ 调全局
music（音乐）
sfx（音效）
ui（界面音）
voice（语音）

-- 设置界面：把玩家的音量偏好写进分组
local function apply_volume(self)
    msg.post("@system:", "set_gain", { group = "music", gain = self.vol_music })
    msg.post("@system:", "set_gain", { group = "sfx",   gain = self.vol_sfx })
end

-- 监听器（耳朵）：通常挂到玩家
local listener = msg.url("#player_audio_listener")

-- 让声音根据游戏物体位置定位：
-- Sound 组件挂到发声物体上，位置决定声像

-- 设置监听器增益（近距音量）
msg.post(listener, "set_listener", { gain = 1 })

Falloff：声音随距离衰减曲线
Rolloff：衰减速率
Range：可听距离
Pan：位置在监听器左右 → 自动声像

1. 每个发声物体挂 Sound 组件（位置即声源）
2. 玩家/相机挂 Listener 组件
3. 调 Falloff/Rolloff 控制衰减手感

-- 停止播放
msg.post("#sfx_engine", "stop")

-- 判断是否在播放（用 go.get）
local playing = go.get("#sfx_engine", "playing")   -- true/false
if not playing then
    msg.post("#sfx_engine", "play")
end

同一个 Sound 组件再次 play → 打断重播
不同组件 → 同时播放（重叠）
需要「每次点击都响」→ 多个组件轮换（round-robin）

-- 3 个脚步音效组件轮换
self.step_idx = (self.step_idx or 0) % 3 + 1
msg.post("#sfx_step" .. self.step_idx, "play")

1. 浏览器自动播放限制：无用户交互前不能播音频
   → 首次点击后解锁（play 一次空音）
2. 格式兼容：优先 OGG/MP3，旧浏览器要 wav
3. 音频加载：懒加载，避免首屏大 OGG

1. 后台/切前台：监听系统事件暂停/恢复音频
2. 静音开关：尊重手机静音键（系统静音则游戏音不响）
3. 体积：音乐用 OGG 压体积，音效控制数量
4. 内存：卸载不用的大音频资源

-- 首次点击解锁音频
local function unlock_audio(self)
    msg.post("#bgm", "play")      -- 触发一次播放解锁
    self.unlocked = true
end

function on_input(self, action_id, action)
    if not self.unlocked and action.pressed then
        unlock_audio(self)
    end
end