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; /// /// 为 Godot 运行时提供 YAML 配置加载适配层。 /// 编辑器态优先直接把项目目录交给 , /// 导出态则把显式声明的 YAML 与 schema 文本同步到运行时缓存目录后再加载。 /// public sealed class GodotYamlConfigLoader : IConfigLoader { private readonly GodotYamlConfigEnvironment _environment; private readonly YamlConfigLoader _loader; private readonly GodotYamlConfigLoaderOptions _options; /// /// 使用指定选项创建一个 Godot YAML 配置加载器。 /// /// 加载器初始化选项。 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); } /// /// 获取配置源根目录。 /// public string SourceRootPath => _options.SourceRootPath; /// /// 获取运行时缓存根目录。 /// public string RuntimeCacheRootPath => _options.RuntimeCacheRootPath; /// /// 获取底层 实际使用的普通文件系统根目录。 /// public string LoaderRootPath { get; } /// /// 获取底层 实例。 /// 调用方可继续在该实例上追加注册表定义或读取注册数量。 /// public YamlConfigLoader Loader => _loader; /// /// 获取一个值,指示当前实例是否可直接针对源目录启用热重载。 /// public bool CanEnableHotReload => UsesSourceDirectoryDirectly(SourceRootPath); /// public async Task LoadAsync(IConfigRegistry registry, CancellationToken cancellationToken = default) { ArgumentNullException.ThrowIfNull(registry); if (!CanEnableHotReload) { SynchronizeRuntimeCache(cancellationToken); } await _loader.LoadAsync(registry, cancellationToken); } /// /// 在当前环境允许的情况下启用底层 YAML 热重载。 /// /// 要被热重载更新的配置注册表。 /// 热重载选项;为空时使用默认值。 /// 用于停止监听的注销句柄。 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 isEditor, Func globalizePath, Func?> enumerateDirectory, Func fileExists, Func 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 IsEditor { get; } public Func GlobalizePath { get; } public Func?> EnumerateDirectory { get; } public Func FileExists { get; } public Func ReadAllBytes { get; } private static IReadOnlyList? 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(); 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);