Game Bot and AI Model Tools for AI Agents

These tools declare the bots a game offers and the AI models they use, and read how fast this device ran the bot test. Importing or removing a model always waits for your click in the tab.

Tools in this family#

7 tools. The tool reference lists every family. An MCP client shows each tool as mcp__diceytable__<name>.

→ D / → H: the call escalates with certain arguments (see the tool). +: the call takes the class of the tool or action it dispatches to. bridge: answered by the bridge, on any surface, with no tab.

ai_models_list#

List AI models (game bots) — List the AI models the editor project declares for its game bots (manifest.aiModels: the .onnx files AI opponents evaluate). Each is re-checked against its draft file with the publish scanner's own ONNX validation, and .onnx files no model declares are listed because publish refuses them. Not the cosmetic player bots.

Input

Output (structured content)

A newer site may add fields; ignore ones you do not recognise.

Lists the AI models the editor project declares for its game bots (manifest.aiModels). These are the ONNX files a game's AI opponents run. The tool also checks each model again against its file in the draft, with the same checks publishing runs. Game bots are opponents that hold a seat. They are not the cosmetic player bots a player wears.

When to use it. After ai_model_import, before bots_set (a bot's modelId must be one of these ids), and before publish_preview, to learn whether a model file would be refused.

Class. R.

What each model carries. The manifest entry (id, label, path, sizeBytes, sha256, inputs, outputs, minTier, opset, difficulties), plus:

• status: valid, invalid (see issues), missing (the declared file is not in the project) or unchecked.
• issues: the publish scanner's own codes, for example ai-model-sha-mismatch (the file is not the one the manifest declares), ai-model-op-forbidden, ai-model-op-not-allowed or ai-model-io-mismatch.
• usedByBots: the bot ids that evaluate it. A model in use cannot be removed.
• nodeCount and parameterCount, read from the file.
• pushWithGit: the file is over the 45 MB the in-app Publish can upload, so the user has to push it to the game's repository with git.

Gotchas.

• untrustedUndeclaredFiles lists .onnx files no model declares. Publishing refuses each of them (ai-model-undeclared): import the file properly, or ask the user to delete it.
• allowed: false means this pack type cannot declare models at all. Only a game pack can.
• A model's label, min tier and difficulties are ordinary fields (manifest.ai-models.* with fields_set). Its id, path, hash and tensors are written only by the import.
• Labels and tensor names come from the model's author and the file; they are returned under untrustedModels.

Example#

One valid model in use by a bot, and a stray file publishing would refuse:

{
  "request": {},
  "response": {
    "untrustedModels": [
      {
        "id": "club",
        "label": "Club",
        "path": "ai/club.onnx",
        "format": "onnx",
        "sizeBytes": 1901039,
        "sha256": "7d1f0c2b9a4e6853c1d0f7a2b4c6e8091a3b5c7d9e0f2a4b6c8d0e1f3a5b7c9d",
        "inputs": [
          {
            "name": "board",
            "shape": [
              -1,
              3,
              8,
              8
            ],
            "dtype": "float32"
          }
        ],
        "outputs": [
          {
            "name": "policy",
            "shape": [
              -1,
              65
            ],
            "dtype": "float32"
          },
          {
            "name": "value",
            "shape": [
              -1,
              1
            ],
            "dtype": "float32"
          }
        ],
        "minTier": "cpu-fast",
        "opset": 17,
        "difficulties": [
          {
            "id": "easy",
            "label": "Easy",
            "simsPerMove": 16
          },
          {
            "id": "normal",
            "label": "Normal",
            "simsPerMove": 64
          },
          {
            "id": "hard",
            "label": "Hard",
            "simsPerMove": 256
          }
        ],
        "usedByBots": [
          "club-ai"
        ],
        "status": "valid",
        "issues": [],
        "nodeCount": 62,
        "parameterCount": 470273,
        "pushWithGit": false
      }
    ],
    "untrustedUndeclaredFiles": [
      "ai/old-experiment.onnx"
    ],
    "totalBytes": 1901039,
    "limits": {
      "maxModels": 4,
      "maxModelBytes": 67108864,
      "maxTotalBytes": 134217728,
      "maxPublishBytes": 47185920
    },
    "allowed": true
  }
}

ai_model_import#

Import AI model (game bots) — Requires the user's confirmation in the DiceyTable tab. Import an ONNX model for the editor project's game bots (AI opponents). With localPath (a .onnx inside the bridge's allowed folders) the file is validated by the publish scanner's own check, written to ai/<id>.onnx and declared in manifest.aiModels with its hash; a refused model is not added. With no source it opens the Import model dialog for the user to pick the file. This is the only way to declare a model.

Input

Output (structured content)

A newer site may add fields; ignore ones you do not recognise.

Imports an ONNX model for the editor project's game bots, the AI opponents a game offers. It also declares the model in manifest.aiModels. This is the only way to declare a model: asset_import refuses .onnx files, and manifest_set refuses the aiModels key.

It works in two ways:

• With localPath: the bridge reads a .onnx file inside its allowed folders and sends it to the tab. The tab checks it with the same validation publishing runs. A model that passes is written to ai/<id>.onnx and declared with its size, SHA-256, tensors and operator set.
• With no source: the tab opens its Import model dialog and the user picks the file. The result is status: "dialog-opened"; call ai_models_list afterwards to see whether a model was added.

When to use it. When a game needs a trained opponent. A scripted bot needs no model: declare it with bots_set alone.

Class. H: the user confirms in the tab either way, and nothing you pass skips that. localPath also needs the files:local scope. A file import needs credit, which answers the import credit gate: the record is AI-attested and a person reviews it before anyone can publish.

What a model may be. Data, never code: a single self-contained .onnx file of at most 64 MB, using only the standard feed-forward operators DiceyTable runs (convolutions, linear layers, activations, pooling, reshapes). A model with control flow (Loop, If, Scan), custom operator domains, external data files, functions or string tensors is refused, and so is one with too many nodes or parameters. A game may declare up to 4 models, 128 MB together.

Gotchas.

• A refused model imports nothing. The error is invalid with detail.reason: "ai-model-rejected" and detail.issues: the scanner's own codes and messages, verbatim. Fix the model in the tool that exported it and import the new file. Issue text quotes the file's own node and tensor names, so it is marked untrusted.
• id defaults to a free slug of the file name, so a call without id never replaces a model. Passing an existing id replaces that model's file and hash and keeps its path, label, difficulties and the bots that use it.
• minTier defaults to the editor's estimate (suggestedTier), measured on the user's device: cpu-basic, cpu-fast or gpu. You may pass a lower one, and the result then carries a warning; hosts on weaker devices will run the bot slowly.
• A new model that looks like a policy/value network gets three difficulties (Easy 16, Normal 64, Hard 256 simulations per move) unless you pass difficulties or suggestDifficulties: false.
• pushWithGit: true means the file is between 45 and 64 MB. It is saved in the project, but the in-app Publish cannot upload it: tell the user to push that file to the game's GitHub repository with git before publishing.
• There is no url source. Download the file into an allowed folder and use localPath.
• sourceName, sourceBytes and sourceSha256 are set by the bridge from the file it read; any value you pass is discarded. The confirmation shows the user all three (the hash short and in full), and the tab refuses the import with detail.reason: "source-mismatch" if the file it received is not that size and hash.
• In an editor tab without the project lease it is refused with read-only-lease, and on a pack that is not a game with bots-not-allowed-for-type.

Example#

After the user allowed it in the tab. The model passed validation and was declared:

{
  "request": {
    "localPath": "training/out/club.onnx",
    "id": "club",
    "label": "Club",
    "credit": {
      "origin": "own-work",
      "notes": "Trained from this game's own rules with the DiceyTable trainer."
    }
  },
  "response": {
    "status": "imported",
    "modelId": "club",
    "path": "ai/club.onnx",
    "sizeBytes": 1901039,
    "sha256": "7d1f0c2b9a4e6853c1d0f7a2b4c6e8091a3b5c7d9e0f2a4b6c8d0e1f3a5b7c9d",
    "minTier": "cpu-fast",
    "suggestedTier": "cpu-fast",
    "estimatedMsPerPosition": 2.1,
    "pushWithGit": false,
    "untrustedSummary": {
      "opset": 17,
      "irVersion": 8,
      "producerName": "diceytable-botnet",
      "nodeCount": 62,
      "parameterCount": 470273,
      "opHistogram": {
        "Conv": 15,
        "BatchNormalization": 15,
        "Relu": 16,
        "Add": 6,
        "Flatten": 2,
        "Gemm": 3,
        "Tanh": 1
      },
      "inputs": [
        {
          "name": "board",
          "dtype": "float32",
          "shape": [
            -1,
            3,
            8,
            8
          ]
        }
      ],
      "outputs": [
        {
          "name": "policy",
          "dtype": "float32",
          "shape": [
            -1,
            65
          ]
        },
        {
          "name": "value",
          "dtype": "float32",
          "shape": [
            -1,
            1
          ]
        }
      ],
      "policyValue": true
    },
    "untrustedSourceName": "club.onnx",
    "untrustedWarnings": [],
    "aiAttested": true,
    "creditId": "cr_b21e",
    "termsVersion": "2026-09-07.1",
    "termsText": "By marking these files as your own work you represent and warrant that you are the author of each file, or that you otherwise own or control all rights necessary to publish, distribute and sublicense it through DiceyTable, and that doing so does not infringe any copyright, trademark, patent, trade secret, right of publicity, moral right, contractual restriction or other right of any third party."
  }
}

ai_model_remove#

Remove AI model (game bots) — Requires the user's confirmation in the DiceyTable tab. Remove an AI model from the editor project's manifest.aiModels and delete its .onnx file. Refused while a game bot still uses the model, as its default model or a difficulty's: repoint or remove those bots first (bots_set, bots_remove).

Input

Output (structured content)

A newer site may add fields; ignore ones you do not recognise.

Removes one AI model from the editor project's manifest.aiModels and deletes its .onnx file from the project. The model belongs to the game's bots, its AI opponents. It is not part of the cosmetic player bots.

When to use it. When the user asks for a model to go. To swap a model for a newer file, do not remove it: call ai_model_import with the same id, which replaces the file and keeps the bots that use it.

Class. H, like asset_delete: it deletes a file, so the user confirms in the tab. The dialog names the model and the file.

Gotchas.

• It is refused while a bot still uses the model — as its default modelId or on one of its difficulties (difficulties[].modelId) — with detail.reason: "model-in-use" and the bot ids. Point those bots (or difficulties) at another model or make them scripted with bots_set, or remove them with bots_remove, then call again.
• The declaration is removed first and the file second, so a failed delete leaves a file no model declares rather than a model with no file. ai_models_list lists such a file under untrustedUndeclaredFiles.
• deletedPath is absent when the declared file was already gone.

Example#

Only after the user confirmed in the tab:

{
  "request": {
    "modelId": "rookie"
  },
  "response": {
    "removed": true,
    "modelId": "rookie",
    "deletedPath": "ai/rookie.onnx"
  }
}

bots_list#

List game bots — List the game bots the editor project declares (manifest.bots: the AI and scripted opponents a game offers in the lobby), the handler ids its scene scripts register with bots.register, and every problem publish would refuse. Not the cosmetic player bots.

Input

Output (structured content)

A newer site may add fields; ignore ones you do not recognise.

Lists the game bots the editor project declares (manifest.bots). These are the AI and scripted opponents a game offers in the lobby and at the table. The tool also returns the handler ids the scene scripts register, and every problem that would block publishing. Game bots hold a seat. They are not the cosmetic player bots a player wears.

When to use it. Before and after bots_set, and after writing a bot's script with script_write, to check that the handler it registers is the one the bot names.

Class. R.

How a bot and its script meet. Each bot names a handler. A scene script registers that id with bots.register({ id: "<handler>", onTurn }), with the id written as a plain string. untrustedRegisteredHandlers is the list of ids found that way in the scripts' compiled bodies, which is exactly what the publish check reads.

Gotchas.

• A bot whose handler is not in untrustedRegisteredHandlers is reported as a warning here and refused at publish.
• untrustedStaleHandlers are ids a script's source registers but its compiled body does not: the script was edited and not saved. Save it with script_write so it compiles.
• untrustedProblems uses manifest paths: bots.1.handler is the second bot's handler, aiModels.0.sha256 the first model's hash. error entries fail the manifest's schema; warning entries are the handler checks.
• An ai bot needs a modelId from ai_models_list. Its fallbackBotId, if any, must be a scripted bot of the same game.
• allowed: false means this pack type cannot declare bots. Only a game pack can.

Example#

Two bots; the AI bot's handler is not registered by any script yet:

{
  "request": {},
  "response": {
    "untrustedBots": [
      {
        "id": "greedy",
        "label": "Greedy",
        "kind": "scripted",
        "handler": "greedy"
      },
      {
        "id": "club-ai",
        "label": "Club AI",
        "kind": "ai",
        "modelId": "club",
        "fallbackBotId": "greedy",
        "handler": "club-ai",
        "difficulties": [
          {
            "id": "easy",
            "label": "Easy"
          },
          {
            "id": "club",
            "label": "Club"
          }
        ],
        "defaultDifficulty": "easy",
        "seats": {
          "max": 1
        }
      }
    ],
    "untrustedRegisteredHandlers": [
      "greedy"
    ],
    "untrustedStaleHandlers": [],
    "untrustedProblems": [
      {
        "severity": "warning",
        "path": "bots.1.handler",
        "message": "Handler \"club-ai\" is not registered by any scene script (bots.register). Publish refuses a bot whose handler nobody registers."
      }
    ],
    "maxBots": 8,
    "allowed": true
  }
}

bots_set#

Set game bot — Create or replace one game bot in the editor project's manifest.bots (an AI or scripted opponent), matched by id. An AI bot's modelId is its default; a difficulty may name its own (difficulties[].modelId), which the table then loads, gates and ranks for that difficulty. Validated with the manifest's own schema and cross-checks (every named model exists and only an AI bot names one, handler unique, fallback is a scripted bot, default difficulty declared); refused if any fails. A handler no scene script registers yet is a warning.

Input

Output (structured content)

A newer site may add fields; ignore ones you do not recognise.

Creates or replaces one game bot in the editor project's manifest.bots, matched by bot.id. A game bot is an opponent the game offers: scripted (script code only) or ai (its script also evaluates a declared AI model). It is not a cosmetic player bot.

When to use it. To declare a bot once its script registers a handler, or to change one. Send the whole bot: the entry replaces the existing one with that id.

Class. W.

The bot object.

• id, handler: lowercase letters, digits and hyphens, starting with a letter. handler is the id the scene script passes to bots.register({ id }), and no two bots may share one.
• label: up to 40 characters of plain text, shown in the lobby and at the table.
• kind: scripted or ai.
• modelId (ai only, required there): an id from ai_models_list. It is the bot's default model.
• fallbackBotId (ai only): a scripted bot of this game that a new host may swap in when their device cannot run the model.
• difficulties (up to 8 of {id, label, description?, modelId?}) and defaultDifficulty, which must be one of them. On an ai bot a difficulty's modelId names the model that difficulty plays with — a separate network per Easy / Medium / Hard. It is what the table loads, checks the host's device against, passes the script as ctx.modelId and ranks that difficulty on. Leave it out to use the bot's modelId.
• seats ({max?}: the most of this bot one table may seat) and description (up to 200 characters).

Gotchas.

• The bot is checked with the manifest's own schema and cross-checks before it is saved. A bot that publishing would refuse is not written: the error is invalid with detail.reason: "bot-invalid" and the problems.
• An unknown key is refused, not dropped. A scripted bot may not carry modelId or fallbackBotId, and its difficulties may not carry modelId. Every model a bot or one of its difficulties names must be declared.
• A handler no scene script registers yet is a warning in untrustedWarnings, not a refusal, so you can declare the bot and write its script in either order. Publishing refuses it until a script registers it.
• At most 8 bots. Only a game pack can declare any (bots-not-allowed-for-type otherwise).
• manifest_set refuses the bots key; this tool and bots_remove are how bots change.

Example#

An AI bot with a scripted fallback. Its script is not written yet, hence the warning:

{
  "request": {
    "bot": {
      "id": "club-ai",
      "label": "Club AI",
      "kind": "ai",
      "modelId": "club",
      "fallbackBotId": "greedy",
      "handler": "club-ai",
      "difficulties": [
        {
          "id": "easy",
          "label": "Easy"
        },
        {
          "id": "club",
          "label": "Club",
          "description": "Plays at club strength."
        }
      ],
      "defaultDifficulty": "easy",
      "seats": {
        "max": 1
      },
      "description": "A trained opponent. Needs a fast processor to host."
    }
  },
  "response": {
    "botId": "club-ai",
    "created": true,
    "index": 1,
    "untrustedWarnings": [
      "Handler \"club-ai\" is not registered by any scene script (bots.register). Publish refuses a bot whose handler nobody registers."
    ]
  }
}

bots_remove#

Remove game bot — Remove one game bot from the editor project's manifest.bots. Destructive: needs confirm: true. AI bots that named it as their fallback lose that fallback, and are listed in the result.

Input

Output (structured content)

A newer site may add fields; ignore ones you do not recognise.

Removes one game bot from the editor project's manifest.bots. A game bot is an opponent the game offers, not a cosmetic player bot.

When to use it. When a bot should no longer be offered. To change a bot, use bots_set with the same id instead.

Class. D: pass confirm: true. The first destructive call of a session creates a restore point, and the manifest change is in the editor's undo history.

Gotchas.

• AI bots that named the removed bot as their fallbackBotId lose that fallback, because a fallback pointing at a bot that is gone would fail publishing. Their ids come back in clearedFallbacks; give them another fallback with bots_set if they need one.
• The bot's script is not touched. A script that still registers the handler is harmless; remove the registration with script_write if you want it gone.
• The model an AI bot used stays declared. Remove it with ai_model_remove if nothing else uses it.

Example#

Removing a scripted bot that an AI bot used as its fallback:

{
  "request": {
    "botId": "greedy",
    "confirm": true
  },
  "response": {
    "removed": true,
    "botId": "greedy",
    "clearedFallbacks": [
      "club-ai"
    ]
  }
}

hardware_tier_get#

Hardware tier — Read what this device last measured as for a model-backed game bot, from the /play lobby tab: the tier, the probe version and the measured facts. Reads the saved result only; it never downloads or runs anything (re-testing is the lobby.bots.retest-device action).

Input

Output (structured content)

A newer site may add fields; ignore ones you do not recognise.

Reads the tier this device last measured for game bots that use an AI model. You get the tier, the measured facts behind it, and what the open lobby's roster shows for the user.

A bot's model runs on the host's device, so DiceyTable tests each device once and sorts it into a tier: none (cannot run a model), cpu-basic (any modern device), cpu-fast (a fast processor) or gpu (a graphics card through WebGPU). The tier only decides whether the user can host a game with an AI bot. It never stops anyone joining one.

When to use it. Before adding an AI bot, to compare the device with the bot's minTier in lobby_state's game.bots. And when lobby_start answers bot-tier-unmet, to see why.

Class. R. It reads the saved result and nothing else: it never downloads the model runtime and never runs the test. Measuring again is a write, because it downloads about 14 MB the first time and runs a benchmark on the user's machine. That is the lobby's Re-test button, the action lobby.bots.retest-device; invoke it with actions_invoke, then call this tool again.

Gotchas.

• probed: false means there is no saved result that is still fresh (a result is kept for a week). tier is then none, and facts is absent. The lobby tests the device by itself when its game offers bots, so wait for testing to turn false and read again.
• tier is the one in use; measuredTier is what the facts classify as. They differ only when overridden is true, which is a developer setting.
• reported is what the lobby's roster currently shows for the user, and it is what the server's Start check reads. It follows tier by one message. A reported.probeVersion of 0 means the tab has not reported yet.
• The tier is the device's own report and it is advisory. It grants nothing, and it is not a security control.
• It answers from a /play lobby tab, with or without a lobby open; reported needs an open lobby.

Example#

A request and the structured result it returns.

{
  "request": {},
  "response": {
    "tier": "cpu-fast",
    "probed": true,
    "testing": false,
    "probeVersion": 1,
    "measuredTier": "cpu-fast",
    "overridden": false,
    "facts": {
      "wasmSimd": true,
      "logicalCores": 8,
      "deviceMemoryGb": 8,
      "cpuProbeMs": 0.5,
      "webgpuVerified": false
    },
    "probedAt": "2026-10-02T15:04:11.000Z",
    "reported": {
      "tier": "cpu-fast",
      "probeVersion": 1
    }
  }
}