package
MapleStory wz parser.
npm install libwzGitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
Tagged topics.
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:
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.
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.
.wz archive parsing with regional MapleStory keysAutoCloseable resource managementCore C++ build:
<expected> supportOptional bindings:
^20.19.0 || >=22.12.0 for the JavaScript package| Path | Purpose |
|---|---|
include/wz/ | Public C++ headers |
include/wz/Properties/ | Concrete WZ property types |
include/wz/wz_api.h | C ABI header |
src/ | C++ implementation |
src/capi/ | C ABI implementation |
src/jni/ | JNI native bridge |
src/node/ | Node-API / emnapi binding |
java/ | Java wrapper and Maven project |
js/ | TypeScript JavaScript wrapper source |
tests/ | C++ and JavaScript tests |
Clone with submodules:
git clone --recurse-submodules https://github.com/toyobayashi/libwz.git
cd libwzBuild the core C++ libraries:
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config ReleaseBuild with JNI enabled:
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_JNI=ON
cmake --build build --config ReleaseBuild the JavaScript package from source:
npm install
npm run buildBuild the WebAssembly artifacts:
npm install
npm run build:wasmRun tests:
cmake -S . -B build -DBUILD_TESTS=ON
cmake --build build
ctest --test-dir build
npm testThe parser tests use sample WZ files from
Harepacker-resurrected/UnitTest_WzFile/WzFiles/.
Include the public headers from include/wz/ and link the wz target.
#include <iostream>
#include "wz/WzFile.h"
#include "wz/WzImage.h"
#include "wz/Properties/WzCanvasProperty.h"
int main() {
wz::WzFile file("Character.wz", wz::WzMapleVersion::GMS);
if (file.ParseWzFile() != wz::WzFileParseStatus::Success) {
std::cerr << "failed to parse WZ file\n";
return 1;
}
auto* root = file.GetWzDirectory();
if (root == nullptr) return 1;
Open a file when you already know the encrypted version or IV:
wz::WzFile byVersion("Character.wz", 87, wz::WzMapleVersion::GMS);
wz::WzFile byIv("Character.wz", std::array<uint8_t, 4>{0x4D, 0x23, 0xC7, 0x2B});Look up an object by WZ path:
wz::WzObject* obj = file.GetObjectFromPath("Character/00002000.img/info");
if (obj != nullptr) {
std::cout << obj->FullPath() << "\n";
}Export a canvas or PNG property:
auto* image = root->GetImageByName("00002000.img");
if (image != nullptr && image->ParseImage().has_value()) {
auto* prop = image->GetFromPath("stand/0");
if (prop != nullptr && prop->PropertyType() == wz::WzPropertyType::Canvas) {
auto* canvas = static_cast<wz::WzCanvasProperty*>(prop);
auto* png = canvas->PngProperty();
if (png != nullptr) {
auto saved = png->SaveToFile
Create and save a small WZ file:
#include "wz/Properties/WzIntProperty.h"
#include "wz/Properties/WzStringProperty.h"
wz::WzFile out(87, wz::WzMapleVersion::GMS);
auto* dir = out.GetWzDirectory();
auto imageResult = dir->CreateImage("Example.img");
if (!imageResult.has_value()) return 1;
auto* image = imageResult.value();
auto added = image->AddProperty(
std::make_unique<wz::WzStringProperty
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.
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:
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_JNI=ON
cmake --build build --config Release
cd java
mvn packageWhen consuming a published artifact, the Maven coordinates are:
<dependency>
<groupId>io.github.toyobayashi</groupId>
<artifactId>libwz</artifactId>
<version>0.1.0</version>
</dependency>Open and traverse a WZ file:
import io.github.toyobayashi.libwz.WzDirectory;
import io.github.toyobayashi.libwz.WzEnums.MapleVersion;
import io.github.toyobayashi.libwz.WzEnums.ParseStatus;
import io.github.toyobayashi.libwz.WzFile;
import io.github.toyobayashi.libwz.WzImage;
public final class ReadWz {
public static void main(String[] args) {
try (WzFile file = new WzFile("Character.wz", MapleVersion.GMS)) {
ParseStatus status = file.parseWzFile();
if (status != ParseStatus.SUCCESS) {
throw new IllegalStateException("parse failed: " +
Read properties and export a canvas:
import io.github.toyobayashi.libwz.WzCanvasProperty;
import io.github.toyobayashi.libwz.WzFile;
import io.github.toyobayashi.libwz.WzImage;
import io.github.toyobayashi.libwz.WzImageProperty;
import static io.github.toyobayashi.libwz.WzEnums.MapleVersion.GMS;
try (WzFile file = new WzFile("Character.wz", GMS)) {
file.parseWzFile();
WzImage image = file.getWzDirectory().getImageByName("00002000.img");
image.parseImage();
WzImageProperty prop = image.getFromPath("stand/0");
if (prop instanceof
Look up by WZ path:
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.
The JavaScript package is ESM-only. Its root entry exports the same wrapper classes for native Node and WebAssembly:
import {
init,
MapleVersion,
ParseStatus,
WzBinaryProperty,
WzCanvasProperty,
WzFile,
getWzBindingType
} from 'libwz'When installed from npm after publication:
npm install libwzWhen using the repository directly:
npm install
npm run buildIn 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:
const file = new WzFile('Character.wz', MapleVersion.GMS)
try {
file.parseWzFile()
console.log(file.getWzDirectory()?.getName())
} finally {
file.close()
}Force WebAssembly in Node.js:
import { init, MapleVersion, WzFile, getWzBindingType } from 'libwz'
await init({ forceWasm: true })
console.log(getWzBindingType()) // "wasm"
using file = new WzFile('Character.wz', MapleVersion.GMS)
file.parseWzFile()Pass a custom Wasm URL when a bundler or CDN serves libwz.wasm from another
location:
await init(new URL('./assets/libwz.wasm', import.meta.url))Open from bytes:
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:
const reader = new FileReaderSync()
using file = WzFile.fromBlobSource(
'Character.wz',
blob.size,
MapleVersion.GMS,
(offset, length, destination) => {
const start = Number(offset)
const end = start + Number(length)
const bytes = new Uint8Array(
reader.readAsArrayBuffer(blob.slice(start, end))
)
if (destination !== undefined) {
destination.set(bytes)
return
}
Traverse and inspect properties:
const image = file.getWzDirectory()?.getImageByName('00002000.img')
image?.parseImage()
for (const prop of image?.wzProperties() ?? []) {
console.log(prop.getName(), prop.getPropertyType())
}
const info = image?.getFromPath('info')
const name = info?.getChildByName('name')?.getString()Export images and sounds:
const canvas = image?.getFromPath('stand/0')
if (canvas instanceof WzCanvasProperty) {
canvas.saveToFile('stand-0.png')
const png = canvas.getPngProperty()
console.log(png?.getWidth(), png?.getHeight())
}const sound = image?.getFromPath('sound')
if (sound instanceof WzBinaryProperty) {
sound.saveToFile('sound.mp3')
}| CMake option | Default | Description |
|---|---|---|
BUILD_TESTS | ON | Build Google Test unit tests |
BUILD_CAPI | ON | Build the C ABI layer |
BUILD_JNI | OFF | Build the JNI shared library |
BUILD_WASM | OFF | Build the WebAssembly target |
| Target | Type | Description |
|---|---|---|
wz | Static library | Core C++ parser |
wz_capi | Static library | C ABI wrapper |
wz_jni | Shared library | JNI native bridge |
wz_wasm | Emscripten executable | JavaScript/Wasm artifact |
# C++
cmake -S . -B build -DBUILD_TESTS=ON
cmake --build build
ctest --test-dir build
# Java
cmake -S . -B build -DBUILD_JNI=ON
cmake --build build
(cd java && mvn test)
# JavaScript
npm run build:ts
npm run build:native
npm test
npm run test:wasmFormat and lint:
./format.sh
./lint.sh
npm run lint:jswz::Result<T> where possible.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.dist/index.js, dist/index.d.ts,
dist/libwz.js, and dist/libwz.wasm.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.
Estimated unpacked size across 3 packages.
4.9 MB
Includes dependencies.
Harepacker-resurrected/| C# reference and WZ test data submodule |