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

GFramework.Game/Config/YamlConfigLoader.cs

@@ -13,6 +13,9 @@ namespace GFramework.Game.Config;
 /// </summary>
 public sealed class YamlConfigLoader : IConfigLoader
 {
+    private const string DefaultHotReloadUnavailableMessage =
+        "Hot reload is not available for the current loader configuration.";
+
     private const string RootPathCannotBeNullOrWhiteSpaceMessage = "Root path cannot be null or whitespace.";
     private const string TableNameCannotBeNullOrWhiteSpaceMessage = "Table name cannot be null or whitespace.";
     private const string RelativePathCannotBeNullOrWhiteSpaceMessage = "Relative path cannot be null or whitespace.";
@@ -22,7 +25,9 @@ public sealed class YamlConfigLoader : IConfigLoader
 
     private static readonly TimeSpan DefaultHotReloadDebounceDelay = TimeSpan.FromMilliseconds(200);
 
+    private readonly Func<bool> _canEnableHotReload;
     private readonly IDeserializer _deserializer;
+    private readonly string _hotReloadUnavailableMessage;
 
     private readonly Dictionary<string, IReadOnlyCollection<string>> _lastSuccessfulDependencies =
         new(StringComparer.Ordinal);
@@ -36,13 +41,38 @@ public sealed class YamlConfigLoader : IConfigLoader
     /// <param name="rootPath">配置根目录。</param>
     /// <exception cref="ArgumentException">当 <paramref name="rootPath" /> 为空时抛出。</exception>
     public YamlConfigLoader(string rootPath)
+        : this(rootPath, null, null)
+    {
+    }
+
+    /// <summary>
+    ///     使用指定配置根目录与热重载可用性守卫创建 YAML 配置加载器。
+    /// </summary>
+    /// <param name="rootPath">配置根目录。</param>
+    /// <param name="canEnableHotReload">
+    ///     用于判断当前实例是否允许启用热重载的委托。
+    ///     宿主适配层可借此把额外的文件系统前置条件下沉到底层加载器，避免公开实例被绕过时启用错误监听目标。
+    /// </param>
+    /// <param name="hotReloadUnavailableMessage">
+    ///     当 <paramref name="canEnableHotReload" /> 返回 <see langword="false" /> 时抛出的异常消息；
+    ///     为空时使用默认消息。
+    /// </param>
+    /// <exception cref="ArgumentException">当 <paramref name="rootPath" /> 为空时抛出。</exception>
+    internal YamlConfigLoader(
+        string rootPath,
+        Func<bool>? canEnableHotReload,
+        string? hotReloadUnavailableMessage)
     {
         if (string.IsNullOrWhiteSpace(rootPath))
         {
             throw new ArgumentException(RootPathCannotBeNullOrWhiteSpaceMessage, nameof(rootPath));
         }
 
         _rootPath = rootPath;
+        _canEnableHotReload = canEnableHotReload ?? (() => true);
+        _hotReloadUnavailableMessage = string.IsNullOrWhiteSpace(hotReloadUnavailableMessage)
+            ? DefaultHotReloadUnavailableMessage
+            : hotReloadUnavailableMessage;
         _deserializer = new DeserializerBuilder()
             .WithNamingConvention(CamelCaseNamingConvention.Instance)
             .IgnoreUnmatchedProperties()
@@ -136,6 +166,7 @@ public IUnRegister EnableHotReload(
     {
         ArgumentNullException.ThrowIfNull(registry);
         options ??= new YamlConfigHotReloadOptions();
+        EnsureHotReloadCanBeEnabled();
         if (options.DebounceDelay < TimeSpan.Zero)
         {
             throw new ArgumentOutOfRangeException(
@@ -154,6 +185,19 @@ public IUnRegister EnableHotReload(
             options.DebounceDelay);
     }
 
+    private void EnsureHotReloadCanBeEnabled()
+    {
+        if (_canEnableHotReload())
+        {
+            return;
+        }
+
+        // Host adapters can attach additional filesystem constraints to the loader instance.
+        // Enforcing the guard here prevents callers from bypassing the adapter by invoking
+        // EnableHotReload directly on the exposed loader reference.
+        throw new InvalidOperationException(_hotReloadUnavailableMessage);
+    }
+
     private void UpdateLastSuccessfulDependencies(IEnumerable<YamlTableLoadResult> loadedTables)
     {
         _lastSuccessfulDependencies.Clear();

GFramework.Game/Properties/AssemblyInfo.cs

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