gamelib package

Module Overview (Start Here)

The gamelib package contains modules that assist in algo creation

The GameState class in game_state.py is the main class most players interact with. It contains functions that let you get information about resources, deploy units, and help you strategize your move.

The GameMap class in game_map.py represents the current game map. It can be used to access information related to the locations of units. Investigating it is useful for any player that wants to access more information about the current state of the game.

The GameUnit class in unit.py represetns a single unit. Investigating it is useful for any player that wants to access information about units.

The AlgoCore class in algocore.py handles communication with the game engine, and forms the bones of an algo. AlgoStrategy inherits from it. Investigating it is useful for advanced players interested in getting data from the action phase or communicating directly with the game engine.

The Navigation class in navigation.py contains functions related to pathfinding, which are used by GameState in pathing related functions. Investigating it is useful for advanced player who want to optimize the slow default pathing algorithm we provide.

util.py contains a small handful of functions that help with communication, including the debug-printing function, debug_write().

Algo Core (gamelib.algocore)

class gamelib.algocore.AlgoCore

Bases: object

This class handles communication with the game engine.

algo_strategy.py subclasses it.

Attributes :

  • config (JSON): json object containing information about the game

on_action_frame(action_frame_game_state)

After each deploy phase, the game engine will run the action phase of the round. The action phase is made up of a sequence of distinct frames. Each of these frames is sent to the algo in order. They can be handled in this function.

on_game_start(config)

This function is called once at the start of the game. By default, it just initializes the config.

You can override it it in algo_strategy.py to perform start of game setup

on_turn(game_state)

This step function is called at the start of each turn. It is passed the current game state, which can be used to initiate a new GameState object. By default, it sends empty commands to the game engine.

algo_strategy.py inherits from AlgoCore and overrides this on turn function. Adjusting the on_turn function in algo_strategy is the main way to adjust your algo’s logic.

start()

Start the parsing loop. After starting the algo, it will wait until it recieves information from the game engine, proccess this information, and respond if needed to take it’s turn. The algo continues this loop until it recieves the “End” turn message from the game.

Game Map (gamelib.game_map)

class gamelib.game_map.GameMap(config)

Bases: object

Holds data about the current game map and provides functions useful for getting information related to the map.

game_map[x, y] will return a list of Units located at that location, or an empty list if there are no units at the location

Attributes :

  • config (JSON): Contains information about the current game rules

  • enable_warnings (bool): If true, debug messages for game_map functions will print out

  • ARENA_SIZE (int): The size of the arena.

  • HALF_ARENA (int): Half of the size of the arena.

  • TOP_RIGHT (int): A constant that represents the top right edge

  • TOP_LEFT (int): A constant that represents the top left edge

  • BOTTOM_LEFT (int): Hidden challenge! Can you guess what this constant represents???

  • BOTTOM_RIGHT (int): A constant that represents the bottom right edge

add_unit(unit_type, location, player_index=0)

Add a single GameUnit to the map at the given location.

Parameters

  • unit_type – The type of the new unit. Use the constants provided in algo_strategy.

  • location – A list of two integers representing the [x,y] coordinate of the new unit

  • player_index – The index corresponding to the player controlling the new unit, 0 for you 1 for the enemy

This function does not affect your turn and only changes the data stored in GameMap. The intended use of this function is to allow you to create arbitrary gamestates. Using this function on the game_map provided with game_state will desynchronize it from the actual gamestate, and can cause issues.

distance_between_locations(location_1, location_2)

Euclidean distance

Parameters

  • location_1 – An arbitrary location, [x, y]

  • location_2 – An arbitrary location, [x, y]

Returns

The euclidean distance between the two locations

get_edge_locations(quadrant_description)

Takes in an edge description and returns a list of locations.

Parameters

quadrant_description – A constant corresponding to one of the 4 edges. See game_map.TOP_LEFT, game_map.BOTTOM_RIGHT, and similar constants.

Returns

A list of locations along the requested edge

get_edges()

Gets all of the edges and their edge locations

Returns

A list with four lists inside of it of locations corresponding to the four edges. [0] = top_right, [1] = top_left, [2] = bottom_left, [3] = bottom_right.

get_locations_in_range(location, radius)

Gets locations in a circular area around a location

Parameters

  • location – The center of our search area

  • radius – The radius of our search area

Returns

The locations that are within our search area

in_arena_bounds(location)

Checks if the given location is inside the diamond shaped game board.

Parameters

location – A map location

Returns

True if the location is on the board, False otherwise

remove_unit(location)

Remove all units on the map in the given location.

Parameters

location – The location that you will empty of units

This function does not affect your turn and only changes the data stored in GameMap. The intended use of this function is to allow you to create arbitrary gamestates. Using this function on the GameMap inside game_state can cause your algo to crash.

warn(message)

Used internally by game_map to print out default messaging

Game State (gamelib.game_state)

class gamelib.game_state.GameState(config, serialized_string)

Bases: object

Represents the entire gamestate for a given turn Provides methods related to resources and unit deployment

Attributes :

  • UNIT_TYPE_TO_INDEX (dict): Maps a unit to a corresponding index

  • WALL (str): A constant representing the wall unit

  • SUPPORT (str): A constant representing the support unit

  • TURRET (str): A constant representing the turret unit

  • SCOUT (str): A constant representing the scout unit

  • DEMOLISHER (str): A constant representing the demolisher unit

  • INTERCEPTOR (str): A constant representing the interceptor unit

  • REMOVE (str): A constant representing removing your own unit

  • UPGRADE (str): A constant representing upgrading a unit

  • STRUCTURE_TYPES (list): A list of the structure units

  • ARENA_SIZE (int): The size of the arena

  • HALF_ARENA (int): Half the size of the arena

  • MP (int): A constant representing the Mobile Points resource, used in the get_resource function

  • SP (int): A constant representing the SP resource, used in the get_resource function

  • game_map (:obj: GameMap): The current GameMap. To retrieve a list of GameUnits at a location, use game_map[x, y]

  • turn_number (int): The current turn number. Starts at 0.

  • my_health (int): Your current remaining health

  • my_time (int): The time you took to submit your previous turn

  • enemy_health (int): Your opponents current remaining health

  • enemy_time (int): Your opponents current remaining time

attempt_remove(locations)

Attempts to remove existing friendly structures in the given locations.

Parameters

locations – A location or list of locations we want to remove structures from

Returns

The number of structures successfully flagged for removal

attempt_spawn(unit_type, locations, num=1)

Attempts to spawn new units with the type given in the given locations.

Parameters

  • unit_type – The type of unit we want to spawn

  • locations – A single location or list of locations to spawn units at

  • num – The number of units of unit_type to deploy at the given location(s)

Returns

The number of units successfully spawned

attempt_upgrade(locations)

Attempts to upgrade units in the given locations.

Parameters

locations – A single location or list of locations to upgrade units at

Returns

The number of units successfully upgraded

can_spawn(unit_type, location, num=1)

Check if we can spawn a unit at a location.

To units, we need to be able to afford them, and the location must be in bounds, unblocked, on our side of the map, not on top of a unit we can’t stack with, and on an edge if the unit is mobile.

Parameters

  • unit_type – The type of the unit

  • location – The location we want to spawn the unit

  • num – The number of units we want to spawn

Returns

True if we can spawn the unit(s)

contains_stationary_unit(location)

Check if a location is blocked, return structures unit if it is

Parameters

location – The location to check

Returns

A structures unit if there is a stationary unit at the location, False otherwise

find_path_to_edge(start_location, target_edge=None)

Gets the path a unit at a given location would take. If final point is not on an edge, it is a self destruct path

Parameters

  • start_location – The location of a hypothetical unit

  • target_edge – The edge the unit wants to reach. game_map.TOP_LEFT, game_map.BOTTOM_RIGHT, etc. Induced from start_location if None.

Returns

A list of locations corresponding to the path the unit would take to get from it’s starting location to the best available end location

get_attackers(location, player_index)

Gets the stationary units threatening a given location

Parameters

  • location – The location of a hypothetical defender

  • player_index – The index corresponding to the defending player, 0 for you 1 for the enemy

Returns

A list of units that would attack a unit controlled by the given player at the given location

get_resource(resource_type, player_index=0)

Gets a players resources

Parameters

  • resource_type – MP (1) or SP (0)

  • player_index – The index corresponding to the player whos resources you are querying, 0 for you 1 for the enemy

Returns

The number of the given resource the given player controls

get_resources(player_index=0)

Gets a players resources as a list

Parameters

player_index – The index corresponding to the player whos resources you are querying, 0 for you 1 for the enemy

Returns

[Float, Float] list where the first entry is SP the second is MP

get_target(attacking_unit)

Returns target of given unit based on current map of the game board. A Unit can often have many other units in range, and Units that attack do so once each frame.

Their targeting priority is as follows:

Infantry > Nearest Unit > Lowest Health > Lowest Y position > Closest to edge (Highest distance of X from the boards center, 13.5)

Parameters

attacking_unit – A GameUnit

Returns

The GameUnit this unit would choose to attack.

get_target_edge(start_location)

Gets the target edge given a starting location

Parameters

start_location – The location of a hypothetical unit

Returns

The edge this unit would attempt to reach if it was spawned at this location (int)

number_affordable(unit_type)

The number of units of a given type we can afford

Parameters

unit_type – A unit type, SCOUT, WALL, etc.

Returns

The number of units affordable of the given unit_type.

project_future_MP(turns_in_future=1, player_index=0, current_MP=None)

Predicts the number of MP we will have on a future turn

Parameters

  • turns_in_future – The number of turns in the future we want to look forward to predict

  • player_index – The player whose MP we are tracking

  • current_MP – If we pass a value here, we will use that value instead of the current MP of the given player.

Returns

The number of MP the given player will have after the given number of turns

submit_turn()

Submit and end your turn. Must be called at the end of your turn or the algo will hang.

suppress_warnings(suppress)

Suppress all warnings

Parameters

suppress – If true, disable warnings. If false, enable warnings.

type_cost(unit_type, upgrade=False)

Gets the cost of a unit based on its type

Parameters

unit_type – The units type (string shorthand)

Returns

The units costs as a list [SP, MP]

warn(message)

Used internally by game_state to print warnings

gamelib.game_state.is_stationary(unit_type)
Parameters

unit_type – A unit type

Returns

Boolean, True if the unit is stationary, False otherwise.

Navigation (gamelib.navigation)

class gamelib.navigation.Node

Bases: object

A pathfinding node

Attributes :

  • visited_idealness (bool): Have we visited this node during the idealness search step?

  • visited_validate (bool): Have we visited this node during the validation step?

  • blocked (bool): Is there a structures at this node’s location

  • pathlength: The distance between this node and the target location

class gamelib.navigation.ShortestPathFinder

Bases: object

Handles pathfinding

Attributes :

  • HORIZONTAL (int): A constant representing a horizontal movement

  • VERTICAL (int): A constant representing a vertical movement

  • game_state (:obj: GameState): The current gamestate

  • game_map (:obj: GameMap): The current gamemap

initialize_map(game_state)

Initializes the map

Parameters

game_state – A GameState object representing the gamestate we want to traverse

navigate_multiple_endpoints(start_point, end_points, game_state)

Finds the path a unit would take to reach a set of endpoints

Parameters

  • start_point (*) – The starting location of the unit

  • end_points (*) – The end points of the unit, should be a list of edge locations

  • game_state (*) – The current game state

Returns

The path a unit at start_point would take when trying to reach end_points given the current game state. Note that this path can change if a tower is destroyed during pathing, or if you or your enemy places structures.

print_map()

Prints an ASCII version of the current game map for debug purposes

Game Unit (gamelib.unit)

class gamelib.unit.GameUnit(unit_type, config, player_index=None, health=None, x=- 1, y=- 1)

Bases: object

Holds information about a Unit.

Attributes :

  • unit_type (string): This unit’s type

  • config (JSON): Contains information about the game

  • player_index (integer): The player that controls this unit. 0 for you, 1 for your opponent.

  • x (integer): The x coordinate of the unit

  • y (integer): The y coordinate of the unit

  • stationary (bool): Whether or not this unit is a structures

  • speed (float): A unit will move once every 1/speed frames

  • damage_f (int): The amount of damage this mobile unit will deal to enemy structures.

  • damage_i (int): The amount of damage this mobile unit will deal to enemy mobile units.

  • attackRange (float): The effective range of this unit for attacking

  • shieldRange (float): The effective range of this unit for shielding

  • max_health (float): The starting health of this unit. Note than ‘health’ can be increased beyond this value by shielding in some game configurations.

  • health (float): The current health of this unit

  • cost ([int, int]): The resource costs of this unit first is SP second is MP

  • shieldPerUnit (float): how much shield is given per unit

  • pending_removal (boolean): If this unit is marked for removal by its owner

  • upgraded (boolean): If this unit is upgraded

upgrade()
gamelib.unit.is_stationary(unit_type, structure_types)
Parameters

unit_type – A unit type

Returns

Boolean, True if the unit is stationary, False otherwise.

Util (gamelib.util)

gamelib.util.debug_write(*msg)

Prints a message to the games debug output

Parameters

msg – The message to output

gamelib.util.get_command()

Gets input from stdin

gamelib.util.send_command(cmd)

Sends your turn to standard output. Should usually only be called by ‘GameState.submit_turn()’