Skip to content

v83‐Client‐Setup‐and‐Development‐Guide

Jump to bottom
Ro edited this page Oct 23, 2023 · 51 revisions

v83 Client Setup and Patch Development Guide for modern HD monitors

Table of Contents

Core Setup

This setup guide is for an open source v83 client patch designed to work with the most developed open source v83 server (currently cosmic)

This guide assumes you followed the server setup guide for your respective v83 server source up until the point you need the localhost/client. Instead of using the provided localhost, download the following:

  • compiled ezorsia v2 DLL and config.ini from releases; follow the instructions in the readme to install it (source is also released for transparency and development)
  • hendi's v83 4g client with admin elevation request removed this is the only edit that was made to the binary directly because i could not get it to work from the dll
    • if you would rather do the edit yourself for verification purposes you can get the original release version from here you will also need the to use the hex editor from cosmic files here and make the following edits shown here
    • mirror for clean, unedited 4g client in case it ever becomes unavailable: clean client mirror
  • a modified UI.wz file containing MapleEzorsiaV2 data to replace the existing UI.wz(remember to rename it as ui.wz exactly afterwards)
    • Ezorsia V2 will automatically load the appropriate login frame based on your chosen resolution as well as other Ezorsia V2 wz edits to the appropriate location, no need for complicated wz edits!
    • for the best experience i recommend 1280x720 along with using the borderless fullscreener provided later. This is the resolution i played and developed it on
    • this UI.wz is a modified UI.wz from the cosmic release, and is up to date as of 2023/10/10. in the event that cosmic updates their UI.wz in release or if you are using a custom wz file, you will have to use a wz editor to update the UI.wz following these instructions:
      • open both the UI.wz provided here and the UI.wz to be updated in a wz editor, select MapleEzorsiaV2wzfiles.img of UI.wz in the editor, copy and paste it to the UI.wz you are updating
        • if you are loading from img files and not wz files. export MapleEzorsiaV2wzfiles.img as IMG file and place it with the other IMG files from UI.wz in the respective folder
        • concerned about Ezorsia V2 wz edits conflicting with your own? see Troubleshooting Section for solution
      • wz editor can be found in the Useful Resources section
    • Note: the game is playable using just the patch, but you would have to toggle the setting in config.ini to EzorsiaV2WzIncluded=false
      • in this case if the login frame in UI.wz is the original 800x600 login frame, also toggle CustomLoginFrame=false
      • it works without Ezorsia V2 wz assets but will just look slightly uglier on the login screen (and medal will clip through the cash shop preview window)
  • download magpie from https://github.com/Blinue/Magpie open magpie while game is running, click new profile and select your client window, then go to the created profile and toggle on auto scale when in foreground. make sure that window mode is on in the ezorsia config when doing this.
    • magpie is a borderless fullscreener that interacts with directx to re-draw pixels into hi-resolution to match your display resolution. this way you can match the aspect ratio of your screen without the normal fullscreen stretching, keep the classic maple look playing in 1280x720, and avoid the scaled down UI elements that occur when a higher resolution is selected in ezorsia config

End User Safety

This guide also aims to provide the safest possible setup for the end user so i think we should talk about this now.

virustotal analysis for hendi's 4g v83 client: scary virustotal score here

  • as you can see 25/71 (more than a third) of AVs detect it, but they are mostly generic/trojan detections which can trigger from modification of binaries as well as lack of official signing (this is still less than the detection ratio of commonly distributed v83 localhosts which range around 40-50/71 detection ratio)
  • hendi has also been very transparent in their release, including releasing the source of the tool used to remove old school themida as well as instructions and methods on how to do so as seen from the initial ragezone release
  • Therefore, i would say it is most likely safe however, i cannot guarantee the safety of cracked software, so it may be smart to consider virtualizating it
    • There are various OS-level virtualization solutions (or even system level virtualization solutions) you can employ. one such solution is sandboxie https://sandboxie-plus.com/ (i won't name which one i use for personal security reasons but the client setup works like a charm within virtualization)

Troubleshooting

  • Help! my client won't run. instead i get a blank window like here!
    • this is caused by missing dependencies, download and install x86 and x64 versions of the vcredist files here. if it still doesn't work use this DLL dependency debugging tool or this DLL dependency debugging tool that has GUI to find out what else is missing and apply the respective fix
    • beware, sometimes just installing vcredist won't actually put the files in the right folders where they should be, in this case you should find where vcredist installed the files to and manually move them to the right place in your systems folder. You could also search the web for the respective dependencies files, but that is not recommended because stray files from the web may contain viruses.
  • Help! My client crashes to desktop help!
    • this can be caused by having incorrect values in config.ini such as EzorsiaV2WzIncluded=true when your UI.wz doesn't actually contain MapleEzorsiaV2wzfiles.img (the wz modification that came with the patch). since i haven't re-written enough checking functions to make a working try-catch block and are relying on human intelligence to put in the right values. other invalid values there can also possibly cause it if the value is too big for the game to take
  • Help! my settings in config.ini aren't working!
    • this can be caused if you interferre with the comments in the config.ini, like making them too long. at some point the program will automatically read it as a new line with the new line not commented which will cause a parse error and the ini to be unreadable. don't mess with comments there
  • Help! the Ezorsia V2 wz edits are conflicting with my own wz edits!
    • if you want the rest of the Ezorsia V2 edits but want to use your own login frame do ownLoginFrame=true; for using your own cash shop frames do ownCashShopFrame=true; both in optional section of config.ini
  • is any part of the patch not working properly? Download ijl15_Debug.dll from here and rename to ijl15.dll and try using it to see if anything changes (note: dll compiled debug build may require manually moving dependencies to system folders for it to work)

Server related things that might help you

  • when trying to set up MySQL Workbench to attach to the database server make sure to enter the parameters like this (assuming you are using cosmic) (i got stuck on this part, so i recorded it and it might help others)
  • if you are using docker like i am, this guide might also help you as it helped me (contains commands you need)

Disclosure before reading about the development process

The following advice about how to use the tools and edit the client is just from what i've learned over the one month that i have joined the scene and have started working with the client. I have a bit of programming experience but had no experience with C++ prior, nor had any experience with asm or reverse engineering. There may very well be better ways to do things and even my own process is in a constant state of change. This is so far, just what i've managed to scrape together, been taught here and there when folks were feeling generous, and what i've found at the time of writing to have successfully worked. I hope it helps, but always be ready to learn more!

What you need to further develop the client patch

  • To compile the dll yourself, you need visual studio 2019
  • you need the source code of the ezorsia v2 dll
  • you need memory dumps of the client to find addresses in and to inspect the client's mechanisms of operation:
  • IDA 7.0 to view the dumped memory: cracked IDA 7.0 (you dont need whole thing, just the version specific to your os. can also get 7.7 in useful links in maple development discord but newer versions of IDA may not be able to read older IDB files)
    • note: i cannot guarantee the safety of cracked software, so it may be smart to consider virtualizating it
      • There are various OS-level virtualization solutions (or even system level virtualization solutions) you can employ. one such solution is sandboxie https://sandboxie-plus.com/ (i won't name which one i use for personal security reasons but the IDA works like a charm within virtualization)
  • A debugger to view the memory of an actively running client during testing, to see for example, if your codecaves are going to the places they should be going: x32dbg (use x32dbg version)
  • data conversion tools online you should bookmark:
  • you may need other tools along the way but this is the basics of what you will need

How to further develop the client patch (the process)

    1. find a lead to the area of the binary's memory you need to work with to affect the change. To do this you can:
    • find relevant functions using functions area in the fully named v95 IDB
      • you'll need to look for a area with similar functionality in v83 dump later if taking this approach but it can help verify a lot of things and the pseudocode generated in the leaked IDB is often easier to read
    • or use stringpool(enums) to find a related area in memory dump (to find the related string you need to look through wz files)
    • or use an existing address that affects what you're trying to change and looking in the same area
    1. look through the asm in the area you identified in step 1 and use F5 to turn it into pseudocode, can right click in IDA view or pseudocode to synchronize and go to the exact spot in the other one, or look at the bottom left bar that shows which address the cursor in pseudocode is at
    • try to figure out how it works and what you may need to change
      • knowledge and experience of procedural programming is very helpful here because it will determine your efficiency when doing this
    • try to keep track of when things are being initialized and cleared, which value(s) are going where, and how the mechanisms are working together
    • can also right click the function name of subroutines and click list cross-references to and from to see what other subroutines work with it; this sometimes works to find related areas but not all the time
    • can also find more information with xrefs but i don't have much experience doing that
    • try to find the constructor of the function (for example CUIScreenMsg::CUIScreenMsg(CUIScreenMsg *this), constructors are the one that call itself), a lot of stuff is initialized there
    • most of the time, one specific subroutine won't have everything you need (for example your intial lead may lead you to CUIScreenMsg::CUIScreenMsg but CUIScreenMsg::LayoutScrMsg will be where you need to make your changes since the first one calls the second one)
      • flowchart view of the IDA may help with this but i have not use the IDA much in that way
    • you should conclude this part with the address of the start of the asm instructions(s) you want to change, and what you want to change it to. If you're changing a whole section of memory using code caving you also need the return address and the amount of bytes in between the initial address and return address for the NOP count (minimum 5)
      • make sure the address you found does not already exist amongst the edits. to do this press Ctrl+F in visual studio, set the search scope to "current project" and enter the address you found.
        • it would also be a good idea to search for related existing addresses just in case, for example for 00849E39, you would search 00849E3, 00849E, 00849, 0084, and so on. addresses tend to be related to the same areas of functionality when they are close to each other but not always
        • try to make sure you aren't making redundant or conflicting edits if something else is already modifying the same thing. this sometimes requires looking at how the existing edits already work and how they would interact with the asm instructions at the address of the new edit if for example when editing closely related addresses
        • make sure the order of the edits are right. if one edit depends on another to work, make sure the dependant is executed by the C++ code after the one it depends on
    1. test the changes using the appropriate "testing" memory editing functions at the bottom of client.cpp; if doing code caves make sure to fill out the relevant information in the testing code cave in codecaves.h
    • when directly editing memory at an address, you need to make sure the value you enter is appropriate for that part of memory or the game will crash on executing it, pay attention to how many bytes of space you have to work with after the initial offset from the beginning of an asm instruction. a single byte can only be 255 max
    • when code caving you need try to add or modify instructions without affecting the existing instructions taken from the original location of the code cave, nor interferring with variables on the stack, in such a way that the application deems unacceptable.
      • if it is crashing, try to do it gradually, for example, by copying the original instructions in the code cave completely, without any edits, and getting that to work. then making modifications and trying to get those to work
    • you could also use function replacement to use the client's own functions in your own way, or to modify how the original function works if you don't need to make edits in the middle of a function; but i don't have much experience making this working in practice (see notes in source)
    1. compile the dll, replace old one, run the game, and test the changes; if the changes are correct, migrate the information from the line(s) used for testing into their own uniquely named lines of codes

  • note: these instructions may not be easily understood at first, and that's normal. you need a degree of understanding of what is going on before you can do it. so here are some tutorials that helped me along the way:

Tutorials for developing the client patch

These are not in any particular order, though i've tried to put the more advanced ones on the bottom. You will likely have to jump back and forth between tutorials and occasionally restudy them to get a handle of what is happening.

Useful Resources

Below are links to other useful tools, resources, and guides i've collected from since i started improving my singleplayer maplestory experience

Clone this wiki locally