mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-03-22 10:34:30 +08:00
docs: 更新文档中的代码示例和链接引用
- 修复 IEventHandler 接口中的参数关键字冲突 - 修正场景管理器接口中的泛型约束拼写错误 - 本地化核心抽象文档链接为中文标题 - 更新事件系统文档中的接口链接路径 - 修复扩展方法文档中的上下文感知链接 - 调整日志系统文档中的接口链接路径 - 重构架构概述中的代码示例和设计原则 - 统一 Godot 设置模块中的代码块格式 - 优化音频和图形设置的代码示例
This commit is contained in:
GeWuYou
parent
d1cdac8082
commit
6cc0ddf7f9
@ -97,7 +97,7 @@ public interface IEvent
|
||||
```csharp
|
||||
public interface IEventHandler<TEvent> where TEvent : IEvent
|
||||
{
|
||||
void Handle(TEvent event);
|
||||
void Handle(TEvent @event);
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
@ -65,7 +65,7 @@ public interface IGameSettings
|
||||
public interface ISceneManager
|
||||
{
|
||||
void SwitchScene<TScene>() where TScene : IScene;
|
||||
Task SwitchSceneAsync<TScene>() where TScnee : IScene;
|
||||
Task SwitchSceneAsync<TScene>() where TScene : IScene;
|
||||
|
||||
void PushScene<TScene>() where TScene : IScene;
|
||||
void PopScene();
|
||||
@ -108,6 +108,6 @@ public interface IAssetManager
|
||||
**相关文档**：
|
||||
|
||||
- [Game 概述](../game)
|
||||
- [Core Abstractions](./core-abstractions)
|
||||
- [核心抽象](./core-abstractions)
|
||||
- [存档系统](../game/storage)
|
||||
- [场景管理](../game/scene-management)
|
||||
|
||||
@ -6,7 +6,7 @@ Events 包提供了一套完整的事件系统，实现了观察者模式（Obse
|
||||
|
||||
## 核心接口
|
||||
|
||||
### 1. [`IEvent`](./events.md)
|
||||
### 1. [IEvent](../GFramework.Core.Abstractions/events/IEvent.cs)
|
||||
|
||||
基础事件接口，定义了事件注册的基本功能。
|
||||
|
||||
@ -16,7 +16,7 @@ Events 包提供了一套完整的事件系统，实现了观察者模式（Obse
|
||||
IUnRegister Register(Action onEvent); // 注册事件处理函数
|
||||
```
|
||||
|
||||
### 2. [`IUnRegister`](./events.md)
|
||||
### 2. [IUnRegister](../GFramework.Core.Abstractions/events/IUnRegister.cs)
|
||||
|
||||
注销接口，用于取消事件注册。
|
||||
|
||||
@ -26,7 +26,7 @@ IUnRegister Register(Action onEvent); // 注册事件处理函数
|
||||
void UnRegister(); // 执行注销操作
|
||||
```
|
||||
|
||||
### 3. [`IUnRegisterList`](./events.md)
|
||||
### 3. [IUnRegisterList](../GFramework.Core.Abstractions/events/IUnRegisterList.cs)
|
||||
|
||||
注销列表接口，用于批量管理注销对象。
|
||||
|
||||
@ -36,7 +36,7 @@ void UnRegister(); // 执行注销操作
|
||||
IList<IUnRegister> UnregisterList { get; } // 获取注销列表
|
||||
```
|
||||
|
||||
### 4. [`IEventBus`](./events.md)
|
||||
### 4. [IEventBus](../GFramework.Core.Abstractions/events/IEventBus.cs)
|
||||
|
||||
事件总线接口，提供基于类型的事件发送和注册。
|
||||
|
||||
@ -50,7 +50,7 @@ void Send<T>() where T : new(); // 发送事件（自动创建实例
|
||||
|
||||
## 核心类
|
||||
|
||||
### 1. [`EasyEvent`](./events.md)
|
||||
### 1. [EasyEvent](EasyEvent.cs)
|
||||
|
||||
无参事件类，支持注册、注销和触发无参事件。
|
||||
|
||||
@ -73,7 +73,7 @@ onClicked.Trigger();
|
||||
unregister.UnRegister();
|
||||
```
|
||||
|
||||
### 2. [`Event<T>`](./events.md)
|
||||
### 2. [Event<T>](EasyEvent.cs)
|
||||
|
||||
单参数泛型事件类，支持一个参数的事件。
|
||||
|
||||
@ -93,13 +93,13 @@ onScoreChanged.Register(newScore =>
|
||||
onScoreChanged.Trigger(100);
|
||||
```
|
||||
|
||||
### 3. [`Event<T, TK>`](./events.md)
|
||||
### 3. [Event<T, TK>](EasyEvent.cs)
|
||||
|
||||
双参数泛型事件类。
|
||||
|
||||
**使用示例：**
|
||||
|
||||
```csharp
|
||||
```
|
||||
// 伤害事件：攻击者、伤害值
|
||||
var onDamageDealt = new Event<string, int>();
|
||||
|
||||
@ -117,7 +117,7 @@ onDamageDealt.Trigger("Player", 50);
|
||||
|
||||
**使用示例：**
|
||||
|
||||
```csharp
|
||||
``csharp
|
||||
// 注册全局事件类型
|
||||
EasyEvents.Register<GameStartEvent>();
|
||||
|
||||
@ -140,7 +140,7 @@ gameStartEvent.Trigger();
|
||||
|
||||
**使用示例：**
|
||||
|
||||
```csharp
|
||||
``csharp
|
||||
// 使用全局事件系统
|
||||
var eventBus = new EventBus();
|
||||
|
||||
@ -166,7 +166,7 @@ eventBus.Send<PlayerDiedEvent>();
|
||||
|
||||
**使用示例：**
|
||||
|
||||
```csharp
|
||||
``csharp
|
||||
Action onUnregister = () => GD.Print("Unregistered");
|
||||
var unregister = new DefaultUnRegister(onUnregister);
|
||||
|
||||
@ -180,7 +180,7 @@ unregister.UnRegister();
|
||||
|
||||
**使用示例：**
|
||||
|
||||
```csharp
|
||||
``csharp
|
||||
var onAnyInput = new OrEvent()
|
||||
.Or(onKeyPressed)
|
||||
.Or(onMouseClicked)
|
||||
@ -199,7 +199,7 @@ onAnyInput.Register(() =>
|
||||
|
||||
**使用示例：**
|
||||
|
||||
```csharp
|
||||
``csharp
|
||||
var unregisterList = new UnRegisterList();
|
||||
|
||||
// 添加到列表
|
||||
|
||||
@ -6,10 +6,10 @@ Extensions 包提供了一系列扩展方法，简化了框架各个接口的使
|
||||
|
||||
## 扩展方法类别
|
||||
|
||||
### 1. ContextAware 扩展 ([`ContextAwareExtensions.cs`](./extensions.md))
|
||||
### 1. ContextAware 扩展 ([ContextAwareExtensions.cs](ContextAwareExtensions.cs))
|
||||
|
||||
为 [`IContextAware`](./rule.md)
|
||||
提供扩展方法，允许直接从实现了 [IContextAware](./rule.md)
|
||||
为 [IContextAware](../GFramework.Core.Abstractions/rule/IContextAware.cs)
|
||||
提供扩展方法，允许直接从实现了 [IContextAware](../GFramework.Core.Abstractions/rule/IContextAware.cs)
|
||||
的对象获取架构组件。
|
||||
|
||||
#### GetSystem 扩展方法
|
||||
@ -91,7 +91,7 @@ public static TResult SendCommand<TResult>(this IContextAware contextAware, ICom
|
||||
|
||||
**使用示例：**
|
||||
|
||||
```csharp
|
||||
```
|
||||
public class GameController : IController
|
||||
{
|
||||
public void OnStartButtonClicked()
|
||||
|
||||
@ -6,7 +6,7 @@ Logging 包提供了灵活的日志系统，支持多级别日志记录。默认
|
||||
|
||||
## 核心接口
|
||||
|
||||
### [ILogger](./logging.md)
|
||||
### [ILogger](../GFramework.Core.Abstractions/logging/ILogger.cs)
|
||||
|
||||
日志记录器接口，定义了日志记录的基本功能。
|
||||
|
||||
@ -62,7 +62,7 @@ void Fatal(string msg, Exception t);
|
||||
string Name();
|
||||
```
|
||||
|
||||
### [ILoggerFactory](./logging.md)
|
||||
### [ILoggerFactory](../GFramework.Core.Abstractions/logging/ILoggerFactory.cs)
|
||||
|
||||
日志工厂接口，用于创建日志记录器实例。
|
||||
|
||||
@ -72,7 +72,7 @@ string Name();
|
||||
ILogger GetLogger(string name, LogLevel minLevel = LogLevel.Info);
|
||||
```
|
||||
|
||||
### [ILoggerFactoryProvider](./logging.md)
|
||||
### [ILoggerFactoryProvider](../GFramework.Core.Abstractions/logging/ILoggerFactoryProvider.cs)
|
||||
|
||||
日志工厂提供程序接口，用于获取日志工厂。
|
||||
|
||||
@ -83,7 +83,7 @@ ILoggerFactory GetLoggerFactory();
|
||||
ILogger CreateLogger(string name);
|
||||
```
|
||||
|
||||
### [LogLevel](./logging.md)
|
||||
### [LogLevel](../GFramework.Core.Abstractions/logging/LogLevel.cs)
|
||||
|
||||
日志级别枚举。
|
||||
|
||||
|
||||
@ -95,36 +95,48 @@ public class PlayerModel : AbstractModel
|
||||
|
||||
应用的业务逻辑处理层。
|
||||
|
||||
```csharp
|
||||
``csharp
|
||||
public class CombatSystem : AbstractSystem
|
||||
{
|
||||
protected override void OnInit()
|
||||
{
|
||||
// 监听战斗相关事件
|
||||
this.RegisterEvent<EnemyAttackEvent>(OnEnemyAttack);
|
||||
this.RegisterEvent<PlayerAttackEvent>(OnPlayerAttack);
|
||||
// 订阅相关事件
|
||||
this.GetEvent<AttackEvent>().Register(OnAttack);
|
||||
}
|
||||
|
||||
private void OnAttack(AttackEvent e)
|
||||
{
|
||||
var attacker = e.Attacker;
|
||||
var target = e.Target;
|
||||
|
||||
// 计算伤害
|
||||
var damage = CalculateDamage(attacker, target);
|
||||
|
||||
// 更新目标生命值
|
||||
target.Health.Value -= damage;
|
||||
|
||||
// 发送伤害事件
|
||||
this.SendEvent(new DamageEvent(target, damage));
|
||||
}
|
||||
|
||||
private void OnEnemyAttack(EnemyAttackEvent e)
|
||||
private int CalculateDamage(Entity attacker, Entity target)
|
||||
{
|
||||
var playerModel = this.GetModel<PlayerModel>();
|
||||
playerModel.Health.Value -= e.Damage;
|
||||
this.SendEvent(new PlayerTookDamageEvent { Damage = e.Damage });
|
||||
return Mathf.Max(1, attacker.Attack.Value - target.Defense.Value);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**职责范围：**
|
||||
**设计原则：**
|
||||
|
||||
- 处理具体的业务逻辑
|
||||
- 响应事件并修改模型数据
|
||||
- 发送新的事件通知其他组件
|
||||
- 处理业务逻辑，不直接存储数据
|
||||
- 通过事件与其他组件通信
|
||||
- 从 Model 获取数据，向 Model 发送更新
|
||||
|
||||
### 4. Controller（控制器）
|
||||
|
||||
连接 UI 和业务逻辑的桥梁。
|
||||
|
||||
```csharp
|
||||
``csharp
|
||||
public class PlayerController : IController
|
||||
{
|
||||
private IArchitecture _architecture;
|
||||
@ -164,7 +176,7 @@ public class PlayerController : IController
|
||||
|
||||
提供无状态的辅助功能。
|
||||
|
||||
```csharp
|
||||
``csharp
|
||||
public class StorageUtility : IUtility
|
||||
{
|
||||
public void SaveData<T>(string key, T data)
|
||||
@ -193,7 +205,7 @@ public class StorageUtility : IUtility
|
||||
|
||||
用于修改应用状态的操作：
|
||||
|
||||
```csharp
|
||||
``csharp
|
||||
public class MovePlayerCommand : AbstractCommand
|
||||
{
|
||||
public Vector2 Direction { get; set; }
|
||||
@ -208,9 +220,9 @@ public class MovePlayerCommand : AbstractCommand
|
||||
|
||||
### 2. Query（查询）
|
||||
|
||||
用于查询应用状态：
|
||||
用于查询应用状态：`
|
||||
|
||||
```csharp
|
||||
``csharp
|
||||
public class GetPlayerHealthQuery : AbstractQuery<int>
|
||||
{
|
||||
protected override int OnDo()
|
||||
@ -223,9 +235,9 @@ public class GetPlayerHealthQuery : AbstractQuery<int>
|
||||
|
||||
### 3. Event（事件）
|
||||
|
||||
组件间通信的主要机制：
|
||||
组件间通信的主要机制：`
|
||||
|
||||
```csharp
|
||||
```
|
||||
// 发送事件
|
||||
this.SendEvent(new PlayerDiedEvent());
|
||||
|
||||
@ -237,7 +249,7 @@ this.RegisterEvent<PlayerDiedEvent>(OnPlayerDied);
|
||||
|
||||
### BindableProperty
|
||||
|
||||
```csharp
|
||||
``csharp
|
||||
public class PlayerModel : AbstractModel
|
||||
{
|
||||
public BindableProperty<int> Health { get; } = new(100);
|
||||
@ -262,7 +274,7 @@ playerModel.Health.Register(newValue => {
|
||||
|
||||
### 1. 分层职责明确
|
||||
|
||||
```csharp
|
||||
``csharp
|
||||
// ✅ 正确：Model 只存储数据
|
||||
public class PlayerModel : AbstractModel
|
||||
{
|
||||
@ -281,7 +293,7 @@ public class PlayerModel : AbstractModel
|
||||
|
||||
### 2. 事件驱动设计
|
||||
|
||||
```csharp
|
||||
``csharp
|
||||
// ✅ 正确：使用事件解耦
|
||||
public class CombatSystem : AbstractSystem
|
||||
{
|
||||
@ -305,7 +317,7 @@ public class CombatSystem : AbstractSystem
|
||||
|
||||
### 3. 命令查询分离
|
||||
|
||||
```csharp
|
||||
``csharp
|
||||
// ✅ 正确：明确区分命令和查询
|
||||
public class MovePlayerCommand : AbstractCommand { } // 修改状态
|
||||
public class GetPlayerPositionQuery : AbstractQuery<Vector2> { } // 查询状态
|
||||
|
||||
@ -86,7 +86,7 @@ graph TD
|
||||
|
||||
#### 基本音频设置
|
||||
|
||||
```csharp
|
||||
``csharp
|
||||
// 创建音频配置数据
|
||||
var settings = new AudioSettings
|
||||
{
|
||||
@ -99,12 +99,12 @@ var settings = new AudioSettings
|
||||
var audioSettings = new GodotAudioSettings(settings, new AudioBusMap());
|
||||
|
||||
// 应用设置
|
||||
await audioSettings.Apply();
|
||||
audioSettings.Apply();
|
||||
```
|
||||
|
||||
#### 自定义音频总线映射
|
||||
|
||||
```csharp
|
||||
``csharp
|
||||
// 自定义音频总线映射
|
||||
var customBusMap = new AudioBusMap
|
||||
{
|
||||
@ -128,7 +128,7 @@ await audioSettings.Apply();
|
||||
|
||||
#### 通过设置系统使用
|
||||
|
||||
```csharp
|
||||
``csharp
|
||||
// 注册音频设置到设置模型
|
||||
var settingsModel = this.GetModel<ISettingsModel>();
|
||||
var audioSettingsData = settingsModel.Get<AudioSettings>();
|
||||
@ -145,7 +145,7 @@ await godotAudioSettings.Apply();
|
||||
|
||||
#### 基本图形设置
|
||||
|
||||
```csharp
|
||||
``csharp
|
||||
// 创建图形设置
|
||||
var graphicsSettings = new GodotGraphicsSettings
|
||||
{
|
||||
@ -160,7 +160,7 @@ await graphicsSettings.Apply();
|
||||
|
||||
#### 窗口模式切换
|
||||
|
||||
```csharp
|
||||
``csharp
|
||||
public class DisplayManager : Node
|
||||
{
|
||||
private GodotGraphicsSettings _graphicsSettings;
|
||||
@ -188,7 +188,7 @@ public class DisplayManager : Node
|
||||
|
||||
#### 预设分辨率配置
|
||||
|
||||
```csharp
|
||||
``csharp
|
||||
public class ResolutionPresets
|
||||
{
|
||||
public static readonly (int width, int height)[] CommonResolutions =
|
||||
@ -214,7 +214,7 @@ public class ResolutionPresets
|
||||
|
||||
### AudioBusMap
|
||||
|
||||
```csharp
|
||||
``csharp
|
||||
public sealed class AudioBusMap
|
||||
{
|
||||
public string Master { get; init; } = "Master";
|
||||
@ -231,7 +231,7 @@ public sealed class AudioBusMap
|
||||
|
||||
### GodotAudioSettings
|
||||
|
||||
```csharp
|
||||
``csharp
|
||||
public class GodotAudioSettings(AudioSettings settings, AudioBusMap busMap) : IApplyAbleSettings
|
||||
{
|
||||
public Task Apply();
|
||||
@ -245,7 +245,7 @@ public class GodotAudioSettings(AudioSettings settings, AudioBusMap busMap) : IA
|
||||
|
||||
**Apply 方法实现：**
|
||||
|
||||
```csharp
|
||||
``csharp
|
||||
public Task Apply()
|
||||
{
|
||||
SetBus(busMap.Master, settings.MasterVolume);
|
||||
@ -257,7 +257,7 @@ public Task Apply()
|
||||
|
||||
### GodotGraphicsSettings
|
||||
|
||||
```csharp
|
||||
``csharp
|
||||
public class GodotGraphicsSettings : GraphicsSettings, IApplyAbleSettings
|
||||
{
|
||||
public Task Apply();
|
||||
@ -277,7 +277,7 @@ public class GodotGraphicsSettings : GraphicsSettings, IApplyAbleSettings
|
||||
|
||||
Godot 音频系统使用分贝（dB）作为音量单位，而我们通常使用线性值（0-1）：
|
||||
|
||||
```csharp
|
||||
``csharp
|
||||
// 线性值到分贝转换
|
||||
float linearVolume = 0.5f; // 50% 音量
|
||||
float dbVolume = Mathf.LinearToDb(linearVolume); // 转换为分贝
|
||||
@ -290,7 +290,7 @@ AudioServer.SetBusVolumeDb(busIndex, dbVolume);
|
||||
|
||||
为避免完全静音（-inf dB），应用了最小音量限制：
|
||||
|
||||
```csharp
|
||||
``csharp
|
||||
float clampedVolume = Mathf.Clamp(linear, 0.0001f, 1f);
|
||||
float dbVolume = Mathf.LinearToDb(clampedVolume);
|
||||
```
|
||||
@ -299,7 +299,7 @@ float dbVolume = Mathf.LinearToDb(clampedVolume);
|
||||
|
||||
#### 全屏模式
|
||||
|
||||
```csharp
|
||||
``csharp
|
||||
// 设置全屏
|
||||
DisplayServer.WindowSetMode(DisplayServer.WindowMode.ExclusiveFullscreen);
|
||||
DisplayServer.WindowSetFlag(DisplayServer.WindowFlags.Borderless, true);
|
||||
@ -307,7 +307,7 @@ DisplayServer.WindowSetFlag(DisplayServer.WindowFlags.Borderless, true);
|
||||
|
||||
#### 窗口化模式
|
||||
|
||||
```csharp
|
||||
``csharp
|
||||
// 设置窗口化
|
||||
DisplayServer.WindowSetMode(DisplayServer.WindowMode.Windowed);
|
||||
DisplayServer.WindowSetSize(newSize);
|
||||
@ -325,7 +325,7 @@ DisplayServer.WindowSetPosition(position);
|
||||
|
||||
#### 音量变化平滑过渡
|
||||
|
||||
```csharp
|
||||
``csharp
|
||||
public class AudioManager : Node
|
||||
{
|
||||
private Tween _volumeTween;
|
||||
@ -398,7 +398,7 @@ public class CustomAudioManager : Node
|
||||
|
||||
#### 音频设置验证
|
||||
|
||||
```csharp
|
||||
``csharp
|
||||
public static class AudioSettingsValidator
|
||||
{
|
||||
public static bool ValidateBusNames(AudioBusMap busMap)
|
||||
@ -428,7 +428,7 @@ public static class AudioSettingsValidator
|
||||
|
||||
#### 分辨率变更安全检查
|
||||
|
||||
```csharp
|
||||
``csharp
|
||||
public static class DisplayValidator
|
||||
{
|
||||
public static bool IsResolutionSupported(int width, int height)
|
||||
@ -451,7 +451,7 @@ public static class DisplayValidator
|
||||
|
||||
#### 图形设置持久化
|
||||
|
||||
```csharp
|
||||
``csharp
|
||||
public class GraphicsSettingsManager : Node
|
||||
{
|
||||
private const string SettingsKey = "graphics_settings";
|
||||
@ -545,7 +545,7 @@ public class GraphicsSettingsManager : Node
|
||||
|
||||
#### 音频调试
|
||||
|
||||
```csharp
|
||||
``csharp
|
||||
// 打印所有音频总线信息
|
||||
for (int i = 0; i < AudioServer.GetBusCount(); i++)
|
||||
{
|
||||
@ -557,7 +557,7 @@ for (int i = 0; i < AudioServer.GetBusCount(); i++)
|
||||
|
||||
#### 图形调试
|
||||
|
||||
```csharp
|
||||
``csharp
|
||||
// 打印当前显示信息
|
||||
var screen = DisplayServer.GetPrimaryScreen();
|
||||
var screenSize = DisplayServer.ScreenGetSize(screen);
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user