音乐

旧写法兼容（ver-23）

旧接口可以继续使用，无须为读档改成地图配置。例如已注册 P登录 和 P通用 时：

local 背景音乐 = 引擎.创建音乐("P登录")

背景音乐.循环 = true

背景音乐.音量 = 40

背景音乐.播放()

-- 进入另一张地图时沿用旧换曲顺序。

背景音乐.停止()

背景音乐.音乐 = "P通用"

背景音乐.播放()

ver-23 去掉地图音量接入对 debug.getmetatable 的依赖，修复旧调用项目也会遇到的载图/读档 FATAL。手动音乐对象继续用自身 音量 控制；地图自动音乐和环境声使用各自的地图音量属性。两套播放对象独立，若给同一地图同时配置并手动播放背景曲，会同时播放，项目应自行决定配乐由哪一处负责。

实际候选闭包 1117 项隔离断言及本机真实引擎 8 组独立静音测试通过，覆盖旧写法、新旧并用和真实存读档。同事客户端、完整游戏听感待复测。

ver-20 音乐播放与换曲

引擎.创建音乐(资源标识)返回独立的音乐对象，创建后需调用播放()；不传标识可先创建空对象。多个对象使用同一音乐文件时，各自的播放、停止、循环和音量互不覆盖。

写入音乐切换资源时立即停止并解除旧句柄；新资源就绪后，重新应用当前音量、音高、循环和声道，再执行最新的播放/暂停/停止请求。加载期间修改的属性可立即读回；迟到的旧请求不会替换当前曲目。同一资源正在加载时，多个对象排队等待各自独立的句柄。同步文件错误和异步失败均结束等待，不再误播旧曲。失败后重新赋同一标识可重试。

新增只读属性：

音量限制为 0～100 并向下取整，默认 100；0 只静音，播放位置继续前进。NaN 和非数值输入忽略。循环默认 false，仅接受逻辑值；地图管理的两个对象自动设为 true。位置以非负整数毫秒读写；暂停、加载期间可设置位置。音高须为有限正数；声道限制为 -1～1。

音乐=false、nil或空串清空对象，停止并归还当前句柄。停止()保留资源对象供后续重播。空闲句柄按文件路径复用，避免同一批地图反复切换时持续创建；同时使用的对象各占句柄。自行创建的对象不用时应先清空音乐，再丢弃引用。

local 背景音乐 = 引擎.创建音乐()

背景音乐.循环 = true

背景音乐.音量 = 40

背景音乐.音乐 = "P通用" -- 必须已在资源表注册

背景音乐.播放() -- 异步加载完成后也会遵从此请求

if 背景音乐.加载状态 == 3 then

    调试输出(背景音乐.加载错误)

end

-- 不再使用时：背景音乐.音乐 = false

地图的自动配乐见地图配置与地图音量属性。普通攻击、技能和界面音效继续走既有引擎.系统设置({音量=...})；单独创建的音乐由自身音量控制。

验证：旧库实际字节码复现换曲丢循环、异步误播/乱序覆盖、共享句柄和缺资源异常；候选字节码隔离回归通过。真实 App.exe 独立静音 WAV 验证循环、同文件独立播放、切图、位置、暂停和缺文件；音量验证记录实际提交给 C 的命令值，不使用未确认的 getVolume 返回值。未测试远程真实下载、完整用户游戏和听感。

属性

音乐

• 类型：文本
• 读写：读写
• 说明：取出/改变当前播放的音乐资源名称。

音量

• 类型：整数
• 读写：读写
• 说明：读写音量大小。

音高

• 类型：小数
• 读写：读写
• 说明：读写音高,越大声音越尖锐,默认：1.0。

声道

• 类型：小数
• 读写：读写
• 说明：范围：[-1, 1],表示左右声道,默认：0。

长度

• 类型：整数
• 读写：只读
• 说明：当前音乐的长度,单位：毫秒。

状态

• 类型：整数
• 读写：只读
• 说明：0：停止 1：暂停 2：播放。

循环

• 类型：逻辑
• 读写：读写
• 说明：当前音乐是否循环播放。

方法

播放

背景音乐.播放()

暂停

背景音乐.暂停()

停止

背景音乐.停止()

更新记录