Introduction to Smart Trainers

Smart Trainers is a configurable battle AI system for Cobblemon. Every NPC trainer can have unique battle behavior defined entirely in JSON — from casual trainers who pick moves randomly to championship-level opponents that predict your strategy, set up sweeps, and switch intelligently.

What is Smart Trainers?

Smart Trainers replaces Cobblemon’s default NPC battle logic with a fully data-driven AI engine. Instead of hard-coding trainer behavior in Java, you write JSON config files that control every aspect of how a trainer fights:

Which moves are favored and when
When to switch Pokemon and which one to send in
When to use items from a battle bag
When to activate gimmick mechanics (Mega Evolution, Terastallization, Dynamax, Z-Moves)
How much randomness to inject so battles feel natural

All conditions are written in Molang, a simple expression language. If you have used Bedrock Edition addons, you already know it. If not, it is straightforward — expressions like q.pokemon.current_hp_percent < 0.5 && q.target.has_status == 0 mean “my active Pokemon is below 50% HP AND the target does not already have a status condition.”

Why Smart Trainers?

Cobblemon has the battle engine, but NPC trainers all fight the same way. Smart Trainers fills that gap:

Every trainer can be unique — a Fire Gym Leader sets up Sunny Day, a rival predicts your switches, a casual Bug Catcher picks moves almost randomly
No code required — all behavior is defined in JSON datapacks that any server operator or modpack author can create
Inheritance system — write a 5-line config that inherits hundreds of lines of behavior from a built-in preset
Hot reloading — run /reload to apply changes without restarting the server
Built-in presets — ship with ready-to-use difficulty tiers from random to champion

How the AI Works

Every turn, the AI follows a 7-step decision flow to pick the best action:

Step 1: Skill Check

The AI rolls against its configured skill level (0—5). If the check fails, it picks a random move and skips everything else. Skill level 5 never fails. Skill level 0 always picks randomly.

Step 2: Score Moves

For each available move, the AI calculates a score. This starts from base power (or estimated damage percentage if use_damage_calc is enabled), then applies STAB bonuses, type effectiveness, accuracy penalties, and any custom move scoring rules you have defined.

Step 3: Score Switches

For each healthy benched Pokemon, the AI calculates a switch score based on type matchup advantage against the current opponent, HP remaining, and custom switch conditions.

Step 4: Score Items

If the trainer has a battle bag, the AI scores each available item based on urgency (HP thresholds, status conditions) and custom item usage rules.

Step 5: Apply Action Priorities

Your custom rules that boost or penalize specific actions based on conditions. For example, “use Swords Dance when healthy and not threatened” or “switch out when under heavy pressure.” These are the primary tool for defining unique trainer behavior.

Step 6: Evaluate Gimmick Rules

The AI checks whether Mega Evolution, Terastallization, Dynamax, or Z-Move should be activated. Gimmick rules are evaluated by priority, and the first matching rule wins. When a gimmick activates, it biases relevant move scores to encourage impactful plays.

Step 7: Apply Personality and Select

Personality modifiers add slight variance — aggression boosts damaging moves, risk tolerance favors high-risk plays, and so on. Finally, the AI picks from the top-scoring options with a configurable margin of randomness (max_select_margin) so it does not play identically every time.

Key Features

Feature	Description
Datapack-driven	All config is JSON in your datapack — no Java code needed
Inheritance	Configs can inherit from parent configs and override specific fields
Built-in presets	8 AI presets from `random` to `champion`, plus battle bag presets
Molang conditions	Every rule uses Molang expressions for flexible, powerful conditions
Personality system	Trainers have personality traits (aggression, risk tolerance, etc.) that subtly influence decisions
Prediction engine	AI remembers revealed moves, items, and abilities across turns
Battle bags	Trainers can use items (potions, revives, X items) with configurable rules
Move categories	Extendable category system (heal, buff, hazard, pivot, etc.) for filtering moves
Gimmick support	Mega Evolution, Terastallization, Dynamax, and Z-Move activation rules
Temp variables	Persistent `t.xxx` variables let you track state across turns within a battle
Debug mode	See every score, rule match, and final ranking in chat for easy testing
Hot reload	Run `/reload` to apply config changes without a server restart

What You Can Configure

Smart Trainers exposes three types of datapack resources:

AI Configs (data/\{namespace\}/battle_ai/) — The core behavior definition. Skill level, biases, action priorities, move scoring rules, switch conditions, gimmick rules, personality, and prediction settings.
Battle Bags (data/\{namespace\}/battle_bags/) — Item inventories and usage rules for trainers that use potions, revives, and other battle items.
Move Categories (data/\{namespace\}/move_categories/) — Custom move-to-category mappings that the AI uses for filtering (e.g., which moves count as “heal” or “hazard”).

All three support the standard datapack merge behavior — multiple datapacks can contribute configs, and inheritance chains let you build specialized trainers from simple building blocks.

Next Steps

Ready to get started? Here is the recommended path:

Installation & Setup — Get Smart Trainers running on your server
Quick Start — Create your first custom trainer AI in five minutes
AI Config Reference — Deep dive into every configurable field