Bot Development

One package, both modules

pip install pachinko-pybind

Python 3.9+ required. pachinko-pybind is a single pre-built wheel that ships two Python modules: pachinko_sdk (the live-server client used by every bot) and pachinko_gym(Gymnasium environment used for offline RL training). The game simulation runs in compiled Rust under the hood — no source build needed. requests, websocket-client, and numpy install automatically.

Optional: training extras

For RL training you'll also want a learning library. The examples below use stable-baselines3 / sb3-contrib:

pip install "pachinko-pybind[train]"

Minimal example

from pachinko_sdk import Bot, run_online, AttackMove, ToggleSpawn

class MyBot(Bot):
    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

if __name__ == "__main__":
    run_online(MyBot(),
               orchestrator_url="https://pachinko-rts.com/orchestrator",
               bot_token="bot_...your_token...")

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 + mulligan overview

A match is wrapped in poker-style betting: one round before the RTS phase opens and one mid-game. The pot aggregates across roundsand is paid out at the end of the game — nothing is awarded between rounds. RTS-eliminated bots keep betting until they fold or run out of bankroll.

If you only care about the RTS layer, do nothing — the base Bot class auto-accepts every mulligan and auto-calls every betting decision (going all-in if the call exceeds your bankroll). To play the betting game, override on_mulligan and/or on_bet_action.

from pachinko_sdk import (
    Bot, BetDecision, BetObservation,
    MulliganDecision, MulliganObservation,
)

class MyBot(Bot):
    def on_mulligan(self, obs: MulliganObservation) -> MulliganDecision:
        # Reroll the two lowest-rarity items if we can afford it.
        from pachinko_sdk import Rarity
        cheap = [i for i, item in enumerate(obs.items) if item.rarity == Rarity.COMMON]
        return MulliganDecision.reroll(cheap[:2]) if cheap else MulliganDecision.accept()

    def on_bet_action(self, obs: BetObservation) -> BetDecision:
        # Fold to aggression if anyone has raised this round; otherwise call.
        from pachinko_sdk import BetActionKind
        raised = any(ev.action == BetActionKind.RAISE for ev in obs.history_this_round)
        if raised and obs.to_call > obs.me.bankroll * 0.1:
            return BetDecision.fold()
        return BetDecision.call()

MulliganObservation fields

StartingItem fields

BetObservation fields

BetEvent fields

Decision constructors

Train offline

pachinko_gym ships inside the same pachinko-pybind wheel you already installed for the live SDK. Use any RL library. The example below uses MaskablePPO from sb3-contrib, but any algorithm or framework works.

from pachinko_gym import PachinkoSeriesEnv
from sb3_contrib import MaskablePPO

env = PachinkoSeriesEnv()

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 numpy as np
from pachinko_sdk import Bot, run_online, 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


if __name__ == "__main__":
    run_online(RLBot(),
               orchestrator_url="https://pachinko-rts.com/orchestrator",
               bot_token="bot_...your_token...")

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.

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. 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 being discarded. Prioritise and keep lists concise.

Token security

Treat your bot token like a password. Anyone with it can play matches as your bot and lose its bankroll. If a token leaks, rotate it from My Bots — the old token stops working immediately.

Logging and debugging

The SDK uses standard Python logging. Enable info-level output to watch the connect / poll / match lifecycle:

import logging
logging.basicConfig(level=logging.INFO)

Watch your bot live on the Spectate page once a match starts.