libwz is a C++23 library for reading, traversing, editing, and exporting
MapleStory .wz archive data. The core parser is implemented in native C++ and
is exposed through three public surfaces:
C++: static libraries for the parser and optional C ABI layer
Java: JNI bindings plus Java wrapper classes
JavaScript: one ESM package that uses a native Node addon in Node.js and a
WebAssembly backend when requested or selected by browser bundlers
The project is an independent clean-room reimplementation guided by the
HaRepacker/MapleLib behavior in the Harepacker-resurrected/ submodule. That
submodule is used as a reference and as a source of test data; source code is not
copied from it.
Status
This project is under active development. The parser already covers common read,
traversal, image, sound, Lua, UOL, and editing workflows, but APIs may still
change before a stable release.
Features
PKG1 .wz archive parsing with regional MapleStory keys
32-bit and 64-bit WZ version handling
Directory and image traversal
Property support for null, numeric, string, sub, canvas, vector, convex,
sound, raw, UOL, Lua, PNG, and video-like/raw data properties
UOL and canvas link resolution
Canvas/PNG export to PNG bytes or files
Sound export to raw MP3/WAV-compatible bytes or files
Lua script decoding
WZ editing and save-to-disk support in native-capable builds
C ABI layer for FFI consumers
JNI wrapper with AutoCloseable resource management
JavaScript ESM wrapper with native Node and WebAssembly backends
Requirements
Core C++ build:
CMake 3.16+
C++23 compiler with <expected> support
Git with submodule support
Optional bindings:
Java 21 and Maven for JNI/JAR builds
Node.js ^20.19.0 || >=22.12.0 for the JavaScript package
libwz is built with exceptions disabled. APIs that can fail return
wz::Result<T> (std::expected<T, wz::Error>) where practical. Check
has_value() before using a result.
Java Usage
The Java layer lives in the Maven project under java/. It wraps the JNI bridge
with ordinary Java classes such as WzFile, WzDirectory, WzImage, and
WzImageProperty.
Build the JNI library and package the JAR locally:
var object = file.getObjectFromPath("Character/00002000.img/info");if (object != null) { System.out.println(object.getName());}
WzFile owns the native file handle and implements AutoCloseable; use
try-with-resources. Objects returned from a file, directory, image, or property
are borrowed wrappers and become invalid after the owning file is closed.
JavaScript Usage
The JavaScript package is ESM-only. Its root entry exports the same wrapper
classes for native Node and WebAssembly:
In Node.js, the package tries to install the native addon when imported. Calling
init() is still supported and is a no-op when native loading succeeded.
import { init, MapleVersion, ParseStatus, WzFile } from 'libwz'await init()using file = new WzFile('Character.wz', MapleVersion.GMS)const status = file.parseWzFile()if (status !== ParseStatus.SUCCESS) { throw new Error(`parse failed: ${status}`)}const root = file.getWzDirectory()for (const image of root.wzImages()) { image.parseImage() console.log(image.getName())
JavaScript wrappers support explicit resource management through
[Symbol.dispose]() and close(). If your runtime does not support using,
write the cleanup explicitly:
import { MapleVersion, WzFile } from 'libwz'const bytes = new Uint8Array(await fileInput.files[0].arrayBuffer())using file = WzFile.fromBytes('Character.wz', bytes, MapleVersion.GMS)file.parseWzFile()
For large browser files, use callback-backed input so the Wasm backend can read
ranges without copying the whole file. In a Worker, FileReaderSync is one
simple way to implement the callback:
The C++ core is built with exceptions and RTTI disabled.
C++ failure paths use wz::Result<T> where possible.
Java and JavaScript wrappers translate native failures to Java exceptions or
JavaScript errors at the binding boundary.
JavaScript saveToDisk() and path-based file APIs depend on the active
backend's runtime capabilities. The WebAssembly backend supports host paths in
Node.js through a mounted filesystem; browser code should prefer bytes or
callback-backed input.
Published Java artifacts are intended to bundle native libraries for Windows
x86_64, Linux x86_64, and macOS ARM64 through the GitHub Actions release
workflow.
The npm package publishes dist/index.js, dist/index.d.ts,
dist/libwz.js, and dist/libwz.wasm.
License
libwz is licensed under the MIT License. The Harepacker-resurrected/ submodule
(test data reference, not part of libwz source) has its own licenses; see that
submodule for details.