Gimmick Rules & Event Hooks

Gimmick Rules & Event Hooks

Gimmick rules control when the AI uses gimmick mechanics — Mega Evolution, Dynamax, Terastallize, and Z-Move. Gimmicks are opt-in — an NPC will never use a gimmick unless its AI config explicitly allows it.

allowed_gimmicks

A top-level field that gates which gimmick types the AI is allowed to use. If omitted or empty, no gimmicks are allowed.

{
  "allowed_gimmicks": ["dynamax"],
  "gimmick_rules": [
    {
      "gimmick_type": "dynamax",
      "condition": "1",
      "preferred_species": "Charizard",
      "priority": 100,
      "bias_multiplier": 10.0
    }
  ]
}

Only gimmick types listed in allowed_gimmicks will be considered. Any gimmick rule for a type not in this list is skipped. Valid values: "mega", "dynamax", "tera", "zmove".

Gimmick Rule Fields

Rules are evaluated sorted by priority (highest first). First matching rule wins — only one gimmick can be used per turn. If the chosen gimmick is not actually available (e.g., already Mega Evolved), the rule is skipped and the next rule is tried.

{
  "allowed_gimmicks": ["tera"],
  "gimmick_rules": [
    {
      "gimmick_type": "tera",
      "condition": "1",
      "preferred_species": "Pawmot",
      "priority": 100,
      "bias_multiplier": 10.0
    }
  ]
}

Field	Type	Default	Description
gimmick_type	string	required	One of: "mega", "dynamax", "tera", "zmove". Must also be listed in allowed_gimmicks.
condition	Molang	required	When to consider using this gimmick. Use "1" for always, or queries like q.pokemon.can_dynamax && q.pokemon.current_hp_percent > 0.5.
priority	int	0	Higher priority rules are evaluated first. First match wins.
bias_multiplier	double	1.0	Score multiplier applied to move scores when the gimmick is activated. Values >1 make moves stronger when gimmicking, encouraging the AI to pick high-impact moves.
move_filter	MoveFilter?	null	Optional. If specified, the bias_multiplier only applies to moves matching this filter. Useful for Tera (boost STAB-type moves) or Z-Moves (boost a specific move).
preferred_species	string?	null	Optional. A PokemonProperties string (e.g., "Charizard", "charizard gmax=true", "pawmot tera_type=electric"). If specified, the gimmick is saved for this Pokemon — it will not activate on other Pokemon as long as the preferred one is alive in the team. See below.

preferred_species — Ace-Only Gimmicking

The preferred_species field implements main-line-style gimmicking: Leon always Dynamaxes his Charizard, Nemona always Terastallizes her Pawmot.

The value is parsed as a PokemonProperties string using Cobblemon’s property matching system. This means you can match by:

• Species only: "Charizard" — matches any Charizard
• Species + form: "charizard gmax=true" — matches only G-Max Charizard
• Species + tera type: "pawmot tera_type=electric" — matches Pawmot with Electric tera type
• Any valid property combo: "gardevoir shiny" — matches only shiny Gardevoir

How it works:

1. If the active Pokemon matches preferred_species → gimmick is allowed (proceed to condition check)
2. If the active Pokemon does NOT match, but the preferred Pokemon is alive in the back → gimmick is deferred (skip this rule, save it for later)
3. If the preferred Pokemon is dead or not in the team → gimmick is allowed on whoever is active (graceful fallback)

Move Filters in Gimmick Rules

The move_filter field lets you focus the gimmick’s score boost on specific moves rather than all moves. This is especially useful for Terastallization (boost only moves matching the Tera type) or Z-Moves (boost only the move that benefits from the Z-Crystal).

When move_filter is specified, the bias_multiplier only applies to moves that pass the filter. All other moves keep their original scores. When move_filter is omitted, the bias_multiplier applies to all move scores.

{
  "gimmick_type": "tera",
  "condition": "q.pokemon.can_tera && q.pokemon.tera_type_advantageous",
  "priority": 60,
  "bias_multiplier": 1.3,
  "move_filter": {
    "condition": "q.move.type == q.pokemon.tera_type"
  }
}

In this example, only moves whose type matches the Pokemon’s Tera type get the 1.3x score boost. Other moves are unaffected, steering the AI toward STAB-boosted attacks when Terastallizing.

Gimmick Inheritance

When a child config defines gimmick rules for a specific gimmick type, all parent rules for that same type are excluded. This prevents a parent’s generic rule from bypassing the child’s preferred_species logic.

For example, if the parent expert config has generic dynamax, tera, mega, and zmove rules, and the child defines a dynamax rule with preferred_species: "Charizard":

• The parent’s dynamax rule is excluded (child overrides it)
• The parent’s tera, mega, zmove rules are inherited (but blocked by allowed_gimmicks if not listed)

This means you do not need to worry about parent configs interfering with your ace-specific gimmick behavior.

Activation Flow

Here is the complete flow for how gimmick evaluation works within the decision process:

1. After initial scoring — Moves, switches, and items are scored and action priorities are applied first.
2. Check allowed_gimmicks — If the gimmick type is not listed in allowed_gimmicks, the rule is skipped.
3. Sort and iterate — The AI evaluates gimmick rules sorted by priority (highest first).
4. Check availability — For each rule, the AI checks if the gimmick is actually available from Showdown (canDynamax, canTerastallize, etc.).
5. Check preferred_species — If set, the deferred/fallback logic runs.
6. Evaluate condition — If the gimmick is available, the Molang condition is evaluated. If it passes, the bias_multiplier is applied to all move scores (or only to moves matching move_filter if specified).
7. First match wins — The gimmick ID from the first passing rule is attached to the final MoveActionResponse. No further gimmick rules are evaluated.
8. Personality after gimmicks — Personality modifiers are applied after gimmick evaluation, so personality variance can still influence the final move choice.

Responding to Opponent Gimmicks

You do not need gimmick rules to respond to an opponent’s gimmick activation. Standard action priority rules work for this — queries like q.target.is_terastallized, q.target.is_mega_evolved, and q.target.is_dynamaxed are available for use in conditions.

For example, this action priority rule boosts Protect and Detect when the opponent is Dynamaxed:

{
  "id": "protect_vs_dynamax",
  "condition": "q.target.is_dynamaxed",
  "action_type": "move",
  "move_filter": { "names": ["protect", "detect"] },
  "priority": 85,
  "bias_multiplier": 3.0,
  "score_bonus": 80.0
}

Action Priority, Not Gimmick Rule

The example above is an action priority rule, not a gimmick rule. It lives in action_priorities, not gimmick_rules. You are responding to the opponent’s gimmick by adjusting your move selection — not by activating your own gimmick.

---

Event Hooks

Event hooks are optional Molang scripts triggered at specific battle events. These fields are parsed and stored in the config, but they are not yet wired up in the AI engine. They exist for future extensibility.

Not Yet Implemented

Event hooks are reserved for future use. The fields below are accepted in config files but have no effect at this time. Do not rely on them for current AI behavior.

Field	Type	Description
on_turn_start	Molang	Triggered at the beginning of each turn.
on_move_select	Molang	Triggered when a move is selected.
on_switch_evaluate	Molang	Triggered when switch options are being evaluated.
on_battle_end	Molang	Triggered when the battle ends.

{
  "on_turn_start": "...",
  "on_move_select": "...",
  "on_switch_evaluate": "...",
  "on_battle_end": "..."
}