HeavenClient
February 25, 2026 · View on GitHub
HeavenClient is a custom, made-from-scratch game client for MapleStory. It is a free, open-source project developed for educational and personal use.
Table of Contents
- Compatibility
- Getting Started
- Configuration
- Required Files
- Dependencies
- Troubleshooting
- Binaries
- Donations
Compatibility
| Platform | Link |
|---|---|
| Server | Compatible with version 83 servers. Tested with HeavenMS using v229.2. |
| Switch | HeavenClientNX |
| Linux | Linux branch |
| Web | MapleStory WASM |
Getting Started
Prerequisites
- Visual Studio 2026 Community Edition (tested with v18.2.1)
- Windows SDK Version: 8.1 (Download)
- Platform Toolset: v140
Build Steps
- Open MapleStory.sln in Visual Studio.
- Verify the SDK and toolset versions are set correctly (see above).
- Build the solution: Build > Build Solution (
Ctrl + Shift + B). - Run the client: Debug > Start Debugging (
F5).
Converting WZ Files to NX
All WZ files from the v229.2 official client must be converted to NX format and placed in the parent folder of the executable. See the NoLifeWzToNx README for conversion instructions.
Configuration
Build Options
Edit MapleStory.h to toggle build-time features:
| Option | Description |
|---|---|
USE_ASIO | Use Asio for networking (requires additional dependency) |
USE_CRYPTO | Enable cryptography for server communication |
USE_NX | Use NX files instead of WZ files |
USE_DEBUG | Suppress generation of the Settings file |
Runtime Settings
Default settings are defined in Configuration.h. A Settings file is generated after a game session with the same options. Editing either file works the same way, but Settings will not persist if deleted.
Required Files
- All WZ files from the official client must be converted to NX format.
- See NxFiles.h for the full list of required NX files.
- See Configuration.h for the latest tested WZ file version (currently v229.2).
Dependencies
| Category | Library |
|---|---|
| NX | NoLifeNx |
| WZ | TBA |
| Graphics | GLFW3, GLEW, FreeType |
| Audio | Bass |
| Networking | Asio (optional) |
Troubleshooting
If you experience in-game glitches, UI rendering issues, or other unexpected behavior, try the following:
- Clean Solution in Visual Studio.
- Close Visual Studio.
- Delete the following files and folders:
.vs/x64/debug.logMapleStory.apsSettings
- Reopen the solution.
- Rebuild the solution.
Binaries
The latest build (e3e97c2) is available here: HeavenClient v228.3.zip
Donations
If you'd like to support the continued development of HeavenClient, you can donate here.
All donations go directly toward the development of this project. Please also remember to support Nexon — this project is not meant to replace anything they offer.
Note: HeavenClient is and will always be free and open-source. Do not pay anyone for services related to this client.