From 2338e306bf1bf8707577751e32d87f32ced40ce1 Mon Sep 17 00:00:00 2001 From: ssdfasd <2156608475@qq.com> Date: Fri, 10 Apr 2026 21:16:17 +0800 Subject: [PATCH] Add editor Assets watcher refresh loop --- ...录Watcher与自动导入刷新计划_2026-04-10.md | 186 ++++++++++++++++ editor/CMakeLists.txt | 1 + editor/src/Core/EditorWorkspace.h | 5 + editor/src/Core/ProjectAssetWatcher.cpp | 207 ++++++++++++++++++ editor/src/Core/ProjectAssetWatcher.h | 72 ++++++ 5 files changed, 471 insertions(+) create mode 100644 docs/plan/Assets目录Watcher与自动导入刷新计划_2026-04-10.md create mode 100644 editor/src/Core/ProjectAssetWatcher.cpp create mode 100644 editor/src/Core/ProjectAssetWatcher.h diff --git a/docs/plan/Assets目录Watcher与自动导入刷新计划_2026-04-10.md b/docs/plan/Assets目录Watcher与自动导入刷新计划_2026-04-10.md new file mode 100644 index 00000000..697f8be2 --- /dev/null +++ b/docs/plan/Assets目录Watcher与自动导入刷新计划_2026-04-10.md @@ -0,0 +1,186 @@ +# Assets目录Watcher与自动导入刷新计划 + +日期: 2026-04-10 + +## 1. 背景 + +当前工程的资产导入链路已经具备以下能力： + +- 打开项目时执行一次 `BootstrapProject` +- 手动执行 `Refresh / Reimport / Reimport All` +- 资源真正加载时通过 `EnsureArtifact` 懒导入 + +但它还缺少 Unity 风格里最关键的一层： + +- `Assets/` 目录发生外部变化时，编辑器能自动感知并刷新资产数据库 + +这里的“外部变化”包括但不限于： + +- 资源文件新增、删除、覆盖 +- `.meta` 文件新增、删除、修改 +- 文件夹新增、删除、重命名 +- DCC 工具重新导出同路径资源 +- `git pull`、脚本生成、资源同步工具写入 + +所以问题不在“拖进 editor 时是否导入”，而在“是否存在一条持续观察 `Assets` 目录变化并驱动资产系统刷新的通路”。 + +## 2. 现状判断 + +从当前代码结构看，这个功能是好加的，难度中等，不是重写级别： + +- `ResourceManager` 已经有 `RefreshProjectAssets()`、`ReimportProjectAsset()`、`RebuildProjectAssetCache()` +- `AssetImportService / AssetDatabase` 已经能扫描项目、维护 Source DB / Artifact DB +- editor 已经有稳定的每帧更新入口 `EditorWorkspace::Update` +- `ProjectManager` 已经支持目录树刷新 + +真正缺的是一个独立的 watcher 层，把“磁盘变化”转成“主线程上的资产刷新动作”。 + +## 3. 目标 + +第一阶段目标： + +- 编辑器运行时自动感知 `Assets/` 目录外部变化 +- 自动刷新 `AssetDatabase` lookup / metadata 状态 +- 自动刷新 Project 面板当前目录 +- 对批量拷贝和连续覆盖做去抖，不要每个文件都立刻刷新一次 + +长期目标： + +- 接近 Unity 的体验：外部改动几乎无需手动 `Refresh` +- 为后续更细粒度的增量 reimport、缩略图刷新、场景引用修复提供基础设施 + +## 4. 非目标 + +第一阶段不做： + +- 原生 Win32 `ReadDirectoryChangesW` 后台线程 watcher +- 精确到单文件的增量 reimport 调度 +- 已经加载到场景里的资源热替换 +- 资产依赖图级别的自动级联重导 +- 跨平台 watcher 后端抽象 + +这些放到后续阶段。 + +## 5. 分阶段方案 + +### Phase 1: 轮询式 Assets Watcher + +实现一个 editor 内部的 `ProjectAssetWatcher`： + +- 只监听当前项目的 `Assets/` +- 通过定时扫描递归快照检测新增/修改/删除 +- 包含普通资源文件、文件夹、`.meta` +- 通过扫描间隔 + 去抖窗口合并一批变化 +- 在主线程触发： + - `ResourceManager::RefreshProjectAssets()` + - `ProjectManager::RefreshCurrentFolder()` + +优点： + +- 实现快，风险低 +- 不引入后台线程和 Win32 句柄生命周期问题 +- 先把“自动感知外部变化”补上 + +缺点： + +- 不是事件驱动，超大项目下效率一般 +- 只能做到“自动刷新资产数据库”，还不是“精确增量重导” + +### Phase 2: 原生 Win32 Directory Watcher + +把 Phase 1 的扫描后端替换为 Win32 原生目录通知： + +- `ReadDirectoryChangesW` +- 递归监听 `Assets/` +- 把原始事件推入线程安全队列 +- 主线程消费并做路径标准化、重命名配对、去抖合并 + +目标： + +- 降低大项目轮询成本 +- 提高外部改动响应速度 + +### Phase 3: 增量 Reimport 调度 + +在 watcher 已经稳定后，再做更接近 Unity 的行为： + +- 对新增/修改的 importable asset 调用增量 reimport +- 删除时清理 lookup / orphan artifact +- 重命名时保证 `.meta` / GUID / path snapshot 同步 +- 限制一次批量刷新中的 `UnloadAll()` 影响范围 + +这个阶段需要重新审视当前 `ResourceManager::ReimportProjectAsset()` 里 `UnloadAll()` 的语义，否则外部频繁改资源会让缓存抖动太大。 + +## 6. 代码落点 + +第一阶段建议改动： + +- `editor/src/Core/ProjectAssetWatcher.h/.cpp` + - watcher 快照、扫描、去抖、变更合并 +- `editor/src/Core/EditorWorkspace.h` + - `Attach / Detach / Update` 接入 watcher 生命周期 +- `editor/CMakeLists.txt` + - 编译新 watcher 文件 + +可能的辅助修改： + +- 日志输出，方便确认自动刷新是否触发 +- 若后续需要 UI 提示，可再补 editor 事件或状态文本 + +## 7. 第一阶段执行细则 + +### 7.1 快照内容 + +每个 `Assets` 路径记录： + +- 规范化相对路径 key +- 是否目录 +- 文件大小 +- 最后写入时间 + +目录也要纳入快照，这样能检测外部新建/删除文件夹。 + +### 7.2 扫描策略 + +- 默认扫描间隔：`0.75s` +- 默认去抖窗口：`0.35s` +- 若扫描发现连续变动，则不断延长本轮刷新触发时间 +- 当一小批变化稳定下来，再统一执行一次刷新 + +### 7.3 主线程动作 + +统一执行： + +- `ResourceManager::Get().RefreshProjectAssets()` +- `context.GetProjectManager().RefreshCurrentFolder()` + +这一步先只刷新资产数据库和 Project 面板，不直接做逐文件 reimport。 + +## 8. 风险点 + +- 递归扫描频率太高会拖慢超大项目 +- 当前 `RefreshProjectAssets()` 不会主动生成所有 artifact，只是同步资产数据库 +- `ProjectManager::RefreshCurrentFolder()` 是整树重建，不是局部刷新 +- editor 内部自己改文件时，watcher 也会看到这些变化，需要接受重复刷新 + +这些都在第一阶段可控范围内。 + +## 9. 验收标准 + +第一阶段完成后，应满足： + +- 外部往 `Assets/` 复制一个资源文件，Project 面板自动出现 +- 外部删除 `Assets/` 下资源，Project 面板自动消失 +- 外部覆盖修改已有资源，资产数据库自动刷新 +- 不需要用户手点 `Refresh` +- 批量复制多个资源时，不会每个文件都触发一次明显卡顿的刷新 + +## 10. 本次执行范围 + +本次开始执行 Phase 1： + +- 先落地轮询式 watcher +- 打通 editor 生命周期 +- 先让 `Assets` 外部变更自动刷新 + +Phase 2 的 Win32 原生 watcher 放在后续迭代。 diff --git a/editor/CMakeLists.txt b/editor/CMakeLists.txt index 6bf1833c..b66fd6b5 100644 --- a/editor/CMakeLists.txt +++ b/editor/CMakeLists.txt @@ -70,6 +70,7 @@ add_executable(${PROJECT_NAME} WIN32 src/Theme.cpp src/Core/UndoManager.cpp src/Core/PlaySessionController.cpp + src/Core/ProjectAssetWatcher.cpp src/ComponentEditors/ComponentEditorRegistry.cpp src/Managers/SceneManager.cpp src/Managers/ProjectManager.cpp diff --git a/editor/src/Core/EditorWorkspace.h b/editor/src/Core/EditorWorkspace.h index abc44d82..7d5b87e0 100644 --- a/editor/src/Core/EditorWorkspace.h +++ b/editor/src/Core/EditorWorkspace.h @@ -3,6 +3,7 @@ #include "Commands/SceneCommands.h" #include "Core/IEditorContext.h" #include "Core/PlaySessionController.h" +#include "Core/ProjectAssetWatcher.h" #include "Layout/DockLayoutController.h" #include "panels/ConsolePanel.h" #include "panels/GameViewPanel.h" @@ -39,12 +40,14 @@ public: m_projectPanel->Initialize(context.GetProjectPath()); Commands::LoadStartupScene(context); m_playSessionController.Attach(context); + m_projectAssetWatcher.Attach(context.GetProjectPath()); m_dockLayoutController->Attach(context); m_panels.AttachAll(); } void Detach(IEditorContext& context) { m_playSessionController.Detach(context); + m_projectAssetWatcher.Detach(); Commands::SaveDirtySceneWithFallback(context, BuildFallbackScenePath(context)); if (m_dockLayoutController) { @@ -61,6 +64,7 @@ public: void Update(float dt) { ::XCEngine::Resources::ResourceManager::Get().UpdateAsyncLoads(); if (IEditorContext* context = m_panels.GetContext()) { + m_projectAssetWatcher.Update(*context, dt); m_playSessionController.Update(*context, dt); } m_panels.UpdateAll(dt); @@ -96,6 +100,7 @@ private: ProjectPanel* m_projectPanel = nullptr; std::unique_ptr m_dockLayoutController; PlaySessionController m_playSessionController; + ProjectAssetWatcher m_projectAssetWatcher; }; } // namespace Editor diff --git a/editor/src/Core/ProjectAssetWatcher.cpp b/editor/src/Core/ProjectAssetWatcher.cpp new file mode 100644 index 00000000..794e5870 --- /dev/null +++ b/editor/src/Core/ProjectAssetWatcher.cpp @@ -0,0 +1,207 @@ +#include "Core/ProjectAssetWatcher.h" +#include "Core/IProjectManager.h" + +#include +#include + +#include +#include +#include + +namespace XCEngine { +namespace Editor { + +namespace fs = std::filesystem; + +namespace { + +constexpr float kScanIntervalSeconds = 0.75f; +constexpr float kDebounceWindowSeconds = 0.35f; + +std::string NormalizePathKey(const fs::path& path) { + std::string key = path.lexically_normal().generic_string(); + std::transform(key.begin(), key.end(), key.begin(), [](unsigned char ch) { + return static_cast(std::tolower(ch)); + }); + return key; +} + +std::uint64_t GetFileSizeValue(const fs::path& path, bool isDirectory) { + if (isDirectory) { + return 0; + } + + std::error_code ec; + const auto fileSize = fs::file_size(path, ec); + return ec ? 0 : static_cast(fileSize); +} + +std::uint64_t GetFileWriteTimeValue(const fs::path& path) { + std::error_code ec; + const auto writeTime = fs::last_write_time(path, ec); + if (ec) { + return 0; + } + + return static_cast(writeTime.time_since_epoch().count()); +} + +} // namespace + +void ProjectAssetWatcher::Attach(const std::string& projectPath) { + RefreshProjectBinding(projectPath); +} + +void ProjectAssetWatcher::Detach() { + m_projectPath.clear(); + m_assetsRoot.clear(); + m_snapshot.clear(); + m_pendingChanges.Clear(); + m_scanCooldownSeconds = 0.0f; + m_debounceSeconds = 0.0f; + m_hasPendingRefresh = false; +} + +void ProjectAssetWatcher::Update(IEditorContext& context, float dt) { + RefreshProjectBinding(context.GetProjectPath()); + if (m_assetsRoot.empty()) { + return; + } + + m_scanCooldownSeconds -= dt; + if (m_scanCooldownSeconds <= 0.0f) { + ScanForChanges(); + m_scanCooldownSeconds = kScanIntervalSeconds; + } + + if (!m_hasPendingRefresh) { + return; + } + + m_debounceSeconds -= dt; + if (m_debounceSeconds <= 0.0f) { + FlushPendingRefresh(context); + } +} + +void ProjectAssetWatcher::RefreshProjectBinding(const std::string& projectPath) { + if (projectPath == m_projectPath) { + return; + } + + m_projectPath = projectPath; + m_assetsRoot = projectPath.empty() ? fs::path() : (fs::path(projectPath) / "Assets"); + m_snapshot.clear(); + m_pendingChanges.Clear(); + m_scanCooldownSeconds = kScanIntervalSeconds; + m_debounceSeconds = 0.0f; + m_hasPendingRefresh = false; + + if (!m_assetsRoot.empty()) { + BuildSnapshot(m_assetsRoot, m_snapshot); + } +} + +void ProjectAssetWatcher::ScanForChanges() { + Snapshot currentSnapshot; + BuildSnapshot(m_assetsRoot, currentSnapshot); + + const ChangeStats changes = DiffSnapshots(m_snapshot, currentSnapshot); + m_snapshot = std::move(currentSnapshot); + if (!changes.HasChanges()) { + return; + } + + m_pendingChanges.Accumulate(changes); + m_hasPendingRefresh = true; + m_debounceSeconds = kDebounceWindowSeconds; +} + +void ProjectAssetWatcher::FlushPendingRefresh(IEditorContext& context) { + if (!m_hasPendingRefresh) { + return; + } + + Resources::ResourceManager::Get().RefreshProjectAssets(); + context.GetProjectManager().RefreshCurrentFolder(); + + Debug::Logger::Get().Info( + Debug::LogCategory::FileSystem, + (std::string("[ProjectAssetWatcher] Refreshed project assets after external changes. added=") + + std::to_string(m_pendingChanges.added) + + " modified=" + + std::to_string(m_pendingChanges.modified) + + " removed=" + + std::to_string(m_pendingChanges.removed)).c_str()); + + m_pendingChanges.Clear(); + m_debounceSeconds = 0.0f; + m_hasPendingRefresh = false; +} + +void ProjectAssetWatcher::BuildSnapshot(const fs::path& assetsRoot, Snapshot& outSnapshot) { + outSnapshot.clear(); + + std::error_code ec; + if (assetsRoot.empty() || !fs::exists(assetsRoot, ec)) { + return; + } + + for (fs::recursive_directory_iterator it( + assetsRoot, + fs::directory_options::skip_permission_denied, + ec), + end; + !ec && it != end; + it.increment(ec)) { + const fs::path entryPath = it->path(); + + std::error_code relativeEc; + const fs::path relativePath = fs::relative(entryPath, assetsRoot, relativeEc); + if (relativeEc || relativePath.empty()) { + continue; + } + + std::error_code typeEc; + const bool isDirectory = it->is_directory(typeEc); + if (typeEc) { + continue; + } + + AssetEntryState entryState; + entryState.isDirectory = isDirectory; + entryState.fileSize = GetFileSizeValue(entryPath, isDirectory); + entryState.writeTime = GetFileWriteTimeValue(entryPath); + outSnapshot.emplace(NormalizePathKey(relativePath), entryState); + } +} + +ProjectAssetWatcher::ChangeStats ProjectAssetWatcher::DiffSnapshots( + const Snapshot& previousSnapshot, + const Snapshot& currentSnapshot) { + ChangeStats changes; + + for (const auto& [pathKey, currentState] : currentSnapshot) { + const auto previousIt = previousSnapshot.find(pathKey); + if (previousIt == previousSnapshot.end()) { + ++changes.added; + continue; + } + + if (!(previousIt->second == currentState)) { + ++changes.modified; + } + } + + for (const auto& [pathKey, previousState] : previousSnapshot) { + (void)previousState; + if (currentSnapshot.find(pathKey) == currentSnapshot.end()) { + ++changes.removed; + } + } + + return changes; +} + +} // namespace Editor +} // namespace XCEngine diff --git a/editor/src/Core/ProjectAssetWatcher.h b/editor/src/Core/ProjectAssetWatcher.h new file mode 100644 index 00000000..7c8f2ebb --- /dev/null +++ b/editor/src/Core/ProjectAssetWatcher.h @@ -0,0 +1,72 @@ +#pragma once + +#include "Core/IEditorContext.h" + +#include +#include +#include +#include + +namespace XCEngine { +namespace Editor { + +class ProjectAssetWatcher { +public: + void Attach(const std::string& projectPath); + void Detach(); + void Update(IEditorContext& context, float dt); + +private: + struct AssetEntryState { + bool isDirectory = false; + std::uint64_t fileSize = 0; + std::uint64_t writeTime = 0; + + bool operator==(const AssetEntryState& other) const { + return isDirectory == other.isDirectory && + fileSize == other.fileSize && + writeTime == other.writeTime; + } + }; + + struct ChangeStats { + std::uint32_t added = 0; + std::uint32_t modified = 0; + std::uint32_t removed = 0; + + bool HasChanges() const { + return added > 0 || modified > 0 || removed > 0; + } + + void Clear() { + added = 0; + modified = 0; + removed = 0; + } + + void Accumulate(const ChangeStats& other) { + added += other.added; + modified += other.modified; + removed += other.removed; + } + }; + + using Snapshot = std::unordered_map; + + void RefreshProjectBinding(const std::string& projectPath); + void ScanForChanges(); + void FlushPendingRefresh(IEditorContext& context); + static void BuildSnapshot(const std::filesystem::path& assetsRoot, Snapshot& outSnapshot); + static ChangeStats DiffSnapshots(const Snapshot& previousSnapshot, const Snapshot& currentSnapshot); + + std::string m_projectPath; + std::filesystem::path m_assetsRoot; + Snapshot m_snapshot; + ChangeStats m_pendingChanges; + float m_scanCooldownSeconds = 0.0f; + float m_debounceSeconds = 0.0f; + bool m_hasPendingRefresh = false; +}; + +} // namespace Editor +} // namespace XCEngine