游戏引擎 / 系统课时
让设置菜单持久化音量画质
让设置菜单持久化音量画质
让暂停菜单中的主音量与画质档位真正影响运行中的游戏,并在切换场景、关闭程序后保留选择。本例使用 Unity 6 的 UI Toolkit、AudioMixer、QualitySettings 和 PlayerPrefs:音量拖动时试听,画质按“应用”后切换,“取消”还原未提交的音量修改。
学习目标
- 将 0~1 的音量滑杆正确转换为 AudioMixer 的分贝值。
- 实现设置的读取、预览、应用、取消与跨场景保存。
- 验证重启恢复,并定位音频路由和画质档位不生效的问题。
配好音频、画质与设置面板
- 在
Assets > Create > Audio > Audio Mixer创建GameMixer。打开它,选中Master组,在 Inspector 中右击音量Volume,选择暴露给脚本的选项,再在Exposed Parameters中将参数改名为MasterVolume。把背景音乐、音效的 AudioSource 输出路由到该 Mixer 的组;没经过 Mixer 的声源不会受到这个滑杆控制。 - 打开
Edit > Project Settings > Quality,根据项目需要配置Low、Medium、High三个质量档位,并确认目标构建平台勾选了对应档位。档位名字是项目自定义的,不要假设所有项目都恰好有这三个名称。 - 在 UI Builder 建立 UXML:
settings-panel(VisualElement)内放master-volume(Slider)、quality-level(DropdownField)、apply-settings与cancel-settings(Button)。这些是元素的 Name,不是显示标签。 - 在启动场景创建根对象
SettingsRoot,添加UIDocument(指定 UXML 的 Source Asset 与 Panel Settings)和下面的脚本,给脚本的Mixer字段指定GameMixer。不要把这个对象作为其他场景对象的子节点。
音量范围设为 0~1,首次启动默认 0.8。线性振幅 0.5 约为 −6.02 dB;直接把 0.5 写入 Mixer 的分贝参数只会得到约 −0.5 dB,听感变化很小。静音时把分贝限制为 −80 dB,避免对 0 求对数。
区分即时试听与真正提交
滑杆变化只修改运行时 Mixer,不立刻写 PlayerPrefs;画质下拉框改变也先不触发昂贵的画质切换。按“应用”时才提交当前值,按“取消”时把试听音量恢复到上次已应用的值。这样即使玩家拖动到 0 后取消,也不会意外永久静音。

PlayerPrefs 适合这种少量本地偏好,但不加密,不要用它保存密码。画质不保存数字索引:不同平台可能剔除部分质量档位,重启后应按名称在 QualitySettings.names 中查找;找不到原档位就回退到当前平台的默认生效档位。
编写持久化控制器
新建 PersistentSettingsMenu.cs 并附加到 SettingsRoot。代码在 Start 恢复 Mixer 音量,避免在 Awake 或 OnEnable 中调用 AudioMixer.SetFloat;该 API 在这些生命周期回调中可能出现非预期行为。
using System;
using System.Collections.Generic;
using UnityEngine;
using UnityEngine.Audio;
using UnityEngine.UIElements;
[DefaultExecutionOrder(-100)]
[RequireComponent(typeof(UIDocument))]
public sealed class PersistentSettingsMenu : MonoBehaviour
{
const string VolumeKey = "opt_master_v1";
const string QualityKey = "opt_quality_v1";
const string VolumeParameter = "MasterVolume";
[SerializeField] AudioMixer mixer;
public static PersistentSettingsMenu Instance { get; private set; }
Slider volumeField;
DropdownField qualityField;
VisualElement panel;
float savedVolume;
string savedQuality;
void Awake()
{
// 避免后续关卡再创建管理器,导致已提交设置被覆盖。
if (Instance != null && Instance != this)
{
Destroy(gameObject);
return;
}
Instance = this;
DontDestroyOnLoad(gameObject);
}
void Start()
{
if (Instance != this) return;
var root = GetComponent<UIDocument>().rootVisualElement;
volumeField = root.Q<Slider>("master-volume");
qualityField = root.Q<DropdownField>("quality-level");
panel = root.Q<VisualElement>("settings-panel");
var apply = root.Q<Button>("apply-settings");
var cancel = root.Q<Button>("cancel-settings");
if (mixer == null || volumeField == null || qualityField == null ||
panel == null || apply == null || cancel == null)
{
Debug.LogError("Settings: check Mixer and UXML element names");
enabled = false;
return;
}
volumeField.lowValue = 0f;
volumeField.highValue = 1f;
qualityField.choices = new List<string>(QualitySettings.names);
savedVolume = Mathf.Clamp01(PlayerPrefs.GetFloat(VolumeKey, 0.8f));
string activeName = QualitySettings.names[QualitySettings.GetQualityLevel()];
string storedName = PlayerPrefs.GetString(QualityKey, activeName);
savedQuality = qualityField.choices.Contains(storedName)
? storedName : activeName;
// 先还原运行时设置,再填控件;不触发控件的变化事件。
SetVolume(savedVolume);
SetQuality(savedQuality);
volumeField.SetValueWithoutNotify(savedVolume);
qualityField.SetValueWithoutNotify(savedQuality);
volumeField.RegisterValueChangedCallback(e => SetVolume(e.newValue));
apply.clicked += Apply;
cancel.clicked += Cancel;
panel.style.display = DisplayStyle.None;
Debug.Log($"Restored: volume={savedVolume:F2}, quality={savedQuality}");
}
void SetVolume(float linear)
{
float db = linear <= 0.0001f
? -80f : Mathf.Clamp(20f * Mathf.Log10(linear), -80f, 0f);
if (!mixer.SetFloat(VolumeParameter, db))
Debug.LogError("Settings: MasterVolume is not exposed");
}
static void SetQuality(string name)
{
int index = Array.IndexOf(QualitySettings.names, name);
if (index >= 0)
QualitySettings.SetQualityLevel(index, true);
}
[ContextMenu("Open Settings")]
public void Open()
{
if (panel == null) return;
volumeField.SetValueWithoutNotify(savedVolume);
qualityField.SetValueWithoutNotify(savedQuality);
SetVolume(savedVolume);
panel.style.display = DisplayStyle.Flex;
}
void Apply()
{
// 画质在确认时才切换,避免拖动/选项变化频繁重建。
savedVolume = volumeField.value;
savedQuality = qualityField.value;
SetVolume(savedVolume);
SetQuality(savedQuality);
PlayerPrefs.SetFloat(VolumeKey, savedVolume);
PlayerPrefs.SetString(QualityKey, savedQuality);
PlayerPrefs.Save();
panel.style.display = DisplayStyle.None;
Debug.Log($"Applied: volume={savedVolume:F2}, quality={savedQuality}");
}
void Cancel()
{
SetVolume(savedVolume);
volumeField.SetValueWithoutNotify(savedVolume);
qualityField.SetValueWithoutNotify(savedQuality);
panel.style.display = DisplayStyle.None;
}
}预期结果:首次进入播放模式,Console 打印 Restored: volume=0.80, quality=<QUALITY_NAME>;若把滑杆设为 0.50、选择项目中存在的 High 并按应用,会输出:
Applied: volume=0.50, quality=High再次启动同一应用时,应输出:
Restored: volume=0.50, quality=High实际档位名称取决于项目配置。暂停菜单的“设置”按钮点击回调可调用 PersistentSettingsMenu.Instance.Open();调试时也能在播放模式下通过组件右上角菜单的 Open Settings 打开面板。SettingsRoot 必须在启动场景先实例化,且后续场景不能销毁它。
验收跨场景与重启恢复
- 播放一段实际经过
GameMixer的音乐,打开设置将音量从 1.00 拖到 0.50:声音应立即变小约 6 dB。点击取消,应恢复上次已应用的音量,重新打开也显示旧值。 - 将音量设为 0.50、画质选为
High并应用,检查 Console 中的Applied日志。切换到另一个关卡后再次打开面板,仍应看到 0.50 和High,不能再创建第二个设置控制器。 - 在独立构建的游戏中退出并重开,核对
Restored日志、实际声音和画质档位。仅在 Editor 中反复点 Play 不能替代构建版重启验证。
若拖动有日志却音量不变,优先检查 AudioSource 的 Output 是否指向 Mixer 组,以及暴露参数名是否精确为 MasterVolume。若画质看不出差异,先确认不同档位确实设置了不同参数,并检查 URP 等渲染管线资产与平台档位映射;调用 SetQualityLevel 并不保证每个项目都会出现肉眼可见的变化。