Player API Reference¶

All the classes, methods, and attributes described in this sections can be used in your next_turn method.

Despite some of these classes have additional methods and attributes not listed here, those are not useful for you in any way.

You shouldn’t expect any useful information from those methods and attributes. Most of them are used by Pythonium internally.

class pythonium.AbstractPlayer¶

name: str¶: Player’s name. Please make it short (less than 12 characters), or you will break the gif and reports.

next_turn(galaxy, context)¶

Compute the player strategy based on the available information in the galaxy and context.

Parameters

galaxy (Galaxy) – The state of the Galaxy known by the player.
context (dict) – Aditional information about the game.

Each player sees a different part of the galaxy, and the galaxy known by every player is different.

A galaxy contains:

All his ships and planets,

All the enemy ships in any of his planets,

All the enemy ships located in the same position as any of his ships,

All the attributes of a planet that has no owner if a player’s ship is on the planet,

The position of all the planets (not the rest of its attributes),

All the explosions that occur in the current turn.

The player won’t know the attributes of enemy ships or planets but the position.

context has the following keys:

ship_types: A dictionary with all the ship types that the player can build. See: ShipType

tolerable_taxes: The level of taxes from where happypoints start to decay.

happypoints_tolerance: The level of happypoints from where * score: A list with the score for each player.

turn: Number of the current turn.

Return type: Galaxy

class pythonium.Galaxy(name, size, things, explosions=None, turn=0)¶

Galaxy of planets that represents the map of the game, and all the known universe of things.

Parameters

size (NewType()(Position, Tuple[int, int])) – Galaxy height and width
things (List[StellarThing]) – Stellar things that compound the galaxy
explosions (Optional[List[Explosion]]) – Known explosions in the galaxy
turn (int) – Time in galaxy

static compute_distance(a, b)¶

Compute the distance in ly between two points (usually two position attributes).

Parameters

a (NewType()(Position, Tuple[int, int])) – Point of origin to compute the distance
b (NewType()(Position, Tuple[int, int])) – Point of destination to compute the distance

Return type

float

distances_to_planets(point)¶

Compute the distance between the point and all the planets in the galaxy.

Return type: Dict[NewType()(Position, Tuple[int, int]), float]

get_ocuped_planets()¶

Return all the planets colonized by any race

Return type: Iterable[Planet]

get_planets_conflicts()¶

Return all the planets in conflict: Planets with at least one enemy ship on it

Return type: Iterable[Tuple[Planet, List[Ship]]]

get_player_planets(player)¶

Returns an iterable for all the known planets that belongs to``player``

Return type: Iterable[Planet]

get_player_ships(player)¶

Returns an iterable for known ships that belong to player

Return type: Iterable[Ship]

get_ships_by_position()¶

Returns a dict with ships ordered by position. Ships in the same positions are grouped in a list.

Return type: Dict[NewType()(Position, Tuple[int, int]), List[Ship]]

get_ships_conflicts()¶

Return all the ships in conflict: Ships with, at last, one enemy ship in the same position

Return type: Iterable[List[Ship]]

get_ships_in_deep_space()¶

Returns an iterable for all the ships that are not located on a planet

Return type: Iterable[Ship]

get_ships_in_planets()¶

Return a list of tuples (planet, ships) where planet is a Planet instance and ships is a list with all the ships located on the planet

Return type: Iterable[Tuple[Planet, List[Ship]]]

get_ships_in_position(position)¶

Returns an iterable for all the known ships in the given position

Return type: Iterable[Ship]

property known_races¶

List all the known races that own at least one ship or one planet.

Return type: Set[str]

nearby_planets(point, neighborhood)¶

Return all the planets that are neighborhood light-years away or less.

Return type: List[Planet]

search_planet(_id)¶

Return the planet with ID id if any

Return type: Planet

search_ship(_id)¶

Return the ship with ID id if any and is known

Return type: Ship

class pythonium.Planet(position, id=NOTHING, *, temperature, underground_pythonium, concentration, pythonium, mine_cost, player=None, megacredits=0, clans=0, mines=0, new_mines=0, new_ship=None, taxes=0)¶

A planet that belongs to a Galaxy

Represent a planet that can be colonized.

The temperature on the planet will determine how happy the clans can be (temperature defines the max_happypoints for the planet).

Each planet has some amount of pythonium on the surface that can be used by the colonizer race, and some underground_pythonium (with a certain concentration) that needs to be extracted with mines.

The higher the taxes are over cfg.tolerable_taxes, the faster the happypoints decay.

The lower the happypoints are over cfg.happypoints_tolerance, the lower the planet production of clans, pythonium, and megacredits will be (in proportion of rioting_index).

can_build_mines()¶

Computes the number of mines that can be built on the planet based on available resources and max_mines

Return type: int

can_build_ship(ship_type)¶

Indicates whether ship_type can be built on this planet with the available resources

Return type: bool

clans: int¶: Amount of clans on the planet

concentration: float¶: Indicates how much pythonium extract one mine. It is always between zero and 1.

property dclans¶

Aditional clans for the next turn. The absolute change in the population considering:

rioting_index: Negative influence,
cfg.max_population_rate: Positive influence,
cfg.max_clans_in_planet: Positive influence,
clans: Positive influence

Return type: int

property dhappypoints¶

Absolute change on happypoints for the next turn

Return type: int

property dmegacredits¶

Absolute change in megacredits for the next turn considering:

taxes: Positive influence
rioting_index: Negative influence,
clans: Positive influence,
taxes_collection_factor: Positive influence

Do not consider new_mines and new_ship cost, or ship transfers.

Return type: int

property dpythonium¶

Absolute change in pythonium for the next turn considering:

mines: Positive influence,
concentration: Positive influence,
rioting_index: Positive influence.

Do not consider new_mines and new_ship cost, or ship transfers.

Return type: int

happypoints: int¶

The level of happyness on the planet.

This has influence on rioting_index

max_happypoints: int¶

The maximum level of happypoints that the population of this planet can reach.

It is based on the planet’s temperature.

Its maximum value (100) is reached when the planet’s temperature is equal to cfg.optimal_temperature

property max_mines¶

The maximum number of mines that can be build in the planet

Return type: int

megacredits: int¶: Amount of megacredits on the planet

mine_cost: pythonium.vectors.Transfer¶: Indicates the cost of building one mine.

mines: int¶: Amount of mines on the planet

new_mines: int¶

Attribute that can be modified by the player

New mines that the player order to build in the current turn. This value is set to zero when the player orders are executed.

new_ship: pythonium.ship_type.ShipType¶

Attribute that can be modified by the player

The new ship that the player order to build in the current turn.

This value is set to None when the player orders are executed

player: str¶: The owner of the planet or None if no one owns it.

pythonium: int¶: Pythonium in the surface of the planet. The available resource to build things.

property rioting_index¶

If the happypoints are less than cfg.happypoints_tolerance this property indicates how much this unhappiness will affect the planet’s economy.

i.e: if rioting_index is 0.5 pythonium production, and megacredits recollection will be %50 less than its standard level.

Return type: float

taxes: int¶

Attribute that can be modified by the player

Taxes set by the player. Must be between zero and 100.

The level of taxes defines how much megacredits will be collected in the current turn.

If the taxes are higher than cfg.tolerable_taxes the planet’s happypoints will decay planet.taxes - cfg.tolerable_taxes per turn.

See dmegacredits

temperature: int¶: The temperature of the planet. It is always between zero and 100.

underground_pythonium: int¶: Amount of pythonium under the surface of the planet, that needs to be extracted with mines.

class pythonium.Ship(position, id=NOTHING, player=None, *, type, max_cargo, max_mc, attack, speed)¶

A ship that belongs to a race.

It can be moved from one point to another, it can be used to move any resource, and in some cases can be used to attack planets or ships.

attack: int¶: Indicates how much attack the ship has. See ShipType.attack

clans: int¶: Amount of clans on the ship

max_cargo: int¶: Indicates how much pythonium and clans (together) can carry the ship. See ShipType.max_cargo

max_mc: int¶: Indicates how much megacredits can carry the ship. See ShipType.max_mc

megacredits: int¶: Amount of megacredits on the ship

pythonium: int¶: Amount of pythonium on the ship

target: NewType.<locals>.new_type¶

Attribute that can be modified by the player

Indicates where the ship is going, or None if it is stoped.

transfer: pythonium.vectors.Transfer¶

Attribute that can be modified by the player

Indicates what resources will be transferred by the ship in the current turn.

If no transfer is made this is an empty transfer.

See Transfer bool conversion.

type: pythonium.ship_type.ShipType¶: Name of the ShipType

class pythonium.ShipType(name, cost, max_cargo, max_mc, attack, speed)¶

Defines the attributes of a ship that the player can built.

attack: int¶: Attack of the ship. It will be used to resolve conflicts.

cost: pythonium.vectors.Transfer¶: Transfer instance that represents the cost of a ship of this type.

max_cargo: int¶

Max cargo of clans and pythonium (together) for this ship.

In other words, you should always expect this:

>>> ship.megacredits + ship.clans <= ship.max_cargo
True

Megacredits do not take up physical space in the ship so are not considered for max_cargo limit.

max_mc: int¶

Max amount of megacredits that can be loaded to the ship.

In other words, you should always expect this:

>>> ship.megacredits <= ship.max_mc
True

name: str¶: A descriptive name for the ship type. i.e: ‘war’, ‘carrier’

class pythonium.Transfer(megacredits=0, pythonium=0, clans=0)¶

Represent the transfer of resources from a ship to a planet and vice-versa, or the cost of structures. This second case can be considered as a transfer between the player and the game.

Some useful properties of this class are:

Negation

Changes the direction of the transfer.

>>> t = Transfer(clans=100, megacredits=100, pythonium=100)
>>> print(-t)
Transfer(megacredits=-100, pythonium=-100, clans=-100)

Addition and Subtraction

Add/subtracts two transfers

>>> t1 = Transfer(clans=100, megacredits=100, pythonium=100)
>>> t2 = Transfer(clans=10, megacredits=10, pythonium=10)
>>> print(t1 + t2)
Transfer(megacredits=110, pythonium=110, clans=110)

Multiplication and Division

Multiplies/divides a transfer with an scalar

>>> t = Transfer(clans=100, megacredits=100, pythonium=100)
>>> print(t*1.5)
Transfer(megacredits=150, pythonium=150, clans=150)
>>> print(t/1.5)
Transfer(megacredits=150, pythonium=150, clans=150)

Empty transfers

The conversion of a transfer to a boolean return False if the transfer is empty

>>> t = Transfer()
>>> print(bool(t))
False

clans: int¶: Amount of clans to transfer

megacredits: int¶: Amount of megacredits to transfer

pythonium: int¶: Amount of pythonium to transfer

class pythonium.Explosion(ship, ships_involved, total_attack)¶

A ship that has exploded because of a conflict

Provides some insights about which ship exploded and where

Parameters

ship (Ship) – Destroyed ship
ships_involved (int) – Amount of ships involved in the combat
total_attack (int) – Total attack involved in the combat

ship¶: Ship that has been destroyed.

ships_involved¶: Amount of ships involved in the combat.

total_attack¶: Total attack involved in the combat.

class pythonium.core.Position(x)¶

class pythonium.core.StellarThing(position, id=NOTHING, player=None)¶

id: <module ‘uuid’ from ‘/home/docs/.pyenv/versions/3.7.9/lib/python3.7/uuid.py’>¶: Unique identifier for the StellarThing

player: str¶: The owner of the StellarThing or None if no one owns it.

position: NewType.<locals>.new_type¶: Position of the StellarThing in (x, y) coordinates.