gewuyou/GFramework
1
0
Fork 0
mirror of https://github.com/GeWuYou/GFramework.git synced 2026-03-25 04:59:01 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat(assets): 重构资产目录系统以支持场景单元和场景页面

Browse Source 
将原有的 `GameUnit` 和 `Template` 概念重构为更具体的 `SceneUnit` 和 `ScenePage`，
并更新了相关的注册、查询和接口定义。同时修改了Godot模块中对这些资源的引用方式，
确保整体架构的一致性和可维护性。
This commit is contained in:
GwWuYou 2025-12-21 17:36:35 +08:00
parent 028ece27db
commit 6c2832915f
6 changed files with 114 additions and 104 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

103
GFramework.Game/assets/AbstractAssetCatalogSystem.cs
View File

@ -9,8 +9,8 @@ namespace GFramework.Game.assets;
/// </summary> /// </summary>
public abstract class AbstractAssetCatalogSystem : AbstractSystem, IAssetCatalogSystem public abstract class AbstractAssetCatalogSystem : AbstractSystem, IAssetCatalogSystem
{ {
private readonly Dictionary<string, AssetCatalog.GameUnitId> _gameUnits = new(); private readonly Dictionary<string, AssetCatalog.SceneUnitId> _sceneUnits = new();
private readonly Dictionary<string, AssetCatalog.TemplateId> _templates = new(); private readonly Dictionary<string, AssetCatalog.ScenePageId> _scenePages = new();
private readonly Dictionary<string, AssetCatalog.AssetId> _assets = new(); private readonly Dictionary<string, AssetCatalog.AssetId> _assets = new();
@ -31,62 +31,65 @@ public abstract class AbstractAssetCatalogSystem : AbstractSystem, IAssetCatalog
#region Register（内部 or Module 使用） #region Register（内部 or Module 使用）
/// <summary> /// <summary>
/// 注册一个游戏单元（GameUnit），使用指定的键和路径。 /// 注册场景单元到资产目录中
/// </summary> /// </summary>
/// <param name="key">唯一标识该游戏单元的字符串键。</param> /// <param name="key">场景单元的唯一标识键</param>
/// <param name="path">该游戏单元对应的资源路径。</param> /// <param name="path">场景单元资源的路径</param>
/// <exception cref="InvalidOperationException">当键已存在时抛出异常。</exception> /// <exception cref="InvalidOperationException">当指定的键已存在时抛出异常</exception>
public void RegisterGameUnit(string key, string path) public void RegisterSceneUnit(string key, string path)
{ {
if (!_gameUnits.TryAdd(key, new AssetCatalog.GameUnitId(path))) // 尝试添加场景单元，如果键已存在则抛出异常
throw new InvalidOperationException($"GameUnit key duplicated: {key}"); if (!_sceneUnits.TryAdd(key, new AssetCatalog.SceneUnitId(path)))
throw new InvalidOperationException($"SceneUnit key duplicated: {key}");
} }
/// <summary> /// <summary>
/// 根据映射对象注册一个游戏单元（GameUnit）。 /// 通过资产目录映射注册场景单元
/// </summary> /// </summary>
/// <param name="mapping">包含键与ID映射关系的对象。</param> /// <param name="mapping">包含场景单元信息的资产目录映射对象</param>
/// <exception cref="InvalidOperationException"> /// <exception cref="InvalidOperationException">当映射ID不是SceneUnitId类型或键已存在时抛出异常</exception>
/// 当映射ID不是 <see cref="AssetCatalog.GameUnitId"/> 类型或键重复时抛出异常。 public void RegisterSceneUnit(AssetCatalog.AssetCatalogMapping mapping)
/// </exception>
public void RegisterGameUnit(AssetCatalog.AssetCatalogMapping mapping)
{ {
if (mapping.Id is not AssetCatalog.GameUnitId sceneId) // 验证映射ID是否为SceneUnitId类型
throw new InvalidOperationException("Mapping ID is not a GameUnitId"); if (mapping.Id is not AssetCatalog.SceneUnitId sceneId)
throw new InvalidOperationException("Mapping ID is not a SceneUnitId");
if (!_gameUnits.TryAdd(mapping.Key, sceneId)) // 尝试添加场景单元，如果键已存在则抛出异常
if (!_sceneUnits.TryAdd(mapping.Key, sceneId))
throw new InvalidOperationException($"Scene key duplicated: {mapping.Key}"); throw new InvalidOperationException($"Scene key duplicated: {mapping.Key}");
} }
/// <summary> /// <summary>
/// 注册一个模板资源（Template），使用指定的键和路径。 /// 注册场景页面模板
/// </summary> /// </summary>
/// <param name="key">唯一标识该模板的字符串键。</param> /// <param name="key">场景页面的唯一标识键</param>
/// <param name="path">该模板对应的资源路径。</param> /// <param name="path">场景页面资源路径</param>
/// <exception cref="InvalidOperationException">当键已存在时抛出异常。</exception> /// <exception cref="InvalidOperationException">当键已存在时抛出异常</exception>
public void RegisterTemplate(string key, string path) public void RegisterScenePage(string key, string path)
{ {
if (!_templates.TryAdd(key, new AssetCatalog.TemplateId(path))) if (!_scenePages.TryAdd(key, new AssetCatalog.ScenePageId(path)))
throw new InvalidOperationException($"Template key duplicated: {key}"); throw new InvalidOperationException($"Template key duplicated: {key}");
} }
/// <summary> /// <summary>
/// 根据映射对象注册一个模板资源（Template）。 /// 通过资产目录映射注册场景页面
/// </summary> /// </summary>
/// <param name="mapping">包含键与ID映射关系的对象。</param> /// <param name="mapping">包含场景页面信息的资产目录映射对象</param>
/// <exception cref="InvalidOperationException"> /// <exception cref="InvalidOperationException">当映射ID不是ScenePageId类型或键已存在时抛出异常</exception>
/// 当映射ID不是 <see cref="AssetCatalog.TemplateId"/> 类型或键重复时抛出异常。 public void RegisterScenePage(AssetCatalog.AssetCatalogMapping mapping)
/// </exception>
public void RegisterTemplate(AssetCatalog.AssetCatalogMapping mapping)
{ {
if (mapping.Id is not AssetCatalog.TemplateId templateId) // 验证映射ID是否为ScenePageId类型
throw new InvalidOperationException("Mapping ID is not a TemplateId"); if (mapping.Id is not AssetCatalog.ScenePageId templateId)
throw new InvalidOperationException("Mapping ID is not a ScenePageId");
if (!_templates.TryAdd(mapping.Key, templateId)) // 尝试添加场景页面，如果键已存在则抛出异常
if (!_scenePages.TryAdd(mapping.Key, templateId))
throw new InvalidOperationException($"Template key duplicated: {mapping.Key}"); throw new InvalidOperationException($"Template key duplicated: {mapping.Key}");
} }
/// <summary> /// <summary>
/// 注册一个通用资源（Asset），使用指定的键和路径。 /// 注册一个通用资源（Asset），使用指定的键和路径。
/// </summary> /// </summary>
@ -119,20 +122,18 @@ public abstract class AbstractAssetCatalogSystem : AbstractSystem, IAssetCatalog
#region Query（对外） #region Query（对外）
/// <summary> /// <summary>
/// 获取指定键对应的游戏单元ID。 /// 根据指定的键获取场景单元标识符
/// </summary> /// </summary>
/// <param name="key">要查找的游戏单元键。</param> /// <param name="key">用于查找场景单元的键值</param>
/// <returns>对应的游戏单元ID。</returns> /// <returns>返回与指定键对应的场景单元标识符</returns>
/// <exception cref="KeyNotFoundException">如果未找到指定键则抛出异常。</exception> public AssetCatalog.SceneUnitId GetSceneUnit(string key) => _sceneUnits[key];
public AssetCatalog.GameUnitId GetGameUnit(string key) => _gameUnits[key];
/// <summary> /// <summary>
/// 获取指定键对应的模板资源ID。 /// 根据指定的键获取场景页面标识符
/// </summary> /// </summary>
/// <param name="key">要查找的模板资源键。</param> /// <param name="key">用于查找场景页面的键值</param>
/// <returns>对应的模板资源ID。</returns> /// <returns>返回与指定键对应的场景页面标识符</returns>
/// <exception cref="KeyNotFoundException">如果未找到指定键则抛出异常。</exception> public AssetCatalog.ScenePageId GetScenePage(string key) => _scenePages[key];
public AssetCatalog.TemplateId GetTemplate(string key) => _templates[key];
/// <summary> /// <summary>
/// 获取指定键对应的通用资源ID。 /// 获取指定键对应的通用资源ID。
@ -143,18 +144,18 @@ public abstract class AbstractAssetCatalogSystem : AbstractSystem, IAssetCatalog
public AssetCatalog.AssetId GetAsset(string key) => _assets[key]; public AssetCatalog.AssetId GetAsset(string key) => _assets[key];
/// <summary> /// <summary>
/// 判断是否存在指定键的游戏单元。 /// 检查是否存在指定键的场景单元
/// </summary> /// </summary>
/// <param name="key">要检查的游戏单元键。</param> /// <param name="key">用于查找场景单元的键值</param>
/// <returns>若存在返回 true，否则返回 false。</returns> /// <returns>存在返回true，否则返回false</returns>
public bool HasGameUnit(string key) => _gameUnits.ContainsKey(key); public bool HasSceneUnit(string key) => _sceneUnits.ContainsKey(key);
/// <summary> /// <summary>
/// 判断是否存在指定键的模板资源。 /// 检查是否存在指定键的场景页面
/// </summary> /// </summary>
/// <param name="key">要检查的模板资源键。</param> /// <param name="key">用于查找场景页面的键值</param>
/// <returns>若存在返回 true，否则返回 false。</returns> /// <returns>存在返回true，否则返回false</returns>
public bool HasTemplate(string key) => _templates.ContainsKey(key); public bool HasScenePage(string key) => _scenePages.ContainsKey(key);
/// <summary> /// <summary>
/// 判断是否存在指定键的通用资源。 /// 判断是否存在指定键的通用资源。

22
GFramework.Game/assets/AssetCatalog.cs
View File

@ -1,5 +1,4 @@
 namespace GFramework.Game.assets;
namespace GFramework.Game.assets;
/// <summary> /// <summary>
/// 资源目录类，用于定义和管理游戏中的场景和资源标识符 /// 资源目录类，用于定义和管理游戏中的场景和资源标识符
@ -24,17 +23,19 @@ public static class AssetCatalog
/// <param name="Id">资源标识符</param> /// <param name="Id">资源标识符</param>
public readonly record struct AssetCatalogMapping(string Key, IAssetId Id); public readonly record struct AssetCatalogMapping(string Key, IAssetId Id);
/// <summary>
/// 模板资源标识符结构体，实现IAssetId接口
/// </summary>
/// <param name="Path">资源路径</param>
public readonly record struct TemplateId(string Path) : IAssetId;
/// <summary> /// <summary>
/// 游戏单位资源标识符结构体，实现IAssetId接口 /// 场景页面资源标识符结构体，用于标识场景页面资源
/// </summary> /// </summary>
/// <param name="Path">资源路径</param> /// <param name="Path">场景页面资源路径</param>
public readonly record struct GameUnitId(string Path) : IAssetId; public readonly record struct ScenePageId(string Path) : IAssetId;
/// <summary>
/// 场景单元资源标识符结构体，用于标识场景单元资源
/// </summary>
/// <param name="Path">场景单元资源路径</param>
public readonly record struct SceneUnitId(string Path) : IAssetId;
/// <summary> /// <summary>
/// 通用资源标识符结构体，实现IAssetId接口 /// 通用资源标识符结构体，实现IAssetId接口
@ -43,3 +44,4 @@ public static class AssetCatalog
public readonly record struct AssetId(string Path) : IAssetId; public readonly record struct AssetId(string Path) : IAssetId;
} }

69
GFramework.Game/assets/IAssetCatalogSystem.cs
View File

@ -8,18 +8,19 @@ namespace GFramework.Game.assets;
public interface IAssetCatalogSystem : ISystem public interface IAssetCatalogSystem : ISystem
{ {
/// <summary> /// <summary>
/// 根据指定的键获取游戏单位ID /// 根据指定的键获取场景单元标识符
/// </summary> /// </summary>
/// <param name="key">用于查找游戏单位的键值</param> /// <param name="key">用于查找场景单元的键值</param>
/// <returns>返回对应的游戏单位ID，如果未找到则返回默认值</returns> /// <returns>返回与指定键对应的场景单元标识符</returns>
AssetCatalog.GameUnitId GetGameUnit(string key); AssetCatalog.SceneUnitId GetSceneUnit(string key);
/// <summary> /// <summary>
/// 根据指定的键获取模板ID /// 根据指定的键获取场景页面标识符
/// </summary> /// </summary>
/// <param name="key">用于查找模板的键值</param> /// <param name="key">用于查找场景页面的键值</param>
/// <returns>返回对应的模板ID，如果未找到则返回默认值</returns> /// <returns>返回与指定键对应的场景页面标识符</returns>
AssetCatalog.TemplateId GetTemplate(string key); AssetCatalog.ScenePageId GetScenePage(string key);
/// <summary> /// <summary>
/// 根据指定的键获取资源ID /// 根据指定的键获取资源ID
@ -29,30 +30,34 @@ public interface IAssetCatalogSystem : ISystem
AssetCatalog.AssetId GetAsset(string key); AssetCatalog.AssetId GetAsset(string key);
/// <summary> /// <summary>
/// 注册游戏单位资源到资产目录中 /// 注册场景单元到资产目录中
/// </summary> /// </summary>
/// <param name="key">游戏单位的唯一标识键值</param> /// <param name="key">场景单元的唯一标识键</param>
/// <param name="path">游戏单位资源的路径</param> /// <param name="path">场景单元资源的路径</param>
void RegisterGameUnit(string key, string path); /// <exception cref="InvalidOperationException">当指定的键已存在时抛出异常</exception>
public void RegisterSceneUnit(string key, string path);
/// <summary> /// <summary>
/// 根据映射配置注册游戏单位资源到资产目录中 /// 通过资产目录映射注册场景单元
/// </summary> /// </summary>
/// <param name="mapping">包含键值和路径映射关系的配置对象</param> /// <param name="mapping">包含场景单元信息的资产目录映射对象</param>
void RegisterGameUnit(AssetCatalog.AssetCatalogMapping mapping); /// <exception cref="InvalidOperationException">当映射ID不是SceneUnitId类型或键已存在时抛出异常</exception>
public void RegisterSceneUnit(AssetCatalog.AssetCatalogMapping mapping);
/// <summary> /// <summary>
/// 注册模板资源到资产目录中 /// 注册场景页面模板
/// </summary> /// </summary>
/// <param name="key">模板的唯一标识键值</param> /// <param name="key">场景页面的唯一标识键</param>
/// <param name="path">模板资源的路径</param> /// <param name="path">场景页面资源路径</param>
void RegisterTemplate(string key, string path); /// <exception cref="InvalidOperationException">当键已存在时抛出异常</exception>
void RegisterScenePage(string key, string path);
/// <summary> /// <summary>
/// 根据映射配置注册模板资源到资产目录中 /// 通过资产目录映射注册场景页面
/// </summary> /// </summary>
/// <param name="mapping">包含键值和路径映射关系的配置对象</param> /// <param name="mapping">包含场景页面信息的资产目录映射对象</param>
void RegisterTemplate(AssetCatalog.AssetCatalogMapping mapping); /// <exception cref="InvalidOperationException">当映射ID不是ScenePageId类型或键已存在时抛出异常</exception>
void RegisterScenePage(AssetCatalog.AssetCatalogMapping mapping);
/// <summary> /// <summary>
/// 注册普通资产资源到资产目录中 /// 注册普通资产资源到资产目录中
@ -67,19 +72,21 @@ public interface IAssetCatalogSystem : ISystem
/// <param name="mapping">包含键值和路径映射关系的配置对象</param> /// <param name="mapping">包含键值和路径映射关系的配置对象</param>
void RegisterAsset(AssetCatalog.AssetCatalogMapping mapping); void RegisterAsset(AssetCatalog.AssetCatalogMapping mapping);
/// <summary>
/// 检查是否存在指定键的游戏单位
/// </summary>
/// <param name="key">用于查找游戏单位的键值</param>
/// <returns>存在返回true，否则返回false</returns>
bool HasGameUnit(string key);
/// <summary> /// <summary>
/// 检查是否存在指定键的模板 /// 检查是否存在指定键的场景单元
/// </summary> /// </summary>
/// <param name="key">用于查找模板的键值</param> /// <param name="key">用于查找场景单元的键值</param>
/// <returns>存在返回true，否则返回false</returns> /// <returns>存在返回true，否则返回false</returns>
bool HasTemplate(string key); bool HasSceneUnit(string key);
/// <summary>
/// 检查是否存在指定键的场景页面
/// </summary>
/// <param name="key">用于查找场景页面的键值</param>
/// <returns>存在返回true，否则返回false</returns>
bool HasScenePage(string key);
/// <summary> /// <summary>
/// 检查是否存在指定键的资源 /// 检查是否存在指定键的资源

4
GFramework.Godot/assets/AbstractResourceFactorySystem.cs
View File

@ -81,7 +81,7 @@ public abstract class AbstractResourceFactorySystem : AbstractSystem, IResourceF
bool preload = false) bool preload = false)
where T : Node where T : Node
{ {
var id = _assetCatalogSystem!.GetGameUnit(sceneKey); var id = _assetCatalogSystem!.GetSceneUnit(sceneKey);
_registry!.Register( _registry!.Register(
sceneKey, sceneKey,
@ -101,7 +101,7 @@ public abstract class AbstractResourceFactorySystem : AbstractSystem, IResourceF
bool preload = false) bool preload = false)
where T : Node where T : Node
{ {
var id = _assetCatalogSystem!.GetTemplate(templateKey); var id = _assetCatalogSystem!.GetScenePage(templateKey);
_registry!.Register( _registry!.Register(
templateKey, templateKey,

4
GFramework.Godot/assets/IResourceLoadSystem.cs
View File

@ -39,7 +39,7 @@ public interface IResourceLoadSystem : ISystem
/// <param name="id">场景资源标识符</param> /// <param name="id">场景资源标识符</param>
/// <returns>创建场景实例的工厂函数</returns> /// <returns>创建场景实例的工厂函数</returns>
Func<T> GetOrRegisterGameUnitFactory<T>( Func<T> GetOrRegisterGameUnitFactory<T>(
AssetCatalog.GameUnitId id AssetCatalog.SceneUnitId id
) where T : Node; ) where T : Node;
/// <summary> /// <summary>
@ -49,7 +49,7 @@ public interface IResourceLoadSystem : ISystem
/// <param name="id">模板资源标识符</param> /// <param name="id">模板资源标识符</param>
/// <returns>创建模板实例的工厂函数</returns> /// <returns>创建模板实例的工厂函数</returns>
Func<T> GetOrRegisterTemplateFactory<T>( Func<T> GetOrRegisterTemplateFactory<T>(
AssetCatalog.TemplateId id AssetCatalog.ScenePageId id
) where T : Node; ) where T : Node;
/// <summary> /// <summary>

4
GFramework.Godot/assets/ResourceLoadSystem.cs
View File

@ -99,7 +99,7 @@ public class ResourceLoadSystem : AbstractSystem, IResourceLoadSystem
return scene.Instantiate<T>(); return scene.Instantiate<T>();
} }
public Func<T> GetOrRegisterGameUnitFactory<T>(AssetCatalog.GameUnitId id) where T : Node public Func<T> GetOrRegisterGameUnitFactory<T>(AssetCatalog.SceneUnitId id) where T : Node
{ {
var path = id.Path; var path = id.Path;
if (_sceneFactories.TryGetValue(path, out var d)) if (_sceneFactories.TryGetValue(path, out var d))
@ -119,7 +119,7 @@ public class ResourceLoadSystem : AbstractSystem, IResourceLoadSystem
return factory; return factory;
} }
public Func<T> GetOrRegisterTemplateFactory<T>(AssetCatalog.TemplateId id) where T : Node public Func<T> GetOrRegisterTemplateFactory<T>(AssetCatalog.ScenePageId id) where T : Node
{ {
var path = id.Path; var path = id.Path;
if (_sceneFactories.TryGetValue(path, out var d)) if (_sceneFactories.TryGetValue(path, out var d))