【Java庫發布】Wzlib-java - 直接讀寫wz檔案

Joey · 發表於 2026-4-1 04:14:06

哈囉 ~ 各位又是我，我看最近好多人都使用JAVA來開發Wz編輯器，所以想說用點時間做個JAVA版的Wzlib。
怕有些人不懂，在這邊盡量白話文說明一下這是甚麼，Wzlib其實就是讀取、修改、保存Wz的核心，
HaRepacker 俗稱：血輪眼Wz編輯器，通常核心處理Wz的就是MapleLib，你把這份想像成Java版本的就可以了!

Github上有一份jwzlib，我看很久沒更新了且只有讀的功能，所以就想說做一份完整性高一點，希望能幫到大家~
移植自 C# MapleLib，讓 Java 開發者可以直接操作 .wz 二進位檔案。
未來會持續在Github上同步更新JAVA版的Wzlib。

廢話不多說，上說明 + 雲端連結載點 Src、JavaDoc、jar：
檔案操作：
✅ 開啟 .wz 檔案（支援 GMS/EMS/BMS/KMS/TMS）
✅ 自動偵測 WZ 版本號（暴力嘗試 0~2000）
✅ 修改屬性值後儲存回 .wz
✅ 64-bit WZ 格式支援（GMSv230+）
✅ 私服支援（自定義 IV + 自定義 AES UserKey）
✅ 從 ZLZ.dll 讀取 IV

圖片處理：
✅ PNG 解碼（BGRA4444/BGRA8888/RGB565/ARGB1555/DXT3/DXT5/RGB565Block）
✅ 取得 BufferedImage 直接使用
✅ 讀取圖片寬高、格式資訊

音效處理：
✅ 擷取 MP3/PCM 音效資料
✅ 取得音效長度（毫秒）

屬性類型（全部支援）：
✅ 基本型別：Null / Short / Int / Long / Float / Double / String
✅ 容器型別：SubProperty / Canvas / Vector / Convex
✅ 特殊型別：UOL / Sound / RawData / Lua / Video

工具功能：
✅ DeepClone — 完整複製屬性樹
✅ PathCache — 路徑快取加速查找
✅ XML 匯出/匯入（與 HaRepacker 格式相容）
✅ List.wz 解析與寫入

技術規格：
✅ 純 JDK 11+，零外部依賴
✅ JAR 僅 72KB
✅ 完整 Javadoc 中英文文件
✅ 從 C# MapleLib 1:1 對照移植

API 速查
✅ getFromPath("路徑") — 用路徑直接導航到任意節點
✅ getFromPathCached("路徑") — 快取版路徑查找
✅ getFullPath() — 取得節點的完整路徑
✅ getName() / setName() — 取得/設定節點名稱
✅ setValue() — 通用設定值
✅ setChanged(true) — 標記已修改（存檔用）
✅ clearPathCache() — 修改後清除快取
✅ getVersion() — 取得偵測到的版本號
✅ is64BitWzFile() — 判斷是否為 64-bit 格式
✅ getHeader() — 取得檔案標頭資訊
✅ countImages() — 計算 Image 數量
✅ isListFile() — 判斷是否為 List.wz 格式
✅ setActiveUserKey() — 設定私服金鑰
✅ resetActiveUserKey() — 重置為預設金鑰
✅ getCompressedBytes() — 取得原始壓縮資料
✅ getSoundBytes() — 取得音效原始資料
✅ getLenMs() — 取得音效長度（毫秒）
✅ encodeDecode() — Lua 腳本加解密