Guide Comprehensive Guide to Setting Up a MapleStory v83 Private Server Using Cosmic Source

H2oR

H2oR

Moderator
Moderator
Joined
Jun 10, 2024
Messages
72
Solutions
1
Reaction score
61
Points
18
Welcome to this comprehensive guide for setting up your very own MapleStory v83 private server on your personal computer, using the Cosmic source. This guide will take you step-by-step through the setup process.
Cosmic launched on March 2021. It is based on code from a long line of server emulators spanning over a decade - starting with OdinMS (2008) and ending with HeavenMS (2019).

but please be aware: I cannot guarantee it’s stable enough for public servers, and using it for such purposes is entirely at your own risk.
This is mainly a Java based project, but there are also a bunch of scripts written in JavaScript. Head developer and maintainer: Ponk.

This guide is intended solely for creating a local server. While I will provide a brief explanation on how to put the server online, no further support will be given.
Also, please do not reach out with questions about MapleStory development or it's environment — I am not experienced in that area. This guide is strictly for setting up a basic server!
By the end, you’ll have a working server on your personal computer ready for basic customization and exploration on your own.
This guide has been tested exclusively on Windows

Part 1: Installations

Step 1: Install Java JDK​
  1. Download and install the JDK from here: (21 is fine).​
  2. Run the .exe file, then click "Next." As in Step 1, you will have the option to change the installation directory.​
  3. That’s up to you if you want to. Proceed by pressing "Next" and then wait for the installation to finish.​
  4. Inside the Cosmic GitHub repository, there is a recommendation to use Amazon Corretto JDK. It’s up to you whether you want to follow this recommendation or stick with the standard provided JDK.​

Step 2: Install IntelliJ IDEA​
  1. Download and Install IntelliJ from here:
    www.jetbrains.com

    Download IntelliJ IDEA – The Leading Java and Kotlin IDE

    Download the latest version of IntelliJ IDEA for Windows, macOS or Linux.
    www.jetbrains.com www.jetbrains.com
    ​
  2. Start the installation.​
  3. The "Welcome to IntelliJ" window will open; click "Next."​
  4. Choose your destination folder or keep it as the default, then click "Next."​

Now you'll see the "Installation Options" window. You have several options, like creating a desktop icon shortcut, etc.
Here, it’s up to you—select whichever options you prefer, click "Next," and then press "Install." and click finsih after.

Step 3: Install MySQL Community Server​
  1. Download and install "MySQL Community Server" from here:

    MySQL :: Download MySQL Community Server

    dev.mysql.com dev.mysql.com
    ​
  2. Run the .exe file, then click "Next." Accept the terms and hit "Next" again.​
  3. Keep the Setup type at "Typical" unless you want to customize it and know what you’re doing. After that, click "Install" and wait for the installation to complete.​

Now run the MySQL configurator and follow the steps shown in the GIF:
* You will have to set a root password, make sure you don't lose it because you will need it later. *
part_1_step_4_00.gif

After completing the configuration, click "Finish."

Step 4: Install MySQL Workbench ​
  1. Download and install "MySQL Workbench" from here:

    MySQL :: Download MySQL Workbench

    dev.mysql.com dev.mysql.com
    ​
  2. Run the .exe file, then click "Next." And again you will have the option to change the installation directory.​
  3. do it or not - click "Next". Select "Setup Type" as "Complete" and then click "Next" and then "Install" and then "Finish" (not need to run mysql at this moment).​
You can also use HeidiSQL if you wish. I don't, in this tutorial.


Part 2: Clone and Configurations

Step 1: Clone Cosmic​
  1. Open IntelliJ IDEA and click "Get from VCS."​
  2. The cloning link is:
    github.com

    GitHub - P0nk/Cosmic: MapleStory Global v83 server emulator

    MapleStory Global v83 server emulator. Contribute to P0nk/Cosmic development by creating an account on GitHub.
    github.com github.com
    ​

Now, follow the GIF:
*Install Git if you see a red message indicating "Git is not installed." *
part_2_step_1_00.gif

If you still encounter issues with Git, download and install it from here:
After the cloning process finishes, you may see a prompt to "Trust and Open Project." Click "Trust Project."
It may take some time to scan and update indexes and files; keep it running and let it finish.

Step 2: Config root password
Open config.yaml. Find the entry labeled DB_PASS and set it to your database's root user password. (the one you were instructed to remember).
If you've changed your MySQL username, update it here as well.

Step 3: Run MySQL Database Scripts
Start MySQL Workbench and connect to your local instance by typing in your MySQL password.
Navigate to your server directory > database > sql and run the queries in the following order:
​
1-db_database.sql
2-db_drops.sql
3-db_shopupdate.sql
4-db-admin.sql​
Click to expand...

1732894705611.png

You can either drag the files to execute the queries or open them directly — whichever you prefer.
If you didn't encounter any issues, the SQL configuration is complete.

Part 3: Start the server from IntelliJ IDEA
After the whole configuration is ready, you can start your server from the main method inside IntelliJ.
The main method is located in "net.server.Server" (src\main\java\net\server\Server.java).
If you see "Cosmic is now online" in the console, it means the server is online and ready to serve traffic.

part_3_step_1_00.png

Part 3.1 (Optioanl): Support for Docker
This information is directly from the github repository of cosmic ms

Support for Docker is also provided out of the box, as an alternative to running straight in the IDE. If you have Docker Desktop installed it's as easy as running
Hey There! 
Please login and(or) register to see this awesome content today.
.

Making changes becomes a bit more tedious though as you have to rebuild the server image via
Hey There! 
Please login and(or) register to see this awesome content today.

On the first launch, the database container will run the scripts which may take so long that the server fails to start. In that case, just wait until the database is done running the scripts and then retry (Ctrl+C and re-run the command).

Part 3.2 (Optional): Maven

Step 1: Extract Apache Maven 3.9.9 from the package to a location of your choice.

Step 2: Copy the entire folder to C:\Program Files (x86).

Step 3: Copy the path of the bin directory inside the Maven folder, for example:​
C:\Program Files (x86)\apache-maven-3.9.9\bin​
Click to expand...

Step 4: In Windows, search for "Edit the system environment variables" and open it.

Step 5: Navigate to the "Advanced" tab and click on "Environment Variables...".
part_3.2_step_5_00.png

Step 6: Add the bin path to System variables

part_3_step_6_00.gif

Step 7: Open Command Prompt, change the directory to where your MapleStory project is located by using the "cd" command.
Then, execute the following command:
Hey There! 
Please login and(or) register to see this awesome content today.
and wait for it to finish building the .jar file.

part_3_step_7_00.png

If everything went successfully, you should be able to run the program through launch.bat instead of running it directly in IntelliJ.
You’ll know it worked if you see the same message as when running it inside the IDE.

part_3_step_7_01.png


Part 4: Client and localhost
​
  1. Step 1:
    Your antivirus will likely detect the file as a trojan or similar and automatically delete it.​
  2. To prevent this from happening, add your Downloads directory and the installation directory as exclusions in your antivirus software.​
  3. On W11, this is under "Virus & threat protection settings" -> "Add or remove exclusions" (This was written inside the github repo).
    After that, download the localhost from here:

    HeavenMS-localhost-WINDOW.exe

    Get free file hosting, and cloud sharing on Hostr.
    hostr.co hostr.co
    ​

Step 2:
Download and install "MapleGlobal-v83-setup.exe" wherever you want.

Google Drive - Download warning

drive.usercontent.google.com drive.usercontent.google.com

Step 3:
Delete the following files from the installation directory: HShield (entire directory), ASPLnchr.exe, MapleStory.exe, and Patcher.exe.

Step 4:
Download CosmicWZ-2024-07-17-v0.14.0.zip from here:

Cosmic tools - Google Drive

drive.google.com drive.google.com
.

Step 5:
Unzip it and copy all .wz-files into the installation directory. Replace the existing ones.

Step 6:
Now extract/copy HeavenMS-localhost-WINDOW.exe into the installation directory,
This is a client modified to connect to your localhost instead of Nexon's server.

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.

Step 7:
All 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.

Step 8: Getting into the game
The client has started, and you're looking at the login screen.
At this point, you can log in to the admin account using the following credentials:

Username: "admin"
Password: "admin"
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).

Maple0000.png

Part 5 and final: Extra Information from me

GM Permission - Run this query inside MySQL:
Hey There! 
Please login and(or) register to see this awesome content today.
Replace H2oR with your character's name. There are 6 levels of GMs, each with different permissions. It’s up to you to investigate the details of each level! :)

Change rates and IP Address - Navigate to the config.yaml file located in the source folder and open it with a text editor.
Look for the following lines; they should be near the beginning.

Hey There! 
Please login and(or) register to see this awesome content today.

If you plan to play or work only on your own computer without allowing access to others you can skip this step.

To edit your IP address, in the same file, look for the address 127.0.0.1 or #Ip Configuration and change the IP accordingly.
Hey There! 
Please login and(or) register to see this awesome content today.

Replace "78.945.561.123" with your ip address.

Editing the Client's IP Address(Text from the github) :
Download and install a hex editor: HxD (https://mh-nexus.de/en/hxd/)
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.
Ctrl+f and search for Text-string "127.0.0.1". You should find three occurrences right above each other.
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.
Done! Now the client will attempt to connect to that ip address instead when you launch it.

Port forwarding - If you are hosting your server on a dedicated server or vps, you need to portforwarding the following:
Hey There! 
Please login and(or) register to see this awesome content today.

Note: Ports 7575-7577 are for each channel. If you have added additional channels, you will need to open more ports.
For example, if you added another channel, you would also need to open port 7578.

Congratulations! You’ve now set up your own MapleStory v83 server using the Cosmic source.
With your server up and running, you’re free to explore, test configurations, and customize the gameplay experience to suit your preferences.

Community Contributions and Knowledge Sharing
The MapleStory development community is quite niche, and resources such as guides and code snippets can be hard to come by where you look for.
If you have any insights, scripts, or experiences that could help other developers, please consider contributing back to lodelight.com. By sharing what you know, you’ll help expand our knowledge base and create a more comprehensive resource for everyone involved in MapleStory development.

Every bit of knowledge counts, whether it’s a small code snippet, a troubleshooting tip, or a detailed guide. Together, we can make MapleStory development more accessible and build a supportive community that fosters growth and creativity.​
 
Last edited:
  • Like
Reactions: Brutal and Tatsuyiaki
You must log in or register to reply here.