Bots

Bots in Kraty are configurable and deterministic. You compose a behavior from small building blocks in the portal; players see the bot scores in their leaderboards alongside humans. There's no setup on your side — bots scale with the leaderboards they're attached to.

Building blocks

Composers

A bot's behavior field is one of three shapes:

• single — one block. The whole bot is that one behavior.
• sequence — a list of blocks run one after another.
• state_machine — named states with conditional transitions between them. The most expressive shape.

{
  "behavior": {
    "type": "state_machine",
    "initial": "stalk",
    "states": {
      "stalk": {
        "block": "track_position",
        "params": { "targetRank": 5, "offset": -1 },
        "transitions": [
          { "when": { "expr": "elapsedSeconds > 600" }, "to": "burst" }
        ]
      },
      "burst": {
        "block": "progress_burst",
        "params": { "targetScore": 500 },
        "transitions": [
          { "when": { "expr": "elapsedSeconds > 660" }, "to": "stalk" }
        ]
      }
    }
  }
}

Visual editor

The bot editor's Diagram section is an interactive canvas — drag states, connect them by dragging from one node's handle to another, and edit a state's block / params / transition expression in the side inspector. Single-block and sequence shapes have a Convert to state machine button that promotes them so they can be edited visually too.

The diagram and the raw JSON above it stay in sync as you edit. The Save button validates the full definition before persisting — see Validation below.

Random-range targets

progress_linear, progress_burst, and complete_at all accept their targetScore as either a fixed number or a random range. In the inspector, click Use random range on a target-score field and you'll get min / max inputs:

"params": { "targetScore": { "min": 80, "max": 120 } }

Each bot rolls one value inside that range, deterministically from its seed. The value stays the same for the bot's entire window — the randomness shapes which bots aim where, not how their score flickers moment to moment.

Validation

Saving a bot runs it through several time samples before persisting. A bot that would error at runtime fails to save instead — the issue list shows up in the editor's Validation section.

A bot must pass validation before it can be published to the marketplace.

Sharing across studios

Bots that work well are worth sharing. See Bot marketplace for how to publish a validated bot, browse other studios' bots, and copy one into your own game.

Walkthrough: build a "shadow rival" bot end-to-end

A bot that tracks the current rank-2 player with a small offset — the classic "always 5 points behind you" effect that keeps a leaderboard feeling competitive even on slow nights:

1. Open Bots under your game and click + New bot. Pick a key (e.g. shadow_rival) and a display name.
2. In the editor's Diagram tab, click Convert to state machine. A blank canvas appears.
3. Drag a track_position block onto the canvas. In the inspector pane set:
   • rank to 2
   • offset to -5 (negative = stay below the target)
   • fallback to last_available (clamp to the lowest known rank when nobody's there yet)
4. Click Save. The bot's validation pass runs three time- sample evaluations behind the scenes; the Validation section confirms it produces a score for each.
5. Click Simulate at the bottom of the editor. The plot shows the trajectory the bot would draw across a synthetic 60-minute window — useful for sanity-checking your offset before binding it to an event.
6. Open any event and add a Bot binding row pointing at shadow_rival, count 1. Save the event.
7. Start an attempt from your game client. The bot is instantiated on the leaderboard within seconds and visible under kraty.leaderboards.read(...) with kind: 'bot'.

Walkthrough: publish a bot to the marketplace and copy it back

1. From the bot editor, scroll to the Marketplace section and click Publish to marketplace. The bot enters a review queue — it's not visible to other studios until a Kraty platform admin approves it. Bots that fail validation can't reach this stage.
2. Once approved, other studios see the bot at the top-level Marketplace tab. From any game they own, they open the bot's detail page and click Copy to my studio. They pick a target game + an optional new key / name, and Kraty inserts an independent copy into their workspace.
3. The copy is independent — they can tune parameters, retire it, even republish a derivative without affecting your original. The copy carries a copiedFromBotId so your bot row tracks how often it's been forked.