HeavenClient is a custom, made-from-scratch game client for MapleStory. It is a free, open-source project developed for educational and personal use.
- Compatibility
- Getting Started
- Configuration
- Required Files
- Dependencies
- Troubleshooting
- Binaries
- Donations
| Platform | Link |
|---|---|
| Server | Compatible with version 83 servers. Tested with HeavenMS using v229.2. |
| Switch | HeavenClientNX |
| Linux | Linux branch |
- Visual Studio 2026 Community Edition (tested with v18.2.1)
- Windows SDK Version: 8.1 (Download)
- Platform Toolset: v140
- 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).
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.
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 |
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.
- 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).
| Category | Library |
|---|---|
| NX | NoLifeNx |
| WZ | TBA |
| Graphics | GLFW3, GLEW, FreeType |
| Audio | Bass |
| Networking | Asio (optional) |
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.
The latest build (e3e97c2) is available here: HeavenClient v228.3.zip
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.