Configuration Overview

Every NPC trainer’s battle behavior is defined in a JSON config file loaded through datapacks. This page covers where configs live, how inheritance works, and the top-level fields that shape overall AI behavior.

File Location

AI configs are loaded from:

data/<namespace>/battle_ai/<name>.json

The config’s resource ID becomes <namespace>:<name>. For example:

data/smart_trainers/battle_ai/expert.json becomes smart_trainers:expert
data/mypack/battle_ai/fire_gym.json becomes mypack:fire_gym

Configs reload when you run /reload.

Inheritance

Configs can inherit from a parent using the parent field:

{
  "parent": "smart_trainers:expert",
  "max_select_margin": 0.05
}

This creates a config that inherits everything from the expert preset but overrides a single value. You can write a specialized config with just a few lines that inherits hundreds of lines of behavior from a parent. Chains work too — a config can inherit from a parent that inherits from a grandparent.

Merge Rules

There are three merge behaviors depending on the type of field:

Scalar Values (move_bias, max_select_margin, etc.) : Child overrides parent. If the child does not specify a value, it inherits from the parent.

Object Values (skill, personality, prediction, team_synergy) : Child replaces the entire object. If the child does not specify it, it inherits the parent’s object.

Rule Lists (action_priorities, move_scoring_rules, switch_conditions, gimmick_rules) : Three behaviors based on what the child provides:

Child Value	Behavior
Not specified (`null`)	Inherits the parent’s list entirely
Empty array (`[]`)	Clears the parent’s rules — starts fresh
Array with rules	Child rules are prepended to parent rules. Child rules come first and are evaluated first.

Top-Level Fields

These fields sit at the root of the config JSON and control global AI behavior:

Field	JSON Key	Type	Default	Description
Move Bias	`move_bias`	`double`	`1.0`	Global multiplier on all move scores. Higher values make the AI more likely to attack.
Status Move Bias	`status_move_bias`	`double`	`0.85`	Additional multiplier applied to status moves (0 base power). Stacks with `move_bias`.
Switch Bias	`switch_bias`	`double`	`0.85`	Global multiplier on all switch scores. Higher values make the AI more willing to switch.
Item Bias	`item_bias`	`double`	`0.85`	Global multiplier on all item usage scores. Higher values make the AI more likely to use items.
Gimmick Bias	`gimmick_bias`	`double`	`1.0`	Global multiplier for gimmick activation scores (Mega, Tera, Dynamax, Z-Move). Currently reserved — gimmick activation is controlled entirely by `gimmick_rules`.
Max Select Margin	`max_select_margin`	`double`	`0.25`	Randomness margin for final action selection. See below for details.

Understanding max_select_margin

After all scoring is done, the AI looks at the highest-scoring action and considers all actions whose score is at least best_score * (1 - max_select_margin). It then picks from those candidates using weighted random selection (higher scores are more likely). This prevents the AI from being 100% predictable while still favoring better options.

Value	Behavior
`0.0`	Perfectly deterministic. Same situation produces the same choice every time.
`0.05` — `0.15`	Championship-level play. Very rarely picks suboptimal moves.
`0.25`	Default. Occasionally makes “interesting” choices.
`0.5+`	Noticeably sloppy. Good for simulating less experienced trainers.
`1.0`	Nearly random selection.