Welcome to dicewars’ documentation!¶

DiceWars is a (quite addictive) quick game, inspired by the Risk board game. It mixes strategy and luck, the objective is to conquer all areas on a map by dice rolls.

It was published for browsers by GAMEDESIGN (2001 for Flash, then ported to JavaScript).

dicewars implements the logic (the backend) that is required to create playable game GUIs (the frontends) and (multi player) game servers in Python:

generate random hexagonal cell grids (grid.Grid)
generate random match configurations (game.Game)
run matches according to the rules (match.Match)
implement and use AI players in matches (player.Player, player.DefaultPlayer)

Beside data for the game logic, grid.Grid instances also provide coordinates to render a map. For frontends w/o point-in-polygon-test support util.pick_grid_area() comes in handy for area selection.

A minimal frontend match loop could look like this (AI players only):

from dicewars.match import Match
from dicewars.player import DefaultPlayer

match = Match()  # uses default grid and game (28x32 cells, 30 areas, 7 seats)
ai_player = DefaultPlayer()

while match.winner < 0:  # at least two players alive
    while match.winner < 0:  # do as many attacks as the current player wishes
        attack_areas = ai_player.get_attack_areas(match.game.grid, match.state)
        if attack_areas:  # tuple of from/to area indices -> attack!
            match.set_from_area(attack_areas[0])  # players's attacking area
            match.set_to_area(attack_areas[1])  # adjacent area to attack
            match.attack()  # roll dice, result is available in match.last_attack
            if match.player_num_areas[match.last_attack.to_player] == 0:
                # attacked area was the owning player's last one -> eliminated
                print(
                    f'player {match.last_attack.from_player} kicked out '
                    f'player {match.last_attack.to_player}.'
                )
        else:  # None -> no more attacks, end player's turn
            break
    match.end_turn()  # supply dice to player's areas, advance to next player

print(f'player {match.winner} wins the match!')

Instead of requesting attack_areas from ai_player, just set the from/to areas from user input for interactive matches.

dicewars is pure Python (>=3.7), has no external dependencies and is distributed under the terms of the GPLv3+.

Welcome to dicewars’ documentation!¶

Table of contents¶

Indices¶