mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-03-22 10:34:30 +08:00
docs: 更新文档结构和链接配置
- 移除架构概览页面的独立文件，将其内容迁移至getting-started目录 - 更新导航菜单中架构概览的链接路径 - 删除game模块中的场景管理文档及其相关引用 - 修复godot模块中相关文档的链接格式 - 清理各个文档末尾的多余链接和许可证信息 - 优化文档间的引用关系，确保链接有效性
This commit is contained in:
GeWuYou
parent
f387e3788e
commit
3d656981b4
@ -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' }
|
||||
]
|
||||
}
|
||||
|
||||
@ -86,28 +86,9 @@ public interface IScene
|
||||
void OnUpdate(float delta);
|
||||
}
|
||||
```
|
||||
|
||||
## 资源管理接口
|
||||
|
||||
### IAssetManager
|
||||
|
||||
资源管理器接口：
|
||||
|
||||
```csharp
|
||||
public interface IAssetManager
|
||||
{
|
||||
T Load<T>(string path) where T : Resource;
|
||||
void Preload<T>(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)
|
||||
|
||||
@ -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
|
||||
---
|
||||
@ -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<ISceneManager>();
|
||||
|
||||
// 初始化场景管理器
|
||||
_sceneManager.Initialize();
|
||||
}
|
||||
|
||||
public async Task SwitchToGameScene()
|
||||
{
|
||||
await _sceneManager.SwitchSceneAsync<GameScene>();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 场景加载
|
||||
|
||||
### 同步加载
|
||||
|
||||
适用于小场景的快速切换：
|
||||
|
||||
```csharp
|
||||
public void LoadMainMenu()
|
||||
{
|
||||
_sceneManager.SwitchScene<MainMenuScene>();
|
||||
}
|
||||
```
|
||||
|
||||
### 异步加载
|
||||
|
||||
大场景建议使用异步加载：
|
||||
|
||||
```csharp
|
||||
public async Task LoadGameLevel(string levelName)
|
||||
{
|
||||
// 显示加载界面
|
||||
loadingUI.Show();
|
||||
|
||||
try
|
||||
{
|
||||
// 异步加载场景
|
||||
await _sceneManager.SwitchSceneAsync<GameLevelScene>(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<TScene>() where TScene : IScene
|
||||
{
|
||||
loadingUI.Show();
|
||||
|
||||
var progress = new Progress<float>(value =>
|
||||
{
|
||||
loadingUI.UpdateProgress(value * 100);
|
||||
});
|
||||
|
||||
await _sceneManager.SwitchSceneAsync<TScene>(progress: progress);
|
||||
|
||||
loadingUI.Hide();
|
||||
}
|
||||
```
|
||||
|
||||
## 场景切换动画
|
||||
|
||||
### 内置切换效果
|
||||
|
||||
```csharp
|
||||
public async Task SwitchWithFade()
|
||||
{
|
||||
// 使用淡入淡出效果
|
||||
await _sceneManager.SwitchSceneAsync<GameScene>(
|
||||
transition: new FadeTransition(
|
||||
duration: 0.5f,
|
||||
fadeColor: Colors.Black
|
||||
)
|
||||
);
|
||||
}
|
||||
|
||||
public async Task SlideTransition()
|
||||
{
|
||||
// 使用滑动效果
|
||||
await _sceneManager.SwitchSceneAsync<GameScene>(
|
||||
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<PauseMenuScene>();
|
||||
}
|
||||
```
|
||||
|
||||
### 弹出场景
|
||||
|
||||
弹出栈顶场景：
|
||||
|
||||
```csharp
|
||||
public void PopScene()
|
||||
{
|
||||
_sceneManager.PopScene();
|
||||
}
|
||||
```
|
||||
|
||||
### 示例：带返回的导航
|
||||
|
||||
```csharp
|
||||
public async Task NavigateToSettings()
|
||||
{
|
||||
// 保存当前场景引用
|
||||
var previousScene = _sceneManager.CurrentScene;
|
||||
|
||||
// 推入设置场景
|
||||
await _sceneManager.PushSceneAsync<SettingsScene>();
|
||||
|
||||
// 设置场景有返回按钮
|
||||
await _sceneManager.PushSceneAsync<ConfirmDialog>(
|
||||
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<GameScene>(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<MainMenuScene>();
|
||||
_sceneManager.PreloadScene<GameLevelScene>(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<MainMenuScene>();
|
||||
|
||||
// 卸载所有场景
|
||||
_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<GameScene>();
|
||||
}
|
||||
|
||||
// 避免：同步加载大场景
|
||||
public void LoadGame()
|
||||
{
|
||||
// 这会导致游戏卡顿
|
||||
_sceneManager.SwitchScene<GameScene>();
|
||||
}
|
||||
```
|
||||
|
||||
### 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<TScene>() where TScene : IScene
|
||||
{
|
||||
try
|
||||
{
|
||||
await _sceneManager.SwitchSceneAsync<TScene>();
|
||||
}
|
||||
catch (SceneNotFoundException)
|
||||
{
|
||||
Logger.Error($"场景 {typeof(TScene)} 未找到");
|
||||
// 回退到默认场景
|
||||
await _sceneManager.SwitchSceneAsync<FallbackScene>();
|
||||
}
|
||||
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>();
|
||||
_gameManager.StartGame();
|
||||
}
|
||||
|
||||
public override void OnExit()
|
||||
{
|
||||
_gameManager.EndGame();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 与存档系统集成
|
||||
|
||||
```csharp
|
||||
public class GameScene : GameSceneBase
|
||||
{
|
||||
private ISaveSystem _saveSystem;
|
||||
|
||||
protected override void OnLoad()
|
||||
{
|
||||
_saveSystem = Context.GetUtility<ISaveSystem>();
|
||||
|
||||
// 检查是否有自动存档
|
||||
if (_saveSystem.HasAutoSave())
|
||||
{
|
||||
var dialog = Context.GetSystem<IDialogSystem>();
|
||||
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)
|
||||
@ -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/)
|
||||
4. **可测试性** - 通过接口实现便于单元测试
|
||||
@ -356,11 +356,4 @@ public class PlayerManager
|
||||
|
||||
- 统一的架构规范
|
||||
- 易于新人上手
|
||||
- 减少代码冲突
|
||||
|
||||
## 下一步学习
|
||||
|
||||
- [深入了解 Architecture 组件](./core/architecture)
|
||||
- [掌握事件系统](./core/events)
|
||||
- [学习命令查询模式](./core/command)
|
||||
- [探索属性系统](./core/property)
|
||||
- 减少代码冲突
|
||||
@ -177,11 +177,3 @@ dotnet build
|
||||
- 确保安装了 `GeWuYou.GFramework.SourceGenerators`
|
||||
- 重启 IDE
|
||||
- 清理并重新构建项目
|
||||
|
||||
## 下一步
|
||||
|
||||
安装完成后，建议：
|
||||
|
||||
1. [快速开始](./getting-started/quick-start) - 构建第一个应用
|
||||
2. [架构概览](./getting-started/architecture-overview) - 了解核心概念
|
||||
3. [Core 模块文档](./core) - 深入学习核心功能
|
||||
@ -318,10 +318,3 @@ Press any key to exit...
|
||||
2. **响应式数据** - BindableProperty 自动更新
|
||||
3. **事件驱动** - 松耦合的组件通信
|
||||
4. **命令模式** - 封装用户操作
|
||||
|
||||
接下来您可以：
|
||||
|
||||
- [深入了解架构组件](./core/architecture)
|
||||
- [学习事件系统](./core/events)
|
||||
- [探索 Godot 集成](./godot/overview)
|
||||
- [查看完整教程](./tutorials/basic-tutorial)
|
||||
@ -400,7 +400,7 @@ A: 未捕获的异常会导致协程停止执行，并可能传播到调用方
|
||||
|
||||
**相关文档**：
|
||||
|
||||
- [Godot 概述](./overview)
|
||||
- [Node 扩展方法](./extensions)
|
||||
- [信号系统](./signal)
|
||||
- [事件系统](../core/events)
|
||||
- [Godot 概述](./index.md)
|
||||
- [Node 扩展方法](./extensions.md)
|
||||
- [信号扩展](./signal.md)
|
||||
- [事件系统](../core/events.md)
|
||||
|
||||
@ -133,7 +133,7 @@ var sprite = childNode.OfType<Sprite2D>();
|
||||
|
||||
### 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) - 通用设置框架
|
||||
```
|
||||
Loading…
x
Reference in New Issue
Block a user