[VIDEO GUIDE] How to Make a MapleStory v146 Private Server – Full Setup Tutorial

[tuanmai7797]

MapleStory v146 Localhost Setup Guide​

1. Install the Server Environment Software​

A. Download Software and Install​

• JDK 7
  • To view the content, you need to sign in or register
  • To view the content, you need to sign in or register
• JCE 7 (Java Cryptography Extension)
  • To view the content, you need to sign in or register
• MySQL Server 5.5
  • To view the content, you need to sign in or register
• MySQL GUI Tools
  • To view the content, you need to sign in or register
• NetBeans IDE 7.4
  • To view the content, you need to sign in or register

B. Extract The JCE 7 Files And Move Them​

After extracting the file UnlimitedJCEPolicyJDK7.zip, you will get two files:

• local_policy.jar
• US_export_policy.jar

and then copy those two files into:

Spoiler

For 64-bit systems:​

C:\Program Files\Java\jdk1.7\jre\lib
C:\Program Files\Java\jdk1.7\jre\lib\ext
C:\Program Files\Java\jdk1.7\jre\lib\security

C:\Program Files\Java\jre7\lib
C:\Program Files\Java\jre7\lib\ext
C:\Program Files\Java\jre7\lib\security

For 32-bit systems:​

C:\Program Files (x86)\Java\jdk1.7\jre\lib
C:\Program Files (x86)\Java\jdk1.7\jre\lib\ext
C:\Program Files (x86)\Java\jdk1.7\jre\lib\security

C:\Program Files (x86)\Java\jre7\lib
C:\Program Files (x86)\Java\jre7\lib\ext
C:\Program Files (x86)\Java\jre7\lib\security

C. Video Tutorial – Environment Setup:​

2. Set Up Server and Game Client (v146)​

A1. Download the Game Client v146​

• To view the content, you need to sign in or register
• To view the content, you need to sign in or register
• To view the content, you need to sign in or register
• To view the content, you need to sign in or register
• To view the content, you need to sign in or register

A2. Install and Remove Unnecessary Files​

After installing the game client, delete the following files/folders from the client directory:

• BlackCipher ( Folder )
• HShield. ( Folder )

B1. Download the Server Source + Localhost v146​

• To view the content, you need to sign in or register
• To view the content, you need to sign in or register

B2. Move Files Localhost​

After downloading localhost, extract the Localhost v14x.rar file and copy the 4 files from the Localhost v14x folder into the game client.

• BlackCipher ( Folder )
• HShield. ( Folder )
• Localhost.dll
• Localhost.exe

NOTE: I changed the way to launch the game client in the tutorial video — instead of using a redirector to connect to the server, I updated the guide so now you can just use localhost to enter the game client and log in as usual.

C. Video Tutorial – Server & Client Setup​

3. Join the Community​

Discord Invite Link:

• To view the content, you need to sign in or register

Fix some bugs​

1. Fix for getting disconnected to the login screen after exiting the Cash Shop​

Spoiler

Try looking for this piece of code:
( \src\main\java\handling\cashshop\handler\CashShopOperation.java )

public class CashShopOperation {

    public static void LeaveCS(final LittleEndianAccessor slea, final MapleClient c, final MapleCharacter chr) {
        CashShopServer.getPlayerStorage().deregisterPlayer(chr);
        c.updateLoginState(MapleClient.LOGIN_SERVER_TRANSITION, c.getSessionIPAddress());

        try {
            World.ChannelChange_Data(new CharacterTransfer(chr), chr.getId(), c.getChannel());
            c.getSession().write(CField.getChannelChange(c, Integer.parseInt(ChannelServer.getInstance(c.getChannel()).getIP().split(":")[1])));
        } finally {
            final String s = c.getSessionIPAddress();
            LoginServer.addIPAuth(s.substring(s.indexOf('/') + 1, s.length()));
            chr.saveToDB(false, true);
            c.setPlayer(null);
            c.setReceiving(false);
            c.getSession().close();
        }
    }
}

Then delete this line:

c.getSession().close();

After that, compile the code again and test if you still get disconnected when leaving the Cash Shop.

2. Fix for Cash Shop showing nothing or displaying "All the goods are sold out."​

Spoiler

Open MySQL Query Browser > File > New Script Tab
Then paste the following two lines:

ALTER TABLE cashshop_menuitems ADD COLUMN mesoSell SMALLINT DEFAULT 0;
ALTER TABLE cashshop_items ADD COLUMN mesoSell SMALLINT DEFAULT 0;

Click Execute.
After that, restart your server console.
Then log into the game and check the Cash Shop again.

 

[symphofear]

Hi, thank you so much for the detailed guide! I have managed to get into the game but is this only for solo playing?

Also realized that the cash shop when click on one of the categories on the left, it always shows items sold out and after exiting the cash shop, the game would return me back to the character selection showing an error. But able to get back into the game after clicking OK.

 

[tuanmai7797]

Hi, thank you so much for the detailed guide! I have managed to get into the game but is this only for solo playing?

Also realized that the cash shop when click on one of the categories on the left, it always shows items sold out and after exiting the cash shop, the game would return me back to the character selection showing an error. But able to get back into the game after clicking OK.

View attachment 279737View attachment 279738

Ehe—thanks for choosing my guide! ​

1. Fix for getting disconnected to the login screen after exiting the Cash Shop​

Spoiler

Try looking for this piece of code:
( \src\main\java\handling\cashshop\handler\CashShopOperation.java )

public class CashShopOperation {

    public static void LeaveCS(final LittleEndianAccessor slea, final MapleClient c, final MapleCharacter chr) {
        CashShopServer.getPlayerStorage().deregisterPlayer(chr);
        c.updateLoginState(MapleClient.LOGIN_SERVER_TRANSITION, c.getSessionIPAddress());

        try {
            World.ChannelChange_Data(new CharacterTransfer(chr), chr.getId(), c.getChannel());
            c.getSession().write(CField.getChannelChange(c, Integer.parseInt(ChannelServer.getInstance(c.getChannel()).getIP().split(":")[1])));
        } finally {
            final String s = c.getSessionIPAddress();
            LoginServer.addIPAuth(s.substring(s.indexOf('/') + 1, s.length()));
            chr.saveToDB(false, true);
            c.setPlayer(null);
            c.setReceiving(false);
            c.getSession().close();
        }
    }
}

Then delete this line:

c.getSession().close();

After that, compile the code again and test if you still get disconnected when leaving the Cash Shop.

2. Fix for Cash Shop showing nothing or displaying "All the goods are sold out."​

Spoiler

Open MySQL Query Browser > File > New Script Tab
Then paste the following two lines:

ALTER TABLE cashshop_menuitems ADD COLUMN mesoSell SMALLINT DEFAULT 0;
ALTER TABLE cashshop_items ADD COLUMN mesoSell SMALLINT DEFAULT 0;

Click Execute.
After that, restart your server console.
Then log into the game and check the Cash Shop again.

 

[symphofear]

I managed to figure out the cashshop disconnect issue but not the sold out goods. Thank for the quick fix!

Did u experience issues with the monsters health? I am unable to kill them unless i keep spamming the skills. Suspect might be due to the opcodes and do u mind sharing your opcodes?

 

[tuanmai7797]

I managed to figure out the cashshop disconnect issue but not the sold out goods. Thank for the quick fix!

Did u experience issues with the monsters health? I am unable to kill them unless i keep spamming the skills. Suspect might be due to the opcodes and do u mind sharing your opcodes?

Can’t kill monsters unless you spam skills?​

I think it might be caused by GM effects set in MySQL. Try creating a new character and testing it again.
I’ve read several posts saying it could be due to the !hide command, which makes your character invisible — and as a result, monsters don’t "react" or become active.

Opcode?​

Actually, there’s not much difference. I didn’t touch them at all since we’re all using the same source anyway.

 

[symphofear]

I found the bug in MapleMonster.java
They had the monster's hp multiplied by 12 causing required more hits to kill them.

 

[klaiu228]

Hiii, I hope you are doing well! First of all, I want to thank you very very much for making a tutorial for this source! I was looking for how to setup this source a while ago and this tutorial was indeed very helpful! This source is way more stable than I thought, I could ever create a Jett without crashing lolol (even though the 1st job is buggy, but still)

But one problem that I didn't knew I would stumble across was the character card system. Everytime I equip any card then log off/get on the game, the cards just unequip themselves. Later on I discovered that the database isn't even storing the values. Is there any possible fix for this? I already tried to use some of the OurStory code as a reference (since there the card equipping was working, didn't tested the stats though) but I lack knowledge and I wasn't lucky . Thanks in advance!

 

[jokinglybad]

All good

 

[tuanmai7797]

Go to the following path:​

src/main/java/constants/ServerConfig.java

/* Rates */
public static boolean fixedRates = true; // use same rates for all worlds
public static final int EXP = 6;         // EXP rate (only works when fixedRates = true)
public static final int MESO = 1;        // Meso rate (only works when fixedRates = true)
public static final int DROP = 2;        // Drop rate (only works when fixedRates = true)
public static final int CASH_DROP_RATE = 2; // Out of 100

 

[burnernovember]

Hi, I am having an issue after making myself a GM via !job 900 or 910, and logging out and logging back in the client crashes with error -38 (reached end of the file). I cannot start the game again unless I delete the character or change the job ID in MySQL. Any ideas? Thanks!

 

[zachlax]

been years since i last touched server dev like v55 and v62 days, having to deal with hamachi, hex editing localhosts, this setup was so simple, had a few hiccups with setting my netbeans package folder to the source folder so im just copy/pasting when i build from the package folder to the source folder and it works with no issue. Thanks a bunch! gonna have some fun messing around with the codebase and source. nastalgia is a force.

 

[ne476]

I did well after watching the tutorial, but the game doesn't run well. What's the problem?

 

[tuanmai7797]

View attachment 281679
I did well after watching the tutorial, but the game doesn't run well. What's the problem?

Please take a close look at the details in the tutorial video at the 5:28 mark, where it shows how to bypass HS (HackShield) properly.
Basically, it involves changing the path of the HD Bypass into the game directory.


If it still gives you an error after doing that, try reinstalling the game.


I deleted the old BlackCipher and HShield folders, then used the v142+ launcher to extract the new ones and replaced them.
After that, I used the v146 localhost to run the game.

 

[muddysap]

@tuanmai7797

Apparently no one is sharing the game as VM, I've shared it here:

VM  MapleStory v146: VirtualBox Server + GMS Client

May 7, 2025

Because I dislike installing Java or running setup on host OS, I installed the server on VirtualBox.

- The client files is already unpacked - no need to run Nexon's setup.exe (installed inside VM & repacked by 7zip)
- All tools & source code included inside VM (you can edit & recompile source code if you wish)
- Credits goes to @tuanmai7797; took same steps to make this server


Server:

To view the content, you need to sign in or register

- Made with Tiny10 with telemetry disabled by "privacy.sexy" website.
- Server files are located in C:/MAPLE/...

• muddysap
• Replies: 12
• Forum: MapleStory Releases

• 
• 
• 

 

[totalnoobie]

Thank you very much in advance for this tutorial!

I’ve set it up on my vps, how is it possible for me to do a client that connects to the server running on my vps?

Also, when i try run localhost i get this error attachted.

EDIT:
I fixed the attached problem by getting the JAVA Policy 8 files.

New problem appered.
Cannot solve this problem.
I'm running the maplestory on my VPS, can it have any influent in the error?


Best Regards.

Error code:

Received data :
2E 00 E9 00 4F 53 28 36 2F 32 2D 39 32 30 30 3A 4E 6F 6E 65 29 20 78 36 34 3A 28 31 29 20 76 65 72 28 31 34 36 29 2C 20 43 68 61 72 61 63 74 65 72 4E 61 6D 65 28 29 2C 20 57 6F 72 6C 64 49 44 28 2D 31 29 2C 20 43 68 49 44 28 2D 31 29 2C 20 46 69 65 6C 64 49 44 28 2D 31 29 2C 20 63 6F 6D 5F 65 72 72 6F 72 28 65 72 72 6F 72 20 63 6F 64 65 20 3A 20 2D 32 31 34 37 34 36 37 32 35 39 20 28 55 6E 73 70 65 63 69 66 69 65 64 20 65 72 72 6F 72 29 29 20 73 6F 75 72 63 65 28 28 6E 75 6C 6C 29 29 0D 0A 37 38 30 35 37 34 37 32 2C 33 38 38 38 30 35 30 31 37 36 2F 34 32 39 34 39 36 37 32 39 35 2C 34 30 31 30 32 30 39 32 38 30 2F 34 32 39 34 38 33 36 32 32 34 29 2C 20 50 6C 61 79 54 69 6D 65 28 30 20 6D 69 6E 29 0D 0A
..é.OS(6/2-9200:None) x64:(1) ver(146), CharacterName(), WorldID(-1), ChID(-1), FieldID(-1), com_error(error code : -2147467259 (Unspecified error)) source((null))..78057472,3888050176/4294967295,4010209280/4294836224), PlayTime(0 min)..
[Recv]  CRASH_INFO                      |       46      |       0x002E
[UNHANDLED] Recv [CRASH_INFO] found
Received data :
3F 00 08 92 00 01 00
?..?...
[Recv]  CLIENT_HELLO                    |       63      |       0x003F
/127.0.0.1 Connected!

 

[shemor95]

@tuanmai7797

Apparently no one is sharing the game as VM, I've shared it here:

VM  MapleStory v146: VirtualBox Server + GMS Client

May 7, 2025

Because I dislike installing Java or running setup on host OS, I installed the server on VirtualBox.

- The client files is already unpacked - no need to run Nexon's setup.exe (installed inside VM & repacked by 7zip)
- All tools & source code included inside VM (you can edit & recompile source code if you wish)
- Credits goes to @tuanmai7797; took same steps to make this server


Server:

To view the content, you need to sign in or register

- Made with Tiny10 with telemetry disabled by "privacy.sexy" website.
- Server files are located in C:/MAPLE/...

• muddysap
• Replies: 12
• Forum: MapleStory Releases

• 
• 
• 

and how to get in the game its not loaded

 

[fitzz764880808]

Thanks for the release! Is it possible to get the launcher source code? I want to play with friends and need to change the server IP it points to.