星火 2.0 开发文档

主题

客户端设置系统 ​

GameCore.ClientSettings 提供客户端代码访问游戏设置的统一入口，适合制作项目自己的设置面板，或在运行时切换画质、帧率、音频和少量本地偏好。

使用边界

  • 仅客户端可用。相关代码应放在 #if CLIENT 内。
  • 设置功能请使用独立客户端调试验证。 编辑器内调试（PIE）暂未完整支持 Graphics、Audio 和 Preferences 的保存与读回，不能据此判断独立客户端是否正常；Preferences 的 Game 和 Device 两种作用域均受此限制。无头编辑器启动的独立调试客户端可用于验证。
  • PIE 中调用这些 API 仍可能修改编辑器进程的音量、帧率或抗锯齿，结束调试时不保证恢复。配套新版编辑器会在每个 PIE 游戏局首次读写设置时警告一次；提示不会阻止调用，也不改变现有设置行为。
  • 设置保存在当前设备或当前游戏的本地配置中，不同步服务器，也不作为玩法权威数据。
  • 普通设置可在打开 UI 时读取，用户确认或拖动控件时写入。需要选项变化通知、默认值或本会话覆盖时，使用能力版本 9 的 ClientPlatform。
  • 不要把进度、货币、背包、付费状态或跨设备存档放进本地偏好；这些数据应使用 CloudData 或项目自己的服务端逻辑。

入口 ​

常用入口在 GameCore.ClientSettings 命名空间下：

csharp
#if CLIENT
using GameCore.ClientSettings;

ClientSettings.Graphics.Preset = GraphicsPreset.Balanced;
ClientSettings.Graphics.MaxFrameRate = 120;

ClientSettings.Audio.Music.Volume = 70;
ClientSettings.Audio.Effects.Enabled = true;

ClientSettings.Preferences.SetBool("show_damage_numbers", true);
#endif

ClientSettings 分为三组：

入口用途
ClientSettings.Graphics画质预设、帧率、渲染分辨率、场景质量、粒子质量、HDR、抗锯齿等图形选项
ClientSettings.Audio音乐、音效、语音和麦克风的音量与开关
ClientSettings.Preferences项目自定义的本地布尔、浮点数和字符串偏好

图形设置 ​

图形设置写入平台已有的游戏设置存储，并尽量立即应用到当前客户端。

csharp
#if CLIENT
using GameCore.ClientSettings;

ClientSettings.Graphics.Preset = GraphicsPreset.High;
ClientSettings.Graphics.RenderResolution = RenderResolutionLevel.High;
ClientSettings.Graphics.SceneQuality = SceneQuality.Ultra;
ClientSettings.Graphics.ParticleQuality = ParticleQuality.High;
ClientSettings.Graphics.DynamicLightsEnabled = true;
ClientSettings.Graphics.HdrEnabled = true;
ClientSettings.Graphics.AntiAliasingEnabled = true;
ClientSettings.Graphics.CharacterOcclusionSilhouetteEnabled = true;
#endif

帧率上限 ​

MaxFrameRate 是 int? 属性。赋值为正整数表示显式帧率上限；赋值为 null 或调用 ClearMaxFrameRate() 表示取消显式上限。项目代码不需要依赖底层存储的特殊值。

csharp
#if CLIENT
using GameCore.ClientSettings;

ClientSettings.Graphics.MaxFrameRate = 144;

int? cap = ClientSettings.Graphics.MaxFrameRate;
if (cap is null)
{
    // 当前没有显式帧率上限。
}

ClientSettings.Graphics.ClearMaxFrameRate();
// 等价写法：ClientSettings.Graphics.MaxFrameRate = null;
#endif

预设仍会设置平台推荐的帧率档位，例如省电或流畅模式可能设置 30 / 60 FPS。项目代码直接写入 MaxFrameRate 时可以使用任意正整数，前提是当前客户端底层和设备性能能够支持。

预设与自定义 ​

设置 Preset 会应用一组平台内置画质配置。单独修改分辨率、质量、帧率或图形开关时，平台设置会被标记为 GraphicsPreset.Custom。

RenderResolutionLevel 表示渲染分辨率档位，不是窗口尺寸或 UI 设计分辨率。需要调整 UI 布局时，应使用 GameUI 布局 API；需要控制渲染画面清晰度时才使用这里的渲染分辨率设置。

能力版本 9 中，移动端显式选择低/中档分别请求短边 540/720 像素，高档恢复系统默认 Surface；这不在启动时自动强制某档分辨率。精确尺寸请求、默认 Surface 查询与恢复使用 ClientPlatform，实际结果以视口变化后读回为准。

当前游戏的独立阴影、Cluster、蒙皮、AO、Shader 宏排除和渲染快照使用 GameGraph.Rendering.GameRenderSettings；这些实时属性不自动持久化，需要 ClientRuntimeFeature.GameRenderSettings。

音频设置 ​

音频设置按通道工作：

csharp
#if CLIENT
using GameCore.ClientSettings;

ClientSettings.Audio.Music.Volume = 60;
ClientSettings.Audio.Effects.Volume = 85;
ClientSettings.Audio.Voice.Enabled = false;

var musicVolume = ClientSettings.Audio.Music.Volume;
var effectsEnabled = ClientSettings.Audio.Effects.Enabled;

// 需要动态选择通道时，也可以使用索引器。
ClientSettings.Audio[AudioChannel.Microphone].Enabled = true;
#endif

Volume 的范围是 0 到 100。Enabled 用于开关对应通道；关闭通道不要求项目代码自己把音量改成 0。

通道常见含义
AudioChannel.Music背景音乐、环境音乐、过场音乐
AudioChannel.EffectsUI、战斗、移动、拟音、场景物件、提示和普通音效
AudioChannel.Voice游戏内对白/语音和语音聊天播放
AudioChannel.Microphone麦克风输入

AudioChannel 和 GameDataSound.Category 不是同一层概念，也不是两个独立音量因子相乘：

层例子作用
GameDataSound.CategoryCombat、Music、Dialogue声音自己的分类；ActorSound 播放时会把它写成底层 sound type 字符串
底层 sound type gaingain["Combat"] = 0.8native 混音时实际使用的分类音量槽
AudioChannelEffects、Music、Voice玩家设置里的批量旋钮；一次写多个底层 sound type gain

因此，ClientSettings.Audio.Effects.Volume = 80 不是设置一个独立的 "Effects" 总线，而是把 UI、Alert、Movement、Foley、Doodad、Combat、Message、Effect 这些底层 sound type gain 批量写成 0.8。如果某个 ActorSound 的 GameDataSound.Category 是 Combat，它会受到 Effects 通道影响，因为它命中了同一个 gain["Combat"] 槽。Music 会覆盖 Ambient、Music、Cutscene、BackgroundMusic；Voice 会覆盖 Dialogue、Voice，并同步语音聊天播放音量。

自定义本地偏好 ​

ClientSettings.Preferences 适合保存项目自己的轻量本地偏好，例如是否显示伤害数字、镜头灵敏度、本地 UI 皮肤选择、辅助准星开关等。

csharp
#if CLIENT
using GameCore.ClientSettings;

ClientSettings.Preferences.SetBool("show_damage_numbers", true);
ClientSettings.Preferences.SetFloat("camera_sensitivity", 0.75f);
ClientSettings.Preferences.SetString("hud_layout", "compact");

var showDamageNumbers = ClientSettings.Preferences.GetBool("show_damage_numbers", defaultValue: true);
var sensitivity = ClientSettings.Preferences.GetFloat("camera_sensitivity", defaultValue: 0.5f);
var hudLayout = ClientSettings.Preferences.GetString("hud_layout", defaultValue: "default");
#endif

默认 scope 是 ClientSettingScope.Game，表示偏好随当前游戏/项目隔离。需要保存同一设备上跨项目共享的工具类偏好时，可以显式使用 ClientSettingScope.Device：

csharp
#if CLIENT
ClientSettings.Preferences.SetBool(
    "developer_overlay_enabled",
    true,
    ClientSettingScope.Device);
#endif

自定义偏好的 key 应稳定、可读，并尽量使用项目自己的命名习惯。不要保存大 JSON、敏感信息、账号凭据或需要跨设备同步的数据。

与平台设置面板的关系 ​

内置图形和音频选项写入平台已有设置。平台设置面板再次打开时通常会从当前平台设置构造界面，因此项目代码写入的内置选项可以被面板读取到。

需要注意的是，平台面板的控件不一定能表达项目代码写入的所有值。例如项目代码可以设置任意正整数帧率上限，但面板如果只提供固定档位，显示和再次保存时可能会折回到面板支持的值。项目自定义的 Preferences 不会自动出现在平台通用设置面板中，应由项目自己的 UI 读取和展示。

推荐模式 ​

  • 打开项目设置 UI 时，读取一次 ClientSettings 当前值初始化控件。
  • 用户拖动滑条或点击确认时写入设置，不要每帧轮询或重复写入。
  • 图形预设适合提供“一键省电 / 流畅 / 平衡 / 高画质”；细项开关适合高级设置页。
  • 如果某个视觉效果需要全体玩家一致，由服务端同步“意图”，每个客户端收到后再应用本地设置或视觉参数。

验证 ​

powershell
dotnet build src\GameEntry.csproj -c Client-Debug

运行客户端后验证：

  1. 打开项目设置 UI，确认初始值来自 ClientSettings。
  2. 修改画质、帧率或音频，观察是否立即生效。
  3. 退出并重新进入游戏，确认本地配置按预期保留。
  4. 如需对照平台设置面板，重新打开面板检查内置图形/音频项是否合理显示。

相关文档 ​