Gimmick Rules & Event Hooks

Gimmick Rules & Event Hooks

Gimmick rules control when the AI uses gimmick mechanics — Mega Evolution, Dynamax, Terastallize, and Z-Move. When a gimmick rule’s condition passes, the AI sets the gimmick flag on the chosen move’s action response, telling Showdown to activate the gimmick alongside the move.

How Gimmick Rules Work

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.

Configuration Example

This example shows all four gimmick types configured together:

{
  "gimmick_rules": [
    {
      "gimmick_type": "mega",
      "condition": "q.pokemon.can_mega && q.pokemon.current_hp_percent > 0.5",
      "priority": 70,
      "bias_multiplier": 1.5
    },
    {
      "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"
      }
    },
    {
      "gimmick_type": "dynamax",
      "condition": "q.pokemon.can_dynamax && q.battle.turn > 2",
      "priority": 55,
      "bias_multiplier": 1.5
    },
    {
      "gimmick_type": "zmove",
      "condition": "q.pokemon.can_zmove && q.pokemon.current_hp_percent > 0.3",
      "priority": 50,
      "bias_multiplier": 1.8
    }
  ]
}

Field Reference

Field	Type	Default	Description
gimmick_type	string	required	One of: "mega", "dynamax", "tera", "zmove"
condition	Molang	required	When this evaluates to >0, the gimmick is considered. Use q.pokemon.can_mega, q.pokemon.can_tera, q.pokemon.can_dynamax, q.pokemon.can_zmove to check availability.
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).

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.

Activation Flow

Here is the complete 6-step 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. Sort and iterate — The AI evaluates gimmick rules sorted by priority (highest first).
3. Check availability — For each rule, the AI checks if the gimmick is actually available via ShowdownMoveset.getGimmicks().
4. 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).
5. First match wins — The gimmick ID from the first passing rule is attached to the final MoveActionResponse. No further gimmick rules are evaluated.
6. Personality after gimmicks — Personality modifiers are applied after gimmick evaluation, so personality variance can still influence the final move choice.

Gimmick Availability Checks

Always include the appropriate availability query in your condition — q.pokemon.can_mega, q.pokemon.can_tera, q.pokemon.can_dynamax, or q.pokemon.can_zmove. If the gimmick is not available, the rule is skipped regardless, but checking upfront makes your config self-documenting and avoids unnecessary condition evaluation.

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": "..."
}