PTCGABC cabt Engine Documentation
=================================

.. contents::
   :depth: 2

Observation Structures
======================

.. rubric:: Game Board to API Mapping

This documentation explains the relationship between the PTCGABC cabt engine's API specification and the actual game board state.  
For detailed API usage and data class structures representing game states, please refer to the :ref:`API Reference`.

Overall Observation Structure
-----------------------------

The Observation object contains three main components:

- ``logs``: Event logs of past actions and game events
- ``current``: Current board state information (player states, turn information, etc.). This can be ``None`` during the initial deck selection phase.
- ``select``: Information about available choices. The index of Options contained in this object is used as Actions. This can be ``None`` during the initial deck selection phase.

.. image:: _static/observation_logs_current_select.png
   :alt: Mapping of the three Observation components
   :width: 700
   :align: center

Observation.current Structure
-----------------------------

``Observation.current`` corresponds to the `State` class and contains the following fields:

- ``players``: Each player's state (`PlayerState`)
- ``stadium``: Current stadium card (`Card`)
- Game progression information such as turn count, first/second player, supporter/stadium/energy usage, retreat state, and game results

.. image:: _static/state_current_players_stadium.png
   :alt: Mapping diagram for current.players/stadium
   :width: 700
   :align: center

PlayerState Structure
---------------------

``PlayerState`` represents each player's board state and primarily contains the following fields:

- ``active``: Active Pokémon in the battle position (`Pokemon`). The list size is 0 or 1, and the element can be ``None`` if the card is face-down.
- ``bench``: List of Benched Pokémon (maximum of 5)
- ``hand``: Hand cards (visible for self only, opponent shows count only)
- ``prize``: Prize cards. Face-down cards are represented as ``None``. The first element is the bottom prize and the last element is the top prize.
- ``deckCount``: Remaining cards in deck
- ``discard``: Discard pile
- ``handCount``: Number of cards in hand
- ``benchMax``: Maximum bench size (typically 5)
- ``poisoned``, ``burned``, ``asleep``, ``paralyzed``, ``confused``: Status condition flags

.. image:: _static/playerstate_mapping.png
   :alt: Field mapping diagram for players[0]/[1]
   :width: 700
   :align: center

----

API Overview
============

.. rubric:: Function Library for Simulation and Battle Control

Sim Module
----------

A collection of APIs for retrieving card information and exploring state transitions.  
Primarily defined in `api.py` and `sim.py`.

Card Data API
~~~~~~~~~~~~~

- ``all_card_data()``  
  Retrieves metadata for all available cards (name, HP, energy, etc.).

- ``all_attack()``  
  Retrieves information for all available attacks (description, damage, required energy).

Search API
~~~~~~~~~~

- ``search_begin(...)``  
  Initializes search state based on an `Observation` and generates a `SearchState`.

- ``search_step(search_id, select)``  
  Advances the search state by one step with the specified choice.

- ``search_end()``  
  Ends the current search state and releases memory.

- ``search_release(search_id)``  
  Explicitly destroys a specific search ID.

Game API
--------

A collection of functions for controlling battle start, selection, and end. Primarily defined in `game.py`.

- ``battle_start(deck0, deck1)``  
  Starts a battle using two decks (60 cards each) and returns a tuple of ``(Observation | None, StartData)``.
  If initialization fails, the observation is ``None`` and ``StartData`` contains the error information.

- ``battle_select(select_list)``  
  Advances the board state by one step based on player selections and returns a new `Observation`.

- ``battle_finish()``  
  Ends the current battle (releases memory).

- ``visualize_data()``  
  Outputs the current board state as a human-readable string (for debugging).

----

Getting Started
===============

.. rubric:: Running a Battle with Minimal Setup

You can run a random-choice battle with a minimal environment by preparing the following two files.

agent.py
--------

.. code-block:: python

    import random

    # Example agent that selects cards at random.
    def agent(obs_dict: dict) -> list[int]:
        return random.sample(
            list(range(len(obs_dict["select"]["option"]))), obs_dict["select"]["maxCount"]
        )


deck.csv
--------

List 60 card IDs, one per line:

.. code-block:: text

    278
    278
    ...
    7
    7

> Card IDs can be obtained using `all_card_data()`.

Example Test Script
-------------------

.. code-block:: python

   from kaggle_environments import make
   from agent import agent

   with open("deck.csv") as f:
       deck = [int(line) for line in f.readlines() if line.strip()]

   env = make("cabt", configuration={"decks": [deck, deck]})
   env.run([agent, agent])

   with open("result.html", "w") as f:
       f.write(env.render(mode="html"))

   print("Simulation finished.")

----

.. _API Reference:

API Reference
=============

.. toctree::
   :maxdepth: 2
   :caption: Overview

   self
   api
   game
   sim
   utils