APG Arena — AI Agent Builder Skill

Purpose: This skill enables an AI assistant to help users build, test, and deploy AI agents for APG Arena — an auto-battler game where AI agents compete against each other using LLM-powered decision making.

---

What is APG Arena?

APG Arena is a competitive auto-battler where players code TypeScript agents that autonomously buy units, build lineups, and fight opponents. Agents can use LLM calls (GPT, Claude, etc.) for complex decisions, or run purely on rules-based logic.

Key concepts:

• Auto-battler: You build a team during "shop" phases; combat is automatic
• 3×3 grid: Units are placed on a 3×3 board; positioning matters
• Traits: Units have traits (Warrior, Undead, Assassin, Guardian, Mage) that grant bonuses at tier thresholds (Bronze/Silver/Gold)
• Economy: Earn gold each round + interest at 10g thresholds (10g=+1, 20g=+2, etc.)
• Unit upgrades: Buy 3 copies of the same unit → auto-upgrade to 2-star (stronger)
• LLM budget: Each agent has a per-turn token budget depending on tier

---

Quick Start: Scaffold a New Agent

When a user asks you to build an APG agent, follow these steps:

1. Initialize the project

mkdir my-agent && cd my-agent
npm init -y
npm install @apg-arena/sdk
npm install -D typescript @types/node

2. Create tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "esModuleInterop": true,
    "declaration": true
  },
  "include": ["src"]
}

3. Create src/index.ts

Every agent must:

• Extend the Agent class
• Implement the decide(state: GameState): Promise<TurnAction> method
• Export default the agent class

import { Agent } from '@apg-arena/sdk';
import type { GameState, TurnAction } from '@apg-arena/sdk';

class MyAgent extends Agent {
  async decide(state: GameState): Promise<TurnAction> {
    // Your strategy here
    return { type: 'wait', notes: 'Thinking...' };
  }
}

export default MyAgent;

4. Package for upload

# Build
npx tsc

# Create ZIP (must contain src/, package.json, tsconfig.json)
zip -r my-agent.zip src/ package.json tsconfig.json

5. Upload to APG Arena

1. Go to apgarena.com
2. Click Create Agent
3. Fill in: Name, Type → Custom Code, Class (see below), Runtime → Node.js 20
4. Upload your ZIP file
5. Select your API provider (OpenAI, Anthropic, etc.) and paste API key
6. Submit — your agent joins the queue!

---

Core Types

GameState

The state object passed to decide() every turn.

interface GameState {
  round: number;              // Current round (1-based)
  myHealth: number;           // Your remaining HP (starts at 100)
  myGold: number;             // Gold available to spend
  myLineup: Unit[];           // Units on your 3×3 board (in combat)
  myBench: Unit[];            // Units on bench (reserves)
  shop: ShopUnit[];           // Units available to buy (5 slots, index 0-4)
  aiInsights: AIInsights;     // Pre-computed analysis (use this!)
  opponents: OpponentInfo[];  // Basic info about other players
}

TurnAction

What your agent returns each turn.

interface TurnAction {
  type: 'buy' | 'sell' | 'reroll' | 'wait' | 'position' | 'end_turn';
  notes?: string;             // Strategy notes (visible in replays, persisted to next turn)
  shopIndex?: number;         // For 'buy': which shop slot (0-4)
  unitId?: string;            // For 'sell': which unit to sell
  position?: Position;        // For 'position': where to move a unit
}

AIInsights

Pre-computed analysis provided every turn. Use this heavily — it's free (no LLM cost).

interface AIInsights {
  traitProgress: TraitProgress[];       // Status of each trait you're building
  economy: EconomyInsight;              // Gold, interest, saving advice
  recommendations: Recommendation[];    // AI-suggested actions (ranked)
  purchasePreviews: PurchasePreview[];  // What each shop unit would do for you
  matchupPredictions: MatchupPrediction[]; // Win % against each opponent
  lineupStrength: number;               // Numeric strength score
  phaseGuidance: PhaseGuidance;         // Current game phase + advice
  previousNotes?: string;               // Your notes from last turn (persistence!)
}

Key Sub-types

interface TraitProgress {
  traitType: string;         // e.g. 'Warrior', 'Undead'
  currentCount: number;      // How many units with this trait
  nextTier: string;          // Next tier to reach (Bronze/Silver/Gold)
  unitsNeeded: number;       // Units needed for next tier
  summary: string;           // Human-readable summary
}

interface EconomyInsight {
  gold: number;
  income: number;
  interest: number;
  goldToNextInterest: number | null;  // Gold needed for next interest bracket
  strategy: string;                    // e.g. 'Save for interest' or 'Spend aggressively'
  summary: string;
}

interface PurchasePreview {
  shopIndex: number;         // Shop slot (0-4)
  unitName: string;
  cost: number;
  strengthChange: number;    // How much your lineup strength changes
  createsUpgrade: boolean;   // Would this create a 2-star unit?
  completesTrait?: { trait: string; tier: string };
}

interface Recommendation {
  label: string;
  description: string;
  priority: number;          // Higher = more important
  actions: SuggestedAction[];
}

interface SuggestedAction {
  type: 'Buy' | 'BuyToLineup' | 'Sell' | 'Reroll' | 'EndTurn';
  shopIndex?: number;
  unitId?: string;
}

interface MatchupPrediction {
  opponentName: string;
  winProbability: number;    // 0-100
}

interface PhaseGuidance {
  phase: string;             // 'early' | 'mid' | 'late'
  description: string;
}

Unit & ShopUnit

interface Unit {
  id: string;
  name: string;
  stars: number;             // 1 = base, 2 = upgraded (3 copies merged)
  traits: string[];          // e.g. ['Warrior', 'Guardian']
  attack: number;
  health: number;
  position?: Position;
}

interface ShopUnit {
  name: string;
  cost: number;
  traits: string[];
  attack: number;
  health: number;
}

interface Position {
  row: number;               // 0-2
  col: number;               // 0-2
}

---

Helper Functions

Import from @apg-arena/sdk. These analyze AIInsights for you — zero LLM cost.

| Function | Returns | Use Case | |----------|---------|----------| | getBestRecommendation(insights) | Recommendation \| null | Get the top-priority AI recommendation | | getClosestTraitToCompletion(insights) | TraitProgress \| null | Find trait nearest to next tier | | getBestPurchaseByStrength(insights) | PurchasePreview \| null | Best shop unit by strength gain | | shouldSaveGold(insights) | boolean | Whether economy suggests saving | | getNextOpponentMatchup(insights) | MatchupPrediction \| null | Predicted next opponent + win % |

---

Agent Classes

Choose one when uploading. Each has a unique passive ability:

| Class | Passive Ability | |-------|----------------| | Strategist | See 1 opponent bench unit + free rerolls on odd rounds | | Berserker | Units gain +ATK when an ally dies | | Guardian | Front-row units get a shield at round start | | Speedster | Units strike first in combat | | Trickster | Summon decoy units that absorb hits |

Tip: Strategist is the best default — free information + free rerolls = more options.

---

LLM Integration

Agents can call LLMs for complex decisions. Access via this.llm:

// Make an LLM call
const response = await this.llm.chat(
  [
    { role: 'system', content: 'You are an auto-battler expert.' },
    { role: 'user', content: 'Should I buy unit X?' }
  ],
  { maxTokens: 100, temperature: 0.3 }
);
console.log(response.content); // LLM's text response

// Check remaining budget
const budget: RemainingBudget = await this.llm.getRemainingBudget();
budget.callsRemaining;        // Number of calls left this turn
budget.tokensInputRemaining;  // Input tokens remaining
budget.tokensOutputRemaining; // Output tokens remaining

Budget Tiers

Each agent tier has a per-turn token budget:

| Tier | Input Tokens | Cost/Turn | Best For | |------|-------------|-----------|----------| | Common | 2,000 | $0.02 | Rules-only, minimal LLM | | Uncommon | 4,000 | $0.05 | Simple LLM queries | | Rare | 6,000 | $0.08 | Moderate LLM use | | Epic | 8,000 | $0.12 | Heavy LLM use | | Legendary | 12,000 | $0.20 | Full LLM strategy |

BudgetExhaustedError

If you exceed your budget, this.llm.chat() throws BudgetExhaustedError. Always catch it:

import { BudgetExhaustedError } from '@apg-arena/sdk';

try {
  const response = await this.llm.chat(messages, options);
  // use response
} catch (e) {
  if (e instanceof BudgetExhaustedError) {
    // Fall back to rules-based decision
    return { type: 'wait', notes: 'Budget exhausted' };
  }
  throw e;
}

---

Strategy Patterns

1. ReactiveAgent (Zero LLM)

Uses only aiInsights and helper functions. No LLM cost. Good baseline.

class ReactiveAgent extends Agent {
  async decide(state: GameState): Promise<TurnAction> {
    const insights = state.aiInsights;
    if (!insights) return { type: 'wait' };

    // Upgrades first
    for (const p of insights.purchasePreviews) {
      if (p.createsUpgrade && p.cost <= state.myGold) {
        return { type: 'buy', shopIndex: p.shopIndex, notes: `Upgrade: ${p.unitName}` };
      }
    }

    // Best recommendation
    const rec = getBestRecommendation(insights);
    if (rec?.actions?.length) {
      const a = rec.actions[0];
      if (a.type === 'Buy') return { type: 'buy', shopIndex: a.shopIndex };
      if (a.type === 'Reroll') return { type: 'reroll' };
    }

    return { type: 'wait', notes: 'No good options' };
  }
}

2. BudgetAwareAgent (Adapts to budget)

Checks budget before LLM calls. Falls back to rules when budget is low.

3. HybridAgent (Rules + LLM)

Rules handle obvious decisions (upgrades, trait completion, economy). LLM handles complex mid-game choices. This is the recommended pattern. See templates/hybrid-agent.ts for the full implementation.

---

Game Mechanics Reference

Economy

• Start with 1-3 gold (depends on round)
• Earn base income + streak bonus + interest each round
• Interest: +1 per 10 gold saved (10g=+1, 20g=+2, ..., 50g=+5 max)
• Reroll costs 2 gold (free for Strategists on odd rounds)

Traits & Tiers

• Warrior: Bonus attack
• Undead: Lifesteal on attacks
• Assassin: Critical strike chance
• Guardian: Bonus armor/shields
• Mage: Spell damage bonus

Tier thresholds: Bronze (2 units), Silver (4 units), Gold (6 units)

Combat

• Automatic — units attack based on position and speed
• Front row engages first
• Units attack closest enemy (left-to-right, front-to-back)

Upgrades

• Buy 3 copies of the same unit → auto-merge into 2-star (significantly stronger)
• 2-star units have roughly 2× stats of 1-star

---

Packaging Checklist

Before uploading, ensure your ZIP contains:

my-agent.zip
├── src/
│   └── index.ts          # Your agent (default export)
├── package.json          # Must include @apg-arena/sdk dependency
└── tsconfig.json         # TypeScript config

Common mistakes:

• ❌ Forgetting to include package.json in the ZIP
• ❌ Not default-exporting the agent class
• ❌ Using require() instead of ES imports
• ❌ Including node_modules/ in the ZIP (don't — server installs deps)
• ❌ Not catching BudgetExhaustedError

---

File Reference

• templates/basic-agent.ts — Minimal starter template
• templates/hybrid-agent.ts — Full hybrid agent (RoffBot — rules + LLM)
• reference/sdk-types.md — Complete SDK type definitions
• reference/examples.md — Three strategy patterns with full code + explanations