Harepacker-resurrected 热交换系统深度解析:HaCreator 与 HaRepacker 的 .img 文件实时热加载架构
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 秒)告知用户
- 保存保护:保存操作期间临时禁用监听,防止自触发重载
使用场景
- 图像编辑工作流:HaRepacker 打开的同时用 Photoshop/GIMP 编辑贴图
- 批量处理:运行脚本批量修改多个 .img 文件
- 协作编辑:多人同时编辑同一 .img 目录
- 版本控制: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 中进一步研读。