From 4fd90e45a1072203630e60cdb1ed3446c0f84348 Mon Sep 17 00:00:00 2001
From: GeWuYou <95328647+GeWuYou@users.noreply.github.com>
Date: Mon, 23 Feb 2026 21:54:49 +0800
Subject: [PATCH] =?UTF-8?q?feat(godot):=20=E6=B7=BB=E5=8A=A0=E8=B5=84?=
 =?UTF-8?q?=E6=BA=90=E4=BB=93=E5=82=A8=E5=8A=9F=E8=83=BD=E6=94=AF=E6=8C=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 新增 IHasKey 接口定义键值访问契约
- 新增 IRepository 接口提供通用数据仓储功能
- 实现 GodotResourceRepository 类支持资源的存储和加载
- 添加 IResourceRepository 接口扩展通用仓储功能
- 实现从路径批量加载 Godot 资源的功能
- 支持递归加载子目录中的资源文件
- 提供 .tres 和 .res 文件的自动识别和加载
---
 GFramework.Core.Abstractions/bases/IHasKey.cs |  26 +++
 GFramework.Core.Tests/ecs/EcsAdvancedTests.cs |   2 -
 .../data/IRepository.cs                       |  68 +++++++
 .../data/GodotResourceRepository.cs           | 184 ++++++++++++++++++
 GFramework.Godot/data/IResourceRepository.cs  |  41 ++++
 5 files changed, 319 insertions(+), 2 deletions(-)
 create mode 100644 GFramework.Core.Abstractions/bases/IHasKey.cs
 create mode 100644 GFramework.Game.Abstractions/data/IRepository.cs
 create mode 100644 GFramework.Godot/data/GodotResourceRepository.cs
 create mode 100644 GFramework.Godot/data/IResourceRepository.cs

diff --git a/GFramework.Core.Abstractions/bases/IHasKey.cs b/GFramework.Core.Abstractions/bases/IHasKey.cs
new file mode 100644
index 0000000..a2b09fa
--- /dev/null
+++ b/GFramework.Core.Abstractions/bases/IHasKey.cs
@@ -0,0 +1,26 @@
+// Copyright (c) 2026 GeWuYou
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// 
+//     http://www.apache.org/licenses/LICENSE-2.0
+// 
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+namespace GFramework.Core.Abstractions.bases;
+
+/// <summary>
+/// 定义具有键值访问能力的接口契约
+/// </summary>
+/// <typeparam name="TKey">键的类型</typeparam>
+public interface IHasKey<out TKey>
+{
+    /// <summary>
+    /// 获取对象的键值
+    /// </summary>
+    TKey Key { get; }
+}
\ No newline at end of file
diff --git a/GFramework.Core.Tests/ecs/EcsAdvancedTests.cs b/GFramework.Core.Tests/ecs/EcsAdvancedTests.cs
index 577f7e1..53582ef 100644
--- a/GFramework.Core.Tests/ecs/EcsAdvancedTests.cs
+++ b/GFramework.Core.Tests/ecs/EcsAdvancedTests.cs
@@ -1,4 +1,3 @@
-using System.Diagnostics.CodeAnalysis;
 using System.Reflection;
 using Arch.Core;
 using GFramework.Core.Abstractions.ecs;
@@ -14,7 +13,6 @@ using NUnit.Framework;
 namespace GFramework.Core.Tests.ecs;
 
 [TestFixture]
-[Experimental("GFrameworkECS")]
 public class EcsAdvancedTests
 {
     [SetUp]
diff --git a/GFramework.Game.Abstractions/data/IRepository.cs b/GFramework.Game.Abstractions/data/IRepository.cs
new file mode 100644
index 0000000..3e7724e
--- /dev/null
+++ b/GFramework.Game.Abstractions/data/IRepository.cs
@@ -0,0 +1,68 @@
+// Copyright (c) 2026 GeWuYou
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// 
+//     http://www.apache.org/licenses/LICENSE-2.0
+// 
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+namespace GFramework.Game.Abstractions.data;
+
+/// <summary>
+/// 定义数据仓储接口，提供键值对数据的基本操作功能
+/// </summary>
+/// <typeparam name="TKey">键的类型</typeparam>
+/// <typeparam name="TValue">值的类型</typeparam>
+public interface IRepository<in TKey, TValue>
+{
+    /// <summary>
+    /// 添加键值对到仓储中
+    /// </summary>
+    /// <param name="key">要添加的键</param>
+    /// <param name="value">要添加的值</param>
+    void Add(TKey key, TValue value);
+
+    /// <summary>
+    /// 根据键获取对应的值
+    /// </summary>
+    /// <param name="key">要查找的键</param>
+    /// <returns>与指定键关联的值</returns>
+    TValue Get(TKey key);
+
+    /// <summary>
+    /// 尝试根据键获取对应的值
+    /// </summary>
+    /// <param name="key">要查找的键</param>
+    /// <param name="value">输出参数，如果找到则返回对应的值，否则返回默认值</param>
+    /// <returns>如果找到键则返回true，否则返回false</returns>
+    bool TryGet(TKey key, out TValue value);
+
+    /// <summary>
+    /// 获取仓储中的所有值
+    /// </summary>
+    /// <returns>包含所有值的只读集合</returns>
+    IReadOnlyCollection<TValue> GetAll();
+
+    /// <summary>
+    /// 检查仓储中是否包含指定的键
+    /// </summary>
+    /// <param name="key">要检查的键</param>
+    /// <returns>如果包含该键则返回true，否则返回false</returns>
+    bool Contains(TKey key);
+
+    /// <summary>
+    /// 从仓储中移除指定键的项
+    /// </summary>
+    /// <param name="key">要移除的键</param>
+    void Remove(TKey key);
+
+    /// <summary>
+    /// 清空仓储中的所有数据
+    /// </summary>
+    void Clear();
+}
\ No newline at end of file
diff --git a/GFramework.Godot/data/GodotResourceRepository.cs b/GFramework.Godot/data/GodotResourceRepository.cs
new file mode 100644
index 0000000..5119f71
--- /dev/null
+++ b/GFramework.Godot/data/GodotResourceRepository.cs
@@ -0,0 +1,184 @@
+// Copyright (c) 2026 GeWuYou
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// 
+//     http://www.apache.org/licenses/LICENSE-2.0
+// 
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+using GFramework.Core.Abstractions.bases;
+using Godot;
+
+namespace GFramework.Godot.data;
+
+/// <summary>
+/// Godot资源仓储实现类，用于管理Godot资源的存储和加载。
+/// 实现了IResourceRepository接口，提供基于键的资源存取功能。
+/// </summary>
+/// <typeparam name="TKey">资源键的类型</typeparam>
+/// <typeparam name="TResource">资源类型，必须继承自Godot.Resource并实现IHasKey接口</typeparam>
+public class GodotResourceRepository<TKey, TResource>
+    : IResourceRepository<TKey, TResource>
+    where TResource : Resource, IHasKey<TKey>
+    where TKey : notnull
+{
+    /// <summary>
+    /// 内部存储字典，用于保存键值对形式的资源
+    /// </summary>
+    private readonly Dictionary<TKey, TResource> _storage = new();
+
+    /// <summary>
+    /// 向仓储中添加资源
+    /// </summary>
+    /// <param name="key">资源的键</param>
+    /// <param name="value">要添加的资源对象</param>
+    /// <exception cref="InvalidOperationException">当键已存在时抛出异常</exception>
+    public void Add(TKey key, TResource value)
+    {
+        if (!_storage.TryAdd(key, value))
+            throw new InvalidOperationException($"Duplicate key detected: {key}");
+    }
+
+    /// <summary>
+    /// 根据键获取资源
+    /// </summary>
+    /// <param name="key">资源的键</param>
+    /// <returns>对应的资源对象</returns>
+    /// <exception cref="KeyNotFoundException">当键不存在时抛出异常</exception>
+    public TResource Get(TKey key)
+    {
+        if (!_storage.TryGetValue(key, out var value))
+            throw new KeyNotFoundException($"Resource with key '{key}' not found.");
+
+        return value;
+    }
+
+    /// <summary>
+    /// 尝试根据键获取资源
+    /// </summary>
+    /// <param name="key">资源的键</param>
+    /// <param name="value">输出参数，返回找到的资源对象</param>
+    /// <returns>如果找到资源返回true，否则返回false</returns>
+    public bool TryGet(TKey key, out TResource value)
+        => _storage.TryGetValue(key, out value!);
+
+    /// <summary>
+    /// 获取所有资源的只读集合
+    /// </summary>
+    /// <returns>包含所有资源的只读集合</returns>
+    public IReadOnlyCollection<TResource> GetAll()
+        => _storage.Values;
+
+    /// <summary>
+    /// 检查是否包含指定键的资源
+    /// </summary>
+    /// <param name="key">要检查的键</param>
+    /// <returns>如果包含该键返回true，否则返回false</returns>
+    public bool Contains(TKey key)
+        => _storage.ContainsKey(key);
+
+    /// <summary>
+    /// 从仓储中移除指定键的资源
+    /// </summary>
+    /// <param name="key">要移除的资源键</param>
+    /// <exception cref="KeyNotFoundException">当键不存在时抛出异常</exception>
+    public void Remove(TKey key)
+    {
+        if (!_storage.Remove(key))
+            throw new KeyNotFoundException($"Resource with key '{key}' not found.");
+    }
+
+    /// <summary>
+    /// 清空仓储中的所有资源
+    /// </summary>
+    public void Clear()
+        => _storage.Clear();
+
+    /// <summary>
+    /// 从指定路径集合加载资源到仓储中
+    /// </summary>
+    /// <param name="paths">资源文件路径的集合</param>
+    /// <param name="recursive">是否递归加载子目录中的资源</param>
+    public void LoadFromPath(IEnumerable<string> paths, bool recursive = false)
+    {
+        foreach (var path in paths)
+        {
+            LoadSinglePath(path, recursive);
+        }
+    }
+
+    /// <summary>
+    /// 从指定路径数组加载资源到仓储中
+    /// 提供便捷的参数数组重载方法
+    /// </summary>
+    /// <param name="recursive">是否递归加载子目录中的资源</param>
+    /// <param name="paths">资源文件路径的参数数组</param>
+    public void LoadFromPath(bool recursive = false, params string[] paths)
+    {
+        LoadFromPath(paths, recursive);
+    }
+
+    /// <summary>
+    /// 从单个路径加载资源
+    /// 遍历目录中的所有.tres和.res文件并加载为资源
+    /// </summary>
+    /// <param name="path">要加载资源的目录路径</param>
+    /// <param name="recursive">是否递归加载子目录中的资源</param>
+    private void LoadSinglePath(string path, bool recursive)
+    {
+        // 打开目录访问对象
+        var dir = DirAccess.Open(path);
+        if (dir == null)
+        {
+            GD.PushWarning($"Path not found: {path}");
+            return;
+        }
+
+        // 开始遍历目录
+        dir.ListDirBegin();
+
+        while (true)
+        {
+            var entry = dir.GetNext();
+            if (string.IsNullOrEmpty(entry))
+                break;
+
+            var fullPath = $"{path}/{entry}";
+
+            // 处理目录项
+            if (dir.CurrentIsDir())
+            {
+                // 递归处理子目录（排除.和..目录）
+                if (recursive && entry != "." && entry != "..")
+                {
+                    LoadSinglePath(fullPath, true);
+                }
+
+                continue;
+            }
+
+            // 只处理.tres和.res文件
+            if (!entry.EndsWith(".tres") && !entry.EndsWith(".res"))
+                continue;
+
+            // 加载资源文件
+            var resource = GD.Load<TResource>(fullPath);
+
+            if (resource == null)
+            {
+                GD.PushWarning($"Failed to load resource: {fullPath}");
+                continue;
+            }
+
+            Add(resource.Key, resource);
+        }
+
+        // 结束目录遍历
+        dir.ListDirEnd();
+    }
+}
\ No newline at end of file
diff --git a/GFramework.Godot/data/IResourceRepository.cs b/GFramework.Godot/data/IResourceRepository.cs
new file mode 100644
index 0000000..c510e67
--- /dev/null
+++ b/GFramework.Godot/data/IResourceRepository.cs
@@ -0,0 +1,41 @@
+// Copyright (c) 2026 GeWuYou
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// 
+//     http://www.apache.org/licenses/LICENSE-2.0
+// 
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+using GFramework.Game.Abstractions.data;
+using Godot;
+
+namespace GFramework.Godot.data;
+
+/// <summary>
+/// 定义资源仓储接口，专门用于管理Godot资源的加载和存储
+/// 继承自通用仓储接口，添加了从路径加载资源的功能
+/// </summary>
+/// <typeparam name="TKey">资源键的类型</typeparam>
+/// <typeparam name="TResource">资源类型，必须继承自Godot.Resource</typeparam>
+public interface IResourceRepository<in TKey, TResource> : IRepository<TKey, TResource> where TResource : Resource
+{
+    /// <summary>
+    /// 从指定路径加载资源到仓储中
+    /// </summary>
+    /// <param name="paths">资源文件的路径集合</param>
+    /// <param name="recursive">是否递归加载子目录中的资源</param>
+    void LoadFromPath(IEnumerable<string> paths, bool recursive = false);
+
+    /// <summary>
+    /// 从指定路径数组加载资源到仓储中
+    /// 提供便捷的参数数组重载方法
+    /// </summary>
+    /// <param name="recursive">是否递归加载子目录中的资源</param>
+    /// <param name="paths">资源文件路径的参数数组</param>
+    void LoadFromPath(bool recursive = false, params string[] paths);
+}
\ No newline at end of file