CloudMusicService

概览

字段	值
Kind	Service · 服务 Service
Realm	common

继承关系

• Unit（4 属性 / 25 函数 / 6 事件）
  • [CloudMusicService]（2 函数）

> Service 继承 Unit 仅表示运行时类型关系；作者可用 API 以当前 Service 页面显式列出的成员为准，不自动包含 Unit 的创建、层级或销毁能力。

云音乐服务负责在地图中播放网易云音乐曲库内的指定歌曲，通过曲目编号即可发起播放，并支持设置起始播放位置与音量比例。同时提供一键恢复地图自身背景音乐的能力，便于在场景音乐与地图默认音频之间灵活切换。

适用场景

适用于需要使用网易云音乐曲库内容替换或穿插地图背景音乐的场景，例如活动主题曲、节日特别音乐或对局内氛围音乐的切换控制。

使用要点

先通过 game:GetService("CloudMusicService") 获取服务实例，再调用 PlayMusic 传入音乐编号、起始时间与音量比例开始播放。需要返回地图默认背景音乐时，调用 ResumeMapMusic 即可恢复。

注意事项

musicID 必须替换为当前项目实际可用的网易云音乐资源 ID；公开契约未定义 default 等内置占位 ID。seekTime 使用秒，volumeScale 为音量缩放系数。

代码示例

使用项目中的云音乐资源并恢复地图背景音乐

-- @runtime client
local cloudMusicService = game:GetService("CloudMusicService")
local musicID = "" -- 替换为当前项目实际可用的云音乐资源 ID
if musicID == "" then
    print("请先填写可用的云音乐资源 ID")
    return
end

cloudMusicService:PlayMusic(musicID, 0, 1.0)
-- 需要切回地图自身配置的背景音乐时调用：
cloudMusicService:ResumeMapMusic()

关联类型

• Unit

函数 (2)

PlayMusic

签名：PlayMusic(musicID: String, seekTime: Float, volumeScale: Float) -> void

用于播放网易云音乐，可指定播放开始时间与音量比例。

参数	类型	说明
musicID	String	云音乐资源ID
seekTime	Float	起始播放时间（秒）
volumeScale	Float	音量缩放系数

返回值 void

示例代码

播放项目中的云音乐资源

-- @runtime client
local cloudMusicService = game:GetService("CloudMusicService")
local musicID = "" -- 替换为当前项目实际可用的云音乐资源 ID
if musicID == "" then
    print("请先填写可用的云音乐资源 ID")
    return
end
cloudMusicService:PlayMusic(musicID, 0, 0.8)

ResumeMapMusic

签名：ResumeMapMusic() -> void

用于恢复地图背景音乐的播放。

返回值 void

示例代码

恢复地图背景音乐

-- @runtime client
local cloudMusicService = game:GetService("CloudMusicService")
cloudMusicService:ResumeMapMusic()