Bot Development

Bot SDK (required for all bots)

pip install pachinko-sdk

No external dependencies. Python 3.9+ required. The SDK is pure Python — it handles the stdin/stdout protocol between your script and the game client.

Gym package (RL training only)

Training RL bots also requires pachinko-gym, which ships as a pre-built binary package (the game simulation runs in compiled Rust — no source build needed):

pip install pachinko-gym stable-baselines3 sb3-contrib

Minimal example

from pachinko_sdk import Bot, run, AttackMove, ToggleSpawn

class MyBot(Bot):
    def on_game_start(self, data: dict) -> None:
        self.player_id = data.get("player_id", 0)

    def on_tick(self, state) -> list:
        actions = []

        # Keep all military buildings spawning
        for b in state.my_buildings:
            if b.kind in ("squarracks", "circhery", "triables"):
                if not b.spawn_toggle:
                    actions.append(ToggleSpawn(b.id, True))

        # Attack-move idle units toward the nearest enemy building
        if state.enemy_buildings:
            target = state.enemy_buildings[0]
            for unit in state.idle_units():
                actions.append(AttackMove(unit.id, target.x, target.y))

        return actions

    def on_bet_round(self, data: dict):
        # Call if the bet is small, fold if expensive
        to_call = data.get("current_bet", 0) - data.get("committed", 0)
        bankroll = data.get("chips", 1)
        if to_call == 0 or to_call / bankroll < 0.10:
            return {"type": "call"}
        return {"type": "fold"}

if __name__ == "__main__":
    run(MyBot())

Counter-unit production

Count the visible enemy unit types and spawn the counter. Square beats Triangle, Triangle beats Circle, Circle beats Square.

def on_tick(self, state) -> list:
    actions = []

    # Count visible enemy types
    sq = sum(1 for u in state.enemy_units if u.unit_type == "square")
    ci = sum(1 for u in state.enemy_units if u.unit_type == "circle")
    tr = sum(1 for u in state.enemy_units if u.unit_type == "triangle")

    if tr > max(sq, ci):
        primary = "squarracks"   # squares beat triangles
    elif sq > max(ci, tr):
        primary = "circhery"     # circles beat squares
    else:
        primary = "triables"     # triangles beat circles

    for b in state.my_buildings:
        if b.kind in ("squarracks", "circhery", "triables"):
            actions.append(ToggleSpawn(b.id, b.kind == primary))

    return actions

Buying upgrades

# Upgrade types: "spawn_rate", "weapon_damage", "armor", "move_speed", "mining_rate"
from pachinko_sdk import Upgrade

def on_tick(self, state) -> list:
    actions = []
    RESERVE = 600   # keep this much hematite in reserve

    for b in state.my_buildings:
        if b.kind == "squarracks":
            if b.upgrades["spawn_rate"] < 5 and state.resources > 300 + RESERVE:
                actions.append(Upgrade(b.id, "spawn_rate"))
        if b.kind == "hematite":
            if b.upgrades["mining_rate"] < 5 and state.resources > 400 + RESERVE:
                actions.append(Upgrade(b.id, "mining_rate"))

    return actions

Bot lifecycle methods

GameState fields

Unit fields

Building fields

ResourceNode fields

Actions

Betting round data

The on_bet_round(data) dict contains:

Return one of:

{"type": "call"}                    # match the current bet
{"type": "fold"}                    # exit this betting round
{"type": "raise", "amount": 200}   # raise by this amount
{"type": "allin"}                   # go all-in

Install

pip install pachinko-gym

Train offline

Use any RL library. The example below uses MaskablePPO from sb3-contrib, but you are free to use any algorithm or framework.

from pachinko_gym import PachinkoTrainEnv
from sb3_contrib import MaskablePPO

env = PachinkoTrainEnv(num_players=8)

model = MaskablePPO("MultiInputPolicy", env, verbose=1)
model.learn(total_timesteps=5_000_000)
model.save("my_rl_bot")   # saves my_rl_bot.zip (SB3 format)

Observation space

The environment exposes a Dict observation with PointNet-style feature arrays — the same information available in on_tick:

Write your bot script

After training, write a normal bot script that loads your model and runs inference each tick. The example below uses SB3, but the pattern works for any framework.

import sys
import os
import numpy as np
sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "bot-sdk"))

from pachinko_sdk import Bot, run, AttackMove, ToggleSpawn
from sb3_contrib import MaskablePPO
from pachinko_gym import obs_from_state, actions_from_output  # your own helpers


class RLBot(Bot):
    def on_game_start(self, data: dict) -> None:
        # Load weights once at game start — not every tick
        self.model = MaskablePPO.load("my_rl_bot.zip")

    def on_tick(self, state) -> list:
        obs = obs_from_state(state)          # convert GameState to numpy obs dict
        action_vec, _ = self.model.predict(obs, deterministic=True)
        return actions_from_output(action_vec, state)  # decode to SDK actions

    def on_bet_round(self, data: dict):
        return {"type": "call"}


if __name__ == "__main__":
    run(RLBot())

You write obs_from_state and actions_from_output yourself — this is intentional. It keeps your observation encoding and action decoding exactly consistent between training and inference, and lets you iterate on them freely without being locked into any fixed interface.

1. Drop your .py file in the bots folder

You can change the folder path inside the client by pressing D on the bot screen.

2. Select Bot Multiplayer in the client

Launch the client, go to the bot screen, and select your bot. Choose Bot (multiplayer) to queue against other human and bot players online. Set a game count to run a continuous cycle — the client re-queues automatically after each game.

3. Watch your bot play

Head to the Spectate page to watch any live game including your bot's. You can also place bets on it.

Command rate limit

The server enforces a token-bucket rate limit per player: 10 commands per second sustained, with a burst allowance of up to 20 commands. Commands beyond the burst cap are silently dropped — they do not error, the game just ignores them. A human player issues 1–3 commands per second at most, so this limit is generous for normal play. For bots, the practical implication is: returning a large list from on_tick is fine occasionally (the burst absorbs it), but flooding hundreds of actions every tick will result in most of them being discarded. Prioritise the most important commands and keep your lists concise.

Logging and debugging

Write debug output to sys.stderr— it appears in the client's bot log panel and is never sent to the game. Stdout is reserved for the JSON protocol.

import sys

def on_tick(self, state) -> list:
    print(f"[tick {state.tick}] resources={state.resources}", file=sys.stderr)
    return []