# 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 as well as animation rendering: <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](https://github.com/fieryhenry/battlecats) 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:
[](https://ko-fi.com/fieryhenry)
[](https://wakatime.com/badge/user/ab1fc9e5-e285-49d1-8dc6-2f2e0198c8f6/project/0350bd63-7366-48f1-8a0d-72dab553a007)
## Getting Started
### Installation
#### From pypi
```bash
pip install tbcml
```
#### From source
```bash
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`
```python
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()
```
Run the script
Windows
```bash
py script.py
```
Everything else
```bash
python3 script.py
```
## Documentation (Not Finished)
<https://tbcml-docs.readthedocs.io/en/latest/>
Raw data
{
"_id": null,
"home_page": "https://github.com/fieryhenry/TBCModLoader",
"name": "tbcml",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "",
"author": "fieryhenry",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/3a/a9/d9e4227a99a3b53dcf8573859e49c3f67844795125584cb71f84814a8982/tbcml-1.0.1.1.tar.gz",
"platform": null,
"description": "# TBCModLoader\n\nThe Battle Cats Mod Loader (TBCML) is a python module for easily creating and\nmanaging mods for the mobile game The Battle Cats.\n\nAt the moment the tool is just a library and so you will need to have\nprogramming experience if you want to use it effectively.\n\nThe tool is very much still a work in progress, I decided to release it early\nbecause if I get a proper modding api working, this project will probably be\nobsolete.\n\n## Credits\n- 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/>\n- Battle Cats Ultimate for what some of the numbers mean in various csvs as well as animation rendering: <https://github.com/battlecatsultimate>\n- This resource for unit csvs: <https://pastebin.com/JrCTPnUV>\n- Vi for enemy csvs\n\n## Functionality\n\nNote that most of these features a work in progress and may not work properly.\n\n- Downloading and extracting apks\n- Downloading server files and event data\n- Decryption and encryption of pack files\n- Parsing of various game data files\n- Modification of game data\n- Frida gadget hooking\n- Smali code injection\n- Java to smali code conversion\n- Patching of libnative-lib.so file\n- Modification of apk assets\n- Animation Viewer / Loader\n- BCU Pack Imports\n- Repacking and signing of modified apks\n- Randomization of encryption keys so that your pack files cannot be easily\n decrypted by other people\n\nNote that the scripting functionality is very limited, especially in later\ngame versions. Once I finish the [game\ndecompilation](https://github.com/fieryhenry/battlecats) I will be able to\nmake a much more powerful modding api.\n\nDiscord: <https://discord.gg/DvmMgvn5ZB> (The server is the same one which is\nused for save editing as I haven't made a modding specific one\nyet)\n\nI've spent so much time working on this project because I've changed my mind on\nwhat this tool should do and how to structure it, but due to all of the\nre-writes, it really doesn't look like it. So I would really appricate it if you\nconsidered donating to my kofi:\n\n[](https://ko-fi.com/fieryhenry)\n\n[](https://wakatime.com/badge/user/ab1fc9e5-e285-49d1-8dc6-2f2e0198c8f6/project/0350bd63-7366-48f1-8a0d-72dab553a007)\n\n## Getting Started\n\n### Installation\n\n#### From pypi\n\n```bash\npip install tbcml\n```\n\n#### From source\n\n```bash\ngit clone https://github.com/fieryhenry/tbcml.git\ncd tbcml\npip install -e .\n```\n\n### Basic Usage\n\nYou can obviously do more advanced things with this tool, but this is just a\nbasic example of how to use it.\n\nI don't have time to create a bunch of examples and the documentation is not\nfinished, so you'll probably have to read the source code to figure out how to\ndo more advanced things.\n\nCreate `script.py`\n\n```python\nfrom tbcml.core import (\n CountryCode,\n GameVersion,\n Apk,\n GamePacks,\n Mod,\n ModEdit,\n CatFormType,\n Cat,\n CatForm,\n)\n\n# Choose the country code\ncc = CountryCode.EN\n\n# Choose a game version\ngv = GameVersion.from_string(\"12.3.0\")\n\n# Get the apk\napk = Apk(gv, cc)\napk.download()\napk.extract()\n\n# Download server files data\napk.download_server_files()\napk.copy_server_files()\n\n# Get the game data\ngame_packs = GamePacks.from_apk(apk)\n\n# Create a mod id, or use an existing one\nmod_id = Mod.create_mod_id()\n\n# Create a mod, not all information is required\nmod = Mod(\n name=\"Test Mod\",\n author=\"Test Author\",\n description=\"Test Description\",\n mod_id=mod_id,\n mod_version=\"1.0.0\",\n password=\"test\",\n)\n\n# Define cat information\ncat_id = 0\ncat_form_type = CatFormType.FIRST\n\n# Create a form with the name \"Test Cat\"\nform = CatForm(cat_id, cat_form_type, name=\"Test Cat\")\n\n# Create a cat\ncat = Cat(cat_id)\n\n# Set the form\ncat.set_form(cat_form_type, form)\n\n# Create a mod edit\nmod_edit = ModEdit([\"cats\", cat_id], cat.to_dict())\n\n# Add the mod edit to the mod\nmod.add_mod_edit(mod_edit)\n\n# Add the mod to the game packs\napk.load_mods([mod], game_packs)\n\n# open the apk folder in the file explorer (optional)\napk.output_path.open()\n\n```\n\nRun the script\n\nWindows\n\n```bash\npy script.py\n```\n\nEverything else\n\n```bash\npython3 script.py\n```\n\n## Documentation (Not Finished)\n\n<https://tbcml-docs.readthedocs.io/en/latest/>\n",
"bugtrack_url": null,
"license": "",
"summary": "A mod loader for The Battle Cats",
"version": "1.0.1.1",
"project_urls": {
"Homepage": "https://github.com/fieryhenry/TBCModLoader"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b02adcd6626831ee2f1229da17ff03d5d149cad689f1f81b7750e1b2719664f0",
"md5": "1bdee555192af61d6e414fc6765937bf",
"sha256": "4813439c8a6fcc2e04793e37614f3cc4129abf3995670d561e39aa61f62aff18"
},
"downloads": -1,
"filename": "tbcml-1.0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1bdee555192af61d6e414fc6765937bf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 24976879,
"upload_time": "2023-10-06T18:51:26",
"upload_time_iso_8601": "2023-10-06T18:51:26.974723Z",
"url": "https://files.pythonhosted.org/packages/b0/2a/dcd6626831ee2f1229da17ff03d5d149cad689f1f81b7750e1b2719664f0/tbcml-1.0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3aa9d9e4227a99a3b53dcf8573859e49c3f67844795125584cb71f84814a8982",
"md5": "861a137eae9f27583c8bd8f898734523",
"sha256": "3d2b4f96a84ef5660895e7003e345bf7208440f03c549545287754ad7f857ebb"
},
"downloads": -1,
"filename": "tbcml-1.0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "861a137eae9f27583c8bd8f898734523",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 24949978,
"upload_time": "2023-10-06T18:52:20",
"upload_time_iso_8601": "2023-10-06T18:52:20.414758Z",
"url": "https://files.pythonhosted.org/packages/3a/a9/d9e4227a99a3b53dcf8573859e49c3f67844795125584cb71f84814a8982/tbcml-1.0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-06 18:52:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fieryhenry",
"github_project": "TBCModLoader",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "beautifulsoup4",
"specs": []
},
{
"name": "cloudscraper",
"specs": []
},
{
"name": "cryptography",
"specs": []
},
{
"name": "ffmpeg_python",
"specs": []
},
{
"name": "lief",
"specs": []
},
{
"name": "PyQt5",
"specs": []
},
{
"name": "Pillow",
"specs": []
},
{
"name": "pycryptodomex",
"specs": []
},
{
"name": "requests",
"specs": []
},
{
"name": "pyYAML",
"specs": []
},
{
"name": "androguard",
"specs": []
},
{
"name": "moviepy",
"specs": []
}
],
"lcname": "tbcml"
}
JSON
