Setting up your own Arcaea server
Before starting
Make sure you have dumped Arcaea APK/IPA from your device before proceeding.
Obtaining content bundle
Note
Only for Arcaea 5.4.0+ and non-Chinese versions.
Starting from Arcaea 5.4.0, the game now uses content bundle to deliver base contents such as characters and songs. You must obtain this before proceeding.
Obtaining the content bundle will requires you to install Arcaea once and let it finish downloading the bundle (~491 MB).
Tip
Force quit the game AFTER the content bundle is downloaded (before file verification).
After downloading it, steps to get the files will be different depending on your operating system
-
For Android, the content bundle is stored in
/data/data/moe.low.arc/files. Root/custom recoveries (e.g. TWRP) is required to access this directory. Shizuku will not work. -
For iOS, the content bundle is stored in
/var/mobile/Containers/Data/Application/<Arcaea data container ID>/Library/Application Support. Filza or an unsandboxed file manager is required to access this directory.
Copy the dltemp folder to your computer. Inside it should contain 2 files with the same filename: one with .bundle and one with .json.
Patching Arcaea
Note
If you had already patched Arcaea, feel free to skip this section and proceed to Setting up private server.
Using Binary Patches
Before starting
You will need a software that allows applying .xdelta binary patches. DeltaPatcher is used in this guide.
Warning
Android will receive patches for newer versions slower than iOS. As an alternative, try patching it yourself or wait until Android patches is made.
Download the appropriate patch for your version:
Now open DeltaPatcher, you will be presented with an interface like this:
Select the appropriate unmodified executable, and the appropriate patch, then press Apply patch.
After that, you are done!
Manual patching (Advanced)
Before starting
This section requires basic knowledge of disassembling as well as Googling. You will also need a disassembler with support for ELF/Mach-O arm64 executables and pseudo-code decompilation for this section. IDA Pro is used here.
About NOP
1F 20 03 D5 is the hex equivalent of ARM64 nop instruction. Overwrite a hex address with it when you want to remove a specific instruction call.
Open the appropriate executable file for your operating system, and wait for the initial auto-analysis to complete (indicated by the status bar at the bottom showing Idle.) This process may take a while depending on your computer so please be patient.
After the initial auto-analysis, Press SHIFT + F12 and wait for the string list to be generated (again, this may take a while.)
In the Strings sub-window, press ALT + T and search for cookieFiIe.txt until you found exactly this.
Double-click it, and while highlighting this part, press X to perform xref (cross-reference.)
Choose the second xref (for Android) or the only present xref (for iOS) and press ENTER.
Press F5 or View > Open subviews > Generate pseudocode (this will not work if IDA is still analyzing the binary), wait for the decompilation to complete (may take a while) until you see something like this (may differ depending on version used but the general structure should be the same):
Scroll to bottom until you see this part, then highlight it by clicking onto it (names may be different but the structure should remain the same.)
Now switch to the Hex View sub-window, make sure it synchronizes with the Pseudo Code sub-window, and NOP it.
After that, make sure the entire code line is absent when re-decompiled.
Now return to the Strings sub-window, and this time search for vtvtvt.
xref it, and choose the first xref entry for iOS, or the one with @PAGE for Android.
| Android | iOS |
|---|---|
Decompile it again, and scroll down a little bit until you see this part:
Highlight this part, and NOP it like above:
Note
This section is a simplified and slightly adjusted version of this guide.
Switch to the IDA View sub-window, and press Alt + I or Search > Immediate value..., a window like this will show up, enter 408, tick Find all occurrences and then search.
After that, you should see something like this.
Click Instruction to sort it, then scroll up until you found this:
Double-click onto it, then press TAB, F5 or View > Open subviews > Generate pseudo-code and you should see something like this.
Click onto the function name and xref it, choose the only entry in the list.
You will be brought to another function, this time switch back to IDA View and enable synchronization by Right click > Synchronize with > Pseudocode-... After that you should now see something like this, NOP the highlighted part:
Return to the IDA View sub-window, and press Alt + I or Search > Immediate value..., enter 488, tick Find all occurrences and then search. You will see something like this:
Sort it, then scroll up until you found something like this:
Double-click onto it, and switch to pseudo-code view and it should look like this:
Continue repeating the same steps as above: click onto the function name, xref it, switch to IDA View and nop the BL instruction.
After patching the executable, save the file and recompress the APK/IPA file. For Android, you must re-sign the APK file before installing it onto your device. You may now transfer and sideload it onto your device using your favorite method.
Setting up private server
For this section, you will need:
-
Python 3.6 or newer.
-
Charles (recommended), Fiddler Classic or any programs that allows redirecting HTTP requests through a proxy.
-
Time and patience.
Warning
Using any other OSes other than Windows for this may or may not work. You may need to figure stuff out on your own.
First, you need to obtain the server software. We will be using Lost-MSth's Arcaea-server for this purpose. You may obtain it using git like this git clone https://github.com/Lost-MSth/Arcaea-server -b dev or by downloading the ZIP file of the dev branch.
After obtaining the server software, navigate to its directory (<Arcaea-server>/latest version), and with Python 3.6 or newer installed, run pip install -m requirements.txt.
From here, certain steps may differ depending on your operating system and the proxy software you picked. We will be using iOS and Charles in this case but the same can also be done for other similarly functioning software.
Proxy setup
Open Charles and you will be presented with an interface like this:
Press CTRL + SHIFT + L or Proxy > SSL Proxying Settings and tick the Enable SSL Proxying box. After that, click Add, fill * for both Host and Port then press OK, after that untick the newly added box. In the end, the SSL Proxying Settings window should look like this:
Close that window, go to Proxy > Proxy Settings and tweak it exactly like this image:
Navigate to the Windows tab and tick all checkboxes:
Close that window, and go to Help > Local IP Addresses. It will look something like this:
Now, ignore everything with "Virtual" in it (as those are for Hyper-V, Wi-Fi hotspots or ad-hoc networks, all of which has nothing to do with what we are doing). Check what type of internet connection are you using (either Ethernet or Wi-Fi) and then pick the appropriate adapter. In this case, my computer is connected through Ethernet connection, and it has a Broadcom adapter, I will pick the first one.
About local IP addresses
This IP address is not a public IP address, and therefore cannot be accessed from other networks.
You may now close that window and press CTRL + ALT + M or Tools > Map Remote..., tick Enable Map Remote and press Add. Tweak it like this:
In the Map To section, the Host textbox needs to be your local IP address that you got from above, and the Port textbox is a 4 digit number that your server will be running on. Pick any numbers you want except for common ports like 8888 and the two ports that you have put in when setting up the prory above (both HTTP and SOCKS) and memorize it along with your local IP address. Press OK. The map remote interface should look like this in the end:
You may now close that window. At this point, the proxy is now ready.
Server software
The server software directory will look like this:
Copy the config.example.py file into a file named config.py and open it with your favorite text editor.
Most of the config properties should already be self-explanatory. Below is guide for a few important parts.
Remember that local IP address and port that you memorized not long ago? Well enter it here:
HOST is your local IP address and PORT is the port you have choosen earlier.
For GAME_API_PREFIX, this will differ depending on your Arcaea version. Refer to the table below.
| Version | Prefix |
|---|---|
| 5.5.6 -> 5.6.3 | /hanami/29 |
For ALLOW_APPVERSION, remove everything inside. You may add a version to the list (e.g. 5.6.1) if you want to restrict the server to (a) specific server.
For this part:
If you want to use link play functionality, the only variables you need to care about are LINKPLAY_HOST and LINKPLAY_AUTHENTICATION.
-
LINKPLAY_HOST needs to be the same as the IP address you have set in the HOST variable earlier unless the SET_LINKPLAY_SERVER_AS_SUB_PROCESS variable is set to
False, at which you will need to specify a separate IP address for the link play server. -
For LINKPLAY_AUTHENTICATION, you can leave it as-is or type in anything you want.
If you do not want to use link play functionality, the LINKPLAY_HOST variable needs to be an empty string.
For SSL_CERT and SSL_KEY, if you want to have the server running under HTTPS, you may supply an SSL certificate here if you have one (.pem and .key file).
Warning
Running the server under HTTPS may cause issues with downloading packs/songs.
Adjust the rest of the config file to your own likings. Save the file after finished.
Now go to the database folder and it will look like this:
Run the database_initialize.py file to generate the database. Make sure you have installed all dependencies prior to running it in order for it to work. A file named arcaea_database.db will be created if successful. After that, do all of these:
- Put the content bundle you have obtained above into the
bundlefolder. The actual bundle must have the.cbextension and the meta file must have the.jsonextension. Both must have the same filename (e.g.5.6.0).
Note
The content bundle in the server must be the same as the one existing in your Arcaea client (the metadata and content MUST match) as otherwise you will encounter issues when trying to login. If you change the content bundle in the server, the one on the client must be re-downloaded.
To avoid issues, use the content bundle that you have obtained earlier.
- Put all charts into the
songsfolder. Each chart is a folder containing at least 3 .aff files (PST/PRS/FTR difficulties, some may also contain additional .aff files for BYD/ETR difficulties), thebase.oggfile (the song itself), PV video (separated into video and audio files respectively EXCEPT for Arghena which only contains the video in two resolutions 720p and 1080p, one will be downloaded by Arcaea client depending on the graphic setting) and all additional files required by it.
Note
When attempting to play a song that is not in the default Arcaea pack, the game will prompt the player to download it from the server. If the chart folder itself or any of the required files are missing, the download will fail. All required files, song, and difficulties are defined in the songlist file bundled in the content bundle. For more details please refer to the respective Custom Charts & Packs page.
- Make any adjustments you want to make (e.g. adding World Mode maps, adding courses, etc...)
At this point, the server software is now ready.
On device setup
Note
Your phone and your computer (the one that runs the server) MUST be connected to the same network for the server to work. If you want to publicize your server, port forwarding or a VPS/cloud serve is required. Setting this up is (at the moment) out of scope for this guide.
Pick one of the methods you want to use.
Info
This is the recommended method; however, it involves using a paid app. Other similarly functioning proxy apps may also work with some configuration. If you do not want to install anything or simply do not wish to use a paid app, considering checking out the Wi-Fi Proxy Settings method instead.
Firstly, install Shadowrocket onto your device.
Now open it, and press on the + icon on the upper right of the interface. Press Type and select Socks5 (without the TLS part). In the Address field, enter your local IP address. In the Port field, enter 8889 (adjust if you have set a different port during proxy setup, specifically, the port for the SOCKS server), press Save while leaving everything else as-is. Press Global Routing and change it to Proxy, return to the main interface and enable the proxy. iOS will prompt you to allow VPN connection, press Allow and authenticate if needed. The VPN icon will show up on your status bar, indicating that you are now connected to the proxy. Press Connectivity Test to check if the connection is working properly.
Info
The alternative method. Requires re-configuration for new Wi-Fi networks.
Open the Settings app, go to Wi-Fi settings, press the ! icon on the connected network, scroll down until you found the HTTP Proxy settings. In the Configure Proxy settings, select Manual and fill in the Server field which is your local IP address and the Port field which is 8888. Now press Save and (optionally) turn off and reconnect to your Wi-Fi network.
Your device should now be connected to the proxy.
On your computer, return to Charles and go to Help > SSL Proxying > Install Charles Root Certificate on a Mobile Device or Remote Browser. A window like this will show up:
Follow the steps listed in it to install the Charles certificate onto your device. You will also need to go to Settings > General > About > Certificate Trust Settings and enable full trust for the newly added certificate for it to take affect.
Go back to Charles and go to Help > SSL Proxying > Save Charles Root Certificate... Save the .pem file somewhere. Rename the .pem extension to .crt. Now transfer this file to your Android device and install it to the VPN & Apps category.
On Android, you will need to rely on a proxifier app such as VProxid or RProxid (requires root, recommended).
After installing either of the proxifier app, open it and press the + icon, for Server IP, enter your local IP address; for Server Port, enter 8889. Scroll down a little bit and press Click to select application(s) then tick Arcaea. Now return and press the play button to start the VPN. Wait until it shows all good.
Now your device is ready to connect to the private server!
Note
Disable the proxy when you have finished playing to prevent connectivity issues. The proxy will need to be re-enabled everytime you want to use the server. A dedicated 24/7 server such as a Raspberry Pi, a spare phone/computer with working shell, or a cloud server (VPS) is recommended for always-on server hosting.
Playing
Return to the root directory of your server and run the run.bat file. It may take a while to start depending on the amount of songs you added. If the server console shows this:
Congratulations! Your server is now up and running! Now all that left is open Arcaea and play!
If you see something like this, it means the server is working as intended.
At this point, you are basically done! Enjoy your new server!
Fixes for notable issues
The game kept prompting to update a pack despite having already downloaded it.
-> Check the song folders to see if they are named correctly and that all files (plus PV videos and audios if exists) are inside.
Cannot download any songs.
-> Make sure the server is running under HTTP connection. For iOS, you may need to edit the Info.plist file using a plist editor to allow HTTP connection without a jailbreak by setting NSAllowsArbitraryLoads property to true.
Nothing works, even logging in.
-> Check if the GAME_API_PREFIX variable in the config.py file is set correctly. If that did not work, make sure you have set up the proxy correctly (refer to the Proxy setup and On device proxy setup section.)
Potential system not working.
-> In order to make potential work, you will need to add the charts data onto the server database with the appropriate difficulty constant. Refer to the respective Custom Charts & Packs page for more info.