tbcml 1.1.0

A mod loader for The Battle Cats

TBCModLoader

The Battle Cats Mod Loader (TBCML) is a python module for easily creating and managing mods for the mobile game The Battle Cats.

At the moment the tool is just a library and so you will need to have programming experience if you want to use it effectively.

The tool is very much still a work in progress, I decided to release it early because if I get a proper modding api working, this project will probably be obsolete.

Credits

• EasyMoneko for the original keys for decrypting/encrypting: https://www.reddit.com/r/battlecats/comments/41e4l1/is_there_anyone_able_to_access_bc_files_your_help/
• Battle Cats Ultimate for what some of the numbers mean in various csvs, helping me to figure out animation rendering, and for providing the empty form icons: https://github.com/battlecatsultimate
• This resource for unit csvs: https://pastebin.com/JrCTPnUV
• Vi for enemy csvs

Functionality

Note that most of these features a work in progress and may not work properly.

• Downloading and extracting apks
• Downloading server files and event data
• Decryption and encryption of pack files
• Parsing of various game data files
• Modification of game data
• Frida gadget hooking
• Smali code injection
• Java to smali code conversion
• Patching of libnative-lib.so file
• Modification of apk assets
• Animation Viewer / Loader
• BCU Pack Imports
• Repacking and signing of modified apks
• Randomization of encryption keys so that your pack files cannot be easily decrypted by other people

Note that the scripting functionality is very limited, especially in later game versions. Once I finish the game decompilation I will be able to make a much more powerful modding api.

Discord: https://discord.gg/DvmMgvn5ZB (The server is the same one which is used for save editing as I haven't made a modding specific one yet)

I've spent so much time working on this project because I've changed my mind on what this tool should do and how to structure it, but due to all of the re-writes, it really doesn't look like it. So I would really appricate it if you considered donating to my kofi:

Getting Started

Installation

From pypi

pip install tbcml

If you want scripting (frida or smali patching or libnative patching), you will also need to install tbcml[scripting]

pip install tbcml[scripting]

If you want to use the model viewer, you will also need to install tbcml[ui]

pip install tbcml[ui]

From source

git clone https://github.com/fieryhenry/tbcml.git
cd tbcml
pip install -e .

Basic Usage

You can obviously do more advanced things with this tool, but this is just a basic example of how to use it.

I don't have time to create a bunch of examples and the documentation is not finished, so you'll probably have to read the source code to figure out how to do more advanced things.

Create script.py

from tbcml.core import (
    CountryCode,
    GameVersion,
    Apk,
    GamePacks,
    Mod,
    ModEdit,
    CatFormType,
    Cat,
    CatForm,
)

# Choose the country code
cc = CountryCode.EN

# Choose a game version
gv = GameVersion.from_string("12.3.0")

# Get the apk
apk = Apk(gv, cc)
apk.download()
apk.extract()

# Download server files data
apk.download_server_files()
apk.copy_server_files()

# Get the game data
game_packs = GamePacks.from_apk(apk)

# Create a mod id, or use an existing one
mod_id = Mod.create_mod_id()

# Create a mod, not all information is required
mod = Mod(
    name="Test Mod",
    author="Test Author",
    description="Test Description",
    mod_id=mod_id,
    mod_version="1.0.0",
    password="test",
)

# Define cat information
cat_id = 0
cat_form_type = CatFormType.FIRST

# Create a form with the name "Test Cat"
form = CatForm(cat_id, cat_form_type, name="Test Cat")

# Create a cat
cat = Cat(cat_id)

# Set the form
cat.set_form(cat_form_type, form)

# Create a mod edit
mod_edit = ModEdit(["cats", cat_id], cat.to_dict())

# Add the mod edit to the mod
mod.add_mod_edit(mod_edit)

# Add the mod to the game packs
apk.load_mods([mod], game_packs)

# open the apk folder in the file explorer (optional)
apk.output_path.open()

If you want to do some script modding, you will also need to add the following code at the top of the script. Note that this only has to be done once as it is saved in the config file.

from tbcml.core import ConfigKey, config
config.set(ConfigKey.ALLOW_SCRIPT_MODS, True)

Run the script

Windows

py script.py

Everything else

python3 script.py

Documentation (Not Finished)

https://tbcml-docs.readthedocs.io/en/latest/