diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 33e2bda..e17e976 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -58,7 +58,7 @@ export default defineConfig({ items: [ { text: '安装配置', link: '/zh-CN/getting-started/installation' }, { text: '快速开始', link: '/zh-CN/getting-started/quick-start' }, - { text: '架构概览', link: '/zh-CN/getting-started/architecture-overview' } + { text: '架构概览', link: '/zh-CN/getting-started' } ] } ], @@ -92,7 +92,6 @@ export default defineConfig({ text: 'Game 游戏模块', items: [ { text: '概览', link: '/zh-CN/game/' }, - { text: '场景管理', link: '/zh-CN/game/scene-management' }, { text: '游戏设置', link: '/zh-CN/game/setting' } ] } diff --git a/docs/zh-CN/abstractions/game-abstractions.md b/docs/zh-CN/abstractions/game-abstractions.md index 22683d5..bb854ca 100644 --- a/docs/zh-CN/abstractions/game-abstractions.md +++ b/docs/zh-CN/abstractions/game-abstractions.md @@ -86,28 +86,9 @@ public interface IScene void OnUpdate(float delta); } ``` - -## 资源管理接口 - -### IAssetManager - -资源管理器接口： - -```csharp -public interface IAssetManager -{ - T Load(string path) where T : Resource; - void Preload(string path) where T : Resource; - void Unload(string path); - bool IsLoaded(string path); -} -``` - --- **相关文档**： -- [Game 概述](../game) -- [核心抽象](./core-abstractions) -- [存档系统](../game/storage) -- [场景管理](../game/scene-management) +- [Game 概述](../game/index.md) +- [核心抽象](./core-abstractions.md) diff --git a/docs/zh-CN/game/index.md b/docs/zh-CN/game/index.md index 7bf506a..2888937 100644 --- a/docs/zh-CN/game/index.md +++ b/docs/zh-CN/game/index.md @@ -1395,12 +1395,4 @@ graph TD - **.NET**: 6.0+ - **Newtonsoft.Json**: 13.0.3+ - **GFramework.Core**: 与 Core 模块版本保持同步 - -## 许可证 - -本项目基于 Apache 2.0 许可证 - 详情请参阅 [LICENSE](../LICENSE) 文件。 - ---- - -**版本**: 1.0.0 -**更新日期**: 2026-01-12 +--- \ No newline at end of file diff --git a/docs/zh-CN/game/scene-management.md b/docs/zh-CN/game/scene-management.md deleted file mode 100644 index be51d23..0000000 --- a/docs/zh-CN/game/scene-management.md +++ /dev/null @@ -1,503 +0,0 @@ -# 场景管理 - -> GFramework.Game 模块提供的场景管理功能，实现游戏场景的加载、切换和状态管理 - -## 概述 - -GFramework.Game 提供了统一的场景管理系统，支持场景的异步加载、切换动画、状态保持等功能。通过场景管理，您可以优雅地处理游戏中的各种场景转换，如主菜单、游戏界面、设置菜单等。 - -## 核心特性 - -- **异步加载**：支持后台异步加载场景，避免卡顿 -- **场景切换动画**：内置淡入淡出等切换效果 -- **状态保持**：场景切换时保持必要的游戏状态 -- **场景栈**：支持场景叠加（如弹出菜单） -- **资源管理**：自动管理场景资源的加载和卸载 - -## 基本用法 - -### 定义场景 - -```csharp -using GFramework.Game.scene; - -public class GameScene : GameSceneBase -{ - protected override void OnLoad() - { - // 场景加载时的初始化 - } - - protected override void OnUnload() - { - // 场景卸载时的清理 - } - - public override void OnEnter() - { - // 进入场景 - } - - public override void OnExit() - { - // 退出场景 - } -} -``` - -### 场景管理器 - -```csharp -using GFramework.Game.scene; - -[ContextAware] -public partial class SceneManager : Node -{ - private ISceneManager _sceneManager; - - public override void _Ready() - { - _sceneManager = Context.GetSystem(); - - // 初始化场景管理器 - _sceneManager.Initialize(); - } - - public async Task SwitchToGameScene() - { - await _sceneManager.SwitchSceneAsync(); - } -} -``` - -## 场景加载 - -### 同步加载 - -适用于小场景的快速切换： - -```csharp -public void LoadMainMenu() -{ - _sceneManager.SwitchScene(); -} -``` - -### 异步加载 - -大场景建议使用异步加载： - -```csharp -public async Task LoadGameLevel(string levelName) -{ - // 显示加载界面 - loadingUI.Show(); - - try - { - // 异步加载场景 - await _sceneManager.SwitchSceneAsync(scene => - { - // 可以在这里传递场景参数 - var gameScene = scene as GameLevelScene; - gameScene.LevelName = levelName; - }); - - GD.Print("场景加载完成"); - } - catch (Exception ex) - { - GD.PrintErr($"场景加载失败: {ex.Message}"); - loadingUI.ShowError(); - } - finally - { - loadingUI.Hide(); - } -} -``` - -### 加载进度 - -监听加载进度： - -```csharp -public async Task LoadSceneWithProgress() where TScene : IScene -{ - loadingUI.Show(); - - var progress = new Progress(value => - { - loadingUI.UpdateProgress(value * 100); - }); - - await _sceneManager.SwitchSceneAsync(progress: progress); - - loadingUI.Hide(); -} -``` - -## 场景切换动画 - -### 内置切换效果 - -```csharp -public async Task SwitchWithFade() -{ - // 使用淡入淡出效果 - await _sceneManager.SwitchSceneAsync( - transition: new FadeTransition( - duration: 0.5f, - fadeColor: Colors.Black - ) - ); -} - -public async Task SlideTransition() -{ - // 使用滑动效果 - await _sceneManager.SwitchSceneAsync( - transition: new SlideTransition( - direction: Vector2.Left, - duration: 0.3f - ) - ); -} -``` - -### 自定义切换动画 - -```csharp -public class CustomTransition : ISceneTransition -{ - public float Duration { get; } = 1.0f; - - public async Task PlayAsync(Node fromScene, Node toScene) - { - // 自定义动画逻辑 - var tween = CreateTween(); - - // 旧场景缩小消失 - tween.TweenProperty(fromScene, "scale", Vector2.Zero, Duration / 2) - .SetTrans(Tween.TransitionType.BackIn); - - await ToSignal(tween, Tween.SignalName.Finished); - - fromScene.Visible = false; - toScene.Visible = true; - toScene.Scale = Vector2.Zero; - - // 新场景放大出现 - tween = CreateTween(); - tween.TweenProperty(toScene, "scale", Vector2.One, Duration / 2) - .SetTrans(Tween.TransitionType.BackOut); - - await ToSignal(tween, Tween.SignalName.Finished); - } -} -``` - -## 场景栈 - -### 推送场景 - -将新场景推入栈中： - -```csharp -public void PushPauseMenu() -{ - _sceneManager.PushScene(); -} -``` - -### 弹出场景 - -弹出栈顶场景： - -```csharp -public void PopScene() -{ - _sceneManager.PopScene(); -} -``` - -### 示例：带返回的导航 - -```csharp -public async Task NavigateToSettings() -{ - // 保存当前场景引用 - var previousScene = _sceneManager.CurrentScene; - - // 推入设置场景 - await _sceneManager.PushSceneAsync(); - - // 设置场景有返回按钮 - await _sceneManager.PushSceneAsync( - data: new ConfirmData - { - Message = "是否保存设置？", - OnConfirm = () => _sceneManager.PopScene(), // 不保存，直接返回 - OnCancel = () => - { - // 保存设置后返回 - SaveSettings(); - _sceneManager.PopScene(); - } - } - ); -} -``` - -## 场景状态管理 - -### 保存状态 - -```csharp -public class GameScene : GameSceneBase -{ - private GameState _state; - - protected override void OnLoad() - { - // 从存档加载状态 - _state = LoadGameState(); - } - - protected override void OnUnload() - { - // 保存状态 - SaveGameState(_state); - } - - public override void OnExit() - { - // 清理工作 - Cleanup(); - } -} -``` - -### 跨场景数据传递 - -```csharp -// 传递数据到新场景 -await _sceneManager.SwitchSceneAsync(data: new GameData -{ - Level = 5, - Difficulty = Difficulty.Hard, - ContinueToken = saveToken -}); - -// 在目标场景中接收数据 -public class GameScene : GameSceneBase -{ - public override void OnEnter(object data) - { - var gameData = data as GameData; - InitializeLevel(gameData.Level, gameData.Difficulty); - } -} -``` - -## 预加载策略 - -### 预加载资源 - -```csharp -public void PreloadCommonResources() -{ - _sceneManager.PreloadScene(); - _sceneManager.PreloadScene(count: 3); -} -``` - -### 预加载配置 - -```csharp -var config = new ScenePreloadConfig -{ - PreloadCount = 5, - Priority = ResourceLoader.CacheMode.Cache, - Timeout = 30.0f -}; - -_sceneManager.ConfigurePreload(config); -``` - -## 资源管理 - -### 自动卸载 - -```csharp -// 配置自动卸载策略 -var unloadConfig = new SceneUnloadConfig -{ - UnloadDelay = 30.0f, // 30秒后卸载 - KeepReferences = true, // 保持引用 - ForceUnloadOnMemoryPressure = true // 内存紧张时强制卸载 -}; - -_sceneManager.ConfigureUnload(unloadConfig); -``` - -### 手动卸载 - -```csharp -// 卸载指定场景 -_sceneManager.UnloadScene(); - -// 卸载所有场景 -_sceneManager.UnloadAllScenes(); -``` - -## 最佳实践 - -### 1. 场景设计原则 - -```csharp -// 推荐：每个场景职责单一 -public class MainMenuScene : GameSceneBase { /* 主菜单 */ } -public class SettingsScene : GameSceneBase { /* 设置菜单 */ } -public class GameHUDScene : GameSceneBase { /* 游戏HUD */ } - -// 避免：场景职责过多 -public class MegaScene : GameSceneBase -{ - /* 包含菜单、设置、HUD、存档管理... 不要这样设计 */ -} -``` - -### 2. 场景切换优化 - -```csharp -// 推荐：使用异步加载 -public async Task LoadGame() -{ - loadingUI.Show("正在加载游戏..."); - await _sceneManager.SwitchSceneAsync(); -} - -// 避免：同步加载大场景 -public void LoadGame() -{ - // 这会导致游戏卡顿 - _sceneManager.SwitchScene(); -} -``` - -### 3. 内存管理 - -```csharp -public class GameScene : GameSceneBase -{ - private Texture2D[] _largeTextures; - - protected override void OnLoad() - { - // 加载资源 - _largeTextures = LoadLargeTextures(); - } - - protected override void OnUnload() - { - // 及时释放大资源 - foreach (var texture in _largeTextures) - { - texture.Dispose(); - } - _largeTextures = null; - } -} -``` - -### 4. 错误处理 - -```csharp -public async Task SafeLoadScene() where TScene : IScene -{ - try - { - await _sceneManager.SwitchSceneAsync(); - } - catch (SceneNotFoundException) - { - Logger.Error($"场景 {typeof(TScene)} 未找到"); - // 回退到默认场景 - await _sceneManager.SwitchSceneAsync(); - } - catch (ResourceLoadException ex) - { - Logger.Error($"资源加载失败: {ex.Message}"); - await ShowRetryDialog(); - } -} -``` - -## 与其他模块集成 - -### 与 Game 模块集成 - -```csharp -public class GameLevelScene : GameSceneBase -{ - private GameManager _gameManager; - - public override void OnEnter() - { - // 初始化游戏管理器 - _gameManager = Context.GetSystem(); - _gameManager.StartGame(); - } - - public override void OnExit() - { - _gameManager.EndGame(); - } -} -``` - -### 与存档系统集成 - -```csharp -public class GameScene : GameSceneBase -{ - private ISaveSystem _saveSystem; - - protected override void OnLoad() - { - _saveSystem = Context.GetUtility(); - - // 检查是否有自动存档 - if (_saveSystem.HasAutoSave()) - { - var dialog = Context.GetSystem(); - await dialog.ShowAsync("发现自动存档，是否继续？", - onConfirm: () => LoadAutoSave(), - onCancel: () => StartNewGame() - ); - } - } - - private void LoadAutoSave() - { - var saveData = _saveSystem.LoadAutoSave(); - RestoreGameState(saveData); - } - - public override void OnExit() - { - // 自动保存 - _saveSystem.SaveAutoSave(CreateSaveData()); - } -} -``` - ---- - -**相关文档**： - -- [Game 概述](./overview) -- [游戏设置](./setting) -- [存储系统](./storage) -- [存档系统](../game/storage) diff --git a/docs/zh-CN/game/setting.md b/docs/zh-CN/game/setting.md index 073a998..7b452aa 100644 --- a/docs/zh-CN/game/setting.md +++ b/docs/zh-CN/game/setting.md @@ -189,10 +189,4 @@ public interface ISettingsSystem 1. **设置分类** - 将相关设置组织到同一个设置类中 2. **延迟应用** - 批量修改后再应用，而不是每次修改都应用 3. **类型安全** - 使用泛型方法确保类型安全 -4. **可测试性** - 通过接口实现便于单元测试 - -## 相关链接 - -- [Godot 设置模块](../../GFramework.Godot/setting/README.md) -- [存储模块](../../GFramework.Godot/storage/README.md) -- [抽象接口定义](../../../GFramework.Core/Abstractions/) \ No newline at end of file +4. **可测试性** - 通过接口实现便于单元测试 \ No newline at end of file diff --git a/docs/zh-CN/getting-started/architecture-overview.md b/docs/zh-CN/getting-started/index.md similarity index 97% rename from docs/zh-CN/getting-started/architecture-overview.md rename to docs/zh-CN/getting-started/index.md index 3da6efb..f973223 100644 --- a/docs/zh-CN/getting-started/architecture-overview.md +++ b/docs/zh-CN/getting-started/index.md @@ -356,11 +356,4 @@ public class PlayerManager - 统一的架构规范 - 易于新人上手 -- 减少代码冲突 - -## 下一步学习 - -- [深入了解 Architecture 组件](./core/architecture) -- [掌握事件系统](./core/events) -- [学习命令查询模式](./core/command) -- [探索属性系统](./core/property) \ No newline at end of file +- 减少代码冲突 \ No newline at end of file diff --git a/docs/zh-CN/getting-started/installation.md b/docs/zh-CN/getting-started/installation.md index 5a61a08..4a76205 100644 --- a/docs/zh-CN/getting-started/installation.md +++ b/docs/zh-CN/getting-started/installation.md @@ -177,11 +177,3 @@ dotnet build - 确保安装了 `GeWuYou.GFramework.SourceGenerators` - 重启 IDE - 清理并重新构建项目 - -## 下一步 - -安装完成后，建议： - -1. [快速开始](./getting-started/quick-start) - 构建第一个应用 -2. [架构概览](./getting-started/architecture-overview) - 了解核心概念 -3. [Core 模块文档](./core) - 深入学习核心功能 \ No newline at end of file diff --git a/docs/zh-CN/getting-started/quick-start.md b/docs/zh-CN/getting-started/quick-start.md index 47c7348..f9e7d65 100644 --- a/docs/zh-CN/getting-started/quick-start.md +++ b/docs/zh-CN/getting-started/quick-start.md @@ -318,10 +318,3 @@ Press any key to exit... 2. **响应式数据** - BindableProperty 自动更新 3. **事件驱动** - 松耦合的组件通信 4. **命令模式** - 封装用户操作 - -接下来您可以： - -- [深入了解架构组件](./core/architecture) -- [学习事件系统](./core/events) -- [探索 Godot 集成](./godot/overview) -- [查看完整教程](./tutorials/basic-tutorial) \ No newline at end of file diff --git a/docs/zh-CN/godot/coroutine.md b/docs/zh-CN/godot/coroutine.md index 2fcc8ad..b994f96 100644 --- a/docs/zh-CN/godot/coroutine.md +++ b/docs/zh-CN/godot/coroutine.md @@ -400,7 +400,7 @@ A: 未捕获的异常会导致协程停止执行，并可能传播到调用方 **相关文档**： -- [Godot 概述](./overview) -- [Node 扩展方法](./extensions) -- [信号系统](./signal) -- [事件系统](../core/events) +- [Godot 概述](./index.md) +- [Node 扩展方法](./extensions.md) +- [信号扩展](./signal.md) +- [事件系统](../core/events.md) diff --git a/docs/zh-CN/godot/extensions.md b/docs/zh-CN/godot/extensions.md index 737c3fa..67038c9 100644 --- a/docs/zh-CN/godot/extensions.md +++ b/docs/zh-CN/godot/extensions.md @@ -133,7 +133,7 @@ var sprite = childNode.OfType(); ### 3. 信号扩展 (SignalFluentExtensions) -提供流畅的信号连接 API，详见 [signal/README.md](signal/README.md)。 +提供流畅的信号连接 API，详见 [信号扩展](signal.md)。 **快速示例：** @@ -325,11 +325,4 @@ unRegister.UnRegisterWhenNodeExitTree(node); // ❌ 避免：手动管理事件生命周期 // 可能导致内存泄漏 -``` - -## 相关链接 - -- [信号连接系统](signal/README.md) - 详细的信号连接 API 文档 -- [存储模块](../storage/README.md) - 文件存储系统 -- [设置模块](../setting/README.md) - 游戏设置系统 -- [设置系统](../../GFramework.Game/setting/README.md) - 通用设置框架 \ No newline at end of file +``` \ No newline at end of file