grasscutter user guide—Android/Windows/IOS are all supported

foreword

grasscutter is an open source backend of a 2D mobile game. Currently, its functions are not complete, but it is being developed by contributors at full speed, and the future can be expected. It can be deployed under linux and windows, and interact with clients of various platforms through a proxy. This article provides the Linux-side deployment of grasscutter (the windows side is relatively simple), and the client connection guidance of the windows/andriod/ios side. Among them, Android provides solutions for both rooted and non-rooted machines. This article needs to have a certain computer foundation, not for beginners, try to be as detailed as possible, the explanation part may contain simple shell commands, execute it yourself, do not provide one-click installation scripts, and do not provide completed servers, suitable for players who love tossing , I don't want anyone to profit from this, technical exchanges are welcome, and you can ask questions.

The key breakthrough point is the installation of mitmproxy on the Android client's ca certificate. Android can use vmos to obtain a rooted virtual machine (vmos should not be downloaded in the app store, it has key functions, so go to the official website to download it. The root function requires vip, and Cixi prepaid version, if you don’t want to spend money, you can find it yourself)

renew

The current dev version has been updated to the secret realm and the abyss, and the big world supports online.

Key words

SSL, CA certificate, grasscutter, a two-dimensional game, proxy forwarding, http injection, Android, IOS, windows

Environmental preparation

It's coming on the 17th
mongodb 4.0+
mitmproxy

Environment preparation please solve by yourself

Linux server construction (centos7)

1. git pulls or directly downloads the source code, and uploads it to the server, decompresses it with tar -xzf

git clone -b development https://github.com/Grasscutters/Grasscutter.git

Pay attention to the downloaded dev version (if the compilation fails and you don’t want to debug, you can change the stable version)

1. Turn off the firewall or configure the release policy (note that in addition to the regular ports, port 22102 of TCP and UDP should be released)

systemctl stop firewalld

I am more direct, 23333. If it is a cloud server, remember to go to the console to configure the security group policy. 90% of the problems on the server side come from here.

2. Start mongodb, how to start mongodb under Baidu linux by yourself, this is basically no problem, if there is a 27017 port problem or a similar error report of mongodb, it is mostly because the mongo service is not started or hangs up.

Here is a tutorial , just start the mongodb service and verify it.

3. To compile, it is necessary to automatically compile the script with gradle in the java17 environment, and the execution is over.

sh gradlew jar

The execution time depends on the server configuration. If there is an error, please check your java environment and network environment, and make good use of Du Niang

After the compilation is successful, a jar file beginning with grasscutter (plus version number) will be generated in the main directory of grasscutter, and run directly

java -jar grasscutter-1.1.0.jar #1.1.0是我下载的版本

It will prompt that there is a lack of resource files, and create a resource file directory for you (resources, if you haven’t created it, create it yourself), and you need to download the content inside.

4. Download resource files

github address

Note: This warehouse has a high probability of being stopped by github, pay attention to backup, the reason is not much to say, dddd.

git clone https://github.com/memetrollsXD/Grasscutter_Resources.git

Copy all the files under Resources to the resources folder under the grasscutter root directory, including BinOutput, ExcelBinOutput, Readable, Scripts, Subtitle, TextMap

5. Start the server

Modify the configuration file config.json

{
  "DatabaseUrl": "mongodb://localhost:27017",
  "DatabaseCollection": "grasscutter",
  "RESOURCE_FOLDER": "./resources/",
  "DATA_FOLDER": "./data/",
  "PACKETS_FOLDER": "./packets/",
  "DUMPS_FOLDER": "./dumps/",
  "KEY_FOLDER": "./keys/",
  "SCRIPTS_FOLDER": "./resources/Scripts/",
  "PLUGINS_FOLDER": "./plugins/",
  "DebugMode": "NONE",
  "RunMode": "HYBRID",
  "GameServer": {
    "Name": "Test",
    "Ip": "0.0.0.0",
    "PublicIp": "your public ip",
    "Port": 22102,
    "PublicPort": 0,
    "DispatchServerDatabaseUrl": "mongodb://localhost:27017",
    "DispatchServerDatabaseCollection": "grasscutter",
    "InventoryLimitWeapon": 2000,
    "InventoryLimitRelic": 2000,
    "InventoryLimitMaterial": 2000,
    "InventoryLimitFurniture": 2000,
    "InventoryLimitAll": 30000,
    "MaxAvatarsInTeam": 4,
    "MaxAvatarsInTeamMultiplayer": 4,
    "MaxEntityLimit": 1000,
    "WatchGacha": false,
    "ServerNickname": "Server",
    "ServerAvatarId": 10000007,
    "ServerNameCardId": 210001,
    "ServerLevel": 1,
    "ServerWorldLevel": 1,
    "ServerSignature": "Server Signature",
    "WelcomeEmotes": [
      2007,
      1002,
      4010
    ],
    "WelcomeMotd": "Welcome to Grasscutter emu",
    "WelcomeMailTitle": "Welcome to Grasscutter!",
    "WelcomeMailSender": "Lawnmower",
    "WelcomeMailContent": "Hi there!\r\nFirst of all, welcome to Grasscutter. If you have any issues, please let us know so that Lawnmower can help you! \r\n\r\nCheck out our:\r\n\u003ctype\u003d\"browser\" text\u003d\"Discord\" href\u003d\"https://discord.gg/T5vZU6UyeG\"/\u003e",
    "WelcomeMailItems": [
      {
        "itemId": 13509,
        "itemCount": 1,
        "itemLevel": 1
      },
      {
        "itemId": 201,
        "itemCount": 10000,
        "itemLevel": 1
      }
    ],
    "EnableOfficialShop": true,
    "Game": {
      "ADVENTURE_EXP_RATE": 1.0,
      "MORA_RATE": 1.0,
      "DOMAIN_DROP_RATE": 1.0
    }
  },
  "DispatchServer": {
    "Ip": "0.0.0.0",
    "PublicIp": "your public ip",
    "Port": 14514,
    "PublicPort": 0,
    "KeystorePath": "./keystore.p12",
    "KeystorePassword": "123456",
    "UseSSL": true,
    "FrontHTTPS": true,
    "CORS": false,
    "CORSAllowedOrigins": [
      "*"
    ],
    "AutomaticallyCreateAccounts": false,
    "defaultPermissions": [
      ""
    ],
    "GameServers": []
  },
  "LocaleLanguage": "en_US",
  "DefaultLanguage": "en",
  "OpenStamina": true
}

In fact, you only need to modify two publicips to your public network ip, and if you don’t want to use port 443, just modify DispatchServer.port. Note that if you modify here, the configuration of mitmdump below also needs to be modified synchronously. For other options that do not involve the Internet, you can change them yourself.

(The port I opened is a bit smelly, 23333)

Execute the start command again

java -jar grasscutter-1.1.0.jar

It shows that the game server is running on port 22102, and the forwarding server is running on port 14514, which means success.

At this time, refer to the command table and enter the account creation command in the shell window

account create echidna 114514233

It will prompt that the account is created successfully.

QA

java compilation failed

To list a few possible causes I've come across,

1. The java environment is not properly configured, which is the most unlikely error, but still check it, enter java --version to see if it is a version at 17:00, and it is not a quick change.
1. Network problem, the compilation process will install gradle and a series of jar dependencies for you, check where the card is stuck, download it and import it yourself.
1. Memory problem, compiling requires a lot of memory, the actual measured memory is 512MB failed, 2G is successful, at least 1G memory is required for running, (I originally wanted to use a vps server, but the vps configuration is poor, so I didn’t compile it, hahaha)
1. It is a normal phenomenon that the dev version fails to compile and build. You can either adjust it yourself or change to the stable version.
1. The above are the problems I have actually encountered. If you still can’t solve it, you can use Baidu yourself. I am a C++ engineer. Java is a bit of a professional blind spot.

program failed

1. Make sure that your resources directory normally exists in the same directory as the entry jar file generated by compilation, and that the contents are complete.
1. Make sure that the json format of your config.json file has not been damaged, such as deleting an extra quotation mark by hand (some people are so stupid, who is it, it can’t be me?)
1. Confirm that your mongodb daemon process is normal, ps -aux | grep mongod
1. Confirm that there is no program occupying your port, netstat -tunlp | grep <the port you set, the default is 443>, the common prisoner under Linux is called ngnix, and the common prisoner under Windows is called vmware, focus on checking.
1. Make sure your available memory is greater than 1G
1. If the password is wrong, you can change the DispatchServer.KeystorePassword in config.json to empty (it was originally empty and changed to 123456, the keys of each version may be placed differently, anyway, one of the two is always correct).

6. Configure packet capture and http injection

Here we use mitmproxy. I have seen many people use fiddler, but fiddler is a program developed based on .net, and it is not convenient to port it to linux.
You can use pip3 to install directly, and install yum without python3.

pip3 install mitmproxy

Will install mitmproxy and its command-line version, mitmdump, and its multi-version ca certificates for you
You can also go to the official website to download the binary version, but without the CA certificate, you need to open the proxy after the deployment is complete and visit mitm.it to download, but domestic cloud servers do not allow domain names to be forwarded to unregistered domain names, so it will be more troublesome.

After the installation is complete, we go back to the main directory of grasscutter

  vim proxy_config.py

Modify the configuration file as follows:

  import os

  # This can also be replaced with another IP address.
  USE_SSL = True
  REMOTE_HOST = "your public ip"
  REMOTE_PORT = 14514

  if os.getenv('MITM_REMOTE_HOST') != None:
      REMOTE_HOST = os.getenv('MITM_REMOTE_HOST')
  if os.getenv('MITM_REMOTE_PORT') != None:
      REMOTE_PORT = int(os.getenv('MITM_REMOTE_PORT'))
  if os.getenv('MITM_USE_SSL') != None:
      USE_SSL = bool(os.getenv('MITM_USE_SSL'))

  print('MITM Remote Host: ' + REMOTE_HOST)
  print('MITM Remote Port: ' + str(REMOTE_PORT))
  print('MITM Use SSL ' + str(USE_SSL))

Note that the REMOTE_PORT here should be consistent with the port of the dispatch server you modified above.

Configure ca certificate

cp ~/.mitmproxy/mitmproxy-ca-cert.crt /etc/ssl/certs # 这句是安装为根证书，未必需要
cp ~/.mitmproxy/mitmproxy-ca-cert.pem /etc/pki/ca-trust/source/anchors
update-ca-trust extract

Perform forwarding. Here comes the important point, there are many problems in the Android proxy of mitmproxy, and a series of parameters need to be added to avoid them, and this part is not mentioned in most tutorials
```
mitmdump -s proxy.py --ssl-insecure --set block_global=false --no-http2
```
Allow insecure ssl connections, disable http2 connections, and disable direct internet access to mitmproxy,.

At this point, the proxy server will start on the default port 8080, please also ensure that the port does not conflict.

login on windows

Configure ca certificate

Take the mitmproxy-ca-cert.p12 file under the ~/.mitmproxy folder on the server side to the windows machine, double-click it directly, and choose to install it on the local computer. If you want the password to be blank, just select the directory automatically, and restart the machine.
The windows side supports the client login of national and international servers. The method is very simple. Open the network and Internet settings, select the proxy, open the manual setting proxy option, fill in the address and port, which is the port of publicip and mitmdump you set above (default 8080 that).
Open the client and log in directly with the account password you created.

QA

Why does my client prompt a network exception?

The proxy port is incorrect. It is recommended to check whether your mitmproxy is alive and whether the port number is correct.
Why 4206?

Probably there is a problem with the installation of the certificate. Either you have not installed it globally, or you can pull out another p12 file in the mitmproxy directory above and install it. It has not been verified whether the certificate under grasscutter needs to be installed. You can try to install that The keystore.p12 file under grasscutter.
The network is very unstable after connecting

Your server bandwidth problem.
Login to display 12-4301

It is recommended to switch to the US service channel to log in
Why did I find that the server of my nohup background program was blown up?

If the hard disk is blown up and ssh cannot be connected, first go to the console to restart. First, nohup must be redirected to dev/null, and there is a bug in grasscutter, which will write latest.log to the log folder of the main directory crazily. Currently, no relevant options are found in config.json. I am too lazy to find it in the code. , directly choose to delete latest.log.
other problems

Check if you have science online or something, turn it off.

IOS login

Search how to install the ca certificate on ios by yourself. The ca certificate we want to install is mitmproxy-ca-cert.pem in the ~/.mitmproxy directory. Note that after the download is complete, you need to find this file, click it, and then execute the two steps of certificate installation. steps (install first, then trust).
Do not use small rockets, there will be bugs, the reason is very simple, small rockets will not forward udp packets, but our grasscuter relies on the udp protocol such as kcp.
The IOS side was successful, and no problems were encountered. If there is a problem, the solution should be similar to the above-mentioned windows side.

Android login

It is more complicated than the above. The main problem is that after Android 7.0, the application can choose not to trust the user certificate, but unfortunately the mobile game app is set to be untrusted. Based on this, I came up with three solution.

magisk is commonly known as mask root, but I don’t have a backup machine, so I don’t plan to wipe my normal mobile phone, so I don’t think about it.
Change the package, set it to accept user certificates, and then repackage, it is worth a try.
Use a virtual machine, that is, an Android emulator.

At first glance, the third point is a very abstract idea, which means installing an Android emulator on the Android machine, isn't it funny. But after searching, there is really such a thing, vmos pro.

As for how to fix this thing, there should be no technical difficulty. Just pay attention to the precautions about vmos pro I said before, and Baidu will solve the rest.

When we have a rooted virtual machine, I need to install the ca certificate in the system directory. For this purpose, openssl is required to make the Android system ca certificate.


yum install openssl
openssl x509 -inform PEM -subject_hash_old -in mitmproxy-ca-cert.pem -noout
cp mitmproxy-ca-cert.pem c8750f0d.0 # 这边的c8750f0d是上一条命令的输出。

Put this file under /system/etc/security/cacerts/, and modify the permission to 644

In the settings, press and hold the wifi you are connected to, choose to modify the network, set the proxy, and the same requirements as other clients above.

Just connect, note that an international server client is required.

epilogue

I am a C++ engineer in the network direction. I thought it could be solved overnight, but I still spent a lot of time studying it. After all, I have to run the dev version of java code (the version I ran had problems with 2333), and a bunch of ca The certificate problem, finally all the clients got it done, and set up a server to play with friends. In order to prevent all hidden dangers of infringement and shield justice rangers, the article will not show pictures, but the nodes that should be mentioned have been mentioned. If you need technical support, please leave a message in the comment area. There is no charge for technical support. I will answer anything that can be solved in a few words ( As long as you are not a novice, most of the problems fall into this category), if you want to make a profit, please do not disturb (I saw a screenshot of a group friend before, roughly speaking, there was a seller named Bao98 selling private servers, but the buyer joined the group, and the seller Said that both windows and ios have been solved, let everyone wait for the solution on the Android side, laugh dead).

Regarding the issue of private servers, I have a rotten attitude, as long as I don’t take advantage of it to make a profit, and making a profit is purely reaping the seeds of injustice. After all, this is a game that focuses on exploring the big world. Private servers lack your core gameplay, so you are destined to just entertain yourself. If a private server with only simple card draws and dungeons can really kill you, shouldn't you think about your own game problems (not referring to your game)? Obviously, this kind of private server can't stir up any waves.