Skip to content

v83‐Client‐Setup‐and‐Development‐Guide

Jump to bottom
Ro edited this page Nov 22, 2023 · 51 revisions

v83 Client Setup and DLL client Development Guide for modern HD monitors

Table of Contents

Core Setup

This setup guide is for an open source v83 DLL client 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 install the game. Instead of using the provided localhost nor deleting anything from the default installation, download the following:

  • compiled ezorsia v2 DLL from releases; follow the instructions in the readme to install it (source is also released for transparency and development)
  • default v83 client with admin elevation request removed, and 4G flag enabled this is the only 2 edits that was made to the binary directly because i could not get it to work from the dll
    • The 4g flag activates the "large address space aware" (LAA) flag in the PE header. This will allow the client to use up to 4 GB of memory instead of only 2.
      • if you would rather do the edit yourself for verification purposes will need the client that came with the installation (reinstall if you deleted or just use the provided one here) you will also need the to use the hex editor from cosmic files here and make the following edits:
        • shown here(only do the first "asInvoker" part, my dll will handle the rest because you can't edit those actual offsets in a packed client).
          • after you edit the admin part you may have to rename the executable to "MapleStory2" or some other name, i have been getting reports that it won't actually remove elevation if it is named the default name for some reason
        • and shown here Note that for the 4g flag in header the default is "0f", you need to change it to "2f". the address is 0000013E if for some reason you cannot load the instructions
  • 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
  • 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 of core setup)
(end of core setup)
(end of core setup)

(as of 2023/11/21 you no longer need this, but i'm keeping it around for reference. Ezorsia V2 now uses its own custom WZ/IMG that won't conflict with any server's files) 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

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.

  • use of a older released executable application localhost:

    • i recommend just using the client that comes with the default game installation with this dll, but if you really want to use a older released executable application localhost please see the End User Safety (outdated) section below
      • i would not recommend using any other executable application localhost than hendi's if you must use one

  • use of an Ezorsia V2 and Ezorsia-V2-like releases(projects that use Ezorsia V2 as a base) from third parties that do not disclose their source (preferably only download from my Ezorsia V2 releases, or compile it yourself from the source)

    • this is risky because as the creator of Ezorsia V2 i must tell you that the project employs some powerful capabilities in the Windows API that third parties could potentially use, to turn it into a malware. Even if they don't intentionally turn it into a malware, it could still do some annoying things if they misuse it, either by accident or intentionally (for a full list of capabilities, try running the release's DLL through virustotal and seeing the the "behaviors" tab)
      • the base dll interacts with windows api functions by hooking several and natively uses several potentially dangerous ones including the ability to drop files (i added this because i noticed a lot of ppl finding it inconvenient to follow the full instructions and just want to download and play, so i put everything into the DLL and allow it to generate on run), and ability to create a process
        • natively, Ezorsia V2 should only be generating it's config and WZ file (both in game directory), and IMG file in Data folder (if using IMG). But i cant promise third parties wont change it to drop bad stuff
        • natively, Ezorsia V2 should only be creating a process to hard-restart itself if WINAPI create window fails for indeterminate reasons (this is failing on the WINAPI side for default packed clients, and has no other fix that ive found). i can't promise third parties wont use this to execute malicious processes, perhaps after dropping a .exe (the preceding mentioned capability)
      • hooks dinput8.dll; Ezorsia V2 hooks dinput8.dll because its the second earliest dll the game uses and this is often used for game mods, but it is important to note that the creation of a DirectInput object could potentially be used to log keys
        • natively Ezorsia V2 only exports the hooked dinput8.dll functions back out to emulate the real dll without further modification, but if you notice modifications to these exports functions and them becoming real hooks/overwrites/rewrites, then that is cause for concern because it could be used to intercept keystrokes. sometimes modders will do this to re-map keys, but be extremely wary
    • if you have any concerns about the binaries in the releases section themselves, you can download the source and follow the compilation instructions to generate your own binary which you can verify is the same as the one in the releases section
      • if you have concerns about the code itself you can download the source and inspect it, you can still do this without much programming knowledge by feeding the code into GPT and asking it what the code is doing
        • i try to ensure that my release is as safe as possible for the end user, but i understand that trust is hard to come by, words are worthless, and that actions speak louder so i have released the source to give you these options
    • all-in-all do not download Ezorsia V2 and Ezorsia-V2-like releases(projects that use Ezorsia V2 as a base) from third parties unless you know you can completely trust them with your (computer's) life
      • or if you do download third party-provided Ezorsia V2 and Ezorsia-V2-like releases, nicely ask them to provide the source code if you have any concerns. One primarily reason Ezorsia V2 is licensed under a AGPL-license is for end user transparency, and they are obligated to use the original license terms and also provide you with this transparency

  • very risky use cases: loading themida'd/vmprotected DLLs ripped from other servers:

    • Ezorsia v2 has the potential to force other "private" dlls to work for any server or player because my non-Windows API hooks/edits are applied after the additional dlls specified by the end-user are loaded, and my release overwrites a lot(maybe all but idk) of the initialization protections put in by NXXXON, so if the "private" dlls repurposed those same protections then those protections will be overwritten.
      • however, other non-protection related useful stuff may also be overwritten so for specific use cases i recommend you adjust the function loading orders yourself to ensure maximum compatibility and recompile from my source
    • however, i recommend caution when using my release to load sourceless dlls, it's easy to hide bitcoin miners in themida'd/vmprotected dlls so you could be infecting yourself(or your entire community(and you will be responsible in this case) if running a server) by doing it and re-distributing sourceless, packed, potentially malicious content)
      • virtualization solutions may protect your system from permanent damage but it won't stop things like bitcoin miners from still using your CPU to mine coin because unfortunately you have to allow internet access for the program in order for it to work (if you aren't playing singleplayer like me)
        • even if you "test" the "sourceless, packed, potentially malicious content" you likely won't be able to ensure it's safe unless you're a real security expert (trust me, i've tried). Miners and other malware can often be designed to detect a debug environment or virtualized setting, which many in the private server community are likely skilled enough to implement because verification and anti-cheat measures also do this kind of thing. Miners and other malware can also just long sleep, sometimes randomly, and don't deliver the payload until after a set amount of time, so a brief debug session or execution in a virtualized environment won't find anything.
    • all in all, don't take the risk, don't use "sourceless, packed, potentially malicious content", this release is here for you so you don't have to bend over and take that risk

End User Safety (outdated)

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 DLL client). 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! / i get config.ini error
    • 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 CustomLoginFrame=true; for using your own cash shop frames do ownCashShopFrame=true; both in optional section of config.ini
  • Help! the Ezorsia V2 dll edits are conflicting with edits from my own dll!
    • if you want the rest of the Ezorsia V2 dll edits but want to use your own dll by loading it with Ezorsia v2 you need to check for address and function hook conflicts in the Ezorsia v2 source if you aren't already using it as a base. Please refer to how to do that here(search conflicts).
  • Help! i get hackshield error/operation completely successfully/other startup error (when using default installation client with the dll)
    • usually only happens if you are loading custom dlls; if you are loading custom dlls try to change sleepTime option # in config.ini because loading is time-sensitive and ppl may load the game at different rates. this number determines how long Ezorsia v2 waits before attempting to apply non-Windows API hooks/edits; it is necessary in the default packed client because interferring with the main thread there may result in themida killing the process, this option allows the user to wait until themida fully unpacks, but before the game actually runs, and then patch at the right time
    • if you aren't using any custom dlls and get any startup error please report it in discord (link in my github profile). non-dll compatibility startup errors involving themida and checks should be fixed

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 DLL client

  • 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 DLL client (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 DLL client

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