Make BattleTabs Mods with Your AI Agent

  • How it works
    • 1. Pick your ships
    • 2. Write the mod
    • 3. Check it
    • 4. Test the balance
    • 5. Play it yourself
    • 6. Publish a draft
    • 7. Confirm in the game
    • 8. Playtest by link
    • 9. Submit to the Arcade
    • 10. Review and listing
  • What you can change
    • Cooldowns
    • Ship shapes
    • Names and descriptions
    • Combos and overcharge
    • Fleets
    • Match rules with hooks
  • What mods can't do
  • What a ship mod looks like
  • The tools your agent gets
    • Build and test
    • Publish
  • Reading balance results
  • Beyond ship mods
  • Questions
    • Can I use the modding tools today?
    • Do I need to know how to code?
    • Which AI agents work with it?
    • Does my mod go to BattleTabs?
    • Is it safe to run a mod?
    • Can I play my mod with friends?
    • How many times can I publish?

Already have an AI agent? Copy this prompt and paste it to your agent (Claude Code, Cursor and others). It sets up Arcade modding for you, builds a first ship mod, and explains how to publish it.

Set up BattleTabs Arcade modding for me, end to end. Do each step yourself, and only stop when you need me.

1. Run `node --version`. It must say v20 or higher. If it doesn't, stop and tell me to install the LTS version from nodejs.org.
2. Run `npx -y battletabs-mod@latest`. It copies the BattleTabs mod tools to a .battletabs-mod folder in my home folder, makes a battletabs-mods folder for my work, and connects Claude Code if I use it.
3. Connect yourself to the tools. If you are not Claude Code, add the MCP server settings the command printed to your own MCP config (the same settings are saved as mcp-settings.json in the battletabs-mods folder). Use that printed block, not an example. Then tell me to restart you, and carry on from step 5 afterwards.
4. Optional: in the battletabs-mods folder, run `npm create battletabs-mod my-mod` for a starter project with tests and agent instructions.
5. Use the battletabs-mod tools. Call get_docs with "ship-mods" and read it, then call list_ships.
6. Build my first ship mod: make the Dolphin's ability ready every 2 turns, and call it Quick Dolphin. Save it, then run typecheck, play_once and simulate_n. Explain in plain words what the numbers mean. Then call play and give me the link so I can play it against a bot.
7. Explain how publishing works, but do not publish until I ask. I need a BattleTabs account that I can sign in to (not a guest) and that is at least 7 days old. You run check_text, then publish_draft. You show me a login code and I type it on battletabs.io. I press Confirm in the game. You get my playtest link with get_playtest_link. When I'm happy, I press Submit to the Arcade on my game's page in BattleTabs.

BattleTabs modding lets you describe a change in plain words and have your own AI agent build it. Your agent writes a small mod file, tests it with bots, and opens a page where you play it, all on your own computer. When you like it, your agent publishes it to the real game. You play it with friends by invite link, and submit it to the BattleTabs Arcade.

Modding is in open beta. Anyone with a BattleTabs account can install the tools and publish. Your account must be signed in, not a guest, and at least 7 days old. The Arcade modder guide has the one-line install and the publishing details.

Install the tools and publish

How it works

MCP stands for Model Context Protocol. It's an open standard that lets an AI agent use outside tools. The BattleTabs modding MCP gives your agent tools to build, test and publish mods, plus the docs and examples it needs. You talk to your agent, and it does the file work.

1. Pick your ships

Tell your agent your idea. It calls list_ships to see the live ships and how each one is shaped.

2. Write the mod

Your agent writes one TypeScript file that says what changes. The real Battleship rules stay in place.

3. Check it

typecheck finds mistakes, starts a test match and checks the text. A bad value fails with a clear reason.

4. Test the balance

play_once runs a full bot game. simulate_n then plays your mod and the stock rules on the same fleets and compares them.

5. Play it yourself

play opens a page on your computer where you play against the bot. Edit the file, press Reload mod, and try again.

6. Publish a draft

check_text checks the name and text for free. Then login gives you a code. Open the page it shows, signed in to BattleTabs, type the code and approve. publish_draft sends the mod, and the game's server plays 20 bot games to make sure it works.

7. Confirm in the game

Your agent gives you a link. Open it in the game, check the name and rules, and press Confirm. Nobody can play it until you do. The first time, you also accept the creator terms.

8. Playtest by link

get_playtest_link gives you an invite link. Send it to friends and play together. Until it's reviewed, the game shows an Unreviewed label, and only your links reach it.

9. Submit to the Arcade

When you're happy, open your game's page in BattleTabs and press Submit to the Arcade.

10. Review and listing

A person on the BattleTabs team reviews it. Once it's approved, it shows in the Arcade tab for everyone. To change it later, publish again with the same id. The listed version keeps running until the new one is approved.

What you can change

Cooldowns

Choose how often a ship's ability can be used. A cooldown of 1 is every turn and 2 is every other turn.

Ship shapes

Give a ship a new footprint. All its tiles must connect, and a bigger ship is easier to find and sink.

Names and descriptions

Rename a ship and rewrite what it says. Both players see the new text.

Combos and overcharge

Change how many combos a ship can chain, and whether it can overcharge.

Fleets

Pick the 4 ships in play, shared by both players or a different fleet for each.

Match rules with hooks

Run your own code at the start of a turn, on an attack or when a ship sinks. You can cancel an attack, skip a turn, keep score, show a message or end the match.

What mods can't do

  • Change what an ability does. You can change when and how often it's used, not the effect.
  • See hidden ships. Hooks never get unrevealed positions, and they can't attack, reveal tiles or deal damage.
  • Place ships by hand. Fleets are placed at random from a seed.
  • Add new art, skins or 3D models.
  • Publish with shop, paid or promotional ships. Ask your agent to list the ships the Arcade allows.
  • Give rewards or count for ranked. Mod matches are friendly only, with no gold, gems, XP or trophies.

What a ship mod looks like

This is a complete mod. The Dolphin's cooldown drops from 4 to 2, so its ability is ready twice as often. In exchange the ship loses a tile, and it gets a new name.

import { classic, defineShipMod } from "@battletabs/mod-api";

export default defineShipMod({
  id: "quick-dolphin",
  apiVersion: 1,
  classicVersion: "classic-2",
  rules: {
    pitch: "Dolphins sonar twice as often, but the ship is shorter.",
    bullets: ["Sink every enemy ship to win", "Dolphin cooldown is 2"],
  },
  maxTurns: 200,
  fleet: ["dolphin", "kayak", "sailboat", "crab"],
  ships: [
    classic.ship("dolphin", {
      cooldown: 2,
      segments: [{ x: 0, y: 0 }, { x: 1, y: 0 }],
      name: "Quick Dolphin",
    }),
  ],
});

The tools your agent gets

Build and test

These run on your computer. They need no account and send nothing to BattleTabs.

get_docs
Reads the modding docs and example mods.
list_ships
Lists the live ships, or draws one ship's shape. It marks the ships the Arcade won't accept.
save_mod
Saves the mod file, for agents with no file tools of their own.
typecheck
Finds errors, starts a test match and runs the text checks.
check_text
Checks the name, rules and ship text against the game's text rules before you publish.
play_once
Plays one full bot game and shows the result and log.
simulate_n
Runs up to 500 bot games and compares your mod with the stock rules.
render_state
Draws the board, including after a list of moves.
play
Opens a page on your computer where you play your mod against the bot.

Publish

These talk to the game, under your BattleTabs account.

login
Links the tools to your account. You type a code on a BattleTabs page and approve.
publish_draft
Sends your mod as a draft. The game's server checks it and plays 20 bot games.
check_publish
Follows a publish that is still running.
get_playtest_link
Gets an invite link for your confirmed game, to play with friends.
publish_budget
Shows how many of your 20 daily publishes are left.

Reading balance results

Small tests lie. A 50-game simulate_n run can move about 14 points either way by chance, so use 500 games before trusting a small difference. The report gives a margin of error and says in plain words whether the change is more than chance. It plays bots only, so play your mod yourself too, and playtest it with friends before you submit it.

Beyond ship mods

The same tools can build a new turn-based board game from scratch, not only ship changes. The examples include Connect Four, a Connect Four variant with a kraken, and a three-player game. You can build, test and play these against a bot on your own computer. For now only ship mods can be published to the game.

Questions

Can I use the modding tools today?

Yes. There's no sign-up. Follow the Arcade modder guide to install them. To publish, you need a signed-in BattleTabs account, not a guest, that is at least 7 days old.

Do I need to know how to code?

You need to be happy working with an AI agent. The agent writes the TypeScript, and you test the result and say what to change.

Which AI agents work with it?

Any agent that can run a local MCP server should work, such as Claude Code, Claude Desktop, Cursor or VS Code. You also need Node.js 20 or newer. You bring your own agent, and any cost for it is between you and its provider.

Does my mod go to BattleTabs?

Only when you publish it. Building and testing run on your computer. Publishing sends your mod to BattleTabs under your account so it can be played in the game. Your AI agent will send what it reads to its own provider, as it does with any other work.

Is it safe to run a mod?

Mods run in a sandbox with limits on memory and time, and no npm packages. If a mod crashes or stalls, the match is voided rather than given a result. A mod that breaks the rules of the sandbox is treated as a bug in the mod.

Can I play my mod with friends?

Yes. Publish it, confirm it in the game, and share its invite link. Submit it to the Arcade and, once it's approved, anyone can find it there.

How many times can I publish?

20 times a day per account. A quick refusal, like a text problem, gives the try back. A mod that fails the server's bot games uses one up, so test on your own computer first.

Make games for the Arcade · How to Play · Submit a Cosmetic