Battle Cats Mailbox Hack

A hack for the mailbox in Battle Cats. It allows you to get any cat, talent orb, or item amount you want without the ban risk of other methods.

It only works on Android and requires you to install a modded apk, but it does not require root.

The main script uses TBCML, a library I've made designed to make modding the game easier and more automated.

Unlike TBCMS, this hack does not require a server to be running, all of the scripting is done on the device using Frida, specifically Frida Gadget.

Credits

jamesiotio's CITM for the original hacking method and the format of the presents. It no longer works due to PONOS adding a signature to the server responses as well as other changes.
NekoB0x for the original presents json file used for example.json.

Setup

Read the TBCML GitHub page so you can get the library installed (with the scripting dependencies). At the moment you will have to install tbcml from source as the latest release doesn't have all the features needed. See https://github.com/fieryhenry/tbcml#from-source for instructions.
Clone this repository, or just download script.js and script.py manually.
Make sure that the 2 files are in the same directory.
Open command prompt or another terminal and navigate to the directory you downloaded the files to. (You can do this by typing cd <path> where <path> is the path to the directory containing the files.)
Run python script.py to create the modded apk.
You may get Relocation R32 not supported! errors, this is normal and can be ignored (idk how to get rid of them).
If the script fails to pack / sign the apk, then you should change loader.initialize() to loader.initialize(decode_resources=False) near the top of script.py.
Install the modded apk on your device. The script will display the path to the apk file.
The app should be called "Battle Cats Mailbox Hack", it won't be if decode resources is set to false. You can change the name in the script if you want, or just delete that line, it will be near the end of script.py.
Open the game and go to the mailbox. You should see that you have some presents.

Customization

When you run python script.py you can pass in a url to a json file of presents e.g python script.py https://example.com/presents.json. This way you can still setup your own server to host the presents if you wanted to, or just host the json file on GitHub or something.

Alternatively you can pass in a path to a json file e.g python script.py presents.json. There is an example json file in this repository called example.json. It is pretty outdated though, and I can't be bothered to update it. But if you want to update it then please make a pull request. I got the original json file from: NekoB0x

If you use a file path, if you want to modify the presents you will have to run the script again to create a new modded apk and then install it to the device. (If you can figure out how to allow the script to read files from the device's storage then please make a pull request.)

Presents Format

The json file should be an array of objects. Each object should have the following:

"title": The title of the present.
"items": An array of objects. Each object should have the following:
- "itemId": The id of the item.
- "itemCategory": The category of the item. See below for the list of categories.
- "amount": The amount of the item.
- "title": The title of the item. Not really used.
"presentCode" (optional): The present code of the present. Normally would be used by the server to verify that the present is valid. The hack forces the present to be valid so this is not needed.
"body" (optional): The description of the present.
"createdAt" (optional): The date the present was created, should be a timestamp.
"acceptedAt" (optional): The date the present was accepted, should be a timestamp.

Example

[
    {
        "presentCode": 1,
        "title": "Mailbox Hack",
        "body": "Made by fieryhenry and made possible\nby jamestiotio's original work:\nhttps://github.com/jamestiotio/CITM",
        "createdAt": 1574529411,
        "acceptedAt": 1,
        "items": [
            {"itemId": 22, "itemCategory": 0, "amount": 100, "title": "Catfood"},
            {"itemId": 21, "itemCategory": 0, "amount": 20, "title": "Rare Ticket"},
        ],
    }
]

Item Categories

Any game files mentioned are stored in the game_files directory of the repo.

Categories:

0: Items (See GatyaitemName.csv for the list of items, item id 0 is the first item in the list)
1: Cats (See https://battle-cats.fandom.com/wiki/Cat_Release_Order for the list of cats)
2: Item Packs (See itemPack.tsv for the list of item packs)
3: True Forms (Uses the same ids as cats)
4: Talent Orbs (Not really a way to list these since ids are generated programatically using equipmentlist.json, equipmentgrade.csv, attribute_explonation.tsv, equipment_explonation.tsv)

fieryhenry / mailboxhack