Grasscutter Quick setup guide Java 2022

Grasscutter Current features
  • Logging in
  • Combat
  • Friends list
  • Teleportation
  • Gacha system
  • Co-op partially works
  • Spawning monsters via console
  • Inventory features (recieving items/characters, upgrading items/characters, etc)

Quick setup guide


  • Java SE – 17 (link)Note: If you just want to run it, then jre only is fine.
  • MongoDB (recommended 4.0+)
  • Proxy daemon: mitmproxy (mitmdump, recommended), Fiddler Classic, etc.


Note: If you updated from an older version, delete config.json to regenerate it.

  1. Get grasscutter.jar
  2. Create a resources folder in the directory where grasscutter.jar is located and move your BinOutput and ExcelBinOutput folders there (Check the wiki for more details how to get those.)
  3. Run Grasscutter with java -jar grasscutter.jarMake sure mongodb service is running as well.

Connecting with the client

½. Create an account using server console command.

  1. Redirect traffic: (choose one)
    • mitmdump: mitmdump -s -kTrust CA certificate:​ **Note:**The CA certificate is usually stored in % USERPROFILE%\ .mitmproxy, or you can download it from​ Double click for install or …
      • Via command linecertutil -addstore root %USERPROFILE%\.mitmproxy\mitmproxy-ca-cert.cer
    • Fiddler Classic: Run Fiddler Classic, turn on Decrypt https traffic in setting and change the default port there (Tools -> Options -> Connections) to anything other than 8888, and load this script.
    • Hosts file
  2. Set network proxy to or the proxy port you specified.

you can also use start.cmd to start servers and proxy daemons automatically


Grasscutter uses Gradle to handle dependencies & building.


  • Java SE Development Kits – 17
  • Git
git clone
cd Grasscutter
.\gradlew.bat # Setting up environments
.\gradlew jar # Compile
git clone
cd Grasscutter
chmod +x gradlew
./gradlew jar # Compile

You can find the output jar in the root of the project folder.


You might want to use this command (java -jar grasscutter.jar -handbook) in a cmd that is in the grasscutter folder. It will create a handbook file (GM Handbook.txt) where you can find the item IDs for stuff you want.

You may want to use this command (java -jar grasscutter.jar -gachamap) to generate a mapping file for the gacha record subsystem. The file will be generated to GRASSCUTTER_RESOURCE/gcstatic folder. Otherwise you may only see number IDs in the gacha record page.

There is a dummy user named “Server” in every player’s friends list that you can message to use commands. Commands also work in other chat rooms, such as private/team chats. to run commands ingame, you need to add prefix / or ! such as /pos

CommandsUsagePermission nodeAvailabilitydescriptionAlias
accountaccount <create|delete> <username> [UID]Server onlyCreates an account with the specified username and the in-game UID for that account. The UID will be auto generated if not set.
broadcastbroadcast <message>server.broadcastBoth sideSends a message to all the players.b
coopcoop <playerId> <target playerId>server.coopBoth sideForces someone to join the world of others.
changescenechangescene <scene id>player.changesceneClient onlySwitch scenes by scene ID.scene
clearclear <all|wp|art|mat> [UID]player.clearinvClient onlyDeletes all unequipped and unlocked level 0 artifacts(art)/weapons(wp)/material(all) or all, including 5-star rarity ones from your inventory.clear
dropdrop <itemID|itemName> [amount]server.dropClient onlyDrops an item around you.d dropitem
enterdungeonenterdungeon <dungeon id>player.enterdungeonClient onlyEnter a dungeon by dungeon ID
givegive [player] <itemId|itemName> [amount] [level] [finement]player.giveBoth sideGives item(s) to you or the specified player. (finement option only weapon.)g item giveitem
givechargivechar <uid> <avatarId>player.givecharBoth sideGives the player a specified character.givec
giveartgiveart [player] <artifactId> <mainPropId> [<appendPropId>[,<times>]]… [level]player.giveartBoth sideGives the player a specified artifact.gart
giveallgiveall [uid] [amount]player.giveallBoth sideGives all items.givea
godmodegodmode [uid]player.godmodeClient onlyPrevents you from taking damage.
healhealplayer.healClient onlyHeals all characters in your current team.h
helphelp [command]Both sideSends the help message or shows information about a specified command.
kickkick <player>server.kickBoth sideKicks the specified player from the server. (WIP)k
killallkillall [playerUid] [sceneId]server.killallBoth sideKills all entities in the current scene or specified scene of the corresponding player.
listlistBoth sideLists online players.
permissionpermission <add|remove> <UID> <permission>*Both sideGrants or removes a permission for a user.
positionpositionClient onlySends your current coordinates.pos
reloadreloadserver.reloadBoth sideReloads the server config
resetconstresetconst [all]player.resetconstellationClient onlyResets the constellation level on your currently selected character, will need to relog after using the command to see any changes.resetconstellation
restartBoth sideRestarts the current session
saysay <player> <message>server.sendmessageBoth sideSends a message to a player as the serversendservmsg sendservermessage sendmessage
setfetterlevelsetfetterlevel <level>player.setfetterlevelClient onlySets the friendship level for your currently selected charactersetfetterlvl
setstatssetstats <stat> <value>player.setstatsClient onlySets a stat for your currently selected characterstats
setworldlevelsetworldlevel <level>player.setworldlevelClient onlySets your world level (Relog to see proper effects)setworldlvl
spawnspawn <entityId> [amount] [level(monster only)]server.spawnClient onlySpawns some entities around you
stopstopserver.stopBoth sideStops the server
talenttalent <talentID> <value>player.settalentClient onlySets talent level for your currently selected character
teleportteleport [@playerUid] <x> <y> <z> [sceneId]player.teleportBoth sideChange the player’s
tpallplayer.tpallClient onlyTeleports all players in your world to your position
weatherweather <weatherID> <climateID>player.weatherClient onlyChanges the weatherw


  • Teleporting
    • When you want to teleport somewhere, use the in-game marking function on the map.
      • Mark a point on the map using the fish hook marking (the last one.)
      • (Optional) rename the map marker to a number to override the default Y coordinate (height, default 300.)
      • Confirm and close the map.
      • You will see your character falling from a very high destination, exact location that you marked.

Quick Troubleshooting

  • If compiling wasn’t successful, please check your JDK installation (JDK 17 and validated JDK’s bin PATH variable)
  • My client doesn’t connect, doesn’t login, 4206, etc… – Your proxy daemon setup is most likely the issue, if you are using Fiddler, make sure it running on another port other than 8888
  • Startup sequence: Mongodb > Grasscutter > Proxy daemon (mitmdump, fiddler, etc.) > Game