match module

Generate and run matches.

Match instances manage and expose the current match state required for the game logic. Additional (pre-calculated) data is provided for AI players and frontend convenience.

A Match is initialized from a match configuration (a Game instance). To restart a match, just create a new instance from the same configuration.

The game logic is implemented in Match.attack() and Match.end_turn(). Only these two methods change the match state. All executed actions are available in Match.history for e.g. match replays.

The match loop is:

• while at least 2 players are alive (Match.winner < 0):

  • while the current player can and wants to attack:

    • set the attacking area (Match.set_from_area())

    • set the attacked area (Match.set_to_area())

    • roll dice to attack (Match.attack())

  • end the current player’s turn (Match.end_turn())

The attacking/attacked areas choice may come from an AI player (e.g. DefaultPlayer) or from user input. See here for a working code example.

For easy interfacing with AI players, frontends, (processing) libraries, (network) protocols, etc., all Match, State, Attack and Supply data are exposed as int, tuple(int) or tuple(tuple(int)) objects. All area/player references and parameters are indices into the respective tuples.

class dicewars.match.Match(game=None)

Generate a runnable match.

Parameters

game (Game or None) – Game instance used to initialize the match state (if None: a Game with default parameters is generated)

Raises

TypeError – if game is not a Game instance

AREA_MAX_NUM_DICE = 8

Maximal number of dice per area. (int)

PLAYER_MAX_NUM_STOCK = 64

Maximal number of stored (i.e. not supplied to areas) dice per player. (int)

property game

The Game instance (configuration) used for the match.

property state

The State instance of the current match state.

property num_steps

The number of (successful) attack() and end_turn() calls. (int)

New in version 0.2.0.

property seat

The current player seat index, -1 if match is finished. (int)

property player

The current player’s index, -1 if match is finished. (int)

property winner

The last remaining player’s index, -1 if match is not finished. (int)

property area_players

The occupying player’s index for each area. (tuple(int))

property area_num_dice

The number of dice placed on each area. (tuple(int))

property player_areas

The indices of all areas occupied by each player. (tuple(tuple(int)))

property player_num_areas

The total number of areas occupied by each player. (tuple(int))

property player_max_size

The maximal number of adjacent areas occupied by each player. (tuple(int))

property player_num_dice

The total number of dice placed on each player’s areas. (tuple(int))

property player_num_stock

The number of each player’s stored dice that could not be supplied to areas. (tuple(int))

property from_area

The index of the currently set attacking area, -1 if not set. (int)

property to_area

The index of the currently set attacked area, -1 if not set. (int)

property last_attack

The Attack instance created by the last (successful) call of attack().

property last_supply

The Supply instance created by the last (successful) call of end_turn().

property history

The sequence of all Attacks and Supplys so far. (tuple(Attack/Supply))

New in version 0.2.0.

set_from_area(area_idx)

Validate and set or unset the attacking area.

Parameters

area_idx (int) – index of the attacking area, < 0 to unset

Returns

True if accepted and changed or unset, False when rejected or unchanged

Return type

bool

Raises

TypeError – if area_idx is not int

set_to_area(area_idx)

Validate and set or unset the attacked area.

Parameters

area_idx (int) – index of the attacked area, < 0 to unset

Returns

True if accepted and changed or unset, False when rejected or unchanged

Return type

bool

Raises

TypeError – if area_idx is not int

attack()

Validate and execute an attack for the current player.

The attack is executed only when valid attacking/attacked areas have been set before. The attack’s result is available via last_attack. Attacking/attacked areas are unset after execution.

Returns

True if executed and match state is updated, False when rejected (match state has not changed)

Return type

bool

end_turn()

End current player’s turn and advance to the next player.

The player’s player_max_size number of dice is randomly supplied to the player’s areas (or stored). The outcome is available via last_supply. The player on the next seat becomes the current player.

Returns

True if match state is updated, False when the match is finished already

Return type

bool

class dicewars.match.State(num_steps, seat, player, winner, area_players, area_num_dice, player_areas, player_num_areas, player_max_size, player_num_dice, player_num_stock)

A convenience wrapper to access the current match state data at once. (namedtuple)

The (copied) value or (referenced) tuple properties of a Match instance are:

• num_steps

• seat

• player

• winner

• area_players

• area_num_dice

• player_areas

• player_num_areas

• player_max_size

• player_num_dice

• player_num_stock

The current State instance is available via Match.state and valid until a (successful) call of Match.attack() or Match.end_turn().

Changed in version 0.2.0: Added num_steps.

class dicewars.match.Attack(step, from_player, from_area, from_dice, from_sum_dice, to_player, to_area, to_dice, to_sum_dice, victory, from_area_num_dice, from_player_num_areas, from_player_max_size, from_player_num_dice, to_area_num_dice, to_player_num_areas, to_player_max_size, to_player_num_dice)

Information and result of an executed attack. (namedtuple)

Attack instances are created in Match.attack() and available via Match.last_attack and Match.history afterwards.

step: int

The Attack’s index in Match.history.

New in version 0.2.0.

from_player: int

The index of the attacking player.

from_area: int

The index of the attacking area.

from_dice: tuple(int)

The randomly generated dice values for the attacking area.

from_sum_dice: int

The sum of from_dice.

to_player: int

The index of the attacked player.

to_area: int

The index of the attacked area.

to_dice: tuple(int)

The randomly generated dice values for the attacked area.

to_sum_dice: int

The sum of to_dice.

victory: bool

True if successful, False if defeated.

from_area_num_dice: int

The number of dice placed on the attacking area (always 1 for standard game rules).

New in version 0.2.0.

from_player_num_areas: int

The total number of areas occupied by the attacking player.

New in version 0.2.0.

from_player_max_size: int

The maximal number of adjacent areas occupied by the attacking player.

New in version 0.2.0.

from_player_num_dice: int

The total number of dice placed on the attacking player’s areas.

New in version 0.2.0.

to_area_num_dice: int

The number of dice placed on the attacked area.

New in version 0.2.0.

to_player_num_areas: int

The total number of areas occupied by the attacked player.

New in version 0.2.0.

to_player_max_size: int

The maximal number of adjacent areas occupied by the attacked player.

New in version 0.2.0.

to_player_num_dice: int

The total number of dice placed on the attacked player’s areas.

New in version 0.2.0.

class dicewars.match.Supply(step, player, areas, dice, sum_dice, area_num_dice, player_num_stock)

The outcome of dice supply at the end of a player’s turn. (namedtuple)

Supply instances are created in Match.end_turn() and available via Match.last_supply and Match.history afterwards.

step: int

The Supply’s index in Match.history.

New in version 0.2.0.

player: int

The index of the player.

areas: tuple(int)

The indices of the player’s areas that got dice supply.

dice: tuple(int)

The number of dice supplied to the areas in areas.

sum_dice: int

The sum of dice.

area_num_dice: tuple(int)

The number of dice placed on the areas in areas.

New in version 0.2.0.

player_num_stock: int

The number of dice stored in the player’s stock.

Changed in version 0.2.0: Renamed from “num_stock”.