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

Batched evaluation

To measure a bot properly, run many matches and aggregate. run_local_batch plays n_games full matches (deterministic per game: seeds are base_seed + game_index) and returns the numbers evaluation cares about for one seat:

from pachinko_sdk import run_local_batch

res = run_local_batch(lambda i: {0: MyBot(), 1: "builtin", 2: "builtin", 3: "builtin"},
                      num_players=4, n_games=100, workers=4)
print(res.first_place_rate(), res.avg_placement(), res.mean_net(), res.placement_counts())

The factory is called once per game so controllers never share state across matches. workers > 1 uses a process pool (the factory must be picklable).

Bot lifecycle methods

GameState fields

Unit fields

Building fields

ResourceNode fields

Star fields

DroppedItem fields

MapInfo fields

Static map geometry, delivered once at game start and attached to every state.map_info. The terrain grid is row-major and shares the coordinate system of state.visibility, so terrain, fog, and your rasterized units all line up on the same grid.

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. Folding is resigning from the battlefield: your remaining units and buildings are removed and you forfeit the pot, but chips you already committed stay in it. Destroying an opponent's last military building earns an elimination bounty (one small blind) off the top of the pot.

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

Settlement fields

Passed to on_match_settled at the end of a match. The same shape is produced live (from the wire) and in self-play (from PyBettingState.distribute_winnings), so a bot reads it identically whether it trained offline or played online.

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)

Pass num_players=8(2–8) to train against up to 7 built-in AI opponents — the realistic online setting, rather than 1v1. Your agent always controls seat 0. The observation shape is identical for every player count (enemy tensors are per-opponent banks, unused seats zero), so a network trained in 1v1 carries unchanged into 8-player free-for-all.

Observation space

The environment exposes a Dict observation of fixed-shape float32 tensors. Enemy tables are banked by owning player slot— the bank index answers “whose unit is this”, per-opponent pooling is a slice, and the shape is the same from 1v1 to 8-player FFA:

max_units defaults to 512 rows per bank (constructor kwarg, up to 4096). Saturation is never silent: globals[9] / globals[10]count any entities that didn't fit this observation — if they're ever nonzero, raise max_units.

Multi-agent self-play

For FFA self-play (one process observing and commanding all seats), drop below the Gymnasium wrapper to the raw engine env: pass ai_seats=[] (or a partial list for mixed AI/self-play leagues), then drive each seat per tick:

import pachinko_pybind as p

env = p.PachinkoEnv(num_games=1, num_players=8, ai_seats=[])
env.reset(seed=1, return_obs=False)
while True:
    for s in range(8):
        obs = env.get_obs(s)                      # same Dict schema, any seat
        env.submit_actions(s, unit_actions, building_actions)
    done, info = env.step_submitted()
    if done:
        break
# info["ranks"] / info["rewards"] / info["bankrolls"] cover all 8 seats;
# terminal reward is placement-graded: +100 for 1st ... -100 for last.

ai_seatscan also name any seats (including 0) for the built-in AI to drive — so you can train from an arbitrary seat. Randomize the learner's seat per episode: the enemy banks are absolute player slots, and the live server can seat your bot anywhere.

Spatial observations: terrain, fog & feature planes

For a visual / CNN policy, the SDK can turn each tick into stacked 2D feature planes (the PySC2 / AlphaStar “feature layers” pattern). Everything lives on one grid (map_info.grid_height × grid_width, 125×125), so terrain, fog, and your rasterized entities align with no resampling.

The terrain grid (state.map_info) is static — sent once at game start, so you cache it. The fog plane (state.visibility) and entity positions update every tick. Featurizer caches the static planes once and rebuilds only the dynamic ones each tick:

from pachinko_sdk import Bot, Featurizer

class VisualBot(Bot):
    def on_game_start(self, data):
        self.feat = None

    def on_tick(self, state):
        if self.feat is None and state.map_info:
            self.feat = Featurizer(state.map_info)   # cache terrain planes ONCE
        obs = self.feat.observe(state)               # (C, H, W) float32, fresh each tick
        # channels: ground, hill, mountain, slope, my_units, enemy_units,
        #           my_buildings, enemy_buildings, stars, dropped_items, visibility
        return self.policy(obs)                       # -> your CNN -> actions

Building the planes is cheap (~0.25 ms/tick) and adds no network cost — the fog data is already on the wire. Prefer the local engine for training (no network, thousands of steps/s); env.fow(player_idx) exposes the same fog grid on the direct API. See examples/rl_feature_planes.py in the wheel for a runnable version with a plane viewer.

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.

Static spec tables

load_specs()returns the full rules table — unit, building and upgrade stats, RPS multipliers, economy and world constants. It's assembled from the engine's own constants, so it can never drift from the live rules, and it's immutable per match, so fetch it once.

from pachinko_sdk import load_specs

specs = load_specs()                       # cached after first call
specs.unit("triangle").speed               # 3.125
specs.unit("square").attack                # 15
specs.building("arrow_tower").vision       # 200.0
specs.rps_multiplier("square", "triangle") # 1.5  (square beats triangle)
specs.economy["starting_bankroll"]         # 1000

UnitSpec: max_hp, attack, speed, cost, production_ticks, attack_range, vision, building_damage_mult, beats. BuildingSpec: max_hp, is_military, produces, vision, valid_upgrades (+ arrow-tower fire stats). UpgradeSpec: base_cost, max_level, per_level, effect.

Self-play economy

PyBettingState binds the realengine betting — blinds, process_action, side pots and distribute_winnings— so an offline tournament pays out bit-identically to the live match-server (no Python pot math to drift). Economy constants are exposed via economy_constants() and module constants (STARTING_BANKROLL, SMALL_BLIND, BIG_BLIND, MIN_RAISE). See examples/selfplay_betting.py in the wheel for a runnable bankroll tournament that ranks bots by money across games.

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.