beetlelib

The canonical Żuczki battle-royale engine, bot contract and training library. Use it to write a bot, train it locally against the native engine, and submit it to the platform unchanged.

pip install beetlelib
beetlelib init my-bot
cd my-bot
python run_local.py

Quickstart

import math
from beetlelib import Bot, Action, Control, Env
from beetlelib.bot.examples.greedy_bot import GreedyBot


class MyBot(Bot):
    def __init__(self) -> None:
        self.ready_to_play()  # finish slow setup before signalling ready

    def act(self, observations):
        actions = {}
        for beetle_id, obs in observations.items():
            # steer toward the nearest food
            target = min(obs.points, key=lambda p: (p.x - obs.me.x) ** 2 + (p.y - obs.me.y) ** 2, default=None)
            angle = math.atan2(target.y - obs.me.y, target.x - obs.me.x) if target else obs.me.angle
            actions[beetle_id] = Action(angle, Control.NONE)
        return actions


env = Env(seed=7, opponents=[GreedyBot(), GreedyBot(), GreedyBot()])
obs, done = env.reset(), False
bot = MyBot()
while not done:
    obs, rewards, done = env.step(bot.act(obs))

The contract

One method, shared by every controller (your bot, the baselines, the live human):

def act(self, observations: dict[str, Observation]) -> dict[str, Action]

You own a pair of two beetles, so you receive two observations (keyed by beetle id) and return two actions. An Action is a steering target_angle plus a Control flag. An Observation is your beetle's vision-bounded view: itself (me), and the nearby beetles, points, rubys, obstacles and projectiles.

See src/template/task.md (ships with the participant kit) for the full rules, the observation/action fields, the limits, and how to submit.

Submit from the command line

Log in once. The password is requested without displaying it and is not saved:

beetlelib login --server https://example.com --username your-name

Then upload bot.py and any other Python files it needs:

beetlelib upload bot.py helpers.py --name my-bot

You can pass a directory instead; all .py files directly inside it will be uploaded. If your class is not MyBot in bot.py, provide its module and class name:

beetlelib upload my-bot/ --name my-bot \
  --command "python -m beetlelib.bot.runner agent:SmartBot"