tradeclash-bot

An AI agent skill for authoring competitive bots for TradeClash — a bot-fight arena on a Red Alert 2 engine. Bots deploy an MCV, build a base, run an economy, produce an army, and out-fight an opponent through a code API. They compete on a betting stream, so they must play well and deterministically.

This repo is a self-contained Agent Skill (the open SKILL.md format). Drop it where your agent discovers skills and it will help you write, test, and iteratively improve a bot.

What's here

SKILL.md                      # the skill: authoring guide + the write→run→read→improve loop
references/
  bot-api.md                  # what a bot can sense and do (the API + correct enum values)
  mechanics.md                # the rules that matter (armor/verses matchups, economy, vision)
  mechanics-full.md           # full RA2 data catalog (units, weapons, 79-warhead verses matrix)
  determinism.md              # the fairness/determinism contract (or the bot is DQ'd)
  architecture.md             # tick model, order→action→task pipeline, receipts
templates/
  starter-bot.ts              # a working baseline bot to start from
scripts/
  run-match.ts                # headless test harness → scoreboard + diagnosis (needs the engine)

Install

• Claude Code: copy this folder into ~/.claude/skills/tradeclash-bot (personal) or .claude/skills/tradeclash-bot (project). It's discovered automatically.
• claude.ai / API: zip the folder and upload it as a custom skill.

Writing a bot

Start from templates/starter-bot.ts. A bot is one module exporting { id, displayName, version, author, createBot(playerName, country) }; createBot returns { onGameStart, onGameTick, onGameEvent }. You sense state via ctx.gameApi and issue orders via ctx.actionsApi — never mutate engine state. See references/bot-api.md.

Testing

scripts/run-match.ts runs your bot headless against the built-in AI and prints a scoreboard with an auto-diagnosis. It requires the TradeClash engine (private) and your own RA2 game files — set TC_ENGINE to your engine checkout and run from it. If you don't have the engine, submit the bot and the TradeClash platform runs matches for you.

Rules (bots that break these are disqualified)

• Deterministic: randomness only via ctx.gameApi.generateRandomInt — never Math.random, Date.now, timers, or network.
• Orders only: affect the world only through ctx.actionsApi.
• Fog-honest: read enemies via getVisibleUnits(name, "enemy", …); don't peek through fog.

See references/determinism.md.

---

Game data in references/mechanics-full.md describes Command & Conquer: Red Alert 2, © Electronic Arts — provided for interoperability/authoring reference only. Bring your own game files.