Docs / Controller API

Controller API Reference

Auto-generated from megagem/engine/controller.py. The Controller object is passed to your bot's main(ct) method each turn.

Players 
def opponents(self) -> tuple[int, ...]
Player indices of every opponent (all players except you). Use these as arguments to `get_balance`, `get_collection`, etc.
Per-player state 
def get_balance(self, player: int | None = None) -> int
Current spendable coins for `player` (defaults to you). This is the amount available to bid; it does not include the end-of-game adjustment.
def get_adjustment(self, player: int | None = None) -> int
End-of-game coin adjustment for `player` (defaults to you). This running total is added to the player's balance at the end of the game. Loans reduce it; investments and completed missions increase it.
def get_collection(self, player: int | None = None) -> tuple[Gem, ...]
Gems `player` has won so far (defaults to you).
def get_hand(self) -> tuple[Gem, ...]
Your private hand of gem cards available to reveal this turn. Each turn you choose one card to reveal alongside your bid; only you can see your hand.
Auction 
def is_gem_auction(self) -> bool
True if the current auction is for gems (GEM1 or GEM2). The winner receives one or two gems added to their collection.
def is_invest_auction(self) -> bool
True if the current auction is an investment (INVEST5 or INVEST10). The winner pays their bid and gets it back plus a bonus at game end.
def is_loan_auction(self) -> bool
True if the current auction is a loan (LOAN10 or LOAN20). The winner receives coins now but takes a deduction at game end.
def gems_on_offer(self) -> list[Gem]
Gems that would be added to your collection if you win this turn. Returns an empty list for investment and loan auctions. GEM1 auctions offer a single gem; GEM2 offers two (or one if only one remains).
def max_bid(self) -> int
The largest bid the engine will accept this turn — bids above this are capped. For loans, the cap is the loan amount (10 or 20); for all other auctions it is your current balance.
def win_effect(self, bid: int) -> tuple[int, int, list[Gem]]
If you won this auction at `bid`, returns (delta_balance, delta_adjustment, gems_gained). Net effect on final score is delta_balance + delta_adjustment + chart value of gems. - Gem auction: balance −bid, no adjustment, gems added to collection. - Investment: balance −bid, adjustment +(bid + bonus), no gems. - Loan: balance +(loan − bid), adjustment −loan amount, no gems.
Gem counting 
def count_in_hand(self, gem: Gem) -> int
Number of `gem` cards in your private hand available to reveal.
def count_in_value_display(self, gem: Gem) -> int
Number of `gem` cards in the public value display (face-up area).
def count_in_collections(self, gem: Gem) -> int
Total number of `gem` cards won across all players' collections.
def count_total_not_auctioned(self, gem: Gem) -> int
Number of `gem` cards that are in play but not yet won by any player (your hand + the value display). These count toward the gem's occurrence total when its chart value is computed at game end.
def chart_value(self, count: int) -> int
Look up how many coins a gem is worth given its total occurrence `count` in the game. The count is how many copies of that gem exist across all collections, hands, and the value display combined. Higher counts generally mean lower per-gem value (clamped to 0..6).
Missions 
def open_missions(self) -> tuple[MissionCard, ...]
Mission cards that have not yet been claimed by any player. Each card specifies a gem requirement and a coin reward; the first player whose collection satisfies the requirement claims it.
def missions_satisfied_by(self, gems: Iterable[Gem]) -> tuple[MissionCard, ...]
Open missions that would be satisfied by the given collection of gems. Pass any list of gems (e.g. a hypothetical future collection) to find out which mission cards it would fulfill.
def missions_if_i_win(self) -> tuple[MissionCard, ...]
Open missions you would claim if you won this auction. Checks your current collection combined with the gems on offer this turn.
def mission_bonus_if_i_win(self) -> int
Total coin reward from all missions you would claim by winning this auction.
Tie-breaking 
def tie_break_priority(self, player: int | None = None) -> int
Tie-break priority of `player` for this turn — higher wins ties. Priority rotates clockwise each round: the player immediately after the last winner has highest priority, continuing in seat order from there.
def tie_break_order(self) -> list[int]
All player indices sorted from highest to lowest tie-break priority this turn. The first element wins any tied bid.
def beats_on_tie(self, other: int) -> bool
True if you would win a tied bid against player `other` this turn.