Concepts

Accounts and bots

Sign in Microsoft accounts and run scriptable bots on your servers.

A Bot is a Minecraft client that runs in your cluster and joins a server, powered by Minecraft-Console-Client (MCC). Bots for offline-mode servers just need a name. Bots for online servers need an Account: a Microsoft account that owns Minecraft.

Accounts

Creating an Account starts the Microsoft device code sign-in:

apiVersion: kobblestone.io/v1alpha1
kind: Account
metadata:
name: farmhand
spec: {}

The account moves to phase AwaitingAuthorization, and its status shows a link and a code:

Terminal window
kubectl get account farmhand -o jsonpath='{.status.deviceFlow.message}'

Open the link, enter the code and sign in with the Microsoft account. The account then becomes Authorized, and status.profile shows the Minecraft username and UUID.

From then on, Kobblestone refreshes the session on its own, by default one hour before it expires (spec.refreshBeforeExpiryMinutes). If a sign-in fails, for example because the code expired or the account has no Minecraft profile, the reason is in status.message and Kobblestone tries again after 10 minutes. Set spec.inactive: true to stop all sign-in attempts.

The session Secret

A signed-in account produces two Secrets:

  • <account>, of type kobblestone.io/minecraft-session, holds the current session: username, uuid, access-token, its expiry and, if available, the chat signing key pair. The same data is also stored as one JSON document in session.json. The format is documented and doesn’t depend on any client, so your own workloads can mount it too.
  • <account>-credentials holds the refresh token. It is never mounted into bots or other workloads, so they can use the session without being able to renew it.

Bots

apiVersion: kobblestone.io/v1alpha1
kind: Bot
metadata:
name: farmer
spec:
target:
targetRef:
kind: Server
name: survival
auth:
accountRef:
name: farmhand
signChat: true
config:
inline: |
[ChatBot.AutoEat]
Enabled = true
scripts:
- name: greet.txt
runOnLogin: true
inline: |
send Hello from Kobblestone!

Target

target.targetRef points at a Server or Network. To connect through a Router, or to any server outside the cluster, set target.host (and target.port if needed) to an address that leads there.

Authentication

With auth.accountRef, the bot joins as that account. It stays Pending until the account is authorized and restarts automatically with every refreshed session. auth.signChat: true signs chat messages with the account’s key. Without auth, the bot joins offline-mode servers as offlineUsername, which defaults to the bot’s name.

Programming a bot

Bots are programmed with MCC’s own tools; Kobblestone does not add its own scripting language.

  • Configuration: config.inline takes MCC configuration in TOML, the format of MinecraftClient.ini. Use it to enable MCC’s built-in chat bots, such as AutoEat, AntiAFK or AutoRelog. config.from adds more layers from ConfigMaps or Secrets, which is handy for shared settings or tokens. Later layers win.
  • Scripts: scripts places files in MCC’s working directory, inline or from ConfigMaps and Secrets. Files ending in .cs are MCC C# scripts, all others are command scripts. With runOnLogin: true, a script runs after every login.
  • Files and data: pod.volumes and pod.volumeMounts mount additional data. MCC’s working directory is /data, so a volume mounted at /data/files is available to scripts as files/.

Some settings are always managed by Kobblestone and can’t be overridden, such as the account, the server address and the session handling.

Status

PhaseMeaning
PendingThe bot is starting or waiting for its account.
ConnectedThe bot has joined its target.
DisconnectedThe bot was kicked, lost the connection or was rejected. It is restarted with backoff, and status.message holds the reason.
Inactivespec.inactive is true.

A bot only ever runs once at a time: two instances logged in with the same account would kick each other.