haive.games.risk.config¶

Comprehensive configuration system for Risk game variants and customization.

This module provides extensive configuration options for the Risk board game, supporting classic rules, modern variants, tournament settings, and custom rule modifications. The configuration system enables fine-tuned control over game mechanics, victory conditions, combat rules, and strategic elements.

The configuration classes use Pydantic for validation and provide factory methods for popular Risk variants including classic Risk, Risk 2210 A.D., Risk: Legacy, and tournament configurations.

Examples

Creating a classic Risk configuration:

config = RiskConfig.classic()
game = RiskGame(config)

Creating a modern Risk configuration:

config = RiskConfig.modern()
config.player_count = 4
config.time_limit_per_turn = 300  # 5 minutes
game = RiskGame(config)

Creating a custom tournament configuration:

config = RiskConfig.tournament()
config.max_game_duration = 7200  # 2 hours
config.sudden_death_enabled = True
game = RiskGame(config)

Creating a fast-paced variant:

config = RiskConfig(
    player_count=4,
    escalating_card_values=True,
    fast_reinforcement=True,
    time_limit_per_turn=60,
    blitz_mode=True,
    initial_armies_multiplier=1.5
)

Custom map configuration:

config = RiskConfig.modern()
config.custom_territories = {
    "North America": ["Alaska", "Northwest Territory", "Greenland"],
    "Europe": ["Iceland", "Great Britain", "Northern Europe"]
}
config.custom_continent_bonuses = {
    "North America": 5,
    "Europe": 5
}

Note

All configuration classes include comprehensive validation to ensure game rule consistency and prevent invalid combinations that would break gameplay mechanics.

Classes¶

RiskConfig

Comprehensive configuration for Risk game variants with extensive customization.

Module Contents¶

class haive.games.risk.config.RiskConfig(/, **data)[source]¶

Bases: pydantic.BaseModel

Comprehensive configuration for Risk game variants with extensive customization.

This configuration class provides complete control over Risk game mechanics, supporting classic rules, modern variants, tournament settings, and custom modifications. It includes validation for rule consistency and provides factory methods for popular Risk variants.

The configuration system supports: - Player count and game scaling options - Victory conditions and mission systems - Combat mechanics and dice rules - Card trading and reinforcement systems - Time limits and tournament settings - Custom maps and continent configurations - AI difficulty and strategic parameters

Parameters:: data (Any)

player_count¶

Number of players participating (2-6 players). Affects initial army distribution and strategic dynamics.

Type:: int

use_mission_cards¶

Enable mission-based victory conditions. Modern Risk variant where players win by completing secret missions.

Type:: bool

allow_card_trade_anytime¶

Allow card trading outside of turn. Strategic variant enabling more flexible resource management.

Type:: bool

escalating_card_values¶

Increase card set values with each trade. Classic mechanic that accelerates late-game army acquisition.

Type:: bool

fortify_from_multiple_territories¶

Allow multi-source fortification. Modern rule enabling armies to move from multiple connected territories.

Type:: bool

balanced_initial_placement¶

Use balanced territory distribution. Ensures fair starting positions by equalizing initial territories.

Type:: bool

reinforce_conquered_territory¶

Minimum armies in conquered territory. Prevents territories from being left completely undefended.

Type:: int

dice_sides¶

Number of sides on combat dice (4-20 sides). Affects combat probability and strategic calculation complexity.

Type:: int

max_attack_dice¶

Maximum dice an attacker can use (1-5). Controls maximum attack strength and combat resolution speed.

Type:: int

max_defense_dice¶

Maximum dice a defender can use (1-3). Balances defensive advantage against attacking forces.

Type:: int

custom_territories¶

Custom map definition. Allows completely custom board layouts and territorial relationships.

Type:: Optional[Dict[str, List[str]]]

custom_continent_bonuses¶

Bonus armies per continent. Defines reinforcement bonuses for controlling entire continents.

Type:: Dict[str, int]

initial_armies_multiplier¶

Multiplier for starting armies. Scales initial army distribution for faster or slower games.

Type:: float

time_limit_per_turn¶

Turn time limit in seconds. Tournament setting to maintain game pace and prevent delays.

Type:: Optional[int]

max_game_duration¶

Maximum game duration in seconds. Prevents excessively long games in competitive settings.

Type:: Optional[int]

sudden_death_enabled¶

Enable sudden death rules for time limits. Tournament rule for decisive game endings when time expires.

Type:: bool

blitz_mode¶

Enable fast-paced gameplay with reduced phases. Accelerated variant with streamlined turn structure.

Type:: bool

fast_reinforcement¶

Allow immediate reinforcement placement. Speeds up gameplay by reducing reinforcement calculation time.

Type:: bool

ai_difficulty_scaling¶

Scale AI difficulty based on game progress. Adaptive AI that becomes more challenging as game progresses.

Type:: bool

eliminate_weak_players¶

Remove players below threshold strength. Tournament rule to maintain competitive balance.

Type:: bool

alliance_system_enabled¶

Allow formal player alliances. Diplomatic variant enabling treaty-based cooperation.

Type:: bool

fog_of_war¶

Hide enemy army counts and movements. Strategic variant increasing uncertainty and intelligence gathering.

Type:: bool

Examples

Standard competitive configuration:

config = RiskConfig(
    player_count=4,
    use_mission_cards=True,
    escalating_card_values=True,
    time_limit_per_turn=180,
    max_game_duration=5400,  # 90 minutes
    balanced_initial_placement=True
)

Fast-paced casual configuration:

config = RiskConfig(
    player_count=3,
    blitz_mode=True,
    fast_reinforcement=True,
    initial_armies_multiplier=2.0,
    time_limit_per_turn=60
)

Strategic depth configuration:

config = RiskConfig(
    player_count=6,
    alliance_system_enabled=True,
    fog_of_war=True,
    use_mission_cards=True,
    fortify_from_multiple_territories=True
)

Custom map configuration:

config = RiskConfig(
    custom_territories={
        "Fantasy Realm": ["Dragon Kingdom", "Elf Forest", "Dwarf Mountains"],
        "Tech Empire": ["Cyber City", "Robot Factory", "AI Core"]
    },
    custom_continent_bonuses={
        "Fantasy Realm": 4,
        "Tech Empire": 3
    }
)

Note

Configuration validation ensures rule consistency and prevents invalid combinations that would break game mechanics or create unfair advantages.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

classmethod blitz()[source]¶

Create a configuration for fast-paced blitz gameplay.

Generates a configuration designed for quick games with accelerated mechanics, increased starting armies, and streamlined phases. Perfect for casual play or when time is limited.

Returns:: Pre-configured instance for blitz Risk gameplay.
Return type:: RiskConfig

Examples

Creating a blitz Risk game:

config = RiskConfig.blitz()
game = RiskGame(config)

# Results in:
# - 3-player fast setup
# - 50% more starting armies
# - 1-minute turn limits
# - Blitz mode enabled
# - Fast reinforcement
# - Modern flexible rules

Note

Blitz configuration typically results in 30-45 minute games with high action and strategic decision-making under time pressure.

classmethod classic()[source]¶

Create a configuration for classic Risk rules (1959-1993).

Generates the original Risk configuration with traditional rules, unbalanced initial placement, and total conquest victory conditions. This configuration emphasizes the original gameplay experience with all the strategic depth and potential imbalances of the classic game.

Returns:: Pre-configured instance for classic Risk gameplay.
Return type:: RiskConfig

Examples

Creating a classic Risk game:

config = RiskConfig.classic()
game = RiskGame(config)

# Results in:
# - Traditional 3-player setup
# - Total conquest victory (no missions)
# - Turn-based card trading only
# - Escalating card values
# - Single-territory fortification
# - Unbalanced initial placement (random)
# - Standard 6-sided dice combat

Note

Classic rules can lead to longer games and potential player elimination early in the game due to unbalanced starting positions.

classmethod modern()[source]¶

Create a configuration for modern Risk rules (2008+).

Generates the contemporary Risk configuration with mission cards, flexible trading, balanced placement, and quality-of-life improvements. This configuration emphasizes fair gameplay and reduced game length through mission-based victory conditions.

Returns:: Pre-configured instance for modern Risk gameplay.
Return type:: RiskConfig

Examples

Creating a modern Risk game:

config = RiskConfig.modern()
config.player_count = 4  # Customize player count
game = RiskGame(config)

# Results in:
# - Mission-based victory conditions
# - Flexible card trading anytime
# - Multi-territory fortification
# - Balanced initial placement
# - Escalating card values
# - Standard combat mechanics

Note

Modern rules generally result in shorter, more balanced games with multiple viable victory paths through mission completion.

classmethod strategic()[source]¶

Create a configuration for deep strategic gameplay.

Generates a configuration emphasizing strategic depth with alliances, fog of war, and complex diplomatic interactions. Designed for experienced players who enjoy intricate strategic planning.

Returns:: Pre-configured instance for strategic Risk gameplay.
Return type:: RiskConfig

Examples

Creating a strategic Risk game:

config = RiskConfig.strategic()
game = RiskGame(config)

# Results in:
# - 6-player maximum complexity
# - Alliance system enabled
# - Fog of war for uncertainty
# - Mission-based victory
# - Flexible trading and fortification
# - Adaptive AI difficulty

Note

Strategic configuration can result in longer games (2-4 hours) with complex diplomatic interactions and shifting alliances.

classmethod tournament()[source]¶

Create a configuration for competitive tournament play.

Generates a configuration optimized for tournament settings with time limits, balanced rules, and provisions for decisive game endings. This configuration ensures fair competition and manageable game duration.

Returns:: Pre-configured instance for tournament Risk gameplay.
Return type:: RiskConfig

Examples

Creating a tournament Risk game:

config = RiskConfig.tournament()
game = RiskGame(config)

# Results in:
# - 4-player balanced setup
# - 3-minute turn time limits
# - 2-hour maximum game duration
# - Sudden death rules enabled
# - Mission-based victory
# - Balanced initial placement
# - Fast reinforcement for efficiency

Note

Tournament configuration prioritizes fairness, time management, and decisive game endings for competitive play environments.

validate_configuration()[source]¶

Validate configuration for internal consistency and game balance.

Returns:: List of validation warnings or errors. Empty list means valid.
Return type:: List[str]

Examples

Checking configuration validity:

config = RiskConfig(...)
issues = config.validate_configuration()

if issues:
    for issue in issues:
        print(f"Warning: {issue}")
else:
    print("Configuration is valid")

classmethod validate_continent_bonuses(v)[source]¶

Validate continent bonus configuration.

Parameters:: v (Dict[str, int]) – Continent bonuses to validate.
Returns:: Validated continent bonuses.
Return type:: Dict[str, int]
Raises:: ValueError – If bonus configuration is invalid.

classmethod validate_custom_territories(v)[source]¶

Validate custom territory configuration.

Parameters:: v (Optional[Dict[str, List[str]]]) – Custom territories to validate.
Returns:: Validated territories.
Return type:: Optional[Dict[str, List[str]]]
Raises:: ValueError – If territory configuration is invalid.

property complexity_level: str¶

Calculate game complexity level based on enabled features.

Returns:: Complexity level (“Beginner”, “Intermediate”, “Advanced”, “Expert”).
Return type:: str

Examples

Checking complexity:

config = RiskConfig.classic()
complexity = config.complexity_level
print(f"Game complexity: {complexity}")  # "Intermediate"

property estimated_game_duration: str¶

Estimate game duration based on configuration settings.

Returns:: Estimated duration range (e.g., “45-90 minutes”).
Return type:: str

Examples

Checking estimated duration:

config = RiskConfig.blitz()
duration = config.estimated_game_duration
print(f"Expected game time: {duration}")  # "30-60 minutes"