treepuncher

an hackable headless Minecraft client, built with aiocraft

Features

persistent storage
configuration file
pluggable plugin system
event system with callbacks
world processing

Quick Start

treepuncher is still in development and thus not available yet on PyPI, to install it fetch directly from git:

pip install "git+https://git.alemi.dev/treepuncher.git@v0.3.0"

currently only 1.16.5 is being targeted, so while simple things should work on any version, more complex interactions may break outside 1.16.5

treepuncher can both be run as a pluggable CLI application or as a library, depending on how much you need to customize its behaviour

as an application

treepuncher ships as a standalone CLI application which you can run with python -m treepuncher

prepare a runtime directory with this layout:

.
|- log/           # will contain rotating log files: MYBOT.log, MYBOT.log.1 ...
|- data/          # will contain session files: MYBOT.session
|- addons/        # put your addons here
|- MYBOT.ini      # your configuration file for one session

create your first addon (for example, a simple chat logger) inside ./addons/chat_logger.py

from dataclasses import dataclass
from treepuncher import Addon, ConfigObject
from treepuncher.events import ChatEvent

class ChatLogger(Addon):
    @dataclass                     # must be a dataclass
    class Options(ConfigObject):   # must extend ConfigObject
        prefix : str = ""
    config : Options               # must add this type annotation

    def register(self):            # register all callbacks and schedulers in here
        @self.client.on(ChatEvent)
        async def print_chat(event: ChatEvent):
            print(f"{event.user} >> {event.text})

create a config file for your session (for example, MYBOT): MYBOT.ini

[Treepuncher]
server = your.server.com
username = your_account_username
client_id = your_microsoft_authenticator_client_id
client_secret = your_microsoft_authenticator_client_secret
code = microsoft_auth_code

; you must specify the addon section to have it loaded,
;  even if it doesn't take any config value
[ChatLogger]
prefix = CHAT |::

run the treepuncher client : python -m treepuncher MYBOT (note that session name must be same as config file, minus .ini)

as a library

under the hood treepuncher is just a library and it's possible to invoke it programmatically

instantiate the treepuncher object

from treepuncher import Treepuncher

client = Treepuncher(
	"my_bot",
	server="your.server.com",
)

prepare your addons (must extend treepuncher.Addon) and install them

from treepuncher import Addon

class MyAddon(Addon):
	pass

addon = MyAddon()
client.install(addon)

run your client

client.run()

Authentication

treepuncher supports both legacy Yggdrasil authentication (with options to override session and auth server) and modern Microsoft OAuth authentication. It will store the auth token inside a session file, to restart without requiring credentials again

to be able to use Microsoft authentication you will need to register an Azure application (see community and microsoft docs on how to do that).

this is a tedious process but can be done just once for many accounts, sadly Microsoft decided that only kids play minecraft and we developers should just suffer...

be warned that Microsoft may limit your account if they find your activity suspicious

once you have your client_id and client_secret use this page to generate a login code: put in your client_id and any state and press auth. you will be brought to Microsoft login page, input your credentials, authorize your application and you will be redirected back to the msauth page, but now there should be a code in the auth code field

put this code in your config and you're good to go!

if you'd rather use classic Yggdrasil authentication, consider ftbsc yggdrasil (src)

legacy Yggdrasil authentication supports both an hardcoded password or a pre-authorized access token

Contributing

development is managed by ftbsc, mostly on our git. If you'd like to contribute, get in contact with any of us using any available channel!

4.5 KiB Raw Permalink Blame History