找物源码导读Cocos Creator 3.8 · assets/scripts
0%
已读 0 / 424
目录— 个文件
目录加载中…
…/core/music/AudioManager.ts
1import { AudioClip, AudioSource, find, Node } from "cc";
2import { FrameworkEntry } from "../../FrameworkEntry";
3import { Framework } from "../../Framework";
4import { VibrateType } from "../../module/sdk/SdkDefine";
5import { frameworkManager } from "../base/FrameworkClassRegistry";
6import { IFrameworkManager } from "../base/IFrameworkManager";
7import { Singleton } from "../base/Singleton";
8import { DataFrameKey } from "../data/DataFrameKey";
9import { EventFrameCode } from "../event/EventFrameCode";
10
11/**
12 * 音乐管理器
13 */
14@frameworkManager()
15export class AudioManager extends Singleton<AudioManager> implements IFrameworkManager {
16 public Name = "MusicManager";
17
18 //音乐管理器组件
19 private audioNode: Node | null = null;
20 //背景声音频组件
21 private musicSource: AudioSource = null!;
22 //音效音频组件
23 private soundSources: AudioSource = null!
24
25 // 音乐和音效启用状态
26 private musicEnabled: boolean = true;
27
28 // 进后台前音乐是否在播放(用于 onShow 时判断是否恢复)
29 private _wasPlayingBeforeHide: boolean = false;
30
31 get MusicEnabled(): boolean {
32 return this.musicEnabled;
33 }
34
35 private soundEnabled: boolean = true;
36
37 get SoundEnabled(): boolean {
38 return this.soundEnabled;
39 }
40
41
42 // 震动启用状态
43 private shakeEnabled: boolean = true;
44
45 get ShakeEnabled(): boolean {
46 return this.shakeEnabled;
47 }
48
49
50
51 public async Init(): Promise<void> {
52 // 记录管理器初始化入口,便于排查启动顺序。
53 Framework.Log.Log(this.Name, "Init", "初始化音频管理器");
54 // 创建音频源组件
55 this.CreateAudioSource();
56 // 玩家存档确认后再恢复音频设置,避免读取尚未准备好的默认数据。
57 Framework.Event.RegisterEvent(EventFrameCode.PLAYER_DATA_READY, this.LoadSettings, this);
58 }
59
60 public DeInit(): void {
61 Framework.Event.UnRegisterEvent(EventFrameCode.PLAYER_DATA_READY, this.LoadSettings, this);
62 // 清理时停止所有音频并释放资源
63 this.StopAllAudio();
64 this.audioNode!.destroy();
65 this.audioNode = null;
66
67 }
68
69 public Update(deltaTime: number): void {
70 // 无需定时更新
71 }
72
73 /**
74 * 创建音频源组件
75 * @constructor
76 * @private
77 */
78 private CreateAudioSource(): void {
79 if (this.audioNode == null) {
80
81 this.audioNode = new Node("AudioManager");
82 // 添加到游戏入口节点作为子节点(确保持久化)
83 this.audioNode.parent = FrameworkEntry.Instance?.node || find('GameEntry');
84
85 let musicNode = new Node("Music");
86 let sound = new Node("Sound");
87 // 添加AudioSource组件并配置
88 musicNode.parent = this.audioNode;
89 sound.parent = this.audioNode;
90
91 this.musicSource = musicNode.addComponent(AudioSource);
92 this.musicSource.loop = true; // 默认循环播放
93 this.musicSource.volume = 1; // 默认音量
94
95 this.soundSources = sound.addComponent(AudioSource);
96 this.soundSources.loop = true; // 默认循环播放
97 this.soundSources.volume = 1; // 默认音量
98 }
99 }
100
101 /** 加载本地保存的设置 */
102 private LoadSettings(): void {
103 const savedMusic = Framework.Data.GetData(DataFrameKey.MUSIC_ENABLED, true);
104 const savedSound = Framework.Data.GetData(DataFrameKey.SOUND_ENABLED, true);
105 const savedShake = Framework.Data.GetData(DataFrameKey.SHAKE_ENABLED, true);
106
107 this.musicEnabled = savedMusic;
108 this.soundEnabled = savedSound;
109 this.shakeEnabled = savedShake;
110 }
111
112 /**
113 * 设置背景音乐启用状态
114 * @param enabled 是否启用
115 */
116 public SetMusicEnabled(enabled: boolean): void {
117 if (this.musicEnabled === enabled) return;
118
119 Framework.Data.SaveData(DataFrameKey.MUSIC_ENABLED, enabled);
120 this.musicEnabled = enabled;
121
122 // 立即应用状态
123 if (enabled && this.musicSource.clip) {
124 this.ResumeMusic();
125 } else {
126 this.PauseMusic()
127 }
128 }
129
130 /**
131 * 设置音效启用状态
132 * @param enabled 是否启用
133 */
134 public SetSoundEnabled(enabled: boolean): void {
135 if (this.soundEnabled === enabled) return;
136
137 Framework.Data.SaveData(DataFrameKey.SOUND_ENABLED, enabled);
138 this.soundEnabled = enabled;
139
140 // 如果禁用音效,立即停止所有播放中的音效
141 if (!enabled) {
142 this.StopSound();
143 }
144 }
145
146 /**
147 * 设置震动启用状态
148 * @param enabled 是否启用
149 */
150 public SetShakeEnabled(enabled: boolean): void {
151 if (this.shakeEnabled === enabled) return;
152
153 Framework.Data.SaveData(DataFrameKey.SHAKE_ENABLED, enabled);
154 this.shakeEnabled = enabled;
155 }
156
157 /**
158 * 播放震动效果
159 * @param type 震动类型
160 */
161 public Vibrate(type: VibrateType = VibrateType.short): void {
162 if (!this.shakeEnabled) return;
163 Framework.Sdk.Vibrate(type);
164 }
165
166 /**
167 * 播放背景音乐
168 * @param url 音乐资源路径(相对于resources目录)
169 * @param loop 是否循环播放(默认true)
170 */
171 public PlayMusic = async (url: string, loop: boolean = true): Promise<void> => {
172 // 关闭 BGM 时仍要加载并挂上 clip,否则之后 SetMusicEnabled(true) 只有 ResumeMusic、clip 为空无法出声
173 this.StopMusic();
174 try {
175 // 使用框架资源管理器加载音频 clip
176 const clip = await Framework.Res.LoadAssetAsync<AudioClip>(`${url}`, AudioClip);
177 if (!clip) {
178 Framework.Log.Error(`MusicManager: 背景音乐资源加载失败 - ${url}`);
179 return;
180 }
181
182 // 更新音频源设置;仅在开启 BGM 时真正播放(异步返回后若用户已打开开关,也会按当前开关播放)
183 this.musicSource.clip = clip;
184 this.musicSource.loop = loop;
185 this.musicSource.volume = 1.0;
186 if (this.musicEnabled) {
187 this.musicSource.play();
188 Framework.Log.Log(`MusicManager: 播放背景音乐 - ${url}`);
189 }
190
191 } catch (e) {
192 Framework.Log.Error(`MusicManager: 播放背景音乐失败 - ${url}, 错误: ${e}`);
193 }
194 }
195
196 /** 停止背景音乐 */
197 public StopMusic(): void {
198 if (this.musicSource.playing) {
199 this.musicSource.stop();
200 }
201 }
202
203 /** 暂停背景音乐 */
204 public PauseMusic(): void {
205 if (this.musicSource.playing) {
206 this.musicSource.pause();
207 }
208 }
209
210 /** 恢复背景音乐 */
211 public ResumeMusic(): void {
212 if (!this.musicEnabled) {
213 return;
214 }
215
216 if (!this.musicSource.playing) {
217 this.musicSource.play();
218 }
219 }
220
221 /**
222 * 播放音效
223 * @param url 音效资源路径(相对于resources目录)
224 * @param volume 音量(0-1之间)
225 */
226 public PlaySound = async (url: string, isLoop: boolean = false, volume: number = 1.0): Promise<void> => {
227 if (!this.soundEnabled) return;
228 try {
229 // 使用框架资源管理器加载音效 clip
230 const clip = await Framework.Res.LoadAssetAsync<AudioClip>(`${url}`, AudioClip);
231 if (!clip) {
232 Framework.Log.Error(`MusicManager: 音效资源加载失败 - ${url}`);
233 return;
234 }
235 if (isLoop) {
236 this.soundSources.loop = isLoop;
237 this.soundSources.volume = volume;
238 this.soundSources.clip = clip;
239 this.soundSources.play();
240 } else {
241 this.soundSources.playOneShot(clip, volume);
242 }
243 } catch (e) {
244 Framework.Log.Error(`MusicManager: 播放音效失败 - ${url}, 错误: ${e}`);
245 }
246 }
247
248 /**
249 * 停止音效
250 * @constructor
251 */
252 public StopSound() {
253 if (this.soundSources.playing) {
254 this.soundSources.stop();
255 }
256 }
257
258
259 /**
260 * 停止所有音效
261 * @constructor
262 */
263 public StopAllAudio(): void {
264 this.StopMusic();
265 this.StopSound();
266 }
267
268 /** 游戏进入后台时的音频处理 */
269 public HandleAppHide(): void {
270 this._wasPlayingBeforeHide = this.musicSource.playing;
271 this.PauseMusic();
272 this.StopSound();
273 }
274
275 /** 游戏回到前台时的音频处理 */
276 public HandleAppShow(): void {
277 if (this._wasPlayingBeforeHide) {
278 this.ResumeMusic();
279 }
280 this._wasPlayingBeforeHide = false;
281 }
282}
讲解283 行
背景音乐与音效管理器人工通读

AudioManager.ts

在入口节点下自建 Music 与 Sound 两个 AudioSource,初始化时创建节点并登记存档就绪监听,等玩家数据准备好后再恢复三个开关。对外提供开关设置、播放、震动和前后台处理,业务通过 Framework.Audio 调用。

按 Init、CreateAudioSource、LoadSettings、三个 Set 开关、PlayMusic 与 PlaySound、StopAllAudio、HandleAppHide 与 HandleAppShow 的顺序读。

特殊处理与易错点

14注释音乐管理器
15注释AudioManager:音频管理器:BGM/音效播放、音乐/音效/震动开关、前后台暂停恢复、设置持久化。
19属性承载两个音频源的常驻节点,Init 时创建,DeInit 时销毁。
21属性背景音乐音源,默认循环、音量一。
23属性音效音源,循环音效复用它,非循环音效走一次性播放。
26属性音乐开关的内存值,存档就绪时恢复,SetMusicEnabled 时更新。
29属性进后台前音乐是否在播,供回到前台时决定是否恢复。
31方法只读返回音乐开关的内存值,供 UI 同步显示状态。
35属性音效开关的内存值。
37方法只读返回音效开关的内存值,供 UI 同步显示状态。
43属性震动开关的内存值,Vibrate 时读取。
45方法只读返回震动开关的内存值,供 UI 同步显示状态。
51方法创建两个音频源组件,并登记存档就绪监听,开关值留到事件触发后再读取。
53注释记录管理器初始化入口,便于排查启动顺序。
55注释创建音频源组件
57注释玩家存档确认后再恢复音频设置,避免读取尚未准备好的默认数据。
60方法注销存档就绪监听,停止全部音频,销毁音频节点并把引用置空。
63注释清理时停止所有音频并释放资源
69方法空实现,音频状态由事件和显式调用驱动,没有逐帧逻辑。
71注释无需定时更新
78方法已有音频节点时直接返回,否则在入口节点下建 Music 与 Sound 子节点并各挂一个音源。
83注释添加到游戏入口节点作为子节点(确保持久化)
88注释添加AudioSource组件并配置
102方法从存档读音乐、音效、震动三个开关,字段缺失时一律按开启处理。
116方法值未变化直接返回,否则写存档更新内存值,并在开或关时分别恢复或暂停音乐。
123注释立即应用状态
134方法值变化时写存档并更新内存值,关闭时立刻停止正在播放的音效。
141注释如果禁用音效,立即停止所有播放中的音效
150方法值变化时写存档并更新内存开关,震动的实际调用留给 Vibrate 判断。
161方法震动开关关闭时直接返回,否则把震动类型转给 SDK 的震动接口。
171方法先停当前音乐,加载音频资源后挂到音乐源,开关打开时立即播放并记录日志。
173注释关闭 BGM 时仍要加载并挂上 clip,否则之后 SetMusicEnabled(true) 只有 ResumeMusic、clip 为空无法出声
176注释使用框架资源管理器加载音频 clip
183注释更新音频源设置;仅在开启 BGM 时真正播放(异步返回后若用户已打开开关,也会按当前开关播放)
197方法音乐正在播放时才调用停止,否则什么都不做。
204方法音乐正在播放时才暂停,未播放时不改变音源状态。
211方法开关关闭直接返回,音源未在播放时才调用播放恢复。
226方法音效开关关闭直接返回,循环音效占用共享音源播放,非循环音效用一次性播放叠加。
230注释使用框架资源管理器加载音效 clip
252方法音效源正在播放时才停止,一次性播放的音效不受它影响。
263方法依次停止背景音乐与音效源,不处理一次性播放的音效。
269方法记下隐藏前音乐是否在播,然后暂停音乐并停止音效。
276方法隐藏前在播才恢复音乐,随后把记录标记清零。