docs(config): 添加游戏内容配置系统完整文档

- 新增面向静态游戏内容的 AI-First 配表方案介绍
- 详细说明 YAML 作为配置源文件和 JSON Schema 结构描述功能
- 提供推荐目录结构和 Schema 示例配置
- 添加 VS Code 插件工具支持说明
- 包含 Godot 文本配置桥接使用指南
- 提供运行时读取和热重载模板示例
- 说明生成器接入约定和运行时校验行为
- 添加开发期热重载和工具支持详细说明
- 创建 Godot 测试项目配置文件
- 实现 GodotYamlConfigLoader 配置加载适配层

GFramework.Godot.Tests/Config/GodotYamlConfigLoaderTests.cs

@@ -0,0 +1,286 @@
+using System;
+using System.IO;
+using System.Linq;
+using System.Threading.Tasks;
+using GFramework.Godot.Config;
+
+namespace GFramework.Godot.Tests.Config;
+
+/// <summary>
+///     验证 Godot YAML 配置加载器能够在编辑器态直读项目目录，并在导出态同步运行时缓存。
+/// </summary>
+[TestFixture]
+public sealed class GodotYamlConfigLoaderTests
+{
+    private string _resourceRoot = null!;
+    private string _testRoot = null!;
+    private string _userRoot = null!;
+
+    /// <summary>
+    ///     为每个测试准备独立的资源根目录与用户目录。
+    /// </summary>
+    [SetUp]
+    public void SetUp()
+    {
+        _testRoot = Path.Combine(
+            Path.GetTempPath(),
+            "GFramework.GodotYamlConfigLoaderTests",
+            Guid.NewGuid().ToString("N"));
+        _resourceRoot = Path.Combine(_testRoot, "res-root");
+        _userRoot = Path.Combine(_testRoot, "user-root");
+        Directory.CreateDirectory(_resourceRoot);
+        Directory.CreateDirectory(_userRoot);
+    }
+
+    /// <summary>
+    ///     清理测试期间创建的临时目录。
+    /// </summary>
+    [TearDown]
+    public void TearDown()
+    {
+        if (Directory.Exists(_testRoot))
+        {
+            Directory.Delete(_testRoot, true);
+        }
+    }
+
+    /// <summary>
+    ///     验证导出态会把注册过的 YAML 与 schema 文本同步到运行时缓存，再交给底层加载器。
+    /// </summary>
+    [Test]
+    public async Task LoadAsync_Should_Copy_Registered_Text_Assets_Into_Runtime_Cache_When_Source_Is_Res_Path()
+    {
+        CreateMonsterFiles(_resourceRoot);
+
+        var loader = CreateLoader(isEditor: false);
+        var registry = new ConfigRegistry();
+
+        await loader.LoadAsync(registry);
+
+        var table = registry.GetTable<int, MonsterConfigStub>("monster");
+        var cacheRoot = Path.Combine(_userRoot, "config_cache");
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(loader.CanEnableHotReload, Is.False);
+            Assert.That(loader.LoaderRootPath, Is.EqualTo(cacheRoot));
+            Assert.That(table.Count, Is.EqualTo(2));
+            Assert.That(table.Get(1).Name, Is.EqualTo("Slime"));
+            Assert.That(File.Exists(Path.Combine(cacheRoot, "monster", "slime.yaml")), Is.True);
+            Assert.That(File.Exists(Path.Combine(cacheRoot, "monster", "goblin.yml")), Is.True);
+            Assert.That(File.Exists(Path.Combine(cacheRoot, "schemas", "monster.schema.json")), Is.True);
+            Assert.That(File.Exists(Path.Combine(cacheRoot, "monster", "notes.txt")), Is.False);
+            Assert.That(Directory.Exists(Path.Combine(cacheRoot, "monster", "nested")), Is.False);
+        });
+    }
+
+    /// <summary>
+    ///     验证编辑器态会直接使用全局化后的项目目录，而不会额外创建运行时缓存副本。
+    /// </summary>
+    [Test]
+    public async Task LoadAsync_Should_Use_Globalized_Res_Directory_Directly_When_Running_In_Editor()
+    {
+        CreateMonsterFiles(_resourceRoot);
+
+        var loader = CreateLoader(isEditor: true);
+        var registry = new ConfigRegistry();
+
+        await loader.LoadAsync(registry);
+
+        var table = registry.GetTable<int, MonsterConfigStub>("monster");
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(loader.CanEnableHotReload, Is.True);
+            Assert.That(loader.LoaderRootPath, Is.EqualTo(_resourceRoot));
+            Assert.That(table.Count, Is.EqualTo(2));
+            Assert.That(table.Get(2).Hp, Is.EqualTo(30));
+            Assert.That(Directory.Exists(Path.Combine(_userRoot, "config_cache")), Is.False);
+        });
+    }
+
+    /// <summary>
+    ///     验证当实例必须依赖运行时缓存时，不允许再直接启用底层文件热重载。
+    /// </summary>
+    [Test]
+    public void EnableHotReload_Should_Throw_When_Source_Root_Cannot_Be_Used_Directly()
+    {
+        var loader = CreateLoader(isEditor: false);
+
+        var exception = Assert.Throws<InvalidOperationException>(() =>
+            loader.EnableHotReload(new ConfigRegistry()));
+
+        Assert.That(exception!.Message, Does.Contain("Hot reload"));
+    }
+
+    /// <summary>
+    ///     创建一个基于临时目录映射的 Godot YAML 配置加载器。
+    /// </summary>
+    /// <param name="isEditor">是否模拟编辑器环境。</param>
+    /// <returns>已配置好的加载器实例。</returns>
+    private GodotYamlConfigLoader CreateLoader(bool isEditor)
+    {
+        return new GodotYamlConfigLoader(
+            new GodotYamlConfigLoaderOptions
+            {
+                SourceRootPath = "res://",
+                RuntimeCacheRootPath = "user://config_cache",
+                TableSources =
+                [
+                    new GodotYamlConfigTableSource(
+                        "monster",
+                        "monster",
+                        "schemas/monster.schema.json")
+                ],
+                ConfigureLoader = static loader =>
+                    loader.RegisterTable<int, MonsterConfigStub>(
+                        "monster",
+                        "monster",
+                        "schemas/monster.schema.json",
+                        static config => config.Id)
+            },
+            CreateEnvironment(isEditor));
+    }
+
+    /// <summary>
+    ///     创建一个把 <c>res://</c> 与 <c>user://</c> 映射到临时目录的测试环境。
+    /// </summary>
+    /// <param name="isEditor">是否模拟编辑器环境。</param>
+    /// <returns>测试专用环境对象。</returns>
+    private GodotYamlConfigEnvironment CreateEnvironment(bool isEditor)
+    {
+        return new GodotYamlConfigEnvironment(
+            () => isEditor,
+            path => MapGodotPath(path),
+            path =>
+            {
+                var absolutePath = MapGodotPath(path);
+                if (!Directory.Exists(absolutePath))
+                {
+                    return null;
+                }
+
+                return Directory
+                    .EnumerateFileSystemEntries(absolutePath, "*", SearchOption.TopDirectoryOnly)
+                    .Select(static entryPath => new GodotYamlConfigDirectoryEntry(
+                        Path.GetFileName(entryPath),
+                        Directory.Exists(entryPath)))
+                    .ToArray();
+            },
+            path => File.Exists(MapGodotPath(path)),
+            path => File.ReadAllBytes(MapGodotPath(path)));
+    }
+
+    /// <summary>
+    ///     创建一组最小可运行的 monster YAML 与 schema 文件。
+    /// </summary>
+    /// <param name="rootPath">目标根目录。</param>
+    private static void CreateMonsterFiles(string rootPath)
+    {
+        WriteFile(
+            rootPath,
+            "schemas/monster.schema.json",
+            """
+            {
+              "type": "object",
+              "required": ["id", "name", "hp"],
+              "properties": {
+                "id": { "type": "integer" },
+                "name": { "type": "string" },
+                "hp": { "type": "integer" }
+              }
+            }
+            """);
+        WriteFile(
+            rootPath,
+            "monster/slime.yaml",
+            """
+            id: 1
+            name: Slime
+            hp: 10
+            """);
+        WriteFile(
+            rootPath,
+            "monster/goblin.yml",
+            """
+            id: 2
+            name: Goblin
+            hp: 30
+            """);
+        WriteFile(
+            rootPath,
+            "monster/notes.txt",
+            "ignored");
+        WriteFile(
+            rootPath,
+            "monster/nested/ghost.yaml",
+            """
+            id: 3
+            name: Ghost
+            hp: 99
+            """);
+    }
+
+    /// <summary>
+    ///     把逻辑相对路径写入指定根目录。
+    /// </summary>
+    /// <param name="rootPath">目标根目录。</param>
+    /// <param name="relativePath">相对文件路径。</param>
+    /// <param name="content">文件内容。</param>
+    private static void WriteFile(string rootPath, string relativePath, string content)
+    {
+        var fullPath = Path.Combine(rootPath, relativePath.Replace('/', Path.DirectorySeparatorChar));
+        var directoryPath = Path.GetDirectoryName(fullPath);
+        if (!string.IsNullOrWhiteSpace(directoryPath))
+        {
+            Directory.CreateDirectory(directoryPath);
+        }
+
+        File.WriteAllText(fullPath, content);
+    }
+
+    /// <summary>
+    ///     将测试中的 Godot 路径映射到本地临时目录。
+    /// </summary>
+    /// <param name="path">Godot 路径或普通路径。</param>
+    /// <returns>映射后的绝对路径。</returns>
+    private string MapGodotPath(string path)
+    {
+        if (path.StartsWith("res://", StringComparison.Ordinal))
+        {
+            return Path.Combine(
+                _resourceRoot,
+                path["res://".Length..].Replace('/', Path.DirectorySeparatorChar));
+        }
+
+        if (path.StartsWith("user://", StringComparison.Ordinal))
+        {
+            return Path.Combine(
+                _userRoot,
+                path["user://".Length..].Replace('/', Path.DirectorySeparatorChar));
+        }
+
+        return path;
+    }
+
+    /// <summary>
+    ///     最小 monster 配置桩类型。
+    /// </summary>
+    private sealed class MonsterConfigStub
+    {
+        /// <summary>
+        ///     主键。
+        /// </summary>
+        public int Id { get; init; }
+
+        /// <summary>
+        ///     名称。
+        /// </summary>
+        public string Name { get; init; } = string.Empty;
+
+        /// <summary>
+        ///     生命值。
+        /// </summary>
+        public int Hp { get; init; }
+    }
+}

GFramework.Godot.Tests/GFramework.Godot.Tests.csproj

@@ -18,6 +18,8 @@
 
     <ItemGroup>
         <ProjectReference Include="..\GFramework.Godot\GFramework.Godot.csproj"/>
+        <ProjectReference Include="..\GFramework.Game.Abstractions\GFramework.Game.Abstractions.csproj"/>
+        <ProjectReference Include="..\GFramework.Core.Abstractions\GFramework.Core.Abstractions.csproj"/>
     </ItemGroup>
 
 </Project>

GFramework.Godot/Config/GodotYamlConfigLoader.cs

@@ -0,0 +1,468 @@
+using System.IO;
+using GFramework.Core.Abstractions.Events;
+using GFramework.Game.Abstractions.Config;
+using GFramework.Game.Config;
+using GFramework.Godot.Extensions;
+
+namespace GFramework.Godot.Config;
+
+/// <summary>
+///     为 Godot 运行时提供 YAML 配置加载适配层。
+///     编辑器态优先直接把项目目录交给 <see cref="YamlConfigLoader" />，
+///     导出态则把显式声明的 YAML 与 schema 文本同步到运行时缓存目录后再加载。
+/// </summary>
+public sealed class GodotYamlConfigLoader : IConfigLoader
+{
+    private readonly GodotYamlConfigEnvironment _environment;
+    private readonly YamlConfigLoader _loader;
+    private readonly GodotYamlConfigLoaderOptions _options;
+
+    /// <summary>
+    ///     使用指定选项创建一个 Godot YAML 配置加载器。
+    /// </summary>
+    /// <param name="options">加载器初始化选项。</param>
+    public GodotYamlConfigLoader(GodotYamlConfigLoaderOptions options)
+        : this(options, GodotYamlConfigEnvironment.Default)
+    {
+    }
+
+    internal GodotYamlConfigLoader(
+        GodotYamlConfigLoaderOptions options,
+        GodotYamlConfigEnvironment environment)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+        ArgumentNullException.ThrowIfNull(environment);
+
+        if (string.IsNullOrWhiteSpace(options.SourceRootPath))
+        {
+            throw new ArgumentException("SourceRootPath cannot be null or whitespace.", nameof(options));
+        }
+
+        if (string.IsNullOrWhiteSpace(options.RuntimeCacheRootPath))
+        {
+            throw new ArgumentException("RuntimeCacheRootPath cannot be null or whitespace.", nameof(options));
+        }
+
+        _options = options;
+        _environment = environment;
+        LoaderRootPath = ResolveLoaderRootPath();
+        _loader = new YamlConfigLoader(LoaderRootPath);
+        options.ConfigureLoader?.Invoke(_loader);
+    }
+
+    /// <summary>
+    ///     获取配置源根目录。
+    /// </summary>
+    public string SourceRootPath => _options.SourceRootPath;
+
+    /// <summary>
+    ///     获取运行时缓存根目录。
+    /// </summary>
+    public string RuntimeCacheRootPath => _options.RuntimeCacheRootPath;
+
+    /// <summary>
+    ///     获取底层 <see cref="YamlConfigLoader" /> 实际使用的普通文件系统根目录。
+    /// </summary>
+    public string LoaderRootPath { get; }
+
+    /// <summary>
+    ///     获取底层 <see cref="YamlConfigLoader" /> 实例。
+    ///     调用方可继续在该实例上追加注册表定义或读取注册数量。
+    /// </summary>
+    public YamlConfigLoader Loader => _loader;
+
+    /// <summary>
+    ///     获取一个值，指示当前实例是否可直接针对源目录启用热重载。
+    /// </summary>
+    public bool CanEnableHotReload => UsesSourceDirectoryDirectly(SourceRootPath);
+
+    /// <inheritdoc />
+    public async Task LoadAsync(IConfigRegistry registry, CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(registry);
+
+        if (!CanEnableHotReload)
+        {
+            SynchronizeRuntimeCache(cancellationToken);
+        }
+
+        await _loader.LoadAsync(registry, cancellationToken);
+    }
+
+    /// <summary>
+    ///     在当前环境允许的情况下启用底层 YAML 热重载。
+    /// </summary>
+    /// <param name="registry">要被热重载更新的配置注册表。</param>
+    /// <param name="options">热重载选项；为空时使用默认值。</param>
+    /// <returns>用于停止监听的注销句柄。</returns>
+    public IUnRegister EnableHotReload(
+        IConfigRegistry registry,
+        YamlConfigHotReloadOptions? options = null)
+    {
+        ArgumentNullException.ThrowIfNull(registry);
+
+        if (!CanEnableHotReload)
+        {
+            throw new InvalidOperationException(
+                "Hot reload is only available when the source root can be accessed as a normal filesystem directory.");
+        }
+
+        return _loader.EnableHotReload(registry, options);
+    }
+
+    private string ResolveLoaderRootPath()
+    {
+        if (UsesSourceDirectoryDirectly(SourceRootPath))
+        {
+            return EnsureAbsolutePath(SourceRootPath, nameof(GodotYamlConfigLoaderOptions.SourceRootPath));
+        }
+
+        return EnsureAbsolutePath(RuntimeCacheRootPath, nameof(GodotYamlConfigLoaderOptions.RuntimeCacheRootPath));
+    }
+
+    private bool UsesSourceDirectoryDirectly(string sourceRootPath)
+    {
+        if (!sourceRootPath.IsGodotPath())
+        {
+            return true;
+        }
+
+        if (sourceRootPath.IsUserPath())
+        {
+            return true;
+        }
+
+        return sourceRootPath.IsResPath() && _environment.IsEditor();
+    }
+
+    private void SynchronizeRuntimeCache(CancellationToken cancellationToken)
+    {
+        foreach (var group in _options.TableSources
+                     .GroupBy(static source => NormalizeRelativePath(source.ConfigRelativePath),
+                         StringComparer.Ordinal))
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+
+            var representative = group.First();
+            var sourceDirectoryPath = CombinePath(SourceRootPath, representative.ConfigRelativePath);
+            var targetDirectoryPath = CombineAbsolutePath(LoaderRootPath, representative.ConfigRelativePath);
+
+            ResetDirectory(targetDirectoryPath);
+            CopyYamlFilesInDirectory(
+                representative.TableName,
+                sourceDirectoryPath,
+                targetDirectoryPath,
+                cancellationToken);
+        }
+
+        foreach (var group in _options.TableSources
+                     .Where(static source => !string.IsNullOrEmpty(source.SchemaRelativePath))
+                     .GroupBy(static source => NormalizeRelativePath(source.SchemaRelativePath!),
+                         StringComparer.Ordinal))
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+
+            var representative = group.First();
+            var sourceSchemaPath = CombinePath(SourceRootPath, representative.SchemaRelativePath!);
+            var targetSchemaPath = CombineAbsolutePath(LoaderRootPath, representative.SchemaRelativePath!);
+
+            CopySingleFile(
+                representative.TableName,
+                sourceSchemaPath,
+                targetSchemaPath,
+                ConfigLoadFailureKind.SchemaFileNotFound,
+                ConfigLoadFailureKind.SchemaReadFailed);
+        }
+    }
+
+    private void CopyYamlFilesInDirectory(
+        string tableName,
+        string sourceDirectoryPath,
+        string targetDirectoryPath,
+        CancellationToken cancellationToken)
+    {
+        var entries = _environment.EnumerateDirectory(sourceDirectoryPath);
+        if (entries == null)
+        {
+            throw CreateConfigLoadException(
+                ConfigLoadFailureKind.ConfigDirectoryNotFound,
+                tableName,
+                $"Config directory '{DescribePath(sourceDirectoryPath)}' was not found while preparing the Godot runtime cache.",
+                configDirectoryPath: DescribePath(sourceDirectoryPath));
+        }
+
+        Directory.CreateDirectory(targetDirectoryPath);
+
+        foreach (var entry in entries)
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+
+            if (entry.IsDirectory || entry.Name is "." or ".." || entry.Name.StartsWith(".", StringComparison.Ordinal))
+            {
+                continue;
+            }
+
+            if (!IsYamlFile(entry.Name))
+            {
+                continue;
+            }
+
+            var sourceFilePath = CombinePath(sourceDirectoryPath, entry.Name);
+            var targetFilePath = Path.Combine(targetDirectoryPath, entry.Name);
+            CopySingleFile(
+                tableName,
+                sourceFilePath,
+                targetFilePath,
+                ConfigLoadFailureKind.ConfigFileReadFailed,
+                ConfigLoadFailureKind.ConfigFileReadFailed,
+                configDirectoryPath: DescribePath(sourceDirectoryPath),
+                yamlPath: DescribePath(sourceFilePath));
+        }
+    }
+
+    private void CopySingleFile(
+        string tableName,
+        string sourceFilePath,
+        string targetAbsolutePath,
+        ConfigLoadFailureKind missingFailureKind,
+        ConfigLoadFailureKind readFailureKind,
+        string? configDirectoryPath = null,
+        string? yamlPath = null)
+    {
+        if (!_environment.FileExists(sourceFilePath))
+        {
+            var missingMessage = missingFailureKind == ConfigLoadFailureKind.SchemaFileNotFound
+                ? $"Schema file '{DescribePath(sourceFilePath)}' was not found while preparing the Godot runtime cache."
+                : $"Config file '{DescribePath(sourceFilePath)}' was not found while preparing the Godot runtime cache.";
+
+            throw CreateConfigLoadException(
+                missingFailureKind,
+                tableName,
+                missingMessage,
+                configDirectoryPath: configDirectoryPath,
+                yamlPath: missingFailureKind == ConfigLoadFailureKind.SchemaFileNotFound
+                    ? null
+                    : yamlPath ?? DescribePath(sourceFilePath),
+                schemaPath: missingFailureKind == ConfigLoadFailureKind.SchemaFileNotFound
+                    ? DescribePath(sourceFilePath)
+                    : null);
+        }
+
+        try
+        {
+            var parentDirectory = Path.GetDirectoryName(targetAbsolutePath);
+            if (!string.IsNullOrWhiteSpace(parentDirectory))
+            {
+                Directory.CreateDirectory(parentDirectory);
+            }
+
+            File.WriteAllBytes(targetAbsolutePath, _environment.ReadAllBytes(sourceFilePath));
+        }
+        catch (Exception exception)
+        {
+            var readMessage = readFailureKind == ConfigLoadFailureKind.SchemaReadFailed
+                ? $"Failed to copy schema file '{DescribePath(sourceFilePath)}' into the Godot runtime cache."
+                : $"Failed to copy config file '{DescribePath(sourceFilePath)}' into the Godot runtime cache.";
+
+            throw CreateConfigLoadException(
+                readFailureKind,
+                tableName,
+                readMessage,
+                configDirectoryPath: configDirectoryPath,
+                yamlPath: readFailureKind == ConfigLoadFailureKind.SchemaReadFailed
+                    ? null
+                    : yamlPath ?? DescribePath(sourceFilePath),
+                schemaPath: readFailureKind == ConfigLoadFailureKind.SchemaReadFailed
+                    ? DescribePath(sourceFilePath)
+                    : null,
+                innerException: exception);
+        }
+    }
+
+    private void ResetDirectory(string directoryPath)
+    {
+        if (Directory.Exists(directoryPath))
+        {
+            Directory.Delete(directoryPath, recursive: true);
+        }
+
+        Directory.CreateDirectory(directoryPath);
+    }
+
+    private string EnsureAbsolutePath(string path, string optionName)
+    {
+        if (string.IsNullOrWhiteSpace(path))
+        {
+            throw new ArgumentException("Path cannot be null or whitespace.", optionName);
+        }
+
+        if (path.IsGodotPath())
+        {
+            var absolutePath = _environment.GlobalizePath(path);
+            if (string.IsNullOrWhiteSpace(absolutePath))
+            {
+                throw new InvalidOperationException(
+                    $"Path option '{optionName}' resolved to an empty absolute path. Value='{path}'.");
+            }
+
+            return absolutePath;
+        }
+
+        return Path.GetFullPath(path);
+    }
+
+    private string DescribePath(string path)
+    {
+        if (path.IsGodotPath())
+        {
+            var absolutePath = _environment.GlobalizePath(path);
+            return string.IsNullOrWhiteSpace(absolutePath) ? path : absolutePath;
+        }
+
+        return Path.GetFullPath(path);
+    }
+
+    private static string CombinePath(string rootPath, string relativePath)
+    {
+        var normalizedRelativePath = NormalizeRelativePath(relativePath);
+        if (rootPath.IsGodotPath())
+        {
+            if (rootPath.EndsWith("://", StringComparison.Ordinal))
+            {
+                return $"{rootPath}{normalizedRelativePath}";
+            }
+
+            return $"{rootPath.TrimEnd('/')}/{normalizedRelativePath}";
+        }
+
+        return Path.Combine(rootPath, normalizedRelativePath.Replace('/', Path.DirectorySeparatorChar));
+    }
+
+    private static string CombineAbsolutePath(string rootPath, string relativePath)
+    {
+        return Path.Combine(rootPath, NormalizeRelativePath(relativePath).Replace('/', Path.DirectorySeparatorChar));
+    }
+
+    private static string NormalizeRelativePath(string relativePath)
+    {
+        return relativePath.Replace('\\', '/').TrimStart('/');
+    }
+
+    private static bool IsYamlFile(string fileName)
+    {
+        return fileName.EndsWith(".yaml", StringComparison.OrdinalIgnoreCase) ||
+               fileName.EndsWith(".yml", StringComparison.OrdinalIgnoreCase);
+    }
+
+    private static ConfigLoadException CreateConfigLoadException(
+        ConfigLoadFailureKind failureKind,
+        string tableName,
+        string message,
+        string? configDirectoryPath = null,
+        string? yamlPath = null,
+        string? schemaPath = null,
+        Exception? innerException = null)
+    {
+        return new ConfigLoadException(
+            new ConfigLoadDiagnostic(
+                failureKind,
+                tableName,
+                configDirectoryPath: configDirectoryPath,
+                yamlPath: yamlPath,
+                schemaPath: schemaPath),
+            message,
+            innerException);
+    }
+}
+
+internal sealed class GodotYamlConfigEnvironment
+{
+    public GodotYamlConfigEnvironment(
+        Func<bool> isEditor,
+        Func<string, string> globalizePath,
+        Func<string, IReadOnlyList<GodotYamlConfigDirectoryEntry>?> enumerateDirectory,
+        Func<string, bool> fileExists,
+        Func<string, byte[]> readAllBytes)
+    {
+        IsEditor = isEditor ?? throw new ArgumentNullException(nameof(isEditor));
+        GlobalizePath = globalizePath ?? throw new ArgumentNullException(nameof(globalizePath));
+        EnumerateDirectory = enumerateDirectory ?? throw new ArgumentNullException(nameof(enumerateDirectory));
+        FileExists = fileExists ?? throw new ArgumentNullException(nameof(fileExists));
+        ReadAllBytes = readAllBytes ?? throw new ArgumentNullException(nameof(readAllBytes));
+    }
+
+    public static GodotYamlConfigEnvironment Default { get; } = new(
+        static () => OS.HasFeature("editor"),
+        static path => ProjectSettings.GlobalizePath(path),
+        EnumerateDirectoryCore,
+        FileExistsCore,
+        ReadAllBytesCore);
+
+    public Func<bool> IsEditor { get; }
+
+    public Func<string, string> GlobalizePath { get; }
+
+    public Func<string, IReadOnlyList<GodotYamlConfigDirectoryEntry>?> EnumerateDirectory { get; }
+
+    public Func<string, bool> FileExists { get; }
+
+    public Func<string, byte[]> ReadAllBytes { get; }
+
+    private static IReadOnlyList<GodotYamlConfigDirectoryEntry>? EnumerateDirectoryCore(string path)
+    {
+        if (!path.IsGodotPath())
+        {
+            if (!Directory.Exists(path))
+            {
+                return null;
+            }
+
+            return Directory
+                .EnumerateFileSystemEntries(path, "*", SearchOption.TopDirectoryOnly)
+                .Select(static entryPath => new GodotYamlConfigDirectoryEntry(
+                    Path.GetFileName(entryPath),
+                    Directory.Exists(entryPath)))
+                .ToArray();
+        }
+
+        using var directory = DirAccess.Open(path);
+        if (directory == null)
+        {
+            return null;
+        }
+
+        var entries = new List<GodotYamlConfigDirectoryEntry>();
+        directory.ListDirBegin();
+        while (true)
+        {
+            var name = directory.GetNext();
+            if (string.IsNullOrEmpty(name))
+            {
+                break;
+            }
+
+            entries.Add(new GodotYamlConfigDirectoryEntry(name, directory.CurrentIsDir()));
+        }
+
+        directory.ListDirEnd();
+        return entries;
+    }
+
+    private static bool FileExistsCore(string path)
+    {
+        return path.IsGodotPath()
+            ? FileAccess.FileExists(path)
+            : File.Exists(path);
+    }
+
+    private static byte[] ReadAllBytesCore(string path)
+    {
+        return path.IsGodotPath()
+            ? FileAccess.GetFileAsBytes(path)
+            : File.ReadAllBytes(path);
+    }
+}
+
+internal readonly record struct GodotYamlConfigDirectoryEntry(
+    string Name,
+    bool IsDirectory);

GFramework.Godot/Config/GodotYamlConfigLoaderOptions.cs

@@ -0,0 +1,36 @@
+using GFramework.Game.Config;
+
+namespace GFramework.Godot.Config;
+
+/// <summary>
+///     描述 Godot YAML 配置加载器的初始化约定。
+/// </summary>
+public sealed class GodotYamlConfigLoaderOptions
+{
+    /// <summary>
+    ///     获取或设置配置源根目录。
+    ///     默认值为 <c>res://</c>，表示从项目资源路径读取 YAML 与 schema 文本。
+    /// </summary>
+    public string SourceRootPath { get; init; } = "res://";
+
+    /// <summary>
+    ///     获取或设置运行时缓存根目录。
+    ///     当 <see cref="SourceRootPath" /> 在当前环境下无法直接映射为普通文件系统目录时，
+    ///     加载器会先把所需文本资产复制到这里，再交给底层 <see cref="YamlConfigLoader" />。
+    /// </summary>
+    public string RuntimeCacheRootPath { get; init; } = "user://config_cache";
+
+    /// <summary>
+    ///     获取或设置本次启动会访问到的配置表来源描述。
+    ///     Godot 导出态无法假设任意文本目录都可被枚举，因此调用方应显式提供参与本轮加载的配置目录与 schema 文件。
+    /// </summary>
+    public IReadOnlyCollection<GodotYamlConfigTableSource> TableSources { get; init; } =
+        Array.Empty<GodotYamlConfigTableSource>();
+
+    /// <summary>
+    ///     获取或设置用于配置底层 <see cref="YamlConfigLoader" /> 的回调。
+    ///     调用方通常应在这里调用生成器产出的 <c>RegisterAllGeneratedConfigTables()</c>，
+    ///     或显式注册当前场景所需的手写表定义。
+    /// </summary>
+    public Action<YamlConfigLoader>? ConfigureLoader { get; init; }
+}

GFramework.Godot/Config/GodotYamlConfigTableSource.cs

@@ -0,0 +1,56 @@
+namespace GFramework.Godot.Config;
+
+/// <summary>
+///     描述一个 Godot YAML 配置表在资源目录中的来源信息。
+/// </summary>
+public sealed class GodotYamlConfigTableSource
+{
+    /// <summary>
+    ///     初始化一个配置表来源描述。
+    /// </summary>
+    /// <param name="tableName">运行时表名称。</param>
+    /// <param name="configRelativePath">相对配置根目录的 YAML 目录。</param>
+    /// <param name="schemaRelativePath">相对配置根目录的 schema 文件路径；未启用 schema 时为空。</param>
+    public GodotYamlConfigTableSource(
+        string tableName,
+        string configRelativePath,
+        string? schemaRelativePath = null)
+    {
+        if (string.IsNullOrWhiteSpace(tableName))
+        {
+            throw new ArgumentException("Table name cannot be null or whitespace.", nameof(tableName));
+        }
+
+        if (string.IsNullOrWhiteSpace(configRelativePath))
+        {
+            throw new ArgumentException("Config relative path cannot be null or whitespace.",
+                nameof(configRelativePath));
+        }
+
+        if (schemaRelativePath != null && string.IsNullOrWhiteSpace(schemaRelativePath))
+        {
+            throw new ArgumentException(
+                "Schema relative path cannot be empty or whitespace when provided.",
+                nameof(schemaRelativePath));
+        }
+
+        TableName = tableName;
+        ConfigRelativePath = configRelativePath;
+        SchemaRelativePath = schemaRelativePath;
+    }
+
+    /// <summary>
+    ///     获取运行时表名称。
+    /// </summary>
+    public string TableName { get; }
+
+    /// <summary>
+    ///     获取相对配置根目录的 YAML 目录路径。
+    /// </summary>
+    public string ConfigRelativePath { get; }
+
+    /// <summary>
+    ///     获取相对配置根目录的 schema 文件路径；未启用 schema 校验时为空。
+    /// </summary>
+    public string? SchemaRelativePath { get; }
+}

GFramework.Godot/Properties/AssemblyInfo.cs

@@ -0,0 +1,3 @@
+using System.Runtime.CompilerServices;
+
+[assembly: InternalsVisibleTo("GFramework.Godot.Tests")]

docs/zh-CN/game/config-system.md

@@ -299,6 +299,63 @@ public sealed class GameConfigHost : IDisposable
 - `InitializeAsync()` 只在首次加载完整成功后才公开运行时状态，避免半初始化对象泄漏到业务层
 - 热重载既可以在初始化时自动启用，也可以在初次加载后显式调用 `StartHotReload(...)`
 
+### Godot 文本配置桥接
+
+如果你的项目运行在 Godot，并且 YAML / schema 文本来自 `res://` 下的原始资源文件，推荐优先使用
+`GFramework.Godot.Config.GodotYamlConfigLoader`，而不是在项目侧手写一层
+“`res://` 遍历 + `user://` 缓存 + `YamlConfigLoader`”桥接代码。
+
+原因很简单：
+
+- `YamlConfigLoader` 需要普通文件系统根目录
+- Godot 编辑器内的 `res://` 可以全局化到项目目录
+- Godot 导出后若仍读取原始文本资产，通常需要先把显式声明的 YAML / schema 文件同步到运行时缓存目录
+
+`GodotYamlConfigLoader` 会按环境自动处理这两条路径：
+
+- 编辑器态：直接把 `ProjectSettings.GlobalizePath("res://...")` 交给底层 `YamlConfigLoader`
+- 导出态：把当前注册会访问到的配置目录与 schema 文件同步到 `user://` 缓存，再交给底层 `YamlConfigLoader`
+
+推荐搭配生成器元数据一起使用，这样项目不需要再自己维护一份重复的配置目录清单：
+
+```csharp
+using GFramework.Game.Abstractions.Config;
+using GFramework.Game.Config;
+using GFramework.Game.Config.Generated;
+using GFramework.Godot.Config;
+
+var registrationOptions = new GeneratedConfigRegistrationOptions
+{
+    IncludedConfigDomains = new[] { "gameplay", "ui" }
+};
+
+var tableSources = GeneratedConfigCatalog
+    .GetTablesForRegistration(registrationOptions)
+    .Select(static metadata => new GodotYamlConfigTableSource(
+        metadata.TableName,
+        metadata.ConfigRelativePath,
+        metadata.SchemaRelativePath))
+    .ToArray();
+
+var loader = new GodotYamlConfigLoader(
+    new GodotYamlConfigLoaderOptions
+    {
+        SourceRootPath = "res://",
+        RuntimeCacheRootPath = "user://config_cache",
+        TableSources = tableSources,
+        ConfigureLoader = yamlLoader => yamlLoader.RegisterAllGeneratedConfigTables(registrationOptions)
+    });
+
+var registry = new ConfigRegistry();
+await loader.LoadAsync(registry);
+```
+
+使用这条路径时，还需要注意两点：
+
+- 导出预设必须显式包含 `.yaml`、`.yml`、`.json`、`.schema.json` 等原始文本资产；否则导出包里根本没有这些文件，任何加载器都无法读取
+- 只有当源根目录可直接映射到普通文件系统目录时，`EnableHotReload(...)` 才可用；如果当前实例依赖 `user://`
+  缓存，热重载会被拒绝，而不是制造“监听了缓存目录却不反映真实源目录”的假象
+
 ### 运行时读取模板
 
 推荐不要在业务代码里直接散落字符串表名查询，而是统一依赖生成的强类型入口：