pykrieg 0.1.3

A Pythonic wargame engine for Guy Debord's Le Jeu de la Guerre

Pykrieg

A Pythonic wargame engine for Guy Debord's Le Jeu de la Guerre (A Game of War).

About

Pykrieg is a Python library that implements the complex rules of Guy Debord's strategic tabletop game, providing a clean, extensible API for developers to build custom interfaces, AI opponents, and analysis tools. The project is inspired by the successful python-chess library and follows similar design principles.

Planned Features

• Complete Game Engine: Full implementation of Debord's strategic game rules
• Clean API: Intuitive Pythonic interface modeled after python-chess
• Extensible Design: Easy to create custom variants, unit types, and victory conditions
• Format Support: Game record and position formats for saving/sharing games
• Engine Protocol: UCI-like protocol for communication between engines and frontends
• Well-Tested: Comprehensive test suite with 85%+ code coverage

Installation

pip install pykrieg

Quick Start

from pykrieg import Board, create_piece

# Create a board
board = Board()

# Add units using the factory function
board.create_and_place_unit(0, 0, 'INFANTRY', 'NORTH')
board.create_and_place_unit(5, 10, 'CAVALRY', 'NORTH')
board.create_and_place_unit(19, 24, 'INFANTRY', 'SOUTH')

# Or create units directly and place them
from pykrieg import Infantry, Cannon
unit = Cannon('NORTH')
board.place_unit(10, 10, unit)

# Query units on the board
print(board.count_units())  # Total number of units
print(board.count_units(unit_type='INFANTRY'))  # Count of infantry
print(board.get_units_by_owner('NORTH'))  # List of coordinates with North's units

# Serialize to FEN
from pykrieg import Fen
fen = Fen.board_to_fen(board)
print(fen)

# Deserialize from FEN
board2 = Fen.fen_to_board(fen)

# Check territory
print(board.get_territory(0, 0))  # 'NORTH'
print(board.get_territory(19, 24))  # 'SOUTH'

# Convert coordinates
print(Board.tuple_to_spreadsheet(0, 0))  # 'A1'
print(Board.spreadsheet_to_tuple('A1'))  # (0, 0)

# Movement
from pykrieg import generate_moves, is_valid_move, execute_move

# Get legal moves for a unit
moves = generate_moves(board, 5, 10)
print(f"Available moves: {moves}")  # List of (row, col) tuples

# Check if a move is valid
if is_valid_move(board, 5, 10, 7, 12):
    print("Move is valid!")

# Execute a move
moved_unit = execute_move(board, 5, 10, 7, 12)
print(f"Moved {moved_unit.unit_type} to (7, 12)")

# Or use Board convenience methods
moves = board.get_legal_moves(5, 10)  # Same as generate_moves()
is_valid = board.is_legal_move(5, 10, 7, 12)  # Same as is_valid_move()
unit = board.make_move(5, 10, 7, 12)  # Same as execute_move()

# Check unit movement properties
from pykrieg import get_movement_range, can_move
unit = board.get_unit(7, 12)
print(f"Movement range: {get_movement_range(unit)}")  # 0, 1, or 2
print(f"Can move: {can_move(unit)}")  # True or False

# Combat
from pykrieg import calculate_combat, execute_capture, CombatOutcome

# Calculate combat for a target square
result = calculate_combat(board, 5, 12, attacker='NORTH', defender='SOUTH')
print(f"Attack Power: {result['attack_power']}")
print(f"Defense Power: {result['defense_power']}")
print(f"Outcome: {result['outcome'].value}")

# Capture a unit if attack was successful
if result['outcome'] == CombatOutcome.CAPTURE:
    captured_unit = execute_capture(board, 5, 12)
    print(f"Captured {captured_unit.unit_type}!")

# Or use Board convenience methods
result = board.calculate_combat(5, 12, 'NORTH', 'SOUTH')
captured = board.execute_capture(5, 12)

# Check turn tracking
print(f"Current turn: {board.turn_number}")
print(f"Current player: {board.turn}")
print(f"Current phase: {board.current_phase}")  # 'M' for movement, 'B' for battle

# Increment turn (switches player and resets phase)
board.increment_turn()

Documentation

Comprehensive documentation is available at docs/ covering:

• Basic usage
• API reference for Board, FEN, and utility functions
• Coordinate system details
• FEN format specification
• Type definitions

Build documentation locally::

cd docs make html

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Donations

If you like the project and want to support future development, consider donating!

License

This project is licensed under the GNU General Public License v3.0 - see LICENSE for details.

The GPL v3 license ensures that:

• The software remains free for all users
• Derivative works must be shared under the same license (copyleft)
• Commercial use is prohibited (requires separate commercial license)
• Users have the freedom to study, modify, and distribute the software