Quick Start

Quick Start

This guide walks you through creating your first custom trainer AI, assigning it to an NPC, and testing it. You will have a working config in under five minutes.

Prefer a visual builder?

You can skip writing JSON entirely and use the Trainer Workbench instead. Toggle EZ Mode to configure trainers with sliders and switches, or use Advanced Mode for full control. It exports a ready-to-use datapack.

Prerequisites

• Smart Trainers installed on your server (see Installation & Setup)
• A datapack (either an existing one or a new one in your world’s datapacks/ folder)
• An NPC trainer to assign the AI to

Step 1: Create Your Config File

Create a new file at:

data/<your_namespace>/battle_ai/my_trainer.json

For example, if your datapack namespace is mypack:

data/mypack/battle_ai/my_trainer.json

Paste the following content:

{
  "parent": "smart_trainers:medium",
  "personality": {
    "enabled": true,
    "trait_variance": 0.1
  },
  "action_priorities": [
    {
      "id": "heal_when_low",
      "condition": "q.pokemon.current_hp_percent < 0.3",
      "action_type": "move",
      "move_filter": { "categories": ["heal"] },
      "priority": 80,
      "bias_multiplier": 2.5,
      "score_bonus": 100.0
    }
  ]
}

This creates a trainer that:

• Inherits from medium — gets skill level 3, STAB bonuses, type effectiveness scoring, and basic switch logic from the built-in preset
• Has personality variance — slight randomness so it does not play identically every battle
• Prioritizes healing — when below 30% HP, strongly favors healing moves like Recover or Roost

Step 2: Understand Each Field

Let’s break down what each part of the config does.

"parent": "smart_trainers:medium"

Inheritance. Your config starts with everything from the medium preset and only overrides what you specify. This single line gives your trainer:

• Skill level 3 (picks randomly ~20% of the time)
• STAB and type effectiveness scoring
• Switch logic for bad matchups
• Priority move finishing

You only need to add what makes your trainer unique.

"personality"

Controls how “human” the AI feels. With trait_variance: 0.1, the trainer’s aggression, risk tolerance, and other traits shift slightly between battles. Two fights against the same trainer will play out a little differently.

Field	Value	Effect
enabled	true	Personality traits influence scoring
trait_variance	0.1	Each trait can deviate up to 10% from its base value

"action_priorities"

The most powerful tool for defining trainer behavior. Each rule boosts or penalizes specific actions when a condition is met.

Field	Value	Purpose
id	"heal_when_low"	Unique name for debug logs
condition	"q.pokemon.current_hp_percent < 0.3"	Triggers when HP is below 30%
action_type	"move"	Applies to move actions
move_filter	\{ "categories": ["heal"] \}	Only affects healing moves
priority	80	Evaluated before lower-priority rules
bias_multiplier	2.5	Multiplies the move’s score by 2.5
score_bonus	100.0	Adds 100 points to the score

Why score_bonus Matters

Status and utility moves start with a base score of ~1.0 (since they have 0 base power). Without score_bonus, even a bias_multiplier of 10.0 only produces a score of 10 — which loses to Earthquake at 100+. The score_bonus is what makes non-damaging moves competitive with attacks.

Step 3: Assign to an NPC

Set your NPC trainer’s AI config to the resource ID of your file:

mypack:my_trainer

The resource ID is derived from the file path: data/mypack/battle_ai/my_trainer.json becomes mypack:my_trainer.

Step 4: Test Your Config

1. Run /reload in-game to load your new config
2. Challenge the NPC trainer to a battle
3. Watch how it behaves — it should fight competently with type awareness and prioritize healing when its Pokemon get low

Enable Debug Mode

For detailed insight into the AI’s decision-making, enable debug mode. This prints every score, rule match, and final ranking to chat each turn so you can see exactly why the AI chose a particular action.

Debug output shows you:

• The score for each available move after all rules are applied
• Which action priority rules triggered and their effect
• Which gimmick rules were evaluated
• The final candidate pool and selected action

This is invaluable for tuning your configs — if the AI is not using Swords Dance when you expect it to, debug mode will show you exactly why another action scored higher.

Expanding Your Config

Once your basic config works, try adding more behavior. Here are common patterns:

Setup Moves When Safe

{
  "id": "swords_dance_when_safe",
  "condition": "q.pokemon.current_hp_percent > 0.8 && q.pokemon.under_threat < 0.3",
  "action_type": "move",
  "move_filter": { "names": ["swordsdance"] },
  "priority": 90,
  "bias_multiplier": 3.0,
  "score_bonus": 120.0
}

When the Pokemon is healthy (above 80% HP) and not threatened, it strongly favors using Swords Dance. The high score_bonus of 120 makes it competitive with strong STAB attacks.

Stop Over-Boosting

{
  "id": "stop_boosting_at_plus_4",
  "condition": "q.pokemon.stat_boosts.atk >= 4 || q.pokemon.stat_boosts.spa >= 4",
  "action_type": "move",
  "move_filter": { "categories": ["buff"] },
  "priority": 200,
  "bias_multiplier": 0.0,
  "score_bonus": -200.0
}

Prevents the AI from endlessly setting up. Once Attack or Special Attack is at +4, buff moves are completely suppressed. The high priority (200) ensures this overrides any other rule that might encourage boosting.

Switch Under Pressure

{
  "id": "switch_under_threat",
  "condition": "q.pokemon.under_threat > 0.5 && q.pokemon.current_hp_percent > 0.3",
  "action_type": "switch",
  "priority": 70,
  "bias_multiplier": 2.5,
  "score_bonus": 60.0
}

When the active Pokemon is heavily threatened but still has enough HP to be worth preserving, the AI favors switching to a better matchup.

Toxic Against Walls

{
  "id": "toxic_on_walls",
  "condition": "!q.target.has_status && q.target.defence > 100 && q.target.special_defence > 100",
  "action_type": "move",
  "move_filter": { "names": ["toxic"] },
  "priority": 85,
  "bias_multiplier": 3.0,
  "score_bonus": 100.0
}

If the opponent is a bulky wall with no status condition, the AI prioritizes using Toxic to wear it down.

Built-in Presets Reference

You can inherit from any of these presets to get a head start:

Preset	Resource ID	Skill	Description
Random	smart_trainers:random	0	Pure random move selection
Easy	smart_trainers:easy	2	Basic type awareness, occasionally random
Medium	smart_trainers:medium	3	STAB bonus, type effectiveness, switches on bad matchups
Hard	smart_trainers:hard	4	Full damage prediction, hazard setup, ability immunities
Expert	smart_trainers:expert	5	Tight margin, KO prediction, gimmick rules
Champion	smart_trainers:champion	5	Setup sweeps, strategic healing, Will-o-Wisp
VGC Master	smart_trainers:vgc_master	5	Doubles-optimized with Fake Out, Protect, speed control
Gen 4 Cynthia	smart_trainers:gen4_cynthia	5	Recreation of Champion Cynthia from Pokemon Platinum

Choosing a Parent Preset

For most custom trainers, smart_trainers:medium or smart_trainers:hard are the best starting points. medium gives competent play without being overwhelming. hard adds damage calculation, hazard awareness, and ability checks for a tougher challenge.

How Inheritance Works

When you set "parent": "smart_trainers:medium", your config inherits all fields from the medium preset. Only fields you explicitly specify are overridden:

• Scalar values (like move_bias, max_select_margin): your value replaces the parent’s
• Object values (like skill, personality): your object replaces the parent’s entire object
• Rule lists (like action_priorities, switch_conditions): your rules are prepended to the parent’s rules — they do not replace them

This means a 10-line config file can inherit hundreds of lines of battle logic. Inheritance chains work too — a config can inherit from a parent that inherits from a grandparent.

Note

If you want to clear a parent’s rule list and start from scratch, use an empty array: "action_priorities": []. This removes all inherited action priorities so only your rules apply.

Next Steps

Now that you have a working custom trainer, explore the full configuration options:

• Introduction — Understand the complete 7-step AI decision flow
• AI Config Reference — Every field, rule type, and scoring detail
• Molang Reference — All available queries for writing conditions