Harepacker-resurrected 热交换系统深度解析:HaCreator 与 HaRepacker 的 .img 文件实时热加载架构

原创2026-10-13 12:50:361,650 阅读
文章标签:游戏开发桌面应用开发工具图像处理

Harepacker-resurrected 热交换系统深度解析:HaCreator 与 HaRepacker 的 .img 文件实时热加载架构

导读

本文聚焦 Harepacker-resurrected 仓库中面向 .img 文件的两套热交换(Hot-Swap)系统:HaCreator 侧针对松散 .img 文件的地图素材实时刷新,以及 HaRepacker 侧针对已打开的 .img 目录的外部变更自动应用。文章以 img-hot-swap.md 为骨架,结合 HotSwapRefreshService.cs、HotSwapManager.cs、MainForm.cs 等源码实现,完整讲解架构分层、事件流转、防抖与缓存失效机制、线程安全策略及各种边界场景的解决方案。读完本文,你将掌握两套系统从文件系统事件到 UI 面板刷新的完整链路,并能理解其设计取舍与可复用的实现模式。


背景:为什么需要热交换

传统 HaCreator 直接读取 MapleStory 客户端 WZ 归档文件,数据只读、启动内存占用大。在迁移到 IMG 文件系统模式后(详见 IMG_FILESYSTEM_MIGRATION_PLAN.md 与 README.md),数据以松散 .img 文件形式存放于磁盘,不再依赖客户端安装,也便于 Git 追踪。

热交换系统正是在这一模式下诞生的实时编辑工作流:用户在 Windows 资源管理器中增删改文件后,应用无需重启即可感知变更并更新内部文件索引与 UI。整个仓库中并存两套热交换系统:

应用 目标文件 目的
HaCreator 松散 .img 文件 地图创建时的素材实时编辑
HaRepacker 松散 .img 目录 IMG 编辑时的外部变更检测

两套系统都基于 System.IO.FileSystemWatcher,但职责不同:HaCreator 侧重“索引与缓存的一致性维护 + 面板通知”,HaRepacker 侧重“自动重载 + 树视图同步 + 极简通知”。

注:本仓库中的 MapleLib 目录以 git submodule 形式引入(见 .gitmodules),当前检出中该目录为空;文档与 HaCreator/HaRepacker 源码通过 using MapleLib.Img; 引用其中类型(如 ImgFileSystemManager、ImgFileSystemDataSource、VirtualWzDirectory、ImgDirectoryWatcherService),下文涉及这些类型的文件路径均为文档所记录的子模块内路径。


Part 1:HaCreator 热交换系统(.img 文件)

1.1 系统分层架构

HaCreator 的热交换系统横跨 UI 层与数据层,事件自下而上流转:

┌───────────────────────────────────────────────────────────────────────┐
│                        UI Layer (HaCreator)                           │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────────┐  │
│  │TilePanel │ │ ObjPanel │ │LifePanel │ │BackPanel │ │ QuestEditor │  │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └──────┬──────┘  │
│       │            │            │            │              │         │
│       └────────────┴─────┬──────┴────────────┴──────────────┘         │
│                          ▼                                            │
│              ┌─────────────────────────┐                              │
│              │  HotSwapRefreshService  │ ◄── Translates events        │
│              │  (HaCreator/Wz)         │     to UI-specific           │
│              └───────────┬─────────────┘     notifications            │
└──────────────────────────┼────────────────────────────────────────────┘
                           │ CategoryIndexChanged event
┌──────────────────────────┼───────────────────────────────────────┐
│                    Data Layer (MapleLib)                         │
│              ┌───────────▼─────────────┐                         │
│              │  ImgFileSystemManager   │ ◄── Core manager with   │
│              │  (MapleLib/Img)         │     LRU cache & index   │
│              └───────────┬─────────────┘                         │
│                          │ OnImgFileChanged                      │
│              ┌───────────▼─────────────┐                         │
│              │ FileSystemWatcherService│ ◄── Monitors filesystem │
│              │  (MapleLib/Img)         │     with debouncing     │
│              └───────────┬─────────────┘                         │
│                          │                                       │
└──────────────────────────┼───────────────────────────────────────┘
                           ▼
              ┌─────────────────────────┐
              │   Windows FileSystem    │
              │   (Mob/, Npc/, Map/...) │
              └─────────────────────────┘

从源码结构看,HaCreator 的数据源遵循统一抽象接口 IDataSource,按数据来源划分为三个实现:

IDataSource (Interface)
├── ImgFileSystemDataSource (Uses ImgFileSystemManager)
├── WzFileDataSource (Legacy WZ file support)
└── HybridDataSource (IMG + WZ fallback)

其中 ImgFileSystemDataSource 是热交换能力的载体:HotSwapRefreshService.SubscribeToDataSource() 正是订阅它的 CategoryIndexChanged 事件(见 HotSwapRefreshService.cs)。

1.2 FileSystemWatcherService(MapleLib/Img)

位于数据层底部的文件系统监听组件,用 System.IO.FileSystemWatcher 监听各分类目录(Mob/、Npc/、Map/Tile/ 等)。

职责:

  • 监听分类目录中的 .img 文件变化
  • 对高频变更做防抖(默认 500ms)
  • 合并同一文件的多次事件
  • 通过 ImgFileChanged 事件上报变更详情

事件表:

事件 参数 说明
ImgFileChanged ImgFileChangedEventArgs 文件 创建/删除/修改/重命名
VersionDirectoryChanged VersionDirectoryChangedEventArgs 版本目录被增删
Error ErrorEventArgs 监听器发生错误

防抖逻辑:

File change detected → Add to pending queue → Start/reset 500ms timer
Timer expires → Process all pending changes → Group by path, take final state

防抖的意义在于:批量复制 10+ 个文件、外部工具保存时“临时文件+改名”的多步写入,都会在短时间内产生大量事件;合并到“每个路径只取最终状态”可以显著降低下游的索引更新与 UI 刷新开销。

1.3 ImgFileSystemManager(MapleLib/Img)

维护**分类索引(category index)**与 LRU 缓存的核心管理器。文档记录其关键方法:

方法 说明
EnableHotSwap() 启动所有分类的文件监听
DisableHotSwap() 停止文件监听
AddToCategoryIndex() 将文件加入分类索引
RemoveFromCategoryIndex() 从分类索引移除文件
ExistsInCategoryIndex() 检查文件是否在索引中
InvalidateCache() 从 LRU 缓存中移除文件

事件处理(OnImgFileChanged):

switch (e.ChangeType)
{
    case Created:
        AddToCategoryIndex() → Raise FileAdded

    case Deleted:
        RemoveFromCategoryIndex() → InvalidateCache() → Raise FileRemoved

    case Changed:
        // Windows quirk: sometimes reports new files as Changed
        if (!ExistsInCategoryIndex())
            AddToCategoryIndex() → Raise FileAdded  // Treat as new
        else
            InvalidateCache() → Raise FileModified

    case Renamed:
        RemoveFromCategoryIndex(oldPath) → AddToCategoryIndex(newPath)
}

关键设计是 Changed 分支的防御性判断:Windows 的 FileSystemWatcher 偶尔会把新文件上报为 Changed,因此先用 ExistsInCategoryIndex() 区分“真正的新文件”与“已有文件的修改”。

1.4 HotSwapRefreshService(HaCreator/Wz)

HotSwapRefreshService 是 HaCreator 侧热交换的编排中枢,将数据层事件翻译为面板级事件,并同步更新 WzInformationManager 的各类字典。源码(HotSwapRefreshService.cs)中定义了 6 个公开事件:TileSetChanged、ObjectSetChanged、BackgroundSetChanged、LifeDataChanged、QuestDataChanged、StringDataChanged。

事件翻译表(文档记录):

CategoryIndexChanged → Panel Event
Map/Tile/* → TileSetChanged
Map/Obj/* → ObjectSetChanged
Map/Back/* → BackgroundSetChanged
Mob/* → LifeDataChanged (Mob)
Npc/* → LifeDataChanged (Npc)
Reactor/* → LifeDataChanged (Reactor)
Quest/* → QuestDataChanged
String/* → StringDataChanged

源码中 ProcessCategoryChange() 先按小写分类名(map/mob/npc/reactor/quest/string)分流;Map 分类再按相对路径首段(tile/obj/back)细分到具体集合(见 HotSwapRefreshService.cs)。对 Quest 与 String 分类,还会根据文件名关键词进一步区分子类型(如 act/check/say,mob/npc/item/skill),并随事件参数 QuestDataType/StringDataType 下发。

InfoManager 更新规则:

  • 更新 WzInformationManager 字典(TileSets、ObjectSets、MobNameCache 等)
  • Mob/Npc 新增时:通过 LookupMobNameFromString() 从 String.wz 反查名称;查不到则回退为占位名
  • 删除时:从缓存中移除条目

以 Mob 为例(源码 HotSwapRefreshService.cs):

case AssetChangeType.Added:
case AssetChangeType.Modified:
    // Look up name from String.wz via data source
    string mobName = LookupMobNameFromString(normalizedId);
    _infoManager.MobNameCache[normalizedId] = mobName ?? $"Mob {normalizedId}";
    break;

case AssetChangeType.Removed:
    _infoManager.MobNameCache.Remove(normalizedId);
    break;

而 LookupMobNameFromString() 的实现会通过数据源读取 String/Mob.img,解析后取 mobId 节点下的 name 字符串属性(见 HotSwapRefreshService.cs);NPC 对应 String/Npc.img 的 name 与 func 字段;Reactor 则直接加载 Reactor/{id}.img 构造 ReactorInfo。

实体 ID 归一化:

磁盘文件名使用 7 位补零格式(如 0100100.img),而 String.wz 的键不带前导零(如 100100)。NormalizeEntityId() 剥离前导零以统一查询键:

"0100100" → "100100"  // File name to String.wz key
"0000001" → "1"       // Edge case handling

源码实现(HotSwapRefreshService.cs)还处理了极端情况——全部为零时归一化为 "0":

private static string NormalizeEntityId(string entityId)
{
    if (string.IsNullOrEmpty(entityId))
        return entityId;

    // Remove leading zeros but keep at least one character
    string normalized = entityId.TrimStart('0');
    return string.IsNullOrEmpty(normalized) ? "0" : normalized;
}

1.5 分类到面板的映射

分类路径 InfoManager 字典 UI 面板 ID 格式
Map/Tile/*.img TileSets TilePanel Set 名(不归一化)
Map/Obj/*.img ObjectSets ObjPanel Set 名(不归一化)
Map/Back/*.img BackgroundSets BackgroundPanel Set 名(不归一化)
Mob/*.img MobNameCache LifePanel 归一化(去前导零)
Npc/*.img NpcNameCache LifePanel 归一化(去前导零)
Reactor/*.img Reactors LifePanel 归一化(去前导零)
Quest/*.img Quest 字典 QuestEditor 原样
String/*.img 各类缓存 多个 原样

值得注意:Map/Tile、Map/Obj、Map/Back 这类集合型素材以“集合名”为键且不做 ID 归一化,因为它们的语义就是目录名(如 grassySoil);而 Mob、Npc、Reactor 以“实体 ID”为键,必须归一化才能与 String.wz 对齐。

1.6 配置常量与路径

HotSwapConstants(MapleLib/Img/HotSwapConstants.cs)

编译期常量,不写入 config.json:

常量 类型 默认值 说明
DefaultEnabled bool true 热交换总开关
DefaultDebounceMs int 500 防抖延迟(毫秒)
DefaultWatchVersions bool true 监听版本目录变化
DefaultWatchCategories bool true 监听分类目录
DefaultAutoInvalidateCache bool true 自动失效 LRU 缓存
DefaultAutoRefreshDisplayedAssets bool true 自动刷新 UI 面板
DefaultConfirmRefreshPlacedItems bool true 刷新画布已放置物件前需确认
DefaultPauseSimulatorOnAssetChange bool false 素材变化时暂停 MapSimulator
DefaultDeletedAssetBehavior enum ShowPlaceholder 已删除素材的处理方式

HaCreatorPaths(MapleLib/Img/HaCreatorPaths.cs)

常量 值
AppDataRoot %AppData%\HaCreator
DefaultConfigPath %AppData%\HaCreator\config.json
DefaultDataPath %AppData%\HaCreator\Data
VersionsFolderName versions
CustomFolderName custom

其中 versions 目录存放提取出的多个版本(如 v83/、v55/、gms_v230/),custom 存放用户自制内容;config.json 对应 HaCreator 的 HaCreatorConfig.cs 体系(文档记录其位于 MapleLib/Img 子模块内)。

1.7 线程安全

组件 机制 目的
ImgFileSystemManager._cacheLock ReaderWriterLockSlim 分类索引读写
HotSwapRefreshService._uiContext SynchronizationContext 事件编组到 UI 线程
LifePanel.RefreshMobList() .ToList() 快照 防止枚举期间集合被修改
待处理变更队列 ConcurrentQueue 线程安全的变更缓冲

UI 线程编组: 所有 UI 更新通过 SynchronizationContext.Post() 投递(源码 HotSwapRefreshService.cs):

private void RaiseOnUIThread(Action action)
{
    if (_uiContext != null)
        _uiContext.Post(_ => action(), null);
    else
        action();
}

集合快照: 为防止 “Collection was modified during enumeration” 异常,UI 刷新方法先做快照再枚举。LifePanel 的 RefreshMobSource() 用 MobNameCache.ToArray() 生成快照后排序填充列表(见 LifePanel.cs)。从源码看,NPC 与 Reactor 的刷新同样采用 ToArray() 快照模式(LifePanel.cs)。

1.8 边界情况与解决方案

1. Windows 将“创建”报告为“Changed”

问题: Windows FileSystemWatcher 有时将新文件报告为 Changed 而非 Created。 方案: 检查文件是否已存在于分类索引中,不存在则按新增处理:

case WatcherChangeTypes.Changed:
    if (!ExistsInCategoryIndex(category, relativePath))
    {
        AddToCategoryIndex(category, relativePath);
        OnCategoryIndexChanged(category, CategoryChangeType.FileAdded, relativePath);
    }
    else
    {
        InvalidateCache(category, relativePath);
        OnCategoryIndexChanged(category, CategoryChangeType.FileModified, relativePath);
    }

在 HotSwapRefreshService 侧也有对应防御:UpdateInfoManagerForTile() 等方法在 Modified 分支里先检查集合中是否已有该 Set,没有则按 Added 处理(见 HotSwapRefreshService.cs)。

2. 实体 ID 格式不一致

问题: Mob/Npc 文件名带前导零(0100100.img),String.wz 键不带(100100)。 方案: 缓存操作前归一化 ID(见上文 NormalizeEntityId())。

3. 删除再添加后名称丢失

问题: mob 文件删除后重新添加,原本从 String.wz 获得的名称丢失。 方案: 文件新增时直接从 String.wz 查名:

case AssetChangeType.Added:
    string mobName = LookupMobNameFromString(normalizedId);
    _infoManager.MobNameCache[normalizedId] = mobName ?? $"Mob {normalizedId}";

4. 快速连续变更

问题: 批量文件操作在短时间内触发大量事件。 方案: 500ms 防抖,按文件路径合并,取最终状态。

5. 刷新期间文件被锁定

问题: 外部进程可能在热交换期间锁定文件。 方案: 指数退避重试(100ms、200ms、400ms),超过最大重试次数后报错。

1.9 初始化流程

从源码看,HaCreator 的初始化遵循“先注册面板、后启动监听”的顺序。文档记录的流程如下:

HaEditor.xaml.cs
    │
    ├── tilePanel.Initialize(hcsm)
    ├── objPanel.Initialize(hcsm)
    ├── lifePanel.Initialize(hcsm)      ◄── Calls hcsm.SetLifePanel(this)
    ├── bgPanel.Initialize(hcsm)        ◄── Calls hcsm.SetBackgroundPanel(this)
    │
    └── hcsm.InitializeHotSwap()        ◄── Must be called AFTER all panels registered
            │
            ├── Create HotSwapRefreshService
            ├── Subscribe to panel events
            └── Call dataSource.EnableHotSwap()
                    │
                    └── FileSystemWatcherService.Start()

HaEditor2_Loaded 中在面板宿主初始化后调用 hcsm.InitializeHotSwap()(见 HaEditor.xaml.cs)。而 HaCreatorStateManager.InitializeHotSwap() 的实现(HaCreatorStateManager.cs)验证了文档中的顺序要求:

public void InitializeHotSwap()
{
    if (Program.DataSource is MapleLib.Img.ImgFileSystemDataSource imgDataSource)
    {
        _assetUsageTracker = new AssetUsageTracker();
        _hotSwapService = new HotSwapRefreshService(
            Program.InfoManager,
            System.Threading.SynchronizationContext.Current);

        _hotSwapService.SubscribeToDataSource(imgDataSource);

        // Subscribe panels
        tilePanel?.SubscribeToHotSwap(_hotSwapService);
        objPanel?.SubscribeToHotSwap(_hotSwapService);
        backgroundPanel?.SubscribeToHotSwap(_hotSwapService);
        lifePanel?.SubscribeToHotSwap(_hotSwapService);
    }
}

各面板通过 SetTilePanel/SetObjPanel/SetBackgroundPanel/SetLifePanel 在初始化时即调用 SubscribeToHotSwap() 完成注册(HaCreatorStateManager.cs),因此 InitializeHotSwap() 必须在其后调用,否则部分面板会收不到事件。

面板侧的事件处理同样遵循“先检查 Dispatcher.CheckAccess(),再编组到 UI 线程”的模式。以 TilePanel 为例(TilePanel.cs):OnTileSetChanged 若不在 UI 线程则 Dispatcher.BeginInvoke,随后在 HandleTileSetChange 中根据变更类型处理——Removed 且正选中该 Set 时清空预览并切换到首项,Modified 且正选中时调用 Program.InfoManager.RefreshTileSet() 重新加载并刷新选择。

QuestEditor 的热交换细节(源码 QuestEditor.xaml.cs):

  • 通过 SubscribeToHotSwap() 订阅 HotSwapRefreshService.QuestDataChanged
  • OnQuestDataChanged() 用 Dispatcher.BeginInvoke 编组到 UI 线程
  • HandleQuestDataChange() 先保存当前选中任务 ID,刷新列表后尝试恢复选择
  • RefreshQuestList() 从 Program.InfoManager.QuestInfos 全量重建任务列表
private void HandleQuestDataChange(Wz.QuestDataChangedEventArgs e)
{
    // Store current selection
    int? selectedQuestId = SelectedQuest?.Id;

    // Reload all quest data
    RefreshQuestList();

    // Restore selection if possible
    if (selectedQuestId.HasValue)
    {
        var previouslySelected = _quests.FirstOrDefault(q => q.Id == selectedQuestId.Value);
        if (previouslySelected != null)
        {
            SelectedQuest = previouslySelected;
        }
    }
}

版本目录监听: HaCreator 的初始化窗口还通过 Program.StartupManager.VersionManager.VersionsChanged 事件感知版本目录的增删(见 Initialization.cs),这是 VersionDirectoryChanged 事件在 UI 层的消费端。

素材占用跟踪: HaCreatorStateManager 同时维护 AssetUsageTracker,用于追踪画布上 BoardItem 正在使用的素材。其实现(AssetUsageTracker.cs)以 ConcurrentDictionary<string, AssetUsageInfo> 记录每个素材的弱引用用户集合,支持 RegisterAssetInUse/UnregisterAssetInUse/IsAssetInUse 与死引用清理——这为“刷新已放置物件前先确认”(DefaultConfirmRefreshPlacedItems)提供了底层支撑。

1.10 文件结构

MapleLib/Img/

文件 用途
FileSystemWatcherService.cs 带防抖的文件系统监听
HaCreatorConfig.cs 配置加载/保存
HaCreatorPaths.cs 路径常量
HotSwapConstants.cs 热交换默认值
ImgFileSystemManager.cs 带分类索引的核心管理器
VersionManager.cs 版本目录管理

HaCreator/Wz/

文件 用途
HotSwapEventArgs.cs 事件参数类(含 AssetChangeType、LifeType 枚举与各 *ChangedEventArgs)
HotSwapRefreshService.cs UI 刷新编排
AssetUsageTracker.cs 追踪 BoardItems 使用的素材
WzInformationManager.cs 素材信息字典

HaCreator/GUI/EditorPanels/

文件 热交换处理入口
TilePanel.cs OnTileSetChanged()
ObjPanel.cs OnObjectSetChanged()
BackgroundPanel.cs OnBackgroundSetChanged()
LifePanel.cs OnLifeDataChanged()

HaCreator/GUI/Quest/

文件 热交换处理入口
QuestEditor.xaml.cs OnQuestDataChanged() → RefreshQuestList()

1.11 测试场景(文档记录)

基础操作

  • [ ] 添加单个 .img 文件 → 面板中出现
  • [ ] 删除单个 .img 文件 → 面板中移除
  • [ ] 修改 .img 文件 → 面板以新内容刷新
  • [ ] 重命名 .img 文件 → 旧的移除、新的添加

Mob/Npc 专项

  • [ ] 删除 mob → 从列表消失
  • [ ] 重新添加 mob → 以 String.wz 中的正确名称出现
  • [ ] 添加新 mob(无 String.wz 条目)→ 以占位名出现

边界情况

  • [ ] 快速批量复制(10+ 文件)→ 防抖后全部出现
  • [ ] 快速“删除+添加”同一文件 → 最终状态正确
  • [ ] 文件被外部应用锁定 → 优雅报错

线程安全

  • [ ] 滚动面板时修改文件 → 不崩溃
  • [ ] 地图编辑期间增删文件 → 无枚举异常

Part 2:HaRepacker 热交换系统(.img 目录)

2.1 概述与设计理念

HaRepacker 的热交换系统监听当前已打开的 .img 目录,检测到外部修改后自动应用变更并给出短暂通知。通过 Windows 资源管理器进行的外部文件变更(增、删、改、重命名)被视为有意操作,立即反映到 UI。

重要限制: 该系统仅支持松散 .img 文件目录(提取/解包格式),不支持打包的 .wz 文件。

设计哲学

  • 信任外部变更:资源管理器中的变更即有意为之
  • 自动应用:无需用户确认,变更立即生效
  • 低调通知:短暂自动消失的消息(3 秒)告知用户
  • 保存保护:保存操作期间临时禁用监听,防止自触发重载

使用场景

  1. 图像编辑工作流:HaRepacker 打开的同时用 Photoshop/GIMP 编辑贴图
  2. 批量处理:运行脚本批量修改多个 .img 文件
  3. 协作编辑:多人同时编辑同一 .img 目录
  4. 版本控制:Git/SVN 操作修改 .img 文件

2.2 系统分层架构

┌─────────────────────────────────────────────────────────────────────┐
│                        UI Layer (HaRepacker)                         │
│  ┌──────────┐  ┌───────────────┐  ┌─────────────────────────────┐   │
│  │ MainForm │──│ TreeView(IMG) │──│ ImgFileModificationNotifier │   │
│  └────┬─────┘  └───────────────┘  └──────────────┬──────────────┘   │
│       │                                          │                   │
│       └──────────────────────────────────────────┘                   │
│                           │ OnImgFileModified event                  │
└───────────────────────────┼──────────────────────────────────────────┘
                            │
┌───────────────────────────┼──────────────────────────────────────────┐
│                     Data Layer (MapleLib)                            │
│              ┌────────────▼───────────────┐                          │
│              │ ImgDirectoryWatcherService │ ◄── Monitors opened IMG  │
│              │   (MapleLib/Img)           │     directories          │
│              └────────────┬───────────────┘                          │
│                           │                                          │
│              ┌────────────▼───────────────┐                          │
│              │   ImgFileChangeTracker     │ ◄── Tracks file hashes   │
│              │   (MapleLib/Img)           │     and timestamps       │
│              └────────────┬───────────────┘                          │
└───────────────────────────┼──────────────────────────────────────────┘
                            ▼
              ┌─────────────────────────────┐
              │     Windows FileSystem      │
              │   (*.img directories)       │
              └─────────────────────────────┘

2.3 ImgDirectoryWatcherService(MapleLib/Img)

用 System.IO.FileSystemWatcher 监听当前在 TreeView 中打开的 .img 目录。

职责:

  • 监听当前打开的 .img 目录
  • 防抖高频变更(默认 500ms)
  • 跟踪文件修改时间戳与大小
  • 检测到外部变更时抛出 ImgFileModified 事件
  • 忽略 HaRepacker 自身保存操作触发的变更

事件表:

事件 参数 说明
ImgFileModified ImgFileModifiedEventArgs .img 文件被外部修改
ImgFileDeleted ImgFileDeletedEventArgs 打开中的 .img 文件被删除
ImgFileAdded ImgFileAddedEventArgs 目录中新增 .img 文件
ImgFileRenamed ImgFileRenamedEventArgs .img 文件被重命名/移动
Error ErrorEventArgs 监听器错误

关键属性(文档记录的结构):

public class ImgDirectoryWatcherService : IDisposable
{
    // Track which directories are being watched
    Dictionary<string, FileSystemWatcher> _watchers;

    // Ignore our own save operations
    HashSet<string> _ignorePaths;

    // Debounce timers per file
    Dictionary<string, Timer> _debounceTimers;
}

2.4 ImgFileChangeTracker(MapleLib/Img)

跟踪文件状态,用于区分“有意义的变化”与“触摸操作”(touch)。

关键方法:

方法 说明
RecordFileState(path) 记录当前哈希/时间戳/大小
HasFileChanged(path) 对比当前状态与记录状态
GetChangeDetails(path) 返回变化详情(大小、内容、时间戳)
ClearTracking(path) 停止跟踪(关闭时)

变化检测类型:

public enum ImgFileChangeType
{
    None,           // No meaningful change
    SizeChanged,    // File size differs
    ContentChanged, // Content hash differs
    Deleted,        // File no longer exists
    Added,          // New file in directory
    Renamed         // File path changed
}

内容级检测依赖 MD5 哈希(对应配置常量 TrackContentHash),可以识别“大小未变但内容已改”的情况。

2.5 HotSwapManager:自动处理行为

HotSwapManager(HotSwapManager.cs)是 HaRepacker 侧的总控:持有 ImgDirectoryWatcherService 与 HotSwapNotificationBar,负责把监听事件翻译为“树视图增删改 + 通知条提示”。

启停与目录生命周期:

  • Enable():创建 ImgDirectoryWatcherService(传入 HotSwapConstants.DebounceMs 与 TrackContentHash)并订阅全部事件(HotSwapManager.cs)
  • WatchDirectory() / UnwatchDirectory():目录加载进树时开始监听、卸载时停止(HotSwapManager.cs)
  • Disable() / Dispose():清理监听器与通知条

在 MainForm 中,打开 IMG 版本目录时会为每个分类调用 _hotSwapManager?.WatchDirectory(categoryPath, node)(见 MainForm.cs);“全部卸载”时调用 UnwatchDirectory(MainForm.cs);窗体关闭时在 MainForm_FormClosing 中 Dispose()(MainForm.cs)。

事件处理(自动应用):

private void OnImgFileModified(object sender, ImgFileModifiedEventArgs e)
{
    if (!_isEnabled)
        return;

    // Auto-reload and show brief notification
    _mainForm.Dispatcher.Invoke(new Action(() =>
    {
        ReloadFile(e.FilePath);
        ShowNotification(e.FilePath, e.ChangeType);
    }));
}

新增、删除、重命名分别对应 AddFileToTree()、RemoveFileFromTree()、HandleRename(),全部经 Dispatcher.Invoke 编组到 UI 线程。删除时通过 VirtualWzDirectory.RemoveImageByPath() 清理内部集合,再从父节点的 Nodes 中移除对应 WzNode(HotSwapManager.cs);新增时若目录节点已展开则即时插入 ImgFileWzImageReference 节点,否则依赖展开时的懒加载(HotSwapManager.cs)。

典型时间线

文件被外部修改:

Timeline:
1. User opens Mob/ directory in HaRepacker
2. External tool modifies 0100100.img
3. FileSystemWatcher detects change (after 500ms debounce)
4. HotSwapManager auto-reloads the WzImage
5. Brief notification: "0100100.img reloaded" (auto-dismisses in 3s)

文件被外部删除:

Timeline:
1. User opens Item/ directory in HaRepacker
2. User deletes Consume/0200000.img via Windows Explorer
3. FileSystemWatcher detects deletion
4. HotSwapManager removes image from VirtualWzDirectory and TreeView
5. Brief notification: "0200000.img removed" (auto-dismisses in 3s)

文件被外部添加:

Timeline:
1. User opens Mob/ directory in HaRepacker
2. User copies 0100200.img into directory via Windows Explorer
3. FileSystemWatcher detects new file
4. HotSwapManager adds image to VirtualWzDirectory and TreeView
5. Brief notification: "0100200.img added" (auto-dismisses in 3s)

保存操作保护:

Timeline:
1. User clicks File > Save on VirtualWzDirectory
2. HotSwapManager calls BeginDirectorySaveOperation() to ignore directory
3. Files are saved to disk
4. EndDirectorySaveOperation() resumes watching after 500ms delay
5. No self-triggered reload occurs

MainForm 的保存代码正是这一模式(MainForm.cs):

// Handle VirtualWzDirectory (IMG filesystem)
if (node.Tag is MapleLib.Img.VirtualWzDirectory virtualDir)
{
    // Temporarily ignore file changes during save to prevent watcher from triggering reload
    _hotSwapManager?.BeginDirectorySaveOperation(virtualDir.FilesystemPath);

    try
    {
        int savedCount = virtualDir.SaveAllChangedImages();
        // Show result...
    }
    finally
    {
        _hotSwapManager?.EndDirectorySaveOperation(virtualDir.FilesystemPath);
    }
    return;
}

HotSwapManager.EndDirectorySaveOperation() 通过 UnignoreDirectoryDelayed(path, 500) 延迟 500ms 恢复监听(HotSwapManager.cs),确保写盘期间的事件不会触发自刷新;EndSaveOperation() 还会同步 RecordFileState(),让后续检测基于保存后的新状态。

2.6 HotSwapNotificationBar:极简通知条

位于工具栏下方、自动消失的状态条。源码(HotSwapNotificationBar.cs)显示其已迁移为 WPF UserControl,用 DispatcherTimer(3000ms)实现自动隐藏,并以 FileModificationInfo.DisplayMessage 生成提示文案。

行为:

  • 工具栏下方显示低调通知条
  • 3 秒后自动消失
  • 成功(新增/重载/移除)为浅绿背景
  • 错误为浅红背景
  • 无需用户交互

消息类型:

变更类型 消息格式 背景色
ContentChanged "{filename} reloaded" 绿
Deleted "{filename} removed" 绿
Added "{filename} added" 绿
Renamed "{oldname} renamed to {newname}" 绿
Error 错误信息 红

文档记录的原始 WinForms 设计(UserControl + Label + 3 秒 Timer,成功 Color.FromArgb(230,245,230)、错误 Color.FromArgb(255,230,230))在代码中以 #if false 保留,现行实现则绑定 WPF 资源 HareDangerBrush(错误)与 HareSurfaceAltBrush(成功)。

public void ShowMessage(string message, bool isError = false)
{
    if (!Dispatcher.CheckAccess()) { Dispatcher.Invoke(() => ShowMessage(message, isError)); return; }
    messageText.Text = message;
    statusBorder.Background = (System.Windows.Media.Brush)FindResource(isError ? "HareDangerBrush" : "HareSurfaceAltBrush");
    Visibility = System.Windows.Visibility.Visible;
    _hideTimer.Stop();
    _hideTimer.Start();
}

2.7 配置常量

HotSwapConstants(MapleLib/Img/HotSwapConstants.cs)

HaRepacker 热交换同样使用编译期常量(用户不可配置):

常量 类型 默认值 说明
EnableImgFileWatching bool true IMG 热交换总开关
DebounceMs int 500 防抖延迟(毫秒)
ShowNotifications bool true 显示简短通知
AutoReloadIfNoChanges bool false (遗留)现所有变更均自动应用
AutoAddNewFiles bool false (遗留)现所有新增均自动应用
TrackContentHash bool true 用 MD5 哈希做变更检测
MaxQueuedNotifications int 50 最大待处理通知数

说明: 现在所有外部文件变更都会自动应用,通知条仅显示 3 秒后自动消失的简短状态消息。MainForm.InitializeHotSwap() 会在 HotSwapConstants.EnableImgFileWatching 为 true 时调用 _hotSwapManager.Enable()(MainForm.cs),并在窗体中挂载通知条到 hotSwapHost 宿主。

2.8 实现状态

Phase 1:核心基础设施(已完成)

  • [x] ImgDirectoryWatcherService.cs - 带防抖的目录监听
  • [x] MD5 哈希变更检测
  • [x] 事件参数类(ImgFileModifiedEventArgs 等)
  • [x] 目录忽略支持(IgnoreDirectory/UnignoreDirectory)

Phase 2:UI 集成(已完成)

  • [x] HotSwapNotificationBar.cs - 3 秒自动消失的通知条
  • [x] HotSwapManager.cs - 自动应用所有外部变更
  • [x] MainForm 集成与保存保护
  • [x] VirtualWzDirectory.RemoveImage() - 文件删除时的清理
  • [x] MapleLib/Img 中的 HotSwapConstants - 编译期配置

Phase 3:高级功能(规划中)

  • [ ] 批量操作的合并通知
  • [ ] 变更历史日志
  • [ ] 自动应用变更的撤销支持

2.9 线程安全

组件 机制 目的
ImgDirectoryWatcherService._watchers lock 监听器集合访问
ImgFileChangeTracker._states ConcurrentDictionary 文件状态跟踪
ImgFileModificationNotifier SynchronizationContext 编组到 UI 线程

UI 线程编组: 所有 UI 更新通过 Control.Invoke() 编组(WinForms 经典模式):

private void OnImgFileModified(object sender, ImgFileModifiedEventArgs e)
{
    if (InvokeRequired)
    {
        Invoke(new Action(() => OnImgFileModified(sender, e)));
        return;
    }

    ShowNotification(e.FilePath, e.ChangeType);
}

实际集成中 HotSwapManager 使用 _mainForm.Dispatcher.Invoke(...) 完成同样的编组(见 2.5 节),并辅以 ConcurrentDictionary<string, WzNode> _watchedNodes 与 ConcurrentDictionary<string, bool> _unsavedChanges 记录被监听目录与未保存状态(HotSwapManager.cs)。HasUnsavedChanges()/MarkFileAsModified() 为“外部变更与本地未保存编辑冲突”提供了检测入口。

2.10 边界情况与解决方案

1. 快速连续修改

问题: 外部工具保存时可能多次写入(先临时文件后改名)。 方案: 使用 500ms 防抖,并通过检查文件是否可访问来判定“写入完成”:

private bool IsFileWriteComplete(string path)
{
    try
    {
        using (var fs = File.Open(path, FileMode.Open, FileAccess.Read, FileShare.None))
            return true;
    }
    catch (IOException)
    {
        return false; // Still being written
    }
}

2. 自触发变更

问题: HaRepacker 自身的保存操作触发监听器,导致非预期的重载。 方案: 保存期间忽略整个目录:

// In MainForm.SaveToolStripMenuItem_Click:
if (node.Tag is VirtualWzDirectory virtualDir)
{
    _hotSwapManager?.BeginDirectorySaveOperation(virtualDir.FilesystemPath);
    try
    {
        int savedCount = virtualDir.SaveAllChangedImages();
        // Show result...
    }
    finally
    {
        _hotSwapManager?.EndDirectorySaveOperation(virtualDir.FilesystemPath);
    }
}

// In ImgDirectoryWatcherService:
public void IgnoreDirectory(string directoryPath)
{
    lock (_ignorePathsLock)
    {
        _ignoreDirectories.Add(Path.GetFullPath(directoryPath));
    }
}

private bool IsPathIgnored(string filePath)
{
    // Check if file is in an ignored directory
    foreach (var ignoredDir in _ignoreDirectories)
    {
        if (fullPath.StartsWith(ignoredDir + Path.DirectorySeparatorChar))
            return true;
    }
    return false;
}

3. 网络/USB 驱动器断开

问题: 驱动器断开时 FileSystemWatcher 失效。 方案: 处理 Error 事件并优雅降级:

private void OnWatcherError(object sender, ErrorEventArgs e)
{
    var path = GetPathForWatcher(sender);
    _logger.Warn($"FileSystemWatcher error for {path}: {e.GetException().Message}");

    // Try to recreate watcher
    RecreateWatcher(path);
}

4. IMG 文件被其他进程锁定

问题: 用户尝试重载但文件被锁定。 方案: 指数退避重试,并给出明确错误:

public async Task<bool> TryReloadWithRetry(string path, int maxRetries = 3)
{
    for (int i = 0; i < maxRetries; i++)
    {
        try
        {
            ReloadImgFile(path);
            return true;
        }
        catch (IOException)
        {
            await Task.Delay(100 * (1 << i)); // 100ms, 200ms, 400ms
        }
    }

    ShowError($"Cannot reload {Path.GetFileName(path)} - file is locked by another process.");
    return false;
}

5. 监听嵌套目录结构

问题: .img 目录可能深嵌套(如 Map/Tile/set1.img/0/)。 方案: 开启 IncludeSubdirectories = true 并配合过滤:

var watcher = new FileSystemWatcher(directoryPath)
{
    NotifyFilter = NotifyFilters.LastWrite | NotifyFilters.FileName,
    Filter = "*.img",
    IncludeSubdirectories = true,
    EnableRaisingEvents = true
};

2.11 文件结构

MapleLib/Img/

文件 用途
ImgDirectoryWatcherService.cs 带防抖与目录忽略的目录监听
VirtualWzDirectory.cs 为热交换新增 RemoveImage()/RemoveImageByPath()
HotSwapConstants.cs 热交换行为的编译期常量

HaRepacker/GUI/HotSwap/

文件 用途
HotSwapManager.cs 自动应用变更、保存保护、树更新
HotSwapNotificationBar.cs 3 秒自动消失的状态消息条

HaRepacker/GUI/

文件 用途
MainForm.cs 事件接线、保存保护集成

2.12 测试场景(文档记录)

基础操作

  • [ ] 打开 .img 目录 → 开始监听
  • [ ] 关闭 .img 目录 → 停止监听
  • [ ] 外部修改 .img 文件 → 自动重载并短暂通知
  • [ ] 外部删除 .img 文件 → 自动从树中移除并通知

文件操作

  • [ ] 外部新增 .img 文件 → 自动加入树并通知
  • [ ] 外部删除 .img 文件 → 自动移除并通知
  • [ ] 外部重命名 .img 文件 → 树自动更新

保存保护

  • [ ] 保存 VirtualWzDirectory → 不触发自重载
  • [ ] 保存期间外部修改 → 保存期间变更被忽略
  • [ ] 保存完成 → 500ms 后恢复监听

边界情况

  • [ ] 快速外部保存 → 防抖后仅一条通知
  • [ ] 删除 Name 为 null 的文件 → 优雅处理
  • [ ] 网络驱动器断开 → 优雅降级
  • [ ] 深嵌套目录 → 所有变更均被检测

线程安全

  • [ ] 树导航期间外部修改 → 不崩溃
  • [ ] 多个 .img 文件同时修改 → 所有通知入队
  • [ ] 后台解析期间重载 → 正确取消

总结

两套热交换系统共享同一批基础设施(FileSystemWatcher + 500ms 防抖 + 目录忽略 + 指数退避),但在语义上刻意分化:

  • HaCreator 以 ImgFileSystemManager(分类索引 + LRU 缓存)为数据核心,HotSwapRefreshService 把 CategoryIndexChanged 翻译为面板级事件,重点保证索引、缓存与 UI 三方一致,并解决 Windows 事件上报怪癖与实体 ID 归一化问题;
  • HaRepacker 以 ImgDirectoryWatcherService + ImgFileChangeTracker(MD5 哈希)为检测核心,HotSwapManager 对树视图执行自动增删改,配合 3 秒自动消失的通知条与保存期目录忽略,实现“外部改、内部更”的零打扰工作流。

对于希望复用该模式的开发者,值得借鉴的关键设计包括:事件上报与索引状态的双重校验(防 Windows 误报)、SynchronizationContext/Dispatcher 的 UI 线程编组、集合快照防枚举异常、保存期间的目录忽略窗口,以及“懒加载 + 缓存失效”相结合的素材刷新策略。相关实现可在 HotSwapRefreshService.cs、HotSwapManager.cs 与 HotSwapNotificationBar.cs 中进一步研读。

登录后查看全文
Harepacker-resurrected