API module

This page documents the core API, including enumerations, data structures, and top-level functions used for interacting with the Pokémon simulation engine.

Enums

enum api.AreaType(value)

Areas where a card can be located.

Used in Option.area, Option.inPlayArea, Log.fromArea, etc.

Member Type:

int

Valid values are as follows:

DECK = <AreaType.DECK: 1>

Card in Deck (ID: 1)

HAND = <AreaType.HAND: 2>

Card in Hand (ID: 2)

DISCARD = <AreaType.DISCARD: 3>

Card in Discard Pile (ID: 3)

ACTIVE = <AreaType.ACTIVE: 4>

Active Spot (ID: 4)

BENCH = <AreaType.BENCH: 5>

Bench (ID: 5)

PRIZE = <AreaType.PRIZE: 6>

Prize cards (ID: 6)

STADIUM = <AreaType.STADIUM: 7>

Stadium card (ID: 7)

ENERGY = <AreaType.ENERGY: 8>

Energy card (ID: 8)

TOOL = <AreaType.TOOL: 9>

Tool card (ID: 9)

PRE_EVOLUTION = <AreaType.PRE_EVOLUTION: 10>

Pre-evolved form (ID: 10)

PLAYER = <AreaType.PLAYER: 11>

Player entity (ID: 11)

LOOKING = <AreaType.LOOKING: 12>

Card being looked at (ID: 12)

enum api.EnergyType(value)

Energy types

Used in Pokemon.energies, CardData.energyType, and Attack.energies.

Member Type:

int

Valid values are as follows:

COLORLESS = <EnergyType.COLORLESS: 0>

Colorless (ID: 0)

GRASS = <EnergyType.GRASS: 1>

Grass (ID: 1)

FIRE = <EnergyType.FIRE: 2>

Fire (ID: 2)

WATER = <EnergyType.WATER: 3>

Water (ID: 3)

LIGHTNING = <EnergyType.LIGHTNING: 4>

Lightning (ID: 4)

PSYCHIC = <EnergyType.PSYCHIC: 5>

Psychic (ID: 5)

FIGHTING = <EnergyType.FIGHTING: 6>

Fighting (ID: 6)

DARKNESS = <EnergyType.DARKNESS: 7>

Darkness (ID: 7)

METAL = <EnergyType.METAL: 8>

Metal (ID: 8)

DRAGON = <EnergyType.DRAGON: 9>

Dragon (ID: 9)

RAINBOW = <EnergyType.RAINBOW: 10>

Every Types (ID: 10)

TEAM_ROCKET = <EnergyType.TEAM_ROCKET: 11>

Psychic or Darkness (ID: 11)

enum api.CardType(value)

Card types

Used in CardData.cardType.

Each type corresponds to a specific category of cards in the game.

Member Type:

int

Valid values are as follows:

POKEMON = <CardType.POKEMON: 0>

Pokémon (ID: 0)

ITEM = <CardType.ITEM: 1>

Item (ID: 1)

TOOL = <CardType.TOOL: 2>

Tool (ID: 2)

SUPPORTER = <CardType.SUPPORTER: 3>

Supporter (ID: 3)

STADIUM = <CardType.STADIUM: 4>

Stadium (ID: 4)

BASIC_ENERGY = <CardType.BASIC_ENERGY: 5>

Basic Energy (ID: 5)

SPECIAL_ENERGY = <CardType.SPECIAL_ENERGY: 6>

Special Energy (ID: 6)

enum api.SpecialConditionType(value)

Special condition types

Used in Option.specialConditionType.

Member Type:

int

Valid values are as follows:

POISON = <SpecialConditionType.POISON: 0>

Poison (ID: 0)

BURN = <SpecialConditionType.BURN: 1>

Burn (ID: 1)

SLEEP = <SpecialConditionType.SLEEP: 2>

Sleep (ID: 2)

PARALYZE = <SpecialConditionType.PARALYZE: 3>

Paralyze (ID: 3)

CONFUSE = <SpecialConditionType.CONFUSE: 4>

Confuse (ID: 4)

enum api.SelectType(value)

Selection type

Used in Observation.select.type.

Each value indicates the category of selection the AI must perform, and determines how to interpret the Option list.

The selection type determines which OptionType values appear in Observation.select.option, for example: - MAIN → [PLAY, ATTACH, ATTACK, END, …] - CARD → [CARD] - ENERGY → [ENERGY] - YES_NO → [YES, NO]

Member Type:

int

Valid values are as follows:

MAIN = <SelectType.MAIN: 0>

Select a main action (ID: 0). OptionTypes: PLAY, ATTACH, EVOLVE, ABILITY, DISCARD, RETREAT, ATTACK, END

CARD = <SelectType.CARD: 1>

Select a card (ID: 1). OptionType: CARD

ATTACHED_CARD = <SelectType.ATTACHED_CARD: 2>

Select an attached card (ID: 2). OptionTypes: TOOL_CARD, ENERGY_CARD

CARD_OR_ATTACHED_CARD = <SelectType.CARD_OR_ATTACHED_CARD: 3>

Select a card or attached card (ID: 3). OptionTypes: CARD, TOOL_CARD, ENERGY_CARD

ENERGY = <SelectType.ENERGY: 4>

Select an energy (ID: 4). OptionType: ENERGY

SKILL = <SelectType.SKILL: 5>

Select a skill (ID: 5). OptionType: SKILL

ATTACK = <SelectType.ATTACK: 6>

Select an attack (ID: 6). OptionType: ATTACK

EVOLVE = <SelectType.EVOLVE: 7>

Select evolution source and target (ID: 7). OptionType: EVOLVE

COUNT = <SelectType.COUNT: 8>

Select a number (ID: 8). OptionType: NUMBER

YES_NO = <SelectType.YES_NO: 9>

Make a yes/no decision (ID: 9). OptionTypes: YES, NO

SPECIAL_CONDITION = <SelectType.SPECIAL_CONDITION: 10>

Select a special condition (ID: 10). OptionType: SPECIAL_CONDITION

enum api.SelectContext(value)

Selection context

Used in Observation.select.context.

Provides detailed context about selection. While SelectType describes the type of the selection, SelectContext gives the specific purpose or scenario for the selection.

Use this in combination with SelectType to determine precise decision-making logic.

Member Type:

int

Valid values are as follows:

MAIN = <SelectContext.MAIN: 0>

Main selection menu (ID: 0). Corresponds to SelectType.MAIN

SETUP_ACTIVE_POKEMON = <SelectContext.SETUP_ACTIVE_POKEMON: 1>

Select Pokémon to place in Active Spot during setup (ID: 1). SelectType.CARD

SETUP_BENCH_POKEMON = <SelectContext.SETUP_BENCH_POKEMON: 2>

Select Pokémon to place on Bench during setup (ID: 2). SelectType.CARD

SWITCH = <SelectContext.SWITCH: 3>

Select Pokémon to switch with Active (ID: 3). SelectType.CARD

TO_ACTIVE = <SelectContext.TO_ACTIVE: 4>

Select Pokémon to move to Active Spot (ID: 4). SelectType.CARD

TO_BENCH = <SelectContext.TO_BENCH: 5>

Select Pokémon to move to Bench (ID: 5). SelectType.CARD

TO_FIELD = <SelectContext.TO_FIELD: 6>

Select Pokémon to put into play (ID: 6). SelectType.CARD

TO_HAND = <SelectContext.TO_HAND: 7>

Select card to return to hand (ID: 7). SelectType.CARD

DISCARD = <SelectContext.DISCARD: 8>

Select card to discard (ID: 8). SelectType.CARD

TO_DECK = <SelectContext.TO_DECK: 9>

Select card to return to deck (ID: 9). SelectType.CARD

TO_DECK_BOTTOM = <SelectContext.TO_DECK_BOTTOM: 10>

Select card to return to bottom of deck (ID: 10). SelectType.CARD

TO_PRIZE = <SelectContext.TO_PRIZE: 11>

Select card to add to prize cards (ID: 11). SelectType.CARD

NOT_MOVE = <SelectContext.NOT_MOVE: 12>

Select card to leave in place (ID: 12). SelectType.CARD

DAMAGE_COUNTER = <SelectContext.DAMAGE_COUNTER: 13>

Select Pokémon to place damage counter (ID: 13). SelectType.CARD

DAMAGE_COUNTER_ANY = <SelectContext.DAMAGE_COUNTER_ANY: 14>

Select Pokémon to freely place damage counters (ID: 14). SelectType.CARD

DAMAGE = <SelectContext.DAMAGE: 15>

Select Pokémon to deal damage to (ID: 15). SelectType.CARD

REMOVE_DAMAGE_COUNTER = <SelectContext.REMOVE_DAMAGE_COUNTER: 16>

Select Pokémon to remove damage counter from (ID: 16). SelectType.CARD

HEAL = <SelectContext.HEAL: 17>

Select Pokémon to heal (ID: 17). SelectType.CARD

EVOLVES_FROM = <SelectContext.EVOLVES_FROM: 18>

Select base Pokémon to evolve from (ID: 18). SelectType.CARD

EVOLVES_TO = <SelectContext.EVOLVES_TO: 19>

Select evolution target (ID: 19). SelectType.CARD

DEVOLVE = <SelectContext.DEVOLVE: 20>

Select Pokémon to devolve (ID: 20). SelectType.CARD

ATTACH_FROM = <SelectContext.ATTACH_FROM: 21>

Select Pokémon to attach the card to (ID: 21). SelectType.CARD

ATTACH_TO = <SelectContext.ATTACH_TO: 22>

Select card to attach to the Pokémon (ID: 22). SelectType.CARD

DETACH_FROM = <SelectContext.DETACH_FROM: 23>

Select Pokémon to remove the card from (ID: 23). SelectType.CARD

LOOK = <SelectContext.LOOK: 24>

Select card to look at (ID: 24). SelectType.CARD

EFFECT_TARGET = <SelectContext.EFFECT_TARGET: 25>

Select card to apply the effect to (ID: 25). SelectType.CARD

DISCARD_ENERGY_CARD = <SelectContext.DISCARD_ENERGY_CARD: 26>

Select energy card to discard (ID: 26). SelectType.ATTACHED_CARD

DISCARD_TOOL_CARD = <SelectContext.DISCARD_TOOL_CARD: 27>

Select tool card to discard (ID: 27). SelectType.ATTACHED_CARD

SWITCH_ENERGY_CARD = <SelectContext.SWITCH_ENERGY_CARD: 28>

Select energy card to switch (ID: 28). SelectType.ATTACHED_CARD

DISCARD_CARD_OR_ATTACHED_CARD = <SelectContext.DISCARD_CARD_OR_ATTACHED_CARD: 29>

Select a card or attached card to discard (ID: 29). SelectType.CARD_OR_ATTACHED_CARD

DISCARD_ENERGY = <SelectContext.DISCARD_ENERGY: 30>

Select energy to discard (ID: 30). SelectType.ENERGY

TO_HAND_ENERGY = <SelectContext.TO_HAND_ENERGY: 31>

Select energy to return to hand (ID: 31). SelectType.ENERGY

TO_DECK_ENERGY = <SelectContext.TO_DECK_ENERGY: 32>

Select energy to return to deck (ID: 32). SelectType.ENERGY

SWITCH_ENERGY = <SelectContext.SWITCH_ENERGY: 33>

Select energy to switch (ID: 33). SelectType.ENERGY

SKILL_ORDER = <SelectContext.SKILL_ORDER: 34>

Select skill activation order (ID: 34). SelectType.SKILL

ATTACK = <SelectContext.ATTACK: 35>

Select attack to use (ID: 35). SelectType.ATTACK

DISABLE_ATTACK = <SelectContext.DISABLE_ATTACK: 36>

Select attack to disable (ID: 36). SelectType.ATTACK

EVOLVE = <SelectContext.EVOLVE: 37>

Select Pokémon to evolve (ID: 37). SelectType.EVOLVE

DRAW_COUNT = <SelectContext.DRAW_COUNT: 38>

Select number of cards to draw (ID: 38). SelectType.COUNT

DAMAGE_COUNTER_COUNT = <SelectContext.DAMAGE_COUNTER_COUNT: 39>

Select number of damage counters to place (ID: 39). SelectType.COUNT

REMOVE_DAMAGE_COUNTER_COUNT = <SelectContext.REMOVE_DAMAGE_COUNTER_COUNT: 40>

Select number of damage counters to remove (ID: 40). SelectType.COUNT

IS_FIRST = <SelectContext.IS_FIRST: 41>

Decide who goes first (ID: 41). SelectType.YES_NO

MULLIGAN = <SelectContext.MULLIGAN: 42>

Decide whether to redraw opening hand (ID: 42). SelectType.YES_NO

ACTIVATE = <SelectContext.ACTIVATE: 43>

Decide whether to activate effect (ID: 43). SelectType.YES_NO

FIRST_EFFECT = <SelectContext.FIRST_EFFECT: 44>

Decide whether to use first effect (ID: 44). SelectType.YES_NO

MORE_DEVOLVE = <SelectContext.MORE_DEVOLVE: 45>

Decide whether to devolve further (ID: 45). SelectType.YES_NO

COIN_HEAD = <SelectContext.COIN_HEAD: 46>

Choose heads or tails (ID: 46). SelectType.YES_NO

AFFECT_SPECIAL_CONDITION = <SelectContext.AFFECT_SPECIAL_CONDITION: 47>

Choose special condition to affect (ID: 47). SelectType.SPECIAL_CONDITION

RECOVER_SPECIAL_CONDITION = <SelectContext.RECOVER_SPECIAL_CONDITION: 48>

Choose special condition to recover (ID: 48). SelectType.SPECIAL_CONDITION

enum api.OptionType(value)

Types of options that can be selected by the AI.

Used in Observation.select.option[*].type.

Each value represents the kind of entity the AI is expected to select. Combined with associated fields like area, index, playerIndex, etc., it defines what object the option refers to and how to use it.

Member Type:

int

Valid values are as follows:

NUMBER = <OptionType.NUMBER: 0>

Select a number (ID: 0).

Field:

• number (int): Count.

YES = <OptionType.YES: 1>

Select Yes (ID: 1).

NO = <OptionType.NO: 2>

Select No (ID: 2).

CARD = <OptionType.CARD: 3>

Select a card (ID: 3).

Fields:

• area (AreaType): Area where the card is located

• index (int): Index within the area

• playerIndex (int): The owning player of the card

TOOL_CARD = <OptionType.TOOL_CARD: 4>

Select a Tool card attached to a Pokémon (ID: 4).

Fields:

• area (AreaType): Area of the attached Pokémon

• index (int): Index within the area of the attached Pokémon

• playerIndex (int): The owning player of the Pokémon

• toolIndex (int): Index within the tool

ENERGY_CARD = <OptionType.ENERGY_CARD: 5>

Select an Energy card attached to a Pokémon (ID: 5).

Fields:

• area (AreaType): Area of the attached Pokémon

• index (int): Index within the area of the attached Pokémon

• playerIndex (int): The owning player of the Pokémon

• energyIndex (int): Index within the energy card

ENERGY = <OptionType.ENERGY: 6>

Select energy (ID: 6).

Fields:

• area (AreaType): Area of the attached Pokémon

• index (int): Index within the area of the attached Pokémon

• playerIndex (int): The owning player of the Pokémon

• energyIndex (int): Index within the energy card

• count (int): How many energy units does it correspond to

PLAY = <OptionType.PLAY: 7>

Select a card to play from your hand (ID: 7).

Field:

• index (int): Index within the hand

ATTACH = <OptionType.ATTACH: 8>

Select a card to attach to a Pokémon (ID: 8).

Fields:

• area (AreaType): Area of the card to attach

• index (int): Index within the area of the card to attach

• inPlayArea (AreaType): Area of the Pokémon on the field

• inPlayIndex (int): Index within the area of the Pokémon on the field

EVOLVE = <OptionType.EVOLVE: 9>

Select a card to evolve a Pokémon (ID: 9).

Fields:

• area (AreaType): Area of the evolved card

• index (int): Index within the area of the evolved card

• inPlayArea (AreaType): Area of the Pokémon on the field

• inPlayIndex (int): Index within the area of the Pokémon on the field

ABILITY = <OptionType.ABILITY: 10>

Select a card to use its Ability (ID: 10).

Fields:

• area (AreaType): Area where the card is located

• index (int): Index within the area

DISCARD = <OptionType.DISCARD: 11>

Select a card to discard from play (ID: 11).

Fields:

• area (AreaType): Area where the card is located

• index (int): Index within the area

RETREAT = <OptionType.RETREAT: 12>

Retreat the Active Pokémon (ID: 12).

ATTACK = <OptionType.ATTACK: 13>

Select an attack to use (ID: 13).

Field:

• attackId (int): Attack ID

END = <OptionType.END: 14>

End the turn (ID: 14).

SKILL = <OptionType.SKILL: 15>

Select a skill to activate (ID: 15).

Fields:

• cardId (int): Card ID

• serial (int): Card serial

SPECIAL_CONDITION = <OptionType.SPECIAL_CONDITION: 16>

Select a special condition (ID: 16).

Fields:

• specialConditionType (SpecialConditionType): Special condition type

enum api.LogType(value)

Types of logs generated during the match.

Used in Log.type.

Each value represents an event that occurred during the game. Related fields in the Log dataclass (e.g. playerIndex, cardId, fromArea, etc.) provide additional context.

Member Type:

int

Valid values are as follows:

SHUFFLE = <LogType.SHUFFLE: 0>

Shuffle deck (ID: 0).

Fields:

• playerIndex (int)

HAS_BASIC_POKEMON = <LogType.HAS_BASIC_POKEMON: 1>

Check for Basic Pokémon existence (ID: 1).

Fields:

• playerIndex (int)

• hasBasicPokemon (bool): If false, then no Basic Pokémon exist

TURN_START = <LogType.TURN_START: 2>

Start turn (ID: 2).

Fields:

• playerIndex (int)

TURN_END = <LogType.TURN_END: 3>

End turn (ID: 3).

Fields:

• playerIndex (int)

DRAW = <LogType.DRAW: 4>

Drew a card from deck (ID: 4).

Fields:

• playerIndex (int)

• cardId (int): Drawn card ID

• serial (int): Drawn card serial

DRAW_REVERSE = <LogType.DRAW_REVERSE: 5>

Opponent drew a card from their deck (ID: 5).

Fields:

• playerIndex (int)

MOVE_CARD = <LogType.MOVE_CARD: 6>

A card moved (ID: 6).

Fields:

• playerIndex (int)

• cardId (int): Moved card ID

• serial (int): Moved card serial

• fromArea (AreaType): Area before movement

• toArea (AreaType): Area after movement

MOVE_CARD_REVERSE = <LogType.MOVE_CARD_REVERSE: 7>

A card moved face-down (ID: 7).

Fields:

• playerIndex (int)

• fromArea (AreaType): Area before movement

• toArea (AreaType): Area after movement

SWITCH = <LogType.SWITCH: 8>

Pokémon were switched (ID: 8).

Fields:

• playerIndex (int)

• cardIdActive (int): Moving to Bench Pokémon ID

• serialActive (int): Moving to Bench Pokémon serial

• cardIdBench (int): Moving to Active Pokémon ID

• serialBench (int): Moving to Active Pokémon serial

CHANGE = <LogType.CHANGE: 9>

Change the Pokémon (ID: 9).

Fields:

• playerIndex (int)

• cardIdBefore (int): Pokémon before change ID

• serialBefore (int): Pokémon before change serial

• cardIdAfter (int): Pokémon after change ID

• serialAfter (int): Pokémon after change serial

PLAY = <LogType.PLAY: 10>

Played a card from hand (ID: 10).

Fields:

• playerIndex (int)

• cardId (int): Played card ID

• serial (int): Played card serial

ATTACH = <LogType.ATTACH: 11>

Attached a card to a Pokémon (ID: 11).

Fields:

• playerIndex (int)

• cardId (int): Attached card ID

• serial (int): Attached card serial

• cardIdTarget (int): Target Pokémon card ID

• serialTarget (int): Target Pokémon card serial

EVOLVE = <LogType.EVOLVE: 12>

Evolved a Pokémon (ID: 12).

Fields:

• playerIndex (int)

• cardId (int): Evolved card ID

• serial (int): Evolved card serial

• cardIdTarget (int): Target Pokémon card ID

• serialTarget (int): Target Pokémon card serial

DEVOLVE = <LogType.DEVOLVE: 13>

Devolved a Pokémon (ID: 13).

Fields:

• playerIndex (int)

• cardId (int): Devolved card ID

• serial (int): Devolved card serial

• cardIdTarget (int): Target Pokémon card ID

• serialTarget (int): Target Pokémon card serial

MOVE_ATTACHED = <LogType.MOVE_ATTACHED: 14>

Move an attached card (ID: 14).

Fields:

• playerIndex (int)

• cardId (int): Attached card ID

• serial (int): Attached card serial

• cardIdBefore (int): Pokémon card ID before moving

• serialBefore (int): Pokémon serial before moving

• cardIdAfter (int): Pokémon card ID after moving

• serialAfter (int): Pokémon serial after moving

ATTACK = <LogType.ATTACK: 15>

Pokémon attack (ID: 15).

Fields:

• playerIndex (int)

• cardId (int): Attacking Pokémon card ID

• serial (int): Attacking Pokémon serial

• attackId (int): Attack ID

HP_CHANGE = <LogType.HP_CHANGE: 16>

A Pokémon’s HP changed (ID: 16).

Fields:

• playerIndex (int)

• cardId (int): HP-changed card ID

• serial (int): HP-changed card serial

• value (int): Amount of HP change

• putDamageCounter (bool): True if the HP change is due to damage counter placement

POISONED = <LogType.POISONED: 17>

Poisoned state changed (ID: 17).

Fields:

• playerIndex (int)

• isRecover (bool): True if the special condition has been recovered

• cardId (int): Card ID

• serial (int): Card serial

BURNED = <LogType.BURNED: 18>

Burned state changed (ID: 18).

Fields:

• playerIndex (int)

• isRecover (bool): True if the special condition has been recovered

• cardId (int): Card ID

• serial (int): Card serial

ASLEEP = <LogType.ASLEEP: 19>

Sleep state changed (ID: 19).

Fields:

• playerIndex (int)

• isRecover (bool): True if the special condition has been recovered

• cardId (int): Card ID

• serial (int): Card serial

PARALYZED = <LogType.PARALYZED: 20>

Paralyzed state changed (ID: 20).

Fields:

• playerIndex (int)

• isRecover (bool): True if the special condition has been recovered

• cardId (int): Card ID

• serial (int): Card serial

CONFUSED = <LogType.CONFUSED: 21>

Confused state changed (ID: 21).

Fields:

• playerIndex (int)

• isRecover (bool): True if the special condition has been recovered

• cardId (int): Card ID

• serial (int): Card serial

COIN = <LogType.COIN: 22>

Result of a coin flip (ID: 22).

Fields:

• playerIndex (int)

• head (bool): True if result is heads

RESULT = <LogType.RESULT: 23>

Match result (ID: 23).

Fields:

• result (int): 0 = player 0 win, 1 = player 1 win, 2 = draw

• reason (int): 1 = 0 prize cards, 2 = no deck, 3 = no Active Pokémon, 4 = card effect

Data Classes

class api.Card(id, serial, playerIndex)

Represents a basic card entity with ID, serial number, and owning player.

id: int

CardData ID.

playerIndex: int

Represents which player’s card.

serial: int

Serial Number. A unique value assigned to each card in the match.

class api.Pokemon(id, serial, hp, maxHp, appearThisTurn, energies, energyCards, tools, preEvolution)

Detailed Pokémon state including HP, energy, tools, and evolution info.

appearThisTurn: bool

True if played this turn.

energies: list[EnergyType]

Energies Array

energyCards: list[Card]

Attached Energy Card Array

hp: int

Current HP.

id: int

CardData ID.

maxHp: int

Current Max HP.

preEvolution: list[Card]

Pre-evolution Card Array

serial: int

Serial Number. A unique value assigned to each card in the match.

tools: list[Card]

Attached Pokémon Tool Array

class api.PlayerState(active, bench, benchMax, deckCount, discard, prize, handCount, hand, poisoned, burned, asleep, paralyzed, confused)

Current in-game state of an individual player.

active: list[Pokemon | None]

Active Pokémon (None if the card is facedown). The array size is either 0 or 1.

asleep: bool

Active Pokémon is Asleep.

bench: list[Pokemon]

Bench Pokémon.

benchMax: int

Maximum Bench Count.

burned: bool

Active Pokémon is Burned.

confused: bool

Active Pokémon is Confused.

deckCount: int

Remaining Cards in Deck.

discard: list[Card]

Discard pile Card Array.

hand: list[Card] | None

Hand Card Array. None for the opponent.

handCount: int

Number of Cards in Hand.

paralyzed: bool

Active Pokémon is Paralyzed.

poisoned: bool

Active Pokémon is Poisoned.

prize: list[Card | None]

Prize cards (None if the card is facedown). The first element is the bottom of the prize, and the last element is the top.

class api.State(turn, turnActionCount, yourIndex, firstPlayer, supporterPlayed, stadiumPlayed, energyAttached, retreated, result, stadium, looking, players)

Current game state including turn count, player indices, and stadium card.

energyAttached: bool

True if the manual Energy attachment for this turn has already been used.

firstPlayer: int

Starting Player Index. When the starting player has not been determined, the value is -1.

looking: list[Card | None] | None

Looking cards (None if the card is facedown). None if not looking cards.

players: list[PlayerState]

An array of player states. The number of elements is 2.

result: int

Win player index. -1 if not battle finished.

retreated: bool

True if retreated this turn.

stadium: list[Card]

Stadium Card. The array size is either 0 or 1.

stadiumPlayed: bool

True if a stadium has already been used this turn.

supporterPlayed: bool

True if a supporter has already been used this turn.

turn: int

Turn Count. 1 indicates the first turn for the starting player. 2 indicates the first turn for the second player. 3 indicates the second turn for the starting player. 0 denotes a time before the starting player’s first turn.

turnActionCount: int

Number of Actions Taken This Turn.

yourIndex: int

Which player is making the selection? (Your Player Index.) 0 or 1.

class api.Option(type, number=None, area=None, index=None, playerIndex=None, toolIndex=None, energyIndex=None, count=None, inPlayArea=None, inPlayIndex=None, attackId=None, cardId=None, serial=None, specialConditionType=None)

A single selectable option shown to the agent or player.

area: AreaType | None = None

Area where the card is located.

attackId: int | None = None

ID of the attack.

cardId: int | None = None

ID of the card.

count: int | None = None

How many energy units does it correspond to.

energyIndex: int | None = None

Index within the energy card.

inPlayArea: AreaType | None = None

Area where the card is in play.

inPlayIndex: int | None = None

Index within the play area.

index: int | None = None

Index within the area.

number: int | None = None

Selected number

playerIndex: int | None = None

The owning player of the card.

serial: int | None = None

Serial number of the card.

specialConditionType: SpecialConditionType | None = None

Type of the special condition.

toolIndex: int | None = None

Index within the tool.

type: OptionType

Use this parameter to determine which option it is.

class api.SelectData(type, context, minCount, maxCount, remainDamageCounter, remainEnergyCost, option, deck, contextCard, effect)

Data for the selection process, including type, context, and available options.

context: SelectContext

What is being selected?

contextCard: Card | None

Which card is the selection concerning? This is sent when the context is “Activate”; otherwise, it is null.

deck: list[Card] | None

An array of cards; None unless selecting cards from the deck.

effect: Card | None

The card that is activating the effect currently being processed.

maxCount: int

Maximum number of selections.

minCount: int

Minimum number of selections. It can also be 0.

option: list[Option]

Array of options.

remainDamageCounter: int

Remaining number of damage counters that can be placed.

remainEnergyCost: int

Used when the type is Energy. The remaining required energy count.

type: SelectType

Selection type.

class api.Log(type, playerIndex=None, hasBasicPokemon=None, cardId=None, serial=None, fromArea=None, toArea=None, cardIdActive=None, serialActive=None, cardIdBench=None, serialBench=None, cardIdBefore=None, serialBefore=None, cardIdAfter=None, serialAfter=None, cardIdTarget=None, serialTarget=None, attackId=None, value=None, putDamageCounter=None, isRecover=None, head=None, result=None, reason=None)

A single log entry representing an event that occurred during the match.

type: LogType

Use this parameter to determine which log it is.

class api.Observation(select, logs, current, search_begin_input=None)

Current state and available choices presented to the agent.

current: State | None

Current state. At the time of the initial deck selection, it will be None.

logs: list[Log]

Events that have occurred since the last selection.

search_begin_input: str | None = None

Input to the search_begin function.

select: SelectData | None

Selection information. At the time of the initial deck selection, it will be None.

class api.SearchState(observation, searchId)

State of the search process, including the current observation and search ID.

observation: Observation

New observation. search_begin_input is None.

searchId: int

Search state ID.

class api.ApiResult(state, error)

Result of the API call, including the search state and any error codes.

error: int

Error if not 0.

state: SearchState | None

Search state.

class api.Skill(name, text)

Represents a skill or ability of a card.

name: str

Skill name.

text: str

Explanation.

class api.CardData(cardId, name, cardType, retreatCost, hp, weakness, resistance, energyType, basic, stage1, stage2, ex, megaEx, tera, aceSpec, evolvesFrom, skills, attacks)

Detailed information about a card, including its type, attributes, and abilities.

aceSpec: bool

True if ACE SPEC.

attacks: list[int]

IDs of usable attacks.

basic: bool

True if Basic Pokémon.

cardId: int

Card ID.

cardType: CardType

Card type

energyType: EnergyType

Pokémon or Basic Energy type.

evolvesFrom: str | None

If the Pokémon has evolved, then the name of its pre-evolution. Otherwise, None.

ex: bool

True if Pokémon ex (including Mega Evolution Pokémon ex).

hp: int

Pokémon HP.

megaEx: bool

True if Mega Evolution Pokémon ex.

name: str

Card name.

resistance: EnergyType | None

Pokémon resistance.

retreatCost: int

Energy cost required to retreat.

skills: list[Skill]

The skills that the card has.

stage1: bool

True if Stage1 Pokémon.

stage2: bool

True if Stage2 Pokémon.

tera: bool

True if Tera Pokémon.

weakness: EnergyType | None

Pokémon weakness.

class api.Attack(attackId, name, text, damage, energies)

Detailed information about an attack, including its ID, name, text, damage, and required energies.

attackId: int

Attack ID.

damage: int

Attack damage

energies: list[EnergyType]

Energy required to use.

name: str

Attack name.

text: str

Explanation.

Functions

api.all_card_data()

Retrieve all available card metadata.

Returns:

A list of all cards defined in the game, including their stats, energy type, evolution state, and more.

Return type:

list[CardData]

api.all_attack()

Return all attacks.

Return type:

list[Attack]

api.to_observation_class(obs)

Convert a dictionary to Observation class.

Returns:

Observation dataclass instance.

Return type:

Observation

api.search_begin(agent_observation, your_deck, your_prize, opponent_deck, opponent_prize, opponent_hand, opponent_active, manual_coin=False)

Start a search for the next action based on the current game state and agent observation.

Parameters:

• agent_observation (Observation) – You must input the observation argument passed to your agent function exactly as is.

• your_deck (list[int]) – Predicted Card ID your Deck. It must have the same number of cards as your deck. If Observation.select.deck != None, ignored this.

• your_prize (list[int]) – Predicted Card ID your Prize cards. It must have the same number of cards as your prize.

• opponent_deck (list[int]) – Predicted Card ID opponent’s deck. It must have the same number of cards as opponent’s deck. At setup, at least one Basic Pokémon card is required.

• opponent_prize (list[int]) – Predicted Card ID opponent’s prize cards. It must have the same number of cards as opponent’s prize.

• opponent_hand (list[int]) – Predicted Card ID opponent’s hand. It must have the same number of cards as opponent’s hand.

• opponent_active (list[int]) – Predicted Card ID opponent’s Active Pokémon. Only if there is a face-down Pokémon in your opponent’s Active Spot. This ID must be a Pokémon card ID.

• manual_coin (bool) – If True, the coin’s heads or tails can be chosen.

Returns:

Root search state.

Return type:

SearchState

api.search_step(search_id, select)

Perform a step in the search process by selecting options based on the current state.

Parameters:

• search_id (int) – Search ID.

• select (list[int]) – Chosen option index.

Returns:

State for the next selection.

Return type:

SearchSate

api.search_end()

Terminate the search. Memory used during the search will be reused in the next search.

Return type:

None

api.search_release(search_id)

Delete the state with the specified ID and make the memory available for reuse.

Parameters:

search_id (int) – Search ID.

Return type:

None