WzComparerR2: reading MapleStory WZ archives with a plugin system

What the tool actually extracts and compares

WzComparerR2 is described in the repository as a MapleStory online extractor, written in C# and assembled against the latest .NET 4.6.2 and .NET 8 targets. The README calls it an adventure island extractor in Chinese, and it says in the same sentence that it carries a set of unusual features: string WZ search, client comparison, equipment simulation and map simulation, among others.

That list describes the shape of the tool better than a generic label would. It is not a converter and not a repacker. It reads the WZ archive format that MapleStory uses to hold its assets, and the interesting part is what you can do once the archive is readable: search strings inside the data, compare one client build against another, and open the visual resources in dedicated plugins.

The audience follows from that. The people who need this are the ones working with MapleStory data for their own reasons, whether that is making a private server, writing a mod, studying how the client structures its assets, or simply inspecting a file that will not load. The tool is the data layer under those workflows, and the repository ships the resource files that the simulation plugins need in the CharaSimResource directory.

One thing the tool does not do is ship the game. The WZ files come from the user's own client installation, so nothing in the repository contains MapleStory content.

The plugin host is the architecture

The module list in the README is the architecture, and it splits into a core and a set of optional plugins.

The core pieces are WzComparerR2 as the main program, WzComparerR2.Common for shared classes, WzComparerR2.PluginBase for the plugin manager, and WzComparerR2.WzLib for WZ file reading. The optional plugins are WzComparerR2.LuaConsole, a Lua console, WzComparerR2.MapRender, described as a map simulator, WzComparerR2.Avatar, described as a paper doll, and WzComparerR2.Network, an online chat room.

The top level of the repository mirrors that structure exactly, with a directory per module plus a WzComparerR2.Updater directory, a Build directory, a References directory, an UpdateLogs directory, a WzComparerR2.sln solution file and an azure-pipelines.yml file. The updater module and the pipeline file together mean new builds are produced automatically rather than packaged by hand.

The plugin design has a practical consequence for anyone extending it. Because the plugin manager is a separate project, a new capability is a plugin rather than a change to the main program, and the optional plugins double as worked examples of the interface. A Lua console in particular suggests the intended extension path includes scripting, which is a faster route to a custom view than writing a full plugin.

The credits section also reveals a layering history. The WZ reading code was adapted from WzExtract and WzPatcher, and the MapRender original code came from a different source with libgif, while rendering leans on SharpDX and MonoGame, audio on BassLibrary, and video decoding on libvpx and libyuv.

Deep maintenance status changes what an adopter should expect

The README opens its status section with a warning, and it is the single most important fact for anyone considering this project. The WzComparerR2 project is now in deep maintenance status, which means only critical bugs or WZ file format breaking changes are considered for inclusion by the owner, and readers should expect slow replies to issues.

Read that literally. The project is not frozen, since the repository is not archived and the last push was on 2026-10-04, but feature work is effectively closed. The kind of change that still lands is the one where a MapleStory client update changes the archive format and the tool can no longer read it, or where an existing function breaks in a way that blocks normal use.

The release record reflects that. The most recent release is an automated build tagged ci-build, CI-Build-20261004.1, published on 2026-10-04, while the last hand named versions are v80315, labelled Wc2.1.1 from 2018-03-15, and v71010 from 2017-10-10. The tip in the README says the project will try to maintain weekly updates and that the Releases page will not carry the most stable build, with the newest version published automatically through the azure pipeline, and it links the update log directory, the roadmap wiki and the ci-build release tag as the places to look.

For a user this means the download you want is the ci-build, not a versioned tag, and the quality of any particular build is a matter of the day it was produced.

Building it on Windows from source

There is no package manager entry for this project, so building from source is the normal route, and the README gives the exact command.

git clone --recurse-submodules -j8 git://github.com/Kagamia/WzComparerR2.git

The recurse-submodules flag is not optional in practice. The repository has a .gitmodules file, and the native dependencies that the video and audio paths rely on are not stored in the main tree, so a plain clone produces a project that will not link.

The build requirements are listed separately. Compiling needs Visual Studio 2022 or higher with the .NET 8 SDK, and the runtime prerequisites differ between the two branches of the project. The 2.x line needs Windows 7 SP1 or later, .NET 4.6.2 or later, and DirectX 11, while the 1.x line needs Windows XP or later, .NET 2.0 or later, and DirectX 9.

Those two rows are worth pausing on. The 1.x line is the old .NET Framework era build with a DirectX 9 renderer, and 2.x moved to the modern .NET with a DirectX 11 renderer. Choosing between them is not a preference, it is a constraint set by the operating system and the graphics stack of the machine.

There is also a VC-LTL5 dependency listed in the credits for the native library build, which is how the project handles the runtime library mismatch that comes with shipping native code on Windows.

Where the tool is the wrong choice

Three limits are structural rather than temporary.

The first is the platform. Everything about the project assumes Windows with DirectX 11, from the Visual Studio build to the MapRender and Avatar plugins that need a GPU path. A Linux or macOS developer is not looking at a port, they are looking at a different project.

The second is the input. The tool reads the WZ archives from a MapleStory client that the user supplies. That means every user needs their own installation, and it means the value of the tool is tied to a game that the publisher updates on its own schedule. The deep maintenance status is a direct consequence of that: a format change in a live client is an external event that forces a fix, and nothing else forces work on the project.

The third is the boundary around the extracted data. The repository contains no game assets, and the simulation plugins load resources from the CharaSimResource directory rather than from the client. Reading a file for your own machine and redistributing extracted assets are different acts with different consequences, and the tool is neutral about which one you do.

A fourth caution is about expectations. With feature work closed and a CI build published every week, a bug you hit today may simply never be fixed unless it blocks reading the format, and the README says as much about issue response times.

How it differs from a generic archive reader

The alternative for inspecting a WZ file is a general purpose tool: a hex editor, a script that parses the container format, or a viewer written from scratch. Those approaches can read a file, and they can be written in a day for a simple case.

The difference is what has already been solved. WzComparerR2 ships the WZ container logic in WzComparerR2.WzLib, adapted from two earlier tools, and on top of that it has the domain knowledge: a string search that understands the string tables, a client comparison that knows how two builds of the archive differ, and simulation plugins that can present a piece of equipment or a map tile in a visual form. A hex editor gives you bytes and leaves every one of those interpretations to you.

The second difference is the direction of effort. A script you write for one question has to be redone for the next question, and questions about a game's data tend to multiply. A plugin host with a Lua console turns the second question into a script instead of a project, which is the difference between a tool that answers one question and a tool that stays useful.

The counter argument is real for a narrow job. If you need to check one field in one file, a parser script is smaller, easier to audit and does not need a Windows development environment with DirectX 11. The value of WzComparerR2 is cumulative, and it only pays off if you have several questions to ask.

MIT licensing, credits and what the repository history implies

The licence is MIT, so the code can be read, modified and redistributed inside other projects provided the notice is kept, and there is no copyleft obligation on anything built with it. That is worth stating plainly because the project depends on a large stack of third party components, and an adopter needs to track both the licences of the code and of the native libraries it links.

The credits section is unusually long and it doubles as an architecture summary. The WZ reading code comes from WzExtract and WzPatcher, the MapRender code and libgif from a separate contributor, .ms file and video format work from another, and then there is a long list of libraries: DotNetBar for the interface, SharpDX and MonoGame for graphics, BassLibrary for sound, IMEHelper for input method handling, Spine-Runtime for skeletal animation, and libvpx with libyuv for video decoding.

Those names tell you what the tool is made of. A WZ extractor alone would be a small program, and the size of the dependency list here reflects the display side, the audio side and the video side, which is what turns a file reader into an application.

The UpdateLogs directory and the roadmap wiki are the two places to watch for the project's own account of what changed and what is planned. Given the maintenance status, the update logs are more informative than the roadmap.

Editorial conclusion

WzComparerR2 suits a modder or a data analyst who already has a MapleStory client installation and needs to read, compare and inspect its WZ archives, and who is willing to build from source because no stable binary is published. It does not suit someone who wants a maintained desktop application, and it is not the right tool for a non Windows machine, since the 2.x line requires DirectX 11 and the project is built with Visual Studio 2022 and the .NET 8 SDK. Before relying on it, check the UpdateLogs directory and the ci-build release for the current WZ format handling, and run the git clone with the recurse-submodules flag, since the native dependencies are not in the main tree.

Frequently asked questions

Official sources

1. Issues
2. Kagamia/WzComparerR2 on GitHub
3. License: MIT
4. README
5. Releases