Plugin System

Plugin System

Register custom bots and network architectures with the framework so they show up in CLI flags, the dashboard dropdown, and Bot.from_name(...).

See also: Bot Approaches | API Reference

---

When to use it

If you are writing a one-off script, just instantiate your bot directly. The plugin system is for bots and networks you want to reuse:

• Pick them by name in CLI flags (e.g. python -m orca.train --opponent my-bot)
• Show them in Bot.list() and the dashboard's opponent dropdown
• Reference them from the leaderboard and model zoo

Registering a Bot

from hexbot import BotProtocol, register_bot, HexGame

class MyBot(BotProtocol):
    def __init__(self, depth=4):
        self.depth = depth

    def best_move(self, game: HexGame):
        return game.search(depth=self.depth)['best_move']

register_bot('my-bot', MyBot)

# Now usable everywhere
from hexbot import Bot
bot = Bot.from_name('my-bot', depth=6)

The protocol is minimal. Any object with a best_move(game) method works.

Registering a Network

import torch.nn as nn
from hexbot import register_network

class MyNet(nn.Module):
    def __init__(self):
        super().__init__()
        # ... layers ...

    def forward(self, x):
        # must return (policy_logits, value)
        ...

register_network('my-net', MyNet)

# Use it in training
# python -m orca.train --config my-net

The network must return (policy_logits, value) as a tuple from forward. Input shape is (B, channels, H, W) where channels are the encoded board state.

Where to register

Put the register_* calls in a module that's imported before the framework looks them up. The simplest pattern is a small plugins.py in your project root:

# plugins.py
from hexbot import register_bot, register_network
from my_bots import BotA, BotB

register_bot('bot-a', BotA)
register_bot('bot-b', BotB)

Then import plugins anywhere in your script before using Bot.from_name(...).

Listing what's registered

from hexbot import registered_bots, registered_networks

print(registered_bots())       # {'random': ..., 'heuristic': ..., 'my-bot': ...}
print(registered_networks())   # {'standard': ..., 'large': ..., 'my-net': ...}

Why this design

Frameworks that hard-code class names force users to fork the codebase to add a bot. With registration, you keep your bots in your own files and the framework discovers them by name. This is the pattern used by gym.register, pytest.register_assert_rewrite, and tox plugins.