Battle Bags
Battle Bags
Section titled “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.
Bag File Location
Section titled “Bag File Location”Battle bags are loaded from:
data/<namespace>/battle_bags/<name>.jsonThe resource ID becomes <namespace>:<name>. For example:
data/smart_trainers/battle_bags/gym_leader.jsonbecomessmart_trainers:gym_leaderdata/mypack/battle_bags/elite.jsonbecomesmypack:elite
Bag Structure
Section titled “Bag Structure”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 } ]}Bag Fields
Section titled “Bag Fields”| Field | Type | Description |
|---|---|---|
id | string | Identifier (set automatically on load). |
enabled | bool | Whether the bag is usable at all. |
maxItemsPerBattle | int | Total number of items that can be used per battle (across all item types). |
items | array | The items available in this bag. |
usageRules | array | Rules governing when items should be used. |
Each entry in the items array defines a single item in the bag:
| Field | Type | Default | Description |
|---|---|---|---|
itemId | string | Required | The Minecraft/Cobblemon item ID (e.g., "cobblemon:full_restore"). |
quantity | int | 1 | How many of this item are available per battle. |
category | string | "OTHER" | Category for filtering in usage rules. |
baseScore | double | 1.0 | Starting score for this item. Higher values make the AI more eager to use it. |
Item Categories
Section titled “Item Categories”| Category | Description |
|---|---|
HEALING | HP restoration: Potion, Super Potion, Hyper Potion, Full Restore |
STATUS_CURE | Status removal: Antidote, Awakening, Full Heal, Full Restore |
STAT_BOOST | X Items: X Attack, X Defense, etc. |
PP_RESTORE | PP restoration: Ether, Elixir |
GUARD | Guard Spec, Dire Hit |
REVIVE | Revival: Revive, Max Revive |
OTHER | Anything else |
Item Usage Rules
Section titled “Item Usage Rules”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.
Usage Rule Fields
Section titled “Usage Rule Fields”| Field | JSON Key | Type | Default | Description |
|---|---|---|---|---|
| ID | id | string | null | Unique name. |
| Condition | condition | Molang | Required | Condition based on the active Pokemon state. q.pokemon.* refers to the active Pokemon. |
| Item Filter | itemFilter | object | null | Filter which items this rule applies to. |
| Priority | priority | int | 0 | Higher priority rules are evaluated first. |
| Bias Multiplier | biasMultiplier | double | 1.0 | Multiplied with the item’s current score. |
| Score Bonus | scoreBonus | double | 0.0 | Added to the item’s score after the multiplier. Critical for items to compete with attack moves. |
| Target Condition | targetCondition | Molang | null | Condition for selecting which Pokemon to target. |
Item Filters
Section titled “Item Filters”Item filters narrow which items a usage rule applies to:
| Field | Type | Description |
|---|---|---|
categories | string[] | Item must be in one of these categories. |
items | string[] | Item ID must be in this list. |
condition | Molang | Additional Molang condition. |
Score Bonus Guidelines
Section titled “Score Bonus Guidelines”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 Bonus | When to Use |
|---|---|
| 60—100 | Situational use. Good to have but not urgent. |
| 120—150 | Important. HP critical or significant advantage worth preserving. |
| 170—200 | Urgent. Nearly dead Pokemon with stat boosts worth keeping alive. |
| 220+ | Emergency. Almost always uses the item. |
Example: Gym Leader Bag
Section titled “Example: Gym Leader Bag”{ "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.
Bag Queries
Section titled “Bag Queries”You can reference bag state in Molang conditions throughout your AI config:
| Query | Returns | Description |
|---|---|---|
q.bag.enabled | 0/1 | Whether the bag is usable |
q.bag.remaining_uses | double | Total remaining item uses this battle |
q.bag.has_healing_item | 0/1 | Has a HEALING category item available |
q.bag.has_status_cure | 0/1 | Has a STATUS_CURE item available |
q.bag.has_revive | 0/1 | Has a REVIVE item available |
q.bag.has_stat_boost | 0/1 | Has a STAT_BOOST item available |
q.bag.remaining_quantity(itemId) | double | Remaining quantity of a specific item |
q.bag.can_use_item(itemId) | 0/1 | Whether a specific item can be used right now |