mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-05-07 00:39:00 +08:00
docs(godot): 刷新存储与设置专题页
- 更新 Godot 存储与设置专题页到当前运行时与 applicator 接线路径 - 补充 Godot 子页巡检结论、验证结果与 RP-014 恢复点记录
This commit is contained in:
gewuyou
parent
71f36c7c20
commit
1a62f337a6
@ -12,11 +12,12 @@
|
||||
|
||||
## 当前恢复点
|
||||
|
||||
- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-013`
|
||||
- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-014`
|
||||
- 当前阶段：`Phase 5 - Governance Maintenance`
|
||||
- 当前焦点：
|
||||
- 继续巡检 `Godot` / `Game` 相关 README、landing page、tutorial 与 API reference 的 cross-link 是否回漂
|
||||
- 保持 `Godot` family 的模块 README、生成器 README 与站内专题页使用同一套 owner / adoption path 叙述
|
||||
- 重点观察 `storage.md` / `setting.md` 这类子页是否继续沿用当前 applicator / adoption path 口径
|
||||
- 仅在发现新的入口漂移时补最小修复，不重复改写已经稳定的 landing page
|
||||
|
||||
## 当前状态摘要
|
||||
@ -42,6 +43,9 @@
|
||||
- `2026-04-23` 的 validation-only 巡检新增结论：
|
||||
- 根 `README.md`、`docs/zh-CN/godot/index.md`、`docs/zh-CN/tutorials/godot-integration.md`、`docs/zh-CN/source-generators/index.md` 与 `docs/zh-CN/api-reference/index.md` 当前仍保持同一套 `Godot` owner / adoption path 叙述，没有发现新的入口漂移
|
||||
- `scan_module_evidence.py Godot` 显示 `docs/zh-CN/godot/storage.md` 与 `setting.md` 仍属于 `Godot` runtime docs surface，应并入 active topic 的最小恢复摘要，避免后续 `boot` 漏掉当前 landing page 的关键入口
|
||||
- `2026-04-23` 的子页巡检新增结论：
|
||||
- `docs/zh-CN/godot/storage.md` 之前仍停留在旧版 API 手册写法，缺少 frontmatter、`IStorage` / repository 边界和 `GodotYamlConfigLoader` 的分流说明
|
||||
- `docs/zh-CN/godot/setting.md` 之前仍把 `GodotAudioSettings` / `GodotGraphicsSettings` 描述成直接持有设置数据对象的旧构造方式，没有反映当前 `ISettingsModel` + `RegisterApplicator(...)` 接法
|
||||
- `2026-04-23` 的交叉链接巡检新增结论：
|
||||
- `GFramework.Godot/README.md` 仍停留在旧版简略描述，缺少当前包关系、子系统地图、最小接入路径与 `docs/zh-CN` 入口
|
||||
- `GFramework.Godot.SourceGenerators/README.md` 虽有示例，但没有覆盖 `AutoScene`、`AutoUiPage`、`AutoRegisterExportedCollections` 等当前生成器分组，也没有把运行时 / 生成器边界说清
|
||||
@ -82,6 +86,8 @@
|
||||
- 更新 `docs/zh-CN/api-reference/index.md` 的 `Godot` 模块映射，使 API 参考能直接落到 `Godot` 专用生成器专题页，而不是仅回到总览页
|
||||
- 修正根 `README.md` 中 `GFramework.Godot.SourceGenerators` 的模块描述，使其与当前生成器职责边界一致
|
||||
- 扩充 `docs/zh-CN/source-generators/index.md` 的 Godot 选包说明，把 Scene / UI 包装与导出集合注册辅助纳入入口摘要
|
||||
- 重写 `docs/zh-CN/godot/storage.md`，补齐 frontmatter、`GodotFileStorage` 的路径语义、repository 分工与 `GodotYamlConfigLoader` 分流边界
|
||||
- 重写 `docs/zh-CN/godot/setting.md`，改回当前 `ISettingsModel` / `RegisterApplicator(...)` 口径，并补上 `LocalizationMap` fallback 与 `CoreGrid` 注册示例
|
||||
|
||||
## Inventory（第一版）
|
||||
|
||||
@ -130,10 +136,10 @@
|
||||
- 结果：通过；PR `#271` 已关闭，latest reviewed commit 为 `df91d3706ba9db71737e803ef2f40f4841ecbbf1`，当前 `2` 条 open thread 都是已被本地文件满足的陈旧信号，不再构成本轮阻塞
|
||||
- 最新构建结论：
|
||||
- `2026-04-23` `cd docs && bun run build`
|
||||
- 结果：通过；在 `Godot` docs surface 的 validation-only 巡检后再次验证通过，仅保留既有 VitePress 大 chunk warning，无构建失败
|
||||
- 结果：通过；在修正 `docs/zh-CN/godot/storage.md` 与 `setting.md` 后再次验证通过，仅保留既有 VitePress 大 chunk warning，无构建失败
|
||||
- 最新稳定性巡检结论：
|
||||
- `2026-04-23` 重新执行 `Godot` docs surface 巡检
|
||||
- 结果：通过；`README.md`、`docs/zh-CN/godot/index.md`、`docs/zh-CN/tutorials/godot-integration.md`、`docs/zh-CN/source-generators/index.md` 与 `docs/zh-CN/api-reference/index.md` 仍保持同一套职责边界，没有发现新的入口漂移
|
||||
- 结果：通过；根入口链路保持稳定，并额外发现 `docs/zh-CN/godot/storage.md`、`setting.md` 两页存在旧版叙述残留，当前已按源码口径完成最小修复
|
||||
- 最新恢复治理结论：
|
||||
- `2026-04-23` 重新读取 `ai-plan/public/archive/documentation-governance-and-refresh/**`
|
||||
- 结果：通过；确认 `Godot` family 适合把最小恢复摘要迁回 active topic，但不需要把整段归档历史重新放回默认 `boot` 路径
|
||||
@ -153,6 +159,8 @@
|
||||
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/index.md`：通过
|
||||
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/index.md`：通过
|
||||
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/godot-integration.md`：通过
|
||||
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/storage.md`：通过
|
||||
- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/setting.md`：通过
|
||||
|
||||
## 下一步
|
||||
|
||||
|
||||
@ -480,3 +480,49 @@
|
||||
1. 若后续分支继续调整 `GFramework.Godot` 运行时入口，优先复核 `docs/zh-CN/godot/storage.md`、`setting.md` 与根
|
||||
`README.md` / landing page 是否仍保持同一套职责边界
|
||||
2. 当后续分支再修改 `Godot` / `Game` family 的 README、docs 或公共 API 时，回到对应模块追加 targeted 巡检与验证
|
||||
|
||||
### 当前恢复点：RP-014
|
||||
|
||||
- 继续沿用 `RP-013` 的 `Godot` docs surface 巡检范围，补读：
|
||||
- `docs/zh-CN/godot/storage.md`
|
||||
- `docs/zh-CN/godot/setting.md`
|
||||
- `GFramework.Godot/Storage/GodotFileStorage.cs`
|
||||
- `GFramework.Godot/Setting/GodotAudioSettings.cs`
|
||||
- `GFramework.Godot/Setting/GodotGraphicsSettings.cs`
|
||||
- `GFramework.Godot/Setting/GodotLocalizationSettings.cs`
|
||||
- `GFramework.Godot/Setting/Data/AudioBusMap.cs`
|
||||
- `GFramework.Godot/Setting/Data/LocalizationMap.cs`
|
||||
- `GFramework.Game.Tests/Setting/GodotLocalizationSettingsTests.cs`
|
||||
- `ai-libs/CoreGrid/scripts/module/UtilityModule.cs`
|
||||
- `ai-libs/CoreGrid/scripts/module/ModelModule.cs`
|
||||
- 巡检发现两处新的 topic 级漂移：
|
||||
- `docs/zh-CN/godot/storage.md` 仍按旧版 API 手册组织，缺少 frontmatter、当前 `IStorage` / repository 分工与
|
||||
`GodotYamlConfigLoader` 分流说明
|
||||
- `docs/zh-CN/godot/setting.md` 仍使用过时的“settings data 直接注入 applicator 构造函数”叙述，没有反映当前
|
||||
`ISettingsModel` + `RegisterApplicator(...)` 的真实接线方式
|
||||
- 因此本轮执行最小修复集：
|
||||
- 重写 `docs/zh-CN/godot/storage.md`
|
||||
- 重写 `docs/zh-CN/godot/setting.md`
|
||||
- 更新 active tracking 的恢复点、巡检结论与验证结果
|
||||
|
||||
### 当前决策（RP-014）
|
||||
|
||||
- 继续遵循“README / landing 稳定时，不重写稳定入口；只修新发现的 topic 漂移”的治理节奏
|
||||
- `storage.md` 应强调宿主路径语义与 repository 分工，而不是重复 `Game` 通用存储手册
|
||||
- `setting.md` 应强调 applicator 注册和运行时边界，而不是重新维护一份过时的设置 API 摘要
|
||||
|
||||
### 当前验证（RP-014）
|
||||
|
||||
- 模块扫描：
|
||||
- `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Godot`：通过
|
||||
- 文档校验：
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/storage.md`：通过
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/setting.md`：通过
|
||||
- 构建校验：
|
||||
- `cd docs && bun run build`：通过；仅保留既有 VitePress 大 chunk warning，无构建失败
|
||||
|
||||
### 下一步
|
||||
|
||||
1. 若后续分支继续调整 `GFramework.Godot` 运行时入口，优先复核 `docs/zh-CN/godot/storage.md`、`setting.md` 与根
|
||||
`README.md` / landing page 是否仍保持同一套职责边界
|
||||
2. 当后续分支再修改 `Godot` / `Game` family 的 README、docs 或公共 API 时，回到对应模块追加 targeted 巡检与验证
|
||||
|
||||
@ -1,603 +1,156 @@
|
||||
# Godot 设置模块 (Godot Settings Module)
|
||||
---
|
||||
title: Godot 设置系统
|
||||
description: 以当前 GFramework.Godot 源码、测试与 CoreGrid 接线为准，说明 Godot settings applicator 的职责、注册方式和运行时边界。
|
||||
---
|
||||
|
||||
## 概述
|
||||
# Godot 设置系统
|
||||
|
||||
Godot 设置模块是 GFramework.Godot 的核心组件之一，专门为 Godot 引擎提供游戏设置系统的实现。该模块将通用的设置框架与 Godot
|
||||
引擎的特定功能相结合，提供了音频设置、图形设置和本地化设置的完整解决方案。
|
||||
`GFramework.Godot` 在设置这一层做的事情很克制：它没有重新发明一套设置模型，而是给
|
||||
`GFramework.Game` 的 `ISettingsModel` 提供三个 Godot 宿主 applicator：
|
||||
|
||||
## 核心类
|
||||
- `GodotAudioSettings`
|
||||
- `GodotGraphicsSettings`
|
||||
- `GodotLocalizationSettings`
|
||||
|
||||
### 音频设置系统
|
||||
这些类型的职责是“把已经存在的设置数据应用到 Godot 引擎和框架运行时”，不是负责设置 UI、设置持久化或设置迁移。
|
||||
|
||||
#### AudioBusMap
|
||||
## 当前公开入口
|
||||
|
||||
音频总线映射配置类，用于定义音频系统中不同类型音频的总线名称。
|
||||
### `GodotAudioSettings`
|
||||
|
||||
**属性：**
|
||||
`GodotAudioSettings` 从 `ISettingsModel` 读取 `AudioSettings`，再按 `AudioBusMap` 中的总线名把音量写入
|
||||
`AudioServer`。
|
||||
|
||||
- `Master` - 主音频总线名称（默认："Master"）
|
||||
- `Bgm` - 背景音乐音频总线名称（默认："BGM"）
|
||||
- `Sfx` - 音效音频总线名称（默认："SFX"）
|
||||
当前行为有几个关键点：
|
||||
|
||||
#### GodotAudioApplier
|
||||
- `Master`、`Bgm`、`Sfx` 三类音量都来自 `AudioSettings`
|
||||
- 应用前会把线性音量限制在 `0.0001f ~ 1f`，再转换成分贝
|
||||
- 如果找不到对应 bus，当前实现只会 `GD.PushWarning(...)`，不会抛异常中断整个设置流程
|
||||
|
||||
音频设置应用器，负责将音频设置应用到 Godot 引擎的音频总线系统。
|
||||
`AudioBusMap` 默认值是：
|
||||
|
||||
**功能：**
|
||||
- `Master`
|
||||
- `BGM`
|
||||
- `SFX`
|
||||
|
||||
- 应用音量设置到指定音频总线
|
||||
- 处理音量格式转换（线性值到分贝）
|
||||
- 音频总线存在性检查和警告
|
||||
如果项目里的 Godot Audio Bus 命名不同，需要在注册 applicator 时替换映射，而不是改写 applicator 本身。
|
||||
|
||||
#### GodotAudioSettings
|
||||
### `GodotGraphicsSettings`
|
||||
|
||||
Godot 音频设置实现类，接收 AudioSettings 配置并实现 IApplyAbleSettings 接口，负责将音频配置应用到 Godot 音频系统。
|
||||
`GodotGraphicsSettings` 从 `ISettingsModel` 读取 `GraphicsSettings`，并把结果同步到 `DisplayServer`：
|
||||
|
||||
**实现关系：**
|
||||
- `Fullscreen = true` 时切到 `ExclusiveFullscreen`
|
||||
- 同时把 `Borderless` flag 设为 `true`
|
||||
- `Fullscreen = false` 时切回窗口模式，设置窗口尺寸，并按主屏尺寸重新居中
|
||||
|
||||
```
|
||||
AudioSettings (配置数据)
|
||||
↓ [组合]
|
||||
GodotAudioSettings (Godot 特定实现) → IApplyAbleSettings (可应用设置接口)
|
||||
```
|
||||
当前实现没有扩展到分辨率档位之外的图形质量、渲染后端或平台特定显示策略。本页不再把这些未实现能力写成既成事实。
|
||||
|
||||
**功能：**
|
||||
### `GodotLocalizationSettings`
|
||||
|
||||
- 接收 AudioSettings 配置对象和 AudioBusMap 总线映射
|
||||
- 实现 `ApplyAsync()` 方法，将音量设置应用到指定音频总线
|
||||
- 支持自定义音频总线映射
|
||||
- 自动处理音量格式转换（线性值到分贝）
|
||||
`GodotLocalizationSettings` 负责把 `LocalizationSettings.Language` 同时同步到：
|
||||
|
||||
### 图形设置系统
|
||||
- Godot `TranslationServer.SetLocale(...)`
|
||||
- GFramework `ILocalizationManager.SetLanguage(...)`
|
||||
|
||||
#### GodotGraphicsSettings
|
||||
这一步依赖 `LocalizationMap` 把“用户可见语言值”拆成两套目标值：
|
||||
|
||||
Godot 图形设置实现类，继承自 GraphicsSettings 并实现 IApplyAbleSettings。
|
||||
- Godot locale，例如 `zh_CN`
|
||||
- 框架语言码，例如 `zhs`
|
||||
|
||||
**功能：**
|
||||
当前默认映射是：
|
||||
|
||||
- 分辨率设置和窗口尺寸调整
|
||||
- 全屏模式切换
|
||||
- 窗口位置自动居中
|
||||
- 多显示器支持
|
||||
- `简体中文` -> Godot `zh_CN`，框架 `zhs`
|
||||
- `English` -> Godot `en`，框架 `eng`
|
||||
|
||||
### 本地化设置系统
|
||||
`GFramework.Game.Tests/Setting/GodotLocalizationSettingsTests.cs` 已覆盖三条关键边界：
|
||||
|
||||
#### LocalizationMap
|
||||
- 英文会同步到 `en` / `eng`
|
||||
- 简体中文会同步到 `zh_CN` / `zhs`
|
||||
- 未知语言值会稳定回退到英文，而不是让 Godot locale 与框架语言状态分裂
|
||||
|
||||
本地化映射配置类，用于把设置系统中保存的用户可见语言值解析为：
|
||||
如果当前架构上下文里解析不到 `ILocalizationManager`，Godot locale 仍会被设置，只是不会额外同步框架语言管理器。
|
||||
|
||||
- Godot `TranslationServer` 使用的 locale
|
||||
- GFramework `ILocalizationManager` 使用的语言码
|
||||
## 最小接入路径
|
||||
|
||||
默认映射如下：
|
||||
|
||||
- `"简体中文"` -> Godot `zh_CN`，框架语言码 `zhs`
|
||||
- `"English"` -> Godot `en`，框架语言码 `eng`
|
||||
|
||||
未知语言值会稳定回退到英文，避免重启后出现设置值与运行时语言状态不一致。
|
||||
|
||||
#### GodotLocalizationSettings
|
||||
|
||||
Godot 本地化设置实现类，负责把 `LocalizationSettings` 同时应用到 Godot 引擎与 GFramework 本地化管理器。
|
||||
|
||||
**功能：**
|
||||
|
||||
- 将语言设置应用到 `TranslationServer.SetLocale(...)`
|
||||
- 同步 `ILocalizationManager.SetLanguage(...)`
|
||||
- 通过统一映射避免 Godot locale 与框架语言码分裂
|
||||
|
||||
## 架构设计
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[AudioSettings] --> B[GodotAudioSettings]
|
||||
C[GraphicsSettings] --> D[GodotGraphicsSettings]
|
||||
E[LocalizationSettings] --> F[GodotLocalizationSettings]
|
||||
G[IApplyAbleSettings] --> B
|
||||
G --> D
|
||||
G --> F
|
||||
|
||||
H[AudioBusMap] --> B
|
||||
I[LocalizationMap] --> F
|
||||
|
||||
B --> J[AudioServer API]
|
||||
D --> K[DisplayServer API]
|
||||
F --> L[TranslationServer API]
|
||||
F --> M[ILocalizationManager]
|
||||
|
||||
N[SettingsSystem] --> O[ApplyAsync Method]
|
||||
O --> B
|
||||
O --> D
|
||||
O --> F
|
||||
```
|
||||
|
||||
## 使用示例
|
||||
|
||||
### 音频设置配置
|
||||
|
||||
#### 基本音频设置
|
||||
当前消费者 `ai-libs/CoreGrid` 的接法，是先注册 `SettingsModel<ISettingsDataRepository>`，再把 Godot applicator
|
||||
挂进去：
|
||||
|
||||
```csharp
|
||||
// 创建音频配置数据
|
||||
var settings = new AudioSettings
|
||||
{
|
||||
MasterVolume = 0.8f, // 80% 主音量
|
||||
BgmVolume = 0.6f, // 60% 背景音乐音量
|
||||
SfxVolume = 0.9f // 90% 音效音量
|
||||
};
|
||||
using GFramework.Game.Abstractions.Data;
|
||||
using GFramework.Game.Abstractions.Setting;
|
||||
using GFramework.Game.Setting;
|
||||
using GFramework.Godot.Setting;
|
||||
using GFramework.Godot.Setting.Data;
|
||||
|
||||
// 创建 Godot 音频设置应用器
|
||||
var audioSettings = new GodotAudioSettings(settings, new AudioBusMap());
|
||||
var settingsDataRepository = architecture.Context.GetUtility<ISettingsDataRepository>();
|
||||
|
||||
// 应用设置
|
||||
await audioSettings.ApplyAsync();
|
||||
architecture.RegisterModel(
|
||||
new SettingsModel<ISettingsDataRepository>(
|
||||
new SettingDataLocationProvider(),
|
||||
settingsDataRepository)
|
||||
.Also(it =>
|
||||
{
|
||||
it.RegisterApplicator(new GodotAudioSettings(it, new AudioBusMap()))
|
||||
.RegisterApplicator(new GodotGraphicsSettings(it))
|
||||
.RegisterApplicator(new GodotLocalizationSettings(it, new LocalizationMap()));
|
||||
}));
|
||||
```
|
||||
|
||||
#### 自定义音频总线映射
|
||||
这条接法说明了当前边界：
|
||||
|
||||
- 设置数据和生命周期由 `SettingsModel` 管
|
||||
- `GodotAudioSettings` / `GodotGraphicsSettings` / `GodotLocalizationSettings` 只是 applicator
|
||||
- 保存、加载和迁移仍然走 `ISettingsDataRepository`、`SettingsModel.InitializeAsync()`、`SaveAllAsync()` 等 `Game`
|
||||
family 入口
|
||||
|
||||
## 运行时使用方式
|
||||
|
||||
业务代码通常不会直接 new 一次 applicator 然后立即调用，而是通过 `ISettingsSystem` 或 `ISettingsModel` 触发应用：
|
||||
|
||||
```csharp
|
||||
// 自定义音频总线映射
|
||||
var customBusMap = new AudioBusMap
|
||||
{
|
||||
Master = "Master_Bus",
|
||||
Bgm = "Background_Music",
|
||||
Sfx = "Sound_Effects"
|
||||
};
|
||||
using GFramework.Game.Abstractions.Setting;
|
||||
using GFramework.Godot.Setting;
|
||||
|
||||
// 创建音频配置
|
||||
var settings = new AudioSettings
|
||||
{
|
||||
MasterVolume = 0.7f,
|
||||
BgmVolume = 0.5f,
|
||||
SfxVolume = 0.8f
|
||||
};
|
||||
|
||||
// 使用自定义总线映射应用设置
|
||||
var audioSettings = new GodotAudioSettings(settings, customBusMap);
|
||||
await audioSettings.ApplyAsync();
|
||||
```
|
||||
|
||||
#### 通过设置系统使用
|
||||
|
||||
```csharp
|
||||
// 注册音频设置到设置模型
|
||||
var settingsModel = this.GetModel<ISettingsModel>();
|
||||
var audioSettingsData = settingsModel.Get<AudioSettings>();
|
||||
audioSettingsData.MasterVolume = 0.8f;
|
||||
audioSettingsData.BgmVolume = 0.6f;
|
||||
audioSettingsData.SfxVolume = 0.9f;
|
||||
var audioData = settingsModel.GetData<AudioSettings>();
|
||||
audioData.MasterVolume = 0.8f;
|
||||
audioData.BgmVolume = 0.6f;
|
||||
audioData.SfxVolume = 0.9f;
|
||||
|
||||
// 创建 Godot 音频设置应用器
|
||||
var godotAudioSettings = new GodotAudioSettings(audioSettingsData, new AudioBusMap());
|
||||
await godotAudioSettings.ApplyAsync();
|
||||
var settingsSystem = this.GetSystem<ISettingsSystem>();
|
||||
await settingsSystem.Apply<GodotAudioSettings>();
|
||||
```
|
||||
|
||||
### 图形设置配置
|
||||
对图形和语言设置的调用方式相同，区别只是 applicator 类型不同。
|
||||
|
||||
#### 基本图形设置
|
||||
## 当前边界
|
||||
|
||||
```csharp
|
||||
// 创建图形设置
|
||||
var graphicsSettings = new GodotGraphicsSettings
|
||||
{
|
||||
ResolutionWidth = 1920,
|
||||
ResolutionHeight = 1080,
|
||||
Fullscreen = true
|
||||
};
|
||||
- 这三个类型都不是设置数据对象；它们读取的是 `AudioSettings`、`GraphicsSettings`、`LocalizationSettings`
|
||||
- 它们不负责设置持久化；是否保存到文件由 `ISettingsDataRepository` 和存储层决定
|
||||
- `ApplyAsync()` 当前都只是同步推进 Godot 引擎调用后返回 `Task.CompletedTask`，不会启动后台工作线程
|
||||
- `GodotAudioSettings` 依赖项目里已经存在对应 bus 名称；缺失时只会警告，不会帮你自动创建总线
|
||||
- `GodotGraphicsSettings` 当前只覆盖窗口模式、尺寸和居中，不等于一个完整的图形选项系统
|
||||
- `GodotLocalizationSettings` 解决的是“用户语言值 -> Godot locale / 框架语言码”双向对齐，不负责翻译资源本身的组织方式
|
||||
|
||||
// 应用设置
|
||||
await graphicsSettings.ApplyAsync();
|
||||
```
|
||||
## 什么时候应该改看别的入口
|
||||
|
||||
#### 窗口模式切换
|
||||
### 先理解设置模型和仓库
|
||||
|
||||
```csharp
|
||||
public class DisplayManager : Node
|
||||
{
|
||||
private GodotGraphicsSettings _graphicsSettings;
|
||||
|
||||
public override void _Ready()
|
||||
{
|
||||
_graphicsSettings = new GodotGraphicsSettings();
|
||||
}
|
||||
|
||||
public async Task ToggleFullscreen()
|
||||
{
|
||||
_graphicsSettings.Fullscreen = !_graphicsSettings.Fullscreen;
|
||||
await _graphicsSettings.ApplyAsync();
|
||||
}
|
||||
|
||||
public async Task SetResolution(int width, int height)
|
||||
{
|
||||
_graphicsSettings.ResolutionWidth = width;
|
||||
_graphicsSettings.ResolutionHeight = height;
|
||||
_graphicsSettings.Fullscreen = false; // 窗口化时自动关闭全屏
|
||||
await _graphicsSettings.ApplyAsync();
|
||||
}
|
||||
}
|
||||
```
|
||||
如果你想先理解 `ISettingsData`、`IResetApplyAbleSettings`、`SettingsModel`、`SettingsSystem` 与设置迁移，先看
|
||||
[`../game/setting.md`](../game/setting.md)。
|
||||
|
||||
#### 预设分辨率配置
|
||||
### 先理解设置如何被持久化
|
||||
|
||||
```csharp
|
||||
public class ResolutionPresets
|
||||
{
|
||||
public static readonly (int width, int height)[] CommonResolutions =
|
||||
{
|
||||
(1920, 1080), // Full HD
|
||||
(2560, 1440), // QHD
|
||||
(3840, 2160), // 4K
|
||||
(1280, 720), // HD
|
||||
(1366, 768), // 常见笔记本分辨率
|
||||
};
|
||||
|
||||
public static async Task ApplyResolution(GodotGraphicsSettings settings, int width, int height)
|
||||
{
|
||||
settings.ResolutionWidth = width;
|
||||
settings.ResolutionHeight = height;
|
||||
settings.Fullscreen = false;
|
||||
await settings.ApplyAsync();
|
||||
}
|
||||
}
|
||||
```
|
||||
如果你关注的是统一设置文件、备份、数据位置和底层存储实现，应该回到：
|
||||
|
||||
## API 详细说明
|
||||
- [`../game/storage.md`](../game/storage.md)
|
||||
- [Godot 存储系统](./storage.md)
|
||||
|
||||
### AudioBusMap
|
||||
本页只补 Godot 宿主如何“应用”设置，不重复维护一份完整设置系统手册。
|
||||
|
||||
```csharp
|
||||
public sealed class AudioBusMap
|
||||
{
|
||||
public string Master { get; init; } = "Master";
|
||||
public string Bgm { get; init; } = "BGM";
|
||||
public string Sfx { get; init; } = "SFX";
|
||||
}
|
||||
```
|
||||
## 继续阅读
|
||||
|
||||
**特点：**
|
||||
|
||||
- 使用 `init` 属性，创建后不可修改
|
||||
- 提供合理的默认值
|
||||
- 支持对象初始化语法
|
||||
|
||||
### GodotAudioSettings
|
||||
|
||||
```csharp
|
||||
public class GodotAudioSettings(AudioSettings settings, AudioBusMap busMap) : IApplyAbleSettings
|
||||
{
|
||||
public Task ApplyAsync();
|
||||
}
|
||||
```
|
||||
|
||||
**构造函数参数：**
|
||||
|
||||
- `settings` - AudioSettings 配置对象，包含音量设置
|
||||
- `busMap` - AudioBusMap 对象，定义音频总线映射
|
||||
|
||||
**Apply 方法实现：**
|
||||
|
||||
```csharp
|
||||
public Task ApplyAsync()
|
||||
{
|
||||
SetBus(busMap.Master, settings.MasterVolume);
|
||||
SetBus(busMap.Bgm, settings.BgmVolume);
|
||||
SetBus(busMap.Sfx, settings.SfxVolume);
|
||||
return Task.CompletedTask;
|
||||
}
|
||||
```
|
||||
|
||||
### GodotGraphicsSettings
|
||||
|
||||
```csharp
|
||||
public class GodotGraphicsSettings : GraphicsSettings, IApplyAbleSettings
|
||||
{
|
||||
public Task ApplyAsync();
|
||||
}
|
||||
```
|
||||
|
||||
**Apply 方法功能：**
|
||||
|
||||
- 设置窗口边框标志
|
||||
- 切换窗口模式（窗口化/全屏）
|
||||
- 调整窗口尺寸
|
||||
- 自动居中窗口
|
||||
|
||||
## 技术实现细节
|
||||
|
||||
### 音频音量转换
|
||||
|
||||
Godot 音频系统使用分贝（dB）作为音量单位，而我们通常使用线性值（0-1）：
|
||||
|
||||
```csharp
|
||||
// 线性值到分贝转换
|
||||
float linearVolume = 0.5f; // 50% 音量
|
||||
float dbVolume = Mathf.LinearToDb(linearVolume); // 转换为分贝
|
||||
|
||||
// 应用到音频总线
|
||||
AudioServer.SetBusVolumeDb(busIndex, dbVolume);
|
||||
```
|
||||
|
||||
### 音量限制和保护
|
||||
|
||||
为避免完全静音（-inf dB），应用了最小音量限制：
|
||||
|
||||
```csharp
|
||||
float clampedVolume = Mathf.Clamp(linear, 0.0001f, 1f);
|
||||
float dbVolume = Mathf.LinearToDb(clampedVolume);
|
||||
```
|
||||
|
||||
### 窗口管理
|
||||
|
||||
#### 全屏模式
|
||||
|
||||
```csharp
|
||||
// 设置全屏
|
||||
DisplayServer.WindowSetMode(DisplayServer.WindowMode.ExclusiveFullscreen);
|
||||
DisplayServer.WindowSetFlag(DisplayServer.WindowFlags.Borderless, true);
|
||||
```
|
||||
|
||||
#### 窗口化模式
|
||||
|
||||
```csharp
|
||||
// 设置窗口化
|
||||
DisplayServer.WindowSetMode(DisplayServer.WindowMode.Windowed);
|
||||
DisplayServer.WindowSetSize(newSize);
|
||||
|
||||
// 居中窗口
|
||||
var screen = DisplayServer.GetPrimaryScreen();
|
||||
var screenSize = DisplayServer.ScreenGetSize(screen);
|
||||
var position = (screenSize - newSize) / 2;
|
||||
DisplayServer.WindowSetPosition(position);
|
||||
```
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 1. 音频设置管理
|
||||
|
||||
#### 音量变化平滑过渡
|
||||
|
||||
```csharp
|
||||
public class AudioManager : Node
|
||||
{
|
||||
private Tween _volumeTween;
|
||||
|
||||
public async Task SmoothVolumeTransition(float targetMasterVolume, float duration = 1.0f)
|
||||
{
|
||||
var currentVolume = AudioServer.GetBusVolumeDb(AudioServer.GetBusIndex("Master"));
|
||||
var currentLinear = Mathf.DbToLinear(currentVolume);
|
||||
|
||||
_volumeTween?.Kill();
|
||||
_volumeTween = CreateTween();
|
||||
|
||||
_volumeTween.TweenMethod(
|
||||
new Callable(this, nameof(SetMasterVolume)),
|
||||
currentLinear,
|
||||
targetMasterVolume,
|
||||
duration
|
||||
);
|
||||
}
|
||||
|
||||
private async void SetMasterVolume(float linearVolume)
|
||||
{
|
||||
var settings = new AudioSettings { MasterVolume = linearVolume };
|
||||
var audioSettings = new GodotAudioSettings(settings, new AudioBusMap());
|
||||
await audioSettings.ApplyAsync();
|
||||
}
|
||||
}
|
||||
|
||||
// 使用自定义总线映射的平滑过渡
|
||||
public class CustomAudioManager : Node
|
||||
{
|
||||
private Tween _volumeTween;
|
||||
private AudioBusMap _customBusMap;
|
||||
|
||||
public override void _Ready()
|
||||
{
|
||||
_customBusMap = new AudioBusMap
|
||||
{
|
||||
Master = "Master_Bus",
|
||||
Bgm = "Background_Music",
|
||||
Sfx = "Sound_Effects"
|
||||
};
|
||||
}
|
||||
|
||||
public async Task SmoothVolumeTransition(float targetMasterVolume, float duration = 1.0f)
|
||||
{
|
||||
var settings = new AudioSettings { MasterVolume = targetMasterVolume };
|
||||
var currentVolume = AudioServer.GetBusVolumeDb(AudioServer.GetBusIndex(_customBusMap.Master));
|
||||
var currentLinear = Mathf.DbToLinear(currentVolume);
|
||||
|
||||
_volumeTween?.Kill();
|
||||
_volumeTween = CreateTween();
|
||||
|
||||
_volumeTween.TweenMethod(
|
||||
new Callable(this, nameof(SetMasterVolume)),
|
||||
currentLinear,
|
||||
targetMasterVolume,
|
||||
duration
|
||||
);
|
||||
}
|
||||
|
||||
private async void SetMasterVolume(float linearVolume)
|
||||
{
|
||||
var audioSettingsData = new AudioSettings { MasterVolume = linearVolume };
|
||||
var audioSettings = new GodotAudioSettings(audioSettingsData, _customBusMap);
|
||||
await audioSettings.ApplyAsync();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 音频设置验证
|
||||
|
||||
```csharp
|
||||
public static class AudioSettingsValidator
|
||||
{
|
||||
public static bool ValidateBusNames(AudioBusMap busMap)
|
||||
{
|
||||
var masterIndex = AudioServer.GetBusIndex(busMap.Master);
|
||||
var bgmIndex = AudioServer.GetBusIndex(busMap.Bgm);
|
||||
var sfxIndex = AudioServer.GetBusIndex(busMap.Sfx);
|
||||
|
||||
return masterIndex >= 0 && bgmIndex >= 0 && sfxIndex >= 0;
|
||||
}
|
||||
|
||||
public static void LogMissingBuses(AudioBusMap busMap)
|
||||
{
|
||||
if (AudioServer.GetBusIndex(busMap.Master) < 0)
|
||||
GD.PrintErr($"Master bus not found: {busMap.Master}");
|
||||
|
||||
if (AudioServer.GetBusIndex(busMap.Bgm) < 0)
|
||||
GD.PrintErr($"BGM bus not found: {busMap.Bgm}");
|
||||
|
||||
if (AudioServer.GetBusIndex(busMap.Sfx) < 0)
|
||||
GD.PrintErr($"SFX bus not found: {busMap.Sfx}");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 图形设置管理
|
||||
|
||||
#### 分辨率变更安全检查
|
||||
|
||||
```csharp
|
||||
public static class DisplayValidator
|
||||
{
|
||||
public static bool IsResolutionSupported(int width, int height)
|
||||
{
|
||||
var screen = DisplayServer.GetPrimaryScreen();
|
||||
var screenSize = DisplayServer.ScreenGetSize(screen);
|
||||
|
||||
return width <= screenSize.x && height <= screenSize.y;
|
||||
}
|
||||
|
||||
public static (int width, int height) GetMaxSafeResolution()
|
||||
{
|
||||
var screen = DisplayServer.GetPrimaryScreen();
|
||||
var screenSize = DisplayServer.ScreenGetSize(screen);
|
||||
|
||||
return ((int)screenSize.x, (int)screenSize.y);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 图形设置持久化
|
||||
|
||||
```csharp
|
||||
public class GraphicsSettingsManager : Node
|
||||
{
|
||||
private const string SettingsKey = "graphics_settings";
|
||||
private GodotGraphicsSettings _settings;
|
||||
|
||||
public override void _Ready()
|
||||
{
|
||||
LoadSettings();
|
||||
}
|
||||
|
||||
private void LoadSettings()
|
||||
{
|
||||
var storage = new GodotFileStorage(new JsonSerializer());
|
||||
|
||||
try
|
||||
{
|
||||
_settings = storage.Read<GodotGraphicsSettings>(SettingsKey);
|
||||
}
|
||||
catch (FileNotFoundException)
|
||||
{
|
||||
_settings = new GodotGraphicsSettings
|
||||
{
|
||||
ResolutionWidth = 1920,
|
||||
ResolutionHeight = 1080,
|
||||
Fullscreen = false
|
||||
};
|
||||
SaveSettings();
|
||||
}
|
||||
}
|
||||
|
||||
public void SaveSettings()
|
||||
{
|
||||
var storage = new GodotFileStorage(new JsonSerializer());
|
||||
storage.Write(SettingsKey, _settings);
|
||||
}
|
||||
|
||||
public async Task ApplyAndSave()
|
||||
{
|
||||
await _settings.ApplyAsync();
|
||||
SaveSettings();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 性能考虑
|
||||
|
||||
### 1. 音频设置应用
|
||||
|
||||
- 音频总线查找是 O(1) 操作
|
||||
- 音量转换计算开销很小
|
||||
- 建议批量应用多个音量设置
|
||||
|
||||
### 2. 图形设置应用
|
||||
|
||||
- 窗口操作需要系统调用，相对较慢
|
||||
- 分辨率变更可能触发窗口重建
|
||||
- 避免频繁切换显示模式
|
||||
|
||||
### 3. 设置持久化
|
||||
|
||||
- 使用异步文件 I/O
|
||||
- 考虑设置变更防抖机制
|
||||
- 压缩设置文件以减少 I/O 开销
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 常见问题
|
||||
|
||||
#### 1. 音频总线未找到
|
||||
|
||||
```
|
||||
错误：Audio bus not found: CustomBGM
|
||||
解决：确保在 Godot 项目中创建了对应的音频总线
|
||||
```
|
||||
|
||||
#### 2. 分辨率设置无效
|
||||
|
||||
```
|
||||
错误：分辨率无法设置到指定值
|
||||
解决：检查分辨率是否超出显示器支持范围
|
||||
```
|
||||
|
||||
#### 3. 全屏模式问题
|
||||
|
||||
```
|
||||
错误：全屏切换失败
|
||||
解决：检查是否在调试器中运行，某些全屏模式在调试时可能不可用
|
||||
```
|
||||
|
||||
### 调试技巧
|
||||
|
||||
#### 音频调试
|
||||
|
||||
```csharp
|
||||
// 打印所有音频总线信息
|
||||
for (int i = 0; i < AudioServer.GetBusCount(); i++)
|
||||
{
|
||||
var name = AudioServer.GetBusName(i);
|
||||
var volume = AudioServer.GetBusVolumeDb(i);
|
||||
GD.Print($"Bus {i}: {name} ({volume} dB)");
|
||||
}
|
||||
```
|
||||
|
||||
#### 图形调试
|
||||
|
||||
```csharp
|
||||
// 打印当前显示信息
|
||||
var screen = DisplayServer.GetPrimaryScreen();
|
||||
var screenSize = DisplayServer.ScreenGetSize(screen);
|
||||
var windowSize = DisplayServer.WindowGetSize();
|
||||
var windowPos = DisplayServer.WindowGetPosition();
|
||||
var windowMode = DisplayServer.WindowGetMode();
|
||||
|
||||
GD.Print($"Screen: {screenSize}");
|
||||
GD.Print($"Window: {windowSize} at {windowPos}");
|
||||
GD.Print($"Mode: {windowMode}");
|
||||
```
|
||||
1. [Godot 运行时集成](./index.md)
|
||||
2. [Game 设置系统](../game/setting.md)
|
||||
3. [Godot 存储系统](./storage.md)
|
||||
4. [Godot 集成教程](../tutorials/godot-integration.md)
|
||||
|
||||
@ -1,275 +1,138 @@
|
||||
# 存储模块 (Storage Module)
|
||||
---
|
||||
title: Godot 存储系统
|
||||
description: 以当前 GFramework.Godot 源码与 CoreGrid 接线为准，说明 GodotFileStorage 的职责、路径边界和最小接入方式。
|
||||
---
|
||||
|
||||
## 概述
|
||||
# Godot 存储系统
|
||||
|
||||
存储模块是 GFramework.Godot 的核心存储实现，专门为 Godot 引擎设计的文件存储系统。该模块支持 Godot 的虚拟路径系统（如
|
||||
`res://` 和 `user://`），并提供了按键级别的细粒度锁机制来保证线程安全。
|
||||
`GFramework.Godot` 在存储这一层提供的核心入口只有 `GodotFileStorage`。
|
||||
|
||||
## 核心类
|
||||
它实现 `GFramework.Game` 侧统一的 `IStorage` 契约，负责把序列化后的读写、目录列举和路径处理接到 Godot 的
|
||||
`res://`、`user://` 和普通文件系统路径上，而不是另外提供一套独立的“Godot 专属存档框架”。
|
||||
|
||||
### GodotFileStorage
|
||||
## 当前公开入口
|
||||
|
||||
Godot 特化的文件存储实现，实现了 `IStorage` 接口。
|
||||
### `GodotFileStorage`
|
||||
|
||||
**主要特性：**
|
||||
`GodotFileStorage` 的当前职责比较集中：
|
||||
|
||||
- ✅ Godot 虚拟路径支持（`res://`, `user://`）
|
||||
- ✅ 线程安全（按键级别的细粒度锁）
|
||||
- ✅ 同步/异步读写操作
|
||||
- ✅ 自动创建目录结构
|
||||
- ❌ 删除操作（Delete 方法未实现）
|
||||
- 对外暴露 `IStorage` 约定的 `Read`、`Write`、`Exists`、`Delete`、目录列举与目录创建能力
|
||||
- 识别并保留 Godot 虚拟路径：`res://`、`user://`
|
||||
- 对普通文件系统路径做段级清理，并拒绝包含 `..` 的非法 key
|
||||
- 使用 `IAsyncKeyLockManager` 对“绝对路径 / Godot 路径”做按 key 细粒度串行化
|
||||
|
||||
## 功能特性
|
||||
构造函数默认会在未注入锁管理器时创建内部 `AsyncKeyLockManager`。这意味着：
|
||||
|
||||
### 路径处理
|
||||
- 同一个 `GodotFileStorage` 实例内，不同文件可以并发访问
|
||||
- 同一个目标路径的读写 / 删除会被串行化
|
||||
- 锁作用域只限当前进程内的当前实例，不是跨进程文件锁
|
||||
|
||||
该存储系统支持三种路径类型：
|
||||
## 路径语义
|
||||
|
||||
#### 1. Godot 资源路径 (`res://`)
|
||||
### `res://`
|
||||
|
||||
- **用途**：存储游戏资源文件
|
||||
- **特点**：只读，包含在游戏构建中
|
||||
- **示例**：`res://config/game_settings.json`
|
||||
`res://` 更适合作为只读资源或配置源目录。
|
||||
|
||||
#### 2. Godot 用户数据路径 (`user://`)
|
||||
当前实现不会阻止你把它传给 `ReadAsync`、`ExistsAsync` 之类的方法，但在导出后的 Godot 项目里，`res://`
|
||||
通常不应被当作用户可写存储根目录。存档、设置和运行时缓存应优先落到 `user://`。
|
||||
|
||||
- **用途**：存储用户数据、存档、配置等
|
||||
- **特点**：可读写，游戏可访问的用户目录
|
||||
- **示例**：`user://saves/save_001.dat`
|
||||
### `user://`
|
||||
|
||||
#### 3. 普通文件系统路径
|
||||
`user://` 是当前推荐的可写路径：
|
||||
|
||||
- **用途**：存储临时文件或调试数据
|
||||
- **特点**：完整的文件系统访问
|
||||
- **示例**：`C:/Games/MyGame/logs/debug.log`
|
||||
- 用户设置
|
||||
- 存档
|
||||
- 运行时缓存
|
||||
- 导出后仍需要读写的 JSON / YAML / 二进制数据
|
||||
|
||||
### 路径验证与清理
|
||||
如果调用 `ListDirectoriesAsync()` 或 `ListFilesAsync()` 时传入空字符串，当前实现会默认从 `user://` 根开始列举。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[输入路径] --> B{包含 ".." ?}
|
||||
B -->|是| C[抛出异常]
|
||||
B -->|否| D{是 Godot 路径?}
|
||||
D -->|是| E[直接使用]
|
||||
D -->|否| F[清理路径段]
|
||||
F --> G[替换无效字符]
|
||||
G --> H[创建目录结构]
|
||||
H --> I[返回绝对路径]
|
||||
C --> J[结束]
|
||||
E --> J
|
||||
I --> J
|
||||
```
|
||||
### 普通文件系统路径
|
||||
|
||||
### 线程安全机制
|
||||
当 key 不是 Godot 路径时，`GodotFileStorage` 会：
|
||||
|
||||
每个文件路径都有独立的锁对象，确保：
|
||||
1. 把 `\` 统一成 `/`
|
||||
2. 拒绝包含 `..` 的 key
|
||||
3. 按路径段清理非法文件名字符
|
||||
4. 在写入或建目录前自动补父目录
|
||||
|
||||
1. **细粒度锁** - 不同文件可以并发访问
|
||||
2. **避免死锁** - 锁的获取顺序一致
|
||||
3. **高性能** - 减少锁竞争
|
||||
这条路径更适合测试、桌面工具链或显式指定外部目录的宿主环境，不建议在项目业务层自己重新拼装一套路径清理逻辑。
|
||||
|
||||
## API 接口
|
||||
## 最小接入路径
|
||||
|
||||
### IStorage 接口
|
||||
当前消费者 `ai-libs/CoreGrid` 的接法是先注册同一个序列化器和存储实例，再让设置仓库、存档仓库等上层组件复用它：
|
||||
|
||||
```csharp
|
||||
public interface IStorage
|
||||
{
|
||||
// 读取操作
|
||||
T Read<T>(string key);
|
||||
T Read<T>(string key, T defaultValue);
|
||||
Task<T> ReadAsync<T>(string key);
|
||||
|
||||
// 写入操作
|
||||
void Write<T>(string key, T value);
|
||||
Task WriteAsync<T>(string key, T value);
|
||||
|
||||
// 检查存在性
|
||||
bool Exists(string key);
|
||||
Task<bool> ExistsAsync(string key);
|
||||
|
||||
// 删除操作（未实现）
|
||||
void Delete(string key);
|
||||
}
|
||||
using GFramework.Core.Abstractions.Serializer;
|
||||
using GFramework.Core.Abstractions.Storage;
|
||||
using GFramework.Game.Abstractions.Data;
|
||||
using GFramework.Game.Storage;
|
||||
using GFramework.Godot.Storage;
|
||||
using Godot;
|
||||
|
||||
var jsonSerializer = new JsonSerializer();
|
||||
architecture.RegisterUtility<ISerializer>(jsonSerializer);
|
||||
|
||||
var storage = new GodotFileStorage(jsonSerializer);
|
||||
architecture.RegisterUtility<IStorage>(storage);
|
||||
|
||||
architecture.RegisterUtility(new UnifiedSettingsDataRepository(
|
||||
storage,
|
||||
jsonSerializer,
|
||||
new DataRepositoryOptions
|
||||
{
|
||||
BasePath = ProjectSettings.GetSetting("application/config/save/setting_path").AsString(),
|
||||
AutoBackup = true
|
||||
}));
|
||||
|
||||
architecture.RegisterUtility<ISaveRepository<GameSaveData>>(new SaveRepository<GameSaveData>(
|
||||
storage,
|
||||
new SaveConfiguration
|
||||
{
|
||||
SaveRoot = ProjectSettings.GetSetting("application/config/save/save_path").AsString(),
|
||||
SaveSlotPrefix = ProjectSettings.GetSetting("application/config/save/save_slot_prefix").AsString(),
|
||||
SaveFileName = ProjectSettings.GetSetting("application/config/save/save_file_name").AsString()
|
||||
}));
|
||||
```
|
||||
|
||||
## 使用示例
|
||||
这里的分工是：
|
||||
|
||||
### 基本使用
|
||||
- `GodotFileStorage` 负责底层 key -> 文件读写
|
||||
- `UnifiedSettingsDataRepository` 负责设置节聚合与持久化
|
||||
- `SaveRepository<TSaveData>` 负责存档结构和保存槽位语义
|
||||
|
||||
```csharp
|
||||
// 创建存储实例（需要序列化器）
|
||||
var serializer = new JsonSerializer(); // 或其他序列化器
|
||||
var storage = new GodotFileStorage(serializer);
|
||||
不要把 `GodotFileStorage` 本身写成“设置系统”或“存档系统”的 owner。
|
||||
|
||||
// 写入用户数据
|
||||
var userData = new UserData
|
||||
{
|
||||
PlayerName = "Alice",
|
||||
Level = 5,
|
||||
Score = 1000
|
||||
};
|
||||
storage.Write("user://player.dat", userData);
|
||||
## 什么时候应该改看别的入口
|
||||
|
||||
// 读取用户数据
|
||||
var loadedData = storage.Read<UserData>("user://player.dat");
|
||||
Console.WriteLine($"Player: {loadedData.PlayerName}, Level: {loadedData.Level}");
|
||||
```
|
||||
### 配置 YAML / schema 文本加载
|
||||
|
||||
### 异步操作
|
||||
如果你的目标是读取 `res://` 下的 YAML 配置，并在导出态同步到运行时缓存，请优先看
|
||||
[`../game/config-system.md`](../game/config-system.md) 里的 `GodotYamlConfigLoader` 接法。
|
||||
|
||||
```csharp
|
||||
// 异步写入游戏配置
|
||||
var config = new GameConfig
|
||||
{
|
||||
Resolution = "1920x1080",
|
||||
Fullscreen = true,
|
||||
Volume = 0.8f
|
||||
};
|
||||
await storage.WriteAsync("user://config.json", config);
|
||||
这类场景的重点不是通用键值存储，而是：
|
||||
|
||||
// 异步读取配置
|
||||
var loadedConfig = await storage.ReadAsync<GameConfig>("user://config.json");
|
||||
```
|
||||
- `res://` 与 `user://` 缓存切换
|
||||
- 生成器表元数据
|
||||
- 热重载可用性边界
|
||||
|
||||
### 不同路径类型使用
|
||||
### 通用存储契约
|
||||
|
||||
```csharp
|
||||
// 读取游戏资源（只读）
|
||||
var levelData = storage.Read<LevelData>("res://levels/level_001.json");
|
||||
如果你想先理解 `IStorage`、`ScopedStorage`、`FileStorage` 和统一数据仓库的宿主无关语义，应先看
|
||||
[`../game/storage.md`](../game/storage.md)。
|
||||
|
||||
// 存储用户存档
|
||||
var saveData = new SaveData { /* ... */ };
|
||||
storage.Write("user://saves/slot_001.dat", saveData);
|
||||
本页只补 Godot 宿主差异，不重复维护一份跨宿主 API 手册。
|
||||
|
||||
// 存储调试信息（普通路径）
|
||||
var debugLog = new DebugLog { /* ... */ };
|
||||
storage.Write("logs/debug_" + DateTime.UtcNow.Ticks + ".json", debugLog);
|
||||
```
|
||||
## 当前边界
|
||||
|
||||
### 存在性检查
|
||||
- 同步 `Read` / `Write` / `Delete` / `Exists` 只是对异步方法的阻塞包装；在带同步上下文的宿主里，优先使用异步 API
|
||||
- `GodotFileStorage` 不负责文件扩展名约定、作用域前缀或保存槽位策略，这些属于上层 repository / scoped storage
|
||||
- 路径安全只覆盖当前 key 的格式校验与路径段清理，不代替业务层的目录规划
|
||||
- 当前实现支持目录列举与目录创建，但没有额外的“监视目录变化”或“自动迁移目录结构”能力
|
||||
|
||||
```csharp
|
||||
// 检查文件是否存在
|
||||
if (storage.Exists("user://settings.json"))
|
||||
{
|
||||
var settings = storage.Read<AppSettings>("user://settings.json");
|
||||
// 使用设置...
|
||||
}
|
||||
else
|
||||
{
|
||||
// 使用默认设置
|
||||
var defaultSettings = new AppSettings();
|
||||
storage.Write("user://settings.json", defaultSettings);
|
||||
}
|
||||
```
|
||||
## 继续阅读
|
||||
|
||||
### 带默认值的读取
|
||||
|
||||
```csharp
|
||||
// 尝试读取，如果文件不存在则返回默认值
|
||||
var settings = storage.Read("user://user_prefs.json", new UserPrefs
|
||||
{
|
||||
Language = "en",
|
||||
Volume = 1.0f,
|
||||
Difficulty = 1
|
||||
});
|
||||
```
|
||||
|
||||
## 路径扩展
|
||||
|
||||
该模块使用了路径扩展方法：
|
||||
|
||||
```csharp
|
||||
public static class GodotPathExtensions
|
||||
{
|
||||
public static bool IsUserPath(this string path);
|
||||
public static bool IsResPath(this string path);
|
||||
public static bool IsGodotPath(this string path);
|
||||
}
|
||||
```
|
||||
|
||||
**使用示例：**
|
||||
|
||||
```csharp
|
||||
string path1 = "user://save.dat";
|
||||
string path2 = "res://config.json";
|
||||
string path3 = "C:/temp/file.txt";
|
||||
|
||||
Console.WriteLine(path1.IsGodotPath()); // true
|
||||
Console.WriteLine(path1.IsUserPath()); // true
|
||||
Console.WriteLine(path2.IsResPath()); // true
|
||||
Console.WriteLine(path3.IsGodotPath()); // false
|
||||
```
|
||||
|
||||
## 性能考虑
|
||||
|
||||
### 1. 锁机制
|
||||
|
||||
- 每个文件路径独立锁，减少锁竞争
|
||||
- 读写操作串行化，避免数据损坏
|
||||
|
||||
### 2. 文件访问
|
||||
|
||||
- Godot 虚拟路径使用 `FileAccess` API
|
||||
- 普通路径使用标准 .NET 文件 I/O
|
||||
- 自动创建目录结构
|
||||
|
||||
### 3. 内存使用
|
||||
|
||||
- 锁对象使用 `ConcurrentDictionary` 管理
|
||||
- 锁对象按需创建，避免内存泄漏
|
||||
|
||||
## 错误处理
|
||||
|
||||
### 常见异常
|
||||
|
||||
1. **ArgumentException** - 路径参数无效
|
||||
- 空路径
|
||||
- 包含 ".." 的路径
|
||||
- 无效的存储键
|
||||
|
||||
2. **FileNotFoundException** - 文件不存在
|
||||
- 读取不存在的文件时抛出
|
||||
|
||||
3. **IOException** - 文件操作失败
|
||||
- 写入权限不足
|
||||
- 磁盘空间不足
|
||||
|
||||
### 错误处理示例
|
||||
|
||||
```csharp
|
||||
try
|
||||
{
|
||||
var data = storage.Read<UserData>("user://save.dat");
|
||||
}
|
||||
catch (FileNotFoundException)
|
||||
{
|
||||
Console.WriteLine("存档文件不存在，创建新的存档");
|
||||
var newSave = new UserData();
|
||||
storage.Write("user://save.dat", newSave);
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
Console.WriteLine($"读取存档失败: {ex.Message}");
|
||||
}
|
||||
```
|
||||
|
||||
## 最佳实践
|
||||
|
||||
1. **路径选择**
|
||||
- 游戏资源使用 `res://`
|
||||
- 用户数据使用 `user://`
|
||||
- 调试/临时文件使用普通路径
|
||||
|
||||
2. **异常处理**
|
||||
- 总是处理 `FileNotFoundException`
|
||||
- 使用带默认值的 `Read` 重载方法
|
||||
|
||||
3. **性能优化**
|
||||
- 批量读写时使用异步方法
|
||||
- 避免频繁的小文件操作
|
||||
|
||||
4. **序列化器选择**
|
||||
- JSON：人类可读，调试友好
|
||||
- 二进制：性能更好，文件更小
|
||||
1. [Godot 运行时集成](./index.md)
|
||||
2. [Game 存储系统](../game/storage.md)
|
||||
3. [Game 配置系统](../game/config-system.md)
|
||||
4. [Godot 集成教程](../tutorials/godot-integration.md)
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user