Skip to content

Battle Bags

Battle bags define the items an NPC trainer can use during battle and the rules governing when to use them. A gym leader might carry two Hyper Potions and a Full Heal, while an Elite Four member might have four Full Restores and Max Revives.

Battle bags are loaded from:

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

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

  • data/smart_trainers/battle_bags/gym_leader.json becomes smart_trainers:gym_leader
  • data/mypack/battle_bags/elite.json becomes mypack:elite

A complete battle bag file looks like this:

{
"id": "gym_leader",
"enabled": true,
"maxItemsPerBattle": 2,
"items": [
{ "itemId": "cobblemon:super_potion", "quantity": 2, "category": "HEALING", "baseScore": 2.0 },
{ "itemId": "cobblemon:full_heal", "quantity": 1, "category": "STATUS_CURE", "baseScore": 1.5 }
],
"usageRules": [
{
"id": "heal_when_critical",
"condition": "q.pokemon.current_hp_percent < 0.25",
"itemFilter": { "categories": ["HEALING"] },
"priority": 20,
"biasMultiplier": 4.0,
"scoreBonus": 150.0
}
]
}
FieldTypeDescription
idstringIdentifier (set automatically on load).
enabledboolWhether the bag is usable at all.
maxItemsPerBattleintTotal number of items that can be used per battle (across all item types).
itemsarrayThe items available in this bag.
usageRulesarrayRules governing when items should be used.

Each entry in the items array defines a single item in the bag:

FieldTypeDefaultDescription
itemIdstringRequiredThe Minecraft/Cobblemon item ID (e.g., "cobblemon:full_restore").
quantityint1How many of this item are available per battle.
categorystring"OTHER"Category for filtering in usage rules.
baseScoredouble1.0Starting score for this item. Higher values make the AI more eager to use it.
CategoryDescription
HEALINGHP restoration: Potion, Super Potion, Hyper Potion, Full Restore
STATUS_CUREStatus removal: Antidote, Awakening, Full Heal, Full Restore
STAT_BOOSTX Items: X Attack, X Defense, etc.
PP_RESTOREPP restoration: Ether, Elixir
GUARDGuard Spec, Dire Hit
REVIVERevival: Revive, Max Revive
OTHERAnything else

Rules in the usageRules array control when the AI uses items. They work similarly to action priorities — each rule checks a Molang condition and modifies the item’s score when the condition passes.

FieldJSON KeyTypeDefaultDescription
IDidstringnullUnique name.
ConditionconditionMolangRequiredCondition based on the active Pokemon state. q.pokemon.* refers to the active Pokemon.
Item FilteritemFilterobjectnullFilter which items this rule applies to.
Prioritypriorityint0Higher priority rules are evaluated first.
Bias MultiplierbiasMultiplierdouble1.0Multiplied with the item’s current score.
Score BonusscoreBonusdouble0.0Added to the item’s score after the multiplier. Critical for items to compete with attack moves.
Target ConditiontargetConditionMolangnullCondition for selecting which Pokemon to target.

Item filters narrow which items a usage rule applies to:

FieldTypeDescription
categoriesstring[]Item must be in one of these categories.
itemsstring[]Item ID must be in this list.
conditionMolangAdditional Molang condition.

Items start from their baseScore, which is typically 1—4. Without a scoreBonus, items will almost never compete with attack moves. Use these guidelines:

Score BonusWhen to Use
60—100Situational use. Good to have but not urgent.
120—150Important. HP critical or significant advantage worth preserving.
170—200Urgent. Nearly dead Pokemon with stat boosts worth keeping alive.
220+Emergency. Almost always uses the item.
{
"enabled": true,
"maxItemsPerBattle": 2,
"items": [
{ "itemId": "cobblemon:hyper_potion", "quantity": 2, "category": "HEALING", "baseScore": 2.0 },
{ "itemId": "cobblemon:full_heal", "quantity": 1, "category": "STATUS_CURE", "baseScore": 1.5 }
],
"usageRules": [
{
"id": "heal_when_critical",
"condition": "q.pokemon.current_hp_percent < 0.25",
"itemFilter": { "categories": ["HEALING"] },
"priority": 20,
"biasMultiplier": 4.0,
"scoreBonus": 150.0
},
{
"id": "cure_status",
"condition": "q.pokemon.has_status",
"itemFilter": { "categories": ["STATUS_CURE"] },
"priority": 15,
"biasMultiplier": 2.0,
"scoreBonus": 80.0
}
]
}

This gym leader carries two Hyper Potions and one Full Heal, can use up to 2 items per battle, heals urgently when below 25% HP, and cures status conditions with moderate priority.

You can reference bag state in Molang conditions throughout your AI config:

QueryReturnsDescription
q.bag.enabled0/1Whether the bag is usable
q.bag.remaining_usesdoubleTotal remaining item uses this battle
q.bag.has_healing_item0/1Has a HEALING category item available
q.bag.has_status_cure0/1Has a STATUS_CURE item available
q.bag.has_revive0/1Has a REVIVE item available
q.bag.has_stat_boost0/1Has a STAT_BOOST item available
q.bag.remaining_quantity(itemId)doubleRemaining quantity of a specific item
q.bag.can_use_item(itemId)0/1Whether a specific item can be used right now