API reference

GameEngine

class battlematica.GameEngine
__init__()

The GameEngine is the object responsible for advancing the state of the game and generating the state snapshots.

give_state_queue()

Creates and returns a Queue in which the display state snapshots will be put during the run of the game.

give_sync_signal()

Creates and returns a sync signal that blocks the execution of the next tick until it is set again.

init_from_files(main_game_file)

Initializes a game from a json gamefile.

init_game(field_width, field_height, bot_list, artifact_list, drop_port_list, seed=16966450, score_fn=<function default_score>)

Initializes a game. The arguments describe the initial condition of the game.

Parameters

  • field_width – width of the game arena in u (units-pixels)

  • field_height – heigth of the game arena in u (units-pixels)

  • bot_list – a list of dicts containing the attributes of the bots

  • artifact_list – a list of dicts containing the attributes of the artifacts

  • drop_port_list – a list of dicts containing the attributes of the drop ports

  • seed – random seed for np.random. A fixed seed will be used if not passed.

run_game(until_tick)

Advances the game until a certain tick number.

Parameters

until_tick – the tick until which to simulate

property state

The state of the game, that is a dict containing information about all the game objects.

GameDisplayProcess

class battlematica.GameDisplayProcess(engine, speed=1.0, sync=False, asset_archive=None)
__init__(engine, speed=1.0, sync=False, asset_archive=None)

A Process that runs the game displayer.

Parameters

  • engine – the GameEngine instance to display

  • speed – a multiplier representing the display speed. Normally the target speed is 60 ticks/s.

  • sync – whether to execute the engine synchronously with the display (the next tick is not produced before the current one is displayed). Useful if you want to interact with the game in some way.

  • asset_archive – optional path to an alternative asset archive

run() → None

Method to be run in sub-process; can be overridden in sub-class

Bot

class battlematica.Bot(x, y, r, hg, max_health=400.0, max_shield=200.0, size=0.5, firing_period=10.0, bullet_decay=0.5, bullet_speed=80.0, bullet_range=300.0, bullet_dmg=35.0, walk_speed=3.0, crawl_speed=1.5, rotation_speed=7.0, shield_reload_speed=3.0, shield_reload_dead_time=40.0, graphics={})
__init__(x, y, r, hg, max_health=400.0, max_shield=200.0, size=0.5, firing_period=10.0, bullet_decay=0.5, bullet_speed=80.0, bullet_range=300.0, bullet_dmg=35.0, walk_speed=3.0, crawl_speed=1.5, rotation_speed=7.0, shield_reload_speed=3.0, shield_reload_dead_time=40.0, graphics={})

The Bot is the fighter of Battlematica.

Parameters

  • x – x coordinate of the bot

  • y – y coordinate of the bot

  • r – rotation of the bot in degrees (0 points right)

  • hg – the team of the bot (integer)

  • max_health – it’s the total HP of the bot.

  • max_shield – it’s the total shield of the bot.

  • size – a float indicating the phisical size of the bot (influences hitbox).

  • firing_period – it’s the amount of ticks that the bot needs to load the next shot.

  • bullet_decay – terminal effectiveness decay of the bullet at max range. value between 0.0-1.0.

  • bullet_speed – the speed in u/tick at which the bullet moves

  • bullet_range – distance in u before the fired bullet becomes ineffective

  • bullet_dmg – hp/shield damage inflicted by one bullet

  • walk_speed – walking speed in u/tick

  • crawl_speed – walking speed in u/tick when carrying an artifact

  • rotation_speed – body rotation speed in degrees/tick

  • shield_reload_speed – shield reload speed in HP/tick

  • shield_reload_dead_time – ticks that must pass without receiving damage for the shield to start reloading

  • graphics – dict of graphic parameters for display (see guide). Can be an empty dict if no display is used.

set_ai(ai)

Sets the Bot’s AI function.

Parameters

ai – a function that accepts (bot_instance, state) and returns a tuple (action, target_x, target_y).

Artifact

class battlematica.Artifact(x, y, hg=None)
__init__(x, y, hg=None)

The Artifact is picked up by Bots and deposited in a DropPort for points.

Parameters

  • x – x coordinate of the artifact

  • y – y coordinate of the artifact

  • hg – the team that can score points with the artifact; 0 for an artifact that can be used by all teams (integer or None)

DropPort

class battlematica.DropPort(x, y, hg=None)
__init__(x, y, hg=None)

The DropPort is the object where the Bots can deposit Artifacts to score points.

Parameters

  • x – x coordinate of the drop port

  • y – y coordinate of the drop port

  • hg – the team that can use the drop port; 0 for a drop port that can be used by all teams (integer or None)

StateQuerier

class battlematica.StateQuerier(state)
__call__(*args)

The first argument must be an identifier ex: battlematica.library.bots()…

The following ones must be filters ex: battlematica.library.health_between(low, high)…

The last one can optionally be a selector ex: battlematica.library.closest_to_xy(X,Y)…

If the last argument is a selector, it returns either the state of the selected object or None if no object meet all filter conditions.

Otherwise, it returns a list containing the state(s) of the selected object(s). The list can be empty if no object meets all conditions.

__init__(state)

The StateQuerier is initialized with a Bot instance and a state snapshot. You then call it with a sequence of functions created with battlematica.library.

library

The library submodule contains a collections of higher level functions used in writing AIs together with a StateQuerier. The functions are divided in identifiers, filters and selectors.

  • identifiers have prefix i_ and select the class of objects you want to query: bots, artifacts or drop ports.

  • filters have prefix f_ and are functions that narrow down a list of objects. A sequence of filters is applied to the totality of the objects contained in the Game State in order to get a list of suitable objects.

  • selectors have prefix s_ and their purpose is to select exactly one element from a list according to the minimization or maximization of some criterion; if a selector is applied to an already empty list, the selector returns None.

class battlematica.library.AnyFilter(filter)

Bases: object

AnyFilter is used when there is more than one set of parameters acceptable for a base filter: for example, one could want to filter bots that are targeting any of several ally bots, not just a particular one.

Instead of being called the first time with a single group of parameters, AnyFilter is called with an iterable containing each group of acceptable parameters.

battlematica.library.f_current_action(ca)
battlematica.library.f_has_target(x, y)
battlematica.library.f_has_uid(uid)
battlematica.library.f_health_between(h1, h2)
battlematica.library.f_health_between_pct(h1, h2)
battlematica.library.f_is_carrying()
battlematica.library.f_is_not_carrying()
battlematica.library.f_not_of_teams(*unacceptable_teams)
battlematica.library.f_of_teams(*acceptable_teams)
battlematica.library.f_position_in_circle(x, y, r)
battlematica.library.f_position_in_cone(x, y, angle, a_half_range)
battlematica.library.f_position_in_rectangle(l, r, t, b)
battlematica.library.f_position_in_ring(x, y, r1, r2)
battlematica.library.f_position_out_of_circle(x, y, r)
battlematica.library.f_position_out_of_rectangle(l, r, t, b)
battlematica.library.f_property_between(prop, p1, p2)
battlematica.library.f_shield_between(s1, s2)
battlematica.library.f_shield_between_pct(s1, s2)
battlematica.library.i_artifacts()
battlematica.library.i_bots()
battlematica.library.i_drop_ports()
battlematica.library.s_closest_to_xy(x, y)
battlematica.library.s_farthest_from_xy(x, y)
battlematica.library.s_highest_abs_health()
battlematica.library.s_highest_abs_shield()
battlematica.library.s_lowest_abs_health()
battlematica.library.s_lowest_abs_shield()

battlang

class battlematica.battlang.BattlangTranslator
dump(filename)

Writes the latest translated program to a python file.

Parameters

filename – the name of the output file

from_file(filename)

Translates a BATTLANG program from a file.

Parameters

filename – the name of the file

translate(program, name)

Returns an AI function from a string containing a BATTLANG program.

Parameters

  • program – string containing the program

  • name – the __name__ that the function will have

battlematica.battlang.translate_battlang_file(filename)

Returns an AI function from a file containing a BATTLANG program.

Parameters

filename – the name of the file

battlematica.battlang.translate_battlang_string(s, program_name)

Returns an AI function from a string containing a BATTLANG program.

Parameters

  • s – string containing the program

  • program_name – the __name__ that the function will have