Skip to content

Update project #307

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
P0nk merged 2 commits into from
Jun 26, 2025
Merged

Update project #307

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ee8758e
Upgrade dependencies
P0nk Jun 26, 2025
ac1f4c8
Refer to Cosmic-client for client setup
P0nk Jun 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 9 additions & 38 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ We will set up the following:
- Client - the client is the application used to _play the game_, i.e. MapleStory.exe.

### 1 - Database
You will start by installing the database server and client, and then run some scripts to prepare it for the server.
You will start by installing the database server and database client, and then run some scripts to prepare it for the server.

#### Steps

Expand Down Expand Up @@ -100,27 +100,12 @@ To run the jar, a ``launch.bat`` file is provided for convenience. Simply double
Alternatively, run the jar file from the terminal. Just remember to provide the `wz-path` system property pointing to your wz directory.

### 3 - Client
You will start by installing the game with the old installer, then overwrite some WZ files with our custom ones, and lastly get the localhost executable in place.
The client files are located in a separate repository: https://github.com/P0nk/Cosmic-client

#### Steps

1. Download _MapleGlobal-v83-setup.exe_ from my [Google Drive](https://drive.google.com/drive/folders/1hgnb92MGL6xqEp9szEMBh0K9pSJcJ6IT). This is the official installer from back then.
2. Install it in a directory of your choice.
3. Delete the following files from the installation directory: _HShield_ (entire directory), _ASPLnchr.exe_, _MapleStory.exe_, and _Patcher.exe_.
4. Download _CosmicWZ-2024-07-17-v0.14.0.zip_ from my [Google Drive](https://drive.google.com/drive/folders/1hgnb92MGL6xqEp9szEMBh0K9pSJcJ6IT).
5. Unzip it and copy all .wz-files into the installation directory. Replace the existing ones.
6. Download _HeavenMS-localhost-WINDOW.exe_ from [hostr.co](https://hostr.co/amuX5SLeeVZx). This is a client modified to connect to your localhost instead of Nexon's server (along with some fixes and custom changes).
- Your antivirus will likely detect the file as a trojan or similar and automatically delete it. To prevent this from happening, add your _Downloads_ directory and the installation directory as exclusions in your antivirus software. On W11, this is under "Virus & threat protection settings" -> "Add or remove exclusions".
7. Move _HeavenMS-localhost-WINDOW.exe_ into the installation directory.
8. Done! Double-click the exe and the game should start.
- The client may be a bit fiddly. Sometimes it won't start, but if you see "Client connected" in the server console it's a good indication. Try spam-clicking it like 10+ times, that usually works for me.

**Important note about localhost clients**: these executables are red-flagged by antivirus tools as potentially malicious software.
This happens due to the reverse engineering methods that were applied onto these software artifacts.
The one provided here has been in use for years already and posed no harm so far, so it is assumed to be safe.
Follow the installation guide in the README.

### 4 - Getting into the game
The client has started, and you're looking at the login screen.
You have successfully started the client, and you're looking at the login screen.

#### Logging in
At this point, you can log in to the admin account using the following credentials:
Expand All @@ -129,7 +114,7 @@ At this point, you can log in to the admin account using the following credentia
* Pin: "0000"
* Pic: "000000"

Or create a regular account by typing in your desired username & password and attempting to log in. This "automatic registration" feature lets you create new accounts to play around with. It is enabled by default (see _config.yaml_).
You can also create a new regular account by typing in your desired username & password and attempting to log in. This "automatic registration" feature lets you create new accounts to play around with. It is enabled by default (see _config.yaml_).

#### Entering the game
Create a new character as you normally would, and then select it to enter the game. Hooray, finally we're in!
Expand All @@ -144,21 +129,14 @@ That's it, have fun playing around in game!
Some slightly more advanced concepts that might be useful once you're up and running.

### Host on remote server
You don't have to host the server on your local machine to play. It's possible to host on a remote server such as a VPS or even a dedicated server.

I leave it to you to figure out the server hosting part, but once you have that running you'll need to edit the client exe to point to your remote server ip.
You don't have to host the server on your local machine to play. It's possible to host on a remote server such as a VPS or a dedicated server.

#### Edit client ip
1. Download and install a hex editor: [HxD](https://mh-nexus.de/en/hxd/)
2. Start HxD and open your client exe (I recommend making a copy of it first). At this point you should see a bunch of hex codes and a "Decoded text" column to the right of it.
3. Ctrl+f and search for Text-string "127.0.0.1". You should find three occurrences right above each other.
4. Place your cursor before the first "127" and start typing the desired ip, overwriting what is already there. Do the same on the other two and click on Save.
5. Done! Now the client will attempt to connect to that ip address instead when you launch it.
I leave it to you to figure out the server hosting part, but once you have that running you'll need to edit the client ip to point to your remote server ip.

### WZ files
WZ files are the asset/data files required by the client and server. Typically, [HaRepacker-resurrected](https://github.com/lastbattle/Harepacker-resurrected) is used to handle (view, edit, export) the .wz files.
WZ files are the asset/data files required by the client and server. Typically, the [HaRepacker-resurrected](https://github.com/lastbattle/Harepacker-resurrected) tool is used to manage (view, edit, export) the .wz files.

The client can read the .wz files directly, but the server requires them in XML format. The server also does not make use of the sprites, which is the motivation for different kinds of exporting.
The client can read the .wz files directly, but the server requires them to be in XML format. The server does not make use of the sprites, which is the motivation for different kinds of exporting.
HaRepacker allows you to export to "Private server", which is the .img files packaged in the .wz stripped of sprites and converted to XML. This takes much less disk space.

This server requires custom .wz files (unfortunately), as you may have noted during installation of the client. The intention is for these to be removed eventually and to solely run on vanilla .wz files.
Expand All @@ -172,10 +150,3 @@ This server requires custom .wz files (unfortunately), as you may have noted dur
Make sure to always export from the client .wz files to the server XML, and not the other way around.

Editing the client .wz without exporting to the server may lead to strange behavior.

### Client features
For more information about the client and its features, see [HeavenMS on GitHub](https://github.com/ronancpl/HeavenMS#download-items).

Some notable features:
* Opens in window mode by default
* Uncapped max speed
23 changes: 11 additions & 12 deletions pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>

<groupId>cosmic-maplestory</groupId>
Expand Down Expand Up @@ -51,24 +50,24 @@
<mainClass>net.server.Server</mainClass>

<!-- Maven plugins -->
<maven-surefire-plugin.version>3.2.5</maven-surefire-plugin.version> <!-- For running unit tests -->
<maven-jar-plugin.version>3.4.1</maven-jar-plugin.version> <!-- Disabled. (for building thin jar) -->
<maven-surefire-plugin.version>3.5.3</maven-surefire-plugin.version> <!-- For running unit tests -->
<maven-jar-plugin.version>3.4.2</maven-jar-plugin.version> <!-- Disabled. (for building thin jar) -->
<maven-assembly-plugin.version>3.7.1
</maven-assembly-plugin.version> <!-- For packaging the executable fat jar -->

<!-- Dependencies -->
<slf4j-api.version>2.0.13</slf4j-api.version> <!-- Logging facade -->
<log4j.version>2.23.1</log4j.version> <!-- Slf4j implementation -->
<slf4j-api.version>2.0.17</slf4j-api.version> <!-- Logging facade -->
<log4j.version>2.25.0</log4j.version> <!-- Slf4j implementation -->
<graalvm-js.version>23.0.4</graalvm-js.version>
<graalvm-js-scriptengine.version>24.0.1</graalvm-js-scriptengine.version> <!-- ScriptEngine implementation -->
<netty.version>4.1.109.Final</netty.version> <!-- Networking -->
<netty.version>4.2.2.Final</netty.version> <!-- Networking -->
<yamlbeans.version>1.17</yamlbeans.version> <!-- Config file -->
<jcip-annotations.version>1.0</jcip-annotations.version> <!-- Annotations for concurrency documentation -->
<HikariCP.version>5.1.0</HikariCP.version> <!-- Database connection pool -->
<mysql-connector-j.version>8.4.0</mysql-connector-j.version> <!-- MySQL JDBC driver -->
<jdbi-version>3.45.1</jdbi-version> <!-- Convenience wrapper around JDBC -->
<junit.version>5.10.2</junit.version> <!-- Unit test -->
<mockito.version>5.11.0</mockito.version> <!-- Unit test -->
<HikariCP.version>6.3.0</HikariCP.version> <!-- Database connection pool -->
<mysql-connector-j.version>9.3.0</mysql-connector-j.version> <!-- MySQL JDBC driver -->
<jdbi-version>3.49.5</jdbi-version> <!-- Convenience wrapper around JDBC -->
<junit.version>5.13.1</junit.version> <!-- Unit test -->
<mockito.version>5.18.0</mockito.version> <!-- Unit test -->
</properties>

<dependencies>
Expand Down