Configuration Overview

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.

Deprecated Path

For backwards compatibility, configs are also loaded from data/<namespace>/battle_ai_configs/<name>.json with a warning. If a config exists in both paths, the new battle_ai/ path takes priority. Move your configs to battle_ai/ to silence the warning.

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) : 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.

Gimmick Rules (gimmick_rules) : Same null/empty behavior as above, but with type-level overriding — if the child defines any rule for a gimmick type (e.g., "dynamax"), ALL parent rules for that same type are excluded. This prevents a parent’s generic gimmick rule from bypassing a child’s preferred_species restriction. Parent rules for other gimmick types are still inherited normally.

Circular Inheritance

Circular inheritance (A inherits B, B inherits A) is detected and throws an error on load.

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 applied on top of each gimmick rule’s bias_multiplier. Effective bias = gimmick_bias * rule.bias_multiplier. Set >1 to make the AI more eager to use gimmicks overall.
Allowed Gimmicks	allowed_gimmicks	string[]?	null	Whitelist of gimmick types this NPC can use. null or absent = no gimmicks allowed (opt-in). Values: "mega", "dynamax", "tera", "zmove". See 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.

Start With Presets

You rarely need to set these fields from scratch. Inherit from a built-in preset like smart_trainers:medium or smart_trainers:expert and override only what you need. The presets already have sensible defaults for all top-level fields.