ProbabilityPewter 0.5.0__py3-none-any.whl

ProbabilityPewter/roll_stats/combat.py

@@ -0,0 +1,715 @@
+"""Combat-odds helpers for tabletop war games.
+
+This module provides lightweight combat win-probability tools for three popular
+strategy games.  The focus is quick, practical estimation — not a full rules
+emulation.
+
+Supported games
+---------------
+Risk
+    Uses **exact** probability calculation: all possible dice outcomes are
+    enumerated once and cached, so results are instant and perfectly accurate.
+    The attacker keeps 1 army in reserve, so a territory with N armies rolls
+    min(3, N-1) dice.  Ties go to the defender.  Pass the **total army count
+    of each territory**, e.g. ``risk_odds(10, 8)`` means 10 vs 8 armies —
+    identical to what you'd type into riskodds.com.
+
+Twilight Imperium 4
+    Uses **Monte Carlo simulation** (repeated random battles).  Each unit type
+    rolls a number of 10-sided dice and hits on a roll >= its combat value.
+    Some units (Dreadnought, War Sun) have *Sustain Damage* — they can absorb
+    one hit before being destroyed; ``ti_odds({'Dreadnought': 1, 'Cruiser': 2}, {'Fighter': 5})``.
+    
+    Casualty allocation assumes optimal defender strategy (spreading damage
+    across fresh Sustain units rather than destroying already-damaged units).
+    
+Axis & Allies
+    Uses **Monte Carlo simulation**.  Units roll D6 and hit on a roll <= their
+    attack (or defense) value.  Attack and defense values differ per unit;
+    ``aa_odds({'Tank': 3, 'Infantry': 2}, {'Infantry': 4})``.
+
+Return format — the ``output`` parameter
+----------------------------------------
+Every public function accepts an ``output`` keyword that controls what is
+returned:
+
+* ``'summary'`` (default) — a plain-text string with the headline numbers.
+* ``'result'`` — a :class:`CombatResult` object with all fields accessible.
+* ``'dict'`` — a plain Python dictionary with the same fields.
+* ``'dataframe'`` — a one-row ``pandas.DataFrame`` (pandas must be installed).
+
+Use ``output='result'`` when you want to pass the result to :func:`plot_combat`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import lru_cache
+import itertools
+import random
+from typing import Dict, Iterable, List, Tuple, Union
+
+import matplotlib.pyplot as plt
+
+
+@dataclass(frozen=True)
+class UnitProfile:
+    """Internal combat profile for one unit type.
+
+    This is a *dataclass* — a plain Python class that mainly holds data.
+    ``@dataclass`` is a decorator that auto-generates ``__init__``, ``__repr__``
+    and other boilerplate so you can write ``UnitProfile(name='Cruiser', ...)``
+    without typing all that yourself.  The ``frozen=True`` flag makes instances
+    immutable (like a named tuple) so they can be safely cached.
+
+    Attributes
+    ----------
+    name : str
+        Display name of the unit.
+    dice_sides : int
+        Number of sides on the die rolled (10 for TI, 6 for A&A).
+    attack_target : int
+        The number the die roll must reach to score a hit while attacking.
+    defense_target : int
+        The number the die roll must reach to score a hit while defending.
+    compare : str
+        ``'ge'`` — hit if roll >= target (TI: roll high to hit).
+        ``'le'`` — hit if roll <= target (A&A: roll low to hit).
+    dice_count : int
+        How many dice this unit rolls per combat round (default 1; War Sun rolls 3).
+    sustain : bool
+        If ``True`` the unit can absorb one hit before being destroyed
+        (TI Dreadnought / War Sun).
+    """
+
+    name: str
+    dice_sides: int
+    attack_target: int
+    defense_target: int
+    compare: str = "le"
+    dice_count: int = 1
+    sustain: bool = False
+
+
+@dataclass
+class CombatResult:
+    """Container returned by every ``*_odds`` function when ``output='result'``.
+
+    A *dataclass* is a normal Python class that mainly stores data.  The
+    ``@dataclass`` decorator writes the ``__init__`` method for you, so each
+    attribute listed below becomes a constructor argument and a readable
+    attribute on the object (e.g. ``result.attacker_wins``).
+
+    Attributes
+    ----------
+    attacker_wins : float
+        Probability [0, 1] that the attacker wins the battle.
+    defender_wins : float
+        Probability [0, 1] that the defender wins the battle.
+    draw : float
+        Probability [0, 1] that both sides are wiped out simultaneously.
+        This is essentially zero for Risk but can occur in simulations.
+    avg_att_remaining : float
+        Average number of attacker units / armies still alive at the end.
+    avg_def_remaining : float
+        Average number of defender units / armies still alive at the end.
+    summary : str
+        Human-readable one-liner with the headline numbers.
+    detail : dict
+        Extra data depending on method — ``'method'`` key is either
+        ``'exact'`` (Risk) or ``'simulation'`` (TI / A&A).  For exact Risk
+        results this also contains the full terminal-state distribution.
+
+    Example
+    -------
+    >>> r = risk_odds(8, 5, output='result')
+    >>> r.attacker_wins
+    0.736396
+    >>> plot_combat(r)   # pass the result object directly to the plot function
+    """
+
+    attacker_wins: float
+    defender_wins: float
+    draw: float
+    avg_att_remaining: float
+    avg_def_remaining: float
+    summary: str
+    detail: Dict
+
+
+TI4_UNITS: Dict[str, UnitProfile] = {
+    "Infantry": UnitProfile("Infantry", dice_sides=10, attack_target=8, defense_target=8, compare="ge"),
+    "Infantry+": UnitProfile("Infantry+", dice_sides=10, attack_target=7, defense_target=7, compare="ge"),
+    "Fighter": UnitProfile("Fighter", dice_sides=10, attack_target=9, defense_target=9, compare="ge"),
+    "Fighter+": UnitProfile("Fighter+", dice_sides=10, attack_target=8, defense_target=8, compare="ge"), #the upgraded versions of the units
+    "Destroyer": UnitProfile("Destroyer", dice_sides=10, attack_target=9, defense_target=9, compare="ge"),
+    "Destroyer+": UnitProfile("Destroyer+", dice_sides=10, attack_target=8, defense_target=8, compare="ge"),
+    "Carrier": UnitProfile("Carrier", dice_sides=10, attack_target=9, defense_target=9, compare="ge"),
+    "Cruiser": UnitProfile("Cruiser", dice_sides=10, attack_target=7, defense_target=7, compare="ge"),
+    "Cruiser+": UnitProfile("Cruiser+", dice_sides=10, attack_target=6, defense_target=6, compare="ge"),
+    "Dreadnought": UnitProfile(
+        "Dreadnought", dice_sides=10, attack_target=5, defense_target=5, compare="ge", sustain=True
+    ),
+    "War Sun": UnitProfile(
+        "War Sun", dice_sides=10, attack_target=3, defense_target=3, compare="ge", dice_count=3, sustain=True
+    ),
+}
+
+AA_UNITS: Dict[str, UnitProfile] = {
+    #Stats based on the Axis & Allies: 50th Anniversary Edition of 2008
+    "Infantry": UnitProfile("Infantry", dice_sides=6, attack_target=1, defense_target=2, compare="le"),
+    "Infantry+": UnitProfile("Infantry+", dice_sides=6, attack_target=2, defense_target=2, compare="le"), #paired with Artillery
+    "Artillery": UnitProfile("Artillery", dice_sides=6, attack_target=2, defense_target=2, compare="le"),
+    "Tank": UnitProfile("Tank", dice_sides=6, attack_target=3, defense_target=3, compare="le"),
+    "Fighter": UnitProfile("Fighter", dice_sides=6, attack_target=3, defense_target=4, compare="le"),
+    "Bomber": UnitProfile("Bomber", dice_sides=6, attack_target=4, defense_target=1, compare="le"),
+    "Cruiser": UnitProfile("Cruiser", dice_sides=6, attack_target=3, defense_target=3, compare="le"),
+    "Carrier": UnitProfile("Carrier", dice_sides=6, attack_target=1, defense_target=3, compare="le"),
+    "Destroyer": UnitProfile("Destroyer", dice_sides=6, attack_target=2, defense_target=2, compare="le"),
+    "Submarine": UnitProfile("Submarine", dice_sides=6, attack_target=2, defense_target=1, compare="le"),
+    "Battleship": UnitProfile(
+        "Battleship", dice_sides=6, attack_target=4, defense_target=4, compare="le", sustain=True
+    ),
+}
+
+
+def _format_result(result: CombatResult, output: str):
+    """Format a CombatResult according to output mode."""
+    if output == "summary":
+        return result.summary
+    if output == "result":
+        return result
+    if output == "dict":
+        return {
+            "attacker_wins": result.attacker_wins,
+            "defender_wins": result.defender_wins,
+            "draw": result.draw,
+            "avg_att_remaining": result.avg_att_remaining,
+            "avg_def_remaining": result.avg_def_remaining,
+            "summary": result.summary,
+            "detail": result.detail,
+        }
+    if output == "dataframe":
+        import pandas as pd
+
+        return pd.DataFrame(
+            [
+                {
+                    "attacker_wins": result.attacker_wins,
+                    "defender_wins": result.defender_wins,
+                    "draw": result.draw,
+                    "avg_att_remaining": result.avg_att_remaining,
+                    "avg_def_remaining": result.avg_def_remaining,
+                }
+            ]
+        )
+    raise ValueError("output must be one of: 'summary', 'result', 'dict', 'dataframe'")
+
+
+def _risk_round_probs(att_dice: int, def_dice: int) -> Dict[Tuple[int, int], float]:
+    """Per-round casualty probabilities for Risk-style dice comparisons.
+
+    Returns probabilities keyed by (attacker_losses, defender_losses).
+    """
+    outcomes: Dict[Tuple[int, int], float] = {}
+    total = 6 ** (att_dice + def_dice)
+
+    for att_rolls in itertools.product(range(1, 7), repeat=att_dice):
+        for def_rolls in itertools.product(range(1, 7), repeat=def_dice):
+            a_sorted = sorted(att_rolls, reverse=True)
+            d_sorted = sorted(def_rolls, reverse=True)
+            pairs = min(att_dice, def_dice)
+            a_loss = 0
+            d_loss = 0
+            for i in range(pairs):
+                if a_sorted[i] > d_sorted[i]:
+                    d_loss += 1
+                else:
+                    a_loss += 1
+            key = (a_loss, d_loss)
+            outcomes[key] = outcomes.get(key, 0.0) + 1.0 / total
+
+    return outcomes
+
+
+@lru_cache(maxsize=None)
+def _risk_transitions(att_dice: int, def_dice: int) -> Tuple[Tuple[int, int, float], ...]:
+    probs = _risk_round_probs(att_dice, def_dice)
+    return tuple((a_loss, d_loss, p) for (a_loss, d_loss), p in probs.items())
+
+
+def _risk_terminal_distribution(attackers: int, defenders: int) -> Dict[Tuple[int, int], float]:
+    """Exact terminal-state distribution for a Risk battle."""
+
+    @lru_cache(maxsize=None)
+    def _solve(a: int, d: int) -> Dict[Tuple[int, int], float]:
+        # Attacker stops at 1 army (must keep 1 in the source territory).
+        # Defender fights until eliminated (no reserve rule for defenders).
+        if a <= 1 or d <= 0:
+            return {(a, max(d, 0)): 1.0}
+
+        adice = min(3, a - 1)  # at most 3 dice; reserve army never fights
+        ddice = min(2, d)
+        combined: Dict[Tuple[int, int], float] = {}
+        for a_loss, d_loss, p in _risk_transitions(adice, ddice):
+            sub = _solve(a - a_loss, d - d_loss)
+            for state, sub_p in sub.items():
+                combined[state] = combined.get(state, 0.0) + p * sub_p
+        return combined
+
+    return _solve(int(attackers), int(defenders))
+
+
+def risk_odds(
+    #validated using https://riskodds.com/
+    attackers: int, 
+    defenders: int, 
+    output: str = "summary"
+    ):
+    """Exact win-probability for a Risk battle fought to completion.
+
+    Pass the **total number of armies in each territory**, exactly as you
+    would enter them on riskodds.com.
+
+    Risk dice rules modelled here
+    ------------------------------
+    * The attacker's source territory must always keep **at least 1 army**
+      behind, so the attacker rolls ``min(3, attackers - 1)`` dice per round.
+      A territory with 2 armies rolls 1 die; with 3 armies, 2 dice; with 4+
+      armies, 3 dice.
+    * The **defender** rolls up to **2 dice** per round (one per defending
+      army, maximum 2); defenders have no reserve rule.
+    * Each pair is resolved highest-vs-highest; **ties always go to the
+      defender** (attacker must roll strictly higher to win a pair).
+    * The battle continues automatically until the attacker is reduced to
+      1 army (can no longer attack) or the defender is eliminated.
+    * **Draws are impossible in Risk.**  The attacker always ends with at
+      least 1 army, so both sides can never reach 0 simultaneously.  The
+      ``draw`` field of the returned :class:`CombatResult` is always 0.
+
+    Results are **exact** — every possible sequence of dice rolls is computed
+    analytically using dynamic programming, not simulation.
+
+    Parameters
+    ----------
+    attackers : int
+        Total armies in the **attacking territory** (including the 1 kept in
+        reserve).  Must be >= 2 to be able to attack; passing 1 returns
+        defender wins immediately.
+    defenders : int
+        Total armies in the **defending territory**.
+    output : str
+        ``'summary'`` (default), ``'result'``, ``'dict'``, or ``'dataframe'``.
+
+    Returns
+    -------
+    str, CombatResult, dict, or pandas.DataFrame
+        Depending on *output*.
+
+    Examples
+    --------
+    >>> risk_odds(10, 8)   # territory with 10 armies attacks territory with 8
+    'Risk odds - attacker win: ..., avg survivors (A/D): ...'
+
+    >>> r = risk_odds(10, 8, output='result')
+    >>> r.attacker_wins
+    0.745...
+    >>> plot_combat(r)
+    """
+    if attackers < 0 or defenders < 0:
+        raise ValueError("attackers and defenders must be >= 0")
+
+    dist = _risk_terminal_distribution(int(attackers), int(defenders))
+    att_win = sum(p for (a, d), p in dist.items() if d == 0)
+    def_win = sum(p for (a, d), p in dist.items() if d > 0)
+    # Draws are structurally impossible in Risk: the attacker always keeps
+    # 1 army in reserve, so both sides can never reach 0 at the same time.
+    draw = 0.0
+
+    avg_att = sum(a * p for (a, _), p in dist.items())
+    avg_def = sum(d * p for (_, d), p in dist.items())
+
+    summary = (
+        f"Risk odds - attacker win: {att_win:.2%}, defender win: {def_win:.2%}, "
+        f"avg survivors (A/D): {avg_att:.2f}/{avg_def:.2f}"
+    )
+    result = CombatResult(
+        attacker_wins=round(att_win, 6),
+        defender_wins=round(def_win, 6),
+        draw=round(draw, 6),
+        avg_att_remaining=round(avg_att, 3),
+        avg_def_remaining=round(avg_def, 3),
+        summary=summary,
+        detail={"terminal_distribution": dist, "method": "exact"},
+    )
+    return _format_result(result, output)
+
+
+def _build_force(units: Dict[str, int], catalog: Dict[str, UnitProfile]) -> List[Dict[str, Union[str, int]]]:
+    """Expand {'Unit': n} into a list of unit instances with hit points."""
+    if not isinstance(units, dict) or not units:
+        raise ValueError("units must be a non-empty dict like {'Cruiser': 2, 'Fighter': 3}")
+
+    force: List[Dict[str, Union[str, int]]] = []
+    for unit_name, count in units.items():
+        if unit_name not in catalog:
+            supported = ", ".join(sorted(catalog))
+            raise ValueError(f"Unknown unit: '{unit_name}'. Supported units: {supported}")
+        if not isinstance(count, int) or count < 0:
+            raise ValueError("unit counts must be integers >= 0")
+
+        profile = catalog[unit_name]
+        for _ in range(count):
+            force.append({
+                "name": profile.name,
+                "hp": 2 if profile.sustain else 1,
+                "max_hp": 2 if profile.sustain else 1,
+            })
+
+    if not force:
+        raise ValueError("force cannot be empty")
+    return force
+
+
+def _hit_success(roll: int, target: int, compare: str) -> bool:
+    if compare == "ge":
+        return roll >= target
+    if compare == "le":
+        return roll <= target
+    raise ValueError("compare must be 'ge' or 'le'")
+
+
+def _roll_hits(force: Iterable[Dict[str, Union[str, int]]], role: str, catalog: Dict[str, UnitProfile], rng) -> int:
+    """Roll all combat dice for one side in one combat round."""
+    hits = 0
+    for unit in force:
+        profile = catalog[str(unit["name"])]
+        target = profile.attack_target if role == "attack" else profile.defense_target
+        for _ in range(profile.dice_count):
+            roll = rng.randint(1, profile.dice_sides)
+            if _hit_success(roll, target, profile.compare):
+                hits += 1
+    return hits
+
+
+def _apply_hits(
+    defender_force: List[Dict[str, Union[str, int]]],
+    hits: int,
+    casualty_order: List[str],
+) -> List[Dict[str, Union[str, int]]]:
+    """Apply incoming hits using an optimal defender casualty strategy.
+
+    Strategy (assumes rational defender allocation):
+    1) Remove fresh non-sustain units (base hp=1) by casualty order
+    2) If only sustain units remain, damage fresh ones (hp=2→1) first
+    3) Only destroy already-damaged sustain units (hp=1 damaged→0) as last resort
+    
+    """
+    order_idx = {name: i for i, name in enumerate(casualty_order)}
+
+    force = defender_force[:]
+    for _ in range(hits):
+        if not force:
+            break
+
+        # Priority 1: Remove fresh non-sustain units (max_hp=1, currently hp=1).
+        # These die immediately and cannot absorb a second hit.
+        fresh_nonsustain = [u for u in force if int(u["max_hp"]) == 1 and int(u["hp"]) == 1]
+        if fresh_nonsustain:
+            victim = min(fresh_nonsustain, key=lambda u: order_idx.get(str(u["name"]), 999))
+            force.remove(victim)
+            continue
+
+        # Priority 2: Damage fresh sustain units (max_hp=2, currently hp=2).
+        # Spreading damage is better than destroying already-damaged units.
+        fresh_sustain = [u for u in force if int(u["max_hp"]) > 1 and int(u["hp"]) == int(u["max_hp"])]
+        if fresh_sustain:
+            victim = min(fresh_sustain, key=lambda u: order_idx.get(str(u["name"]), 999))
+            victim["hp"] = int(victim["hp"]) - 1
+            continue
+
+        # Priority 3: Destroy already-damaged sustain units (hp=1, max_hp=2).
+        damaged_sustain = [u for u in force if int(u["max_hp"]) > 1 and int(u["hp"]) == 1]
+        if damaged_sustain:
+            victim = min(damaged_sustain, key=lambda u: order_idx.get(str(u["name"]), 999))
+            force.remove(victim)
+            continue
+
+        # Fallback (should not reach here if logic is sound).
+        force.pop(0)
+
+    return force
+
+
+def _simulate_battle(
+    attacker_units: Dict[str, int],
+    defender_units: Dict[str, int],
+    catalog: Dict[str, UnitProfile],
+    casualty_order: List[str],
+    n_sim: int,
+    rounds: int | None,
+    seed: int | None,
+) -> CombatResult:
+    """Monte Carlo battle simulation for heterogeneous unit sets."""
+    if n_sim <= 0:
+        raise ValueError("n_sim must be > 0")
+
+    rng = random.Random(seed)
+    att_wins = 0
+    def_wins = 0
+    draws = 0
+    total_att_remaining = 0
+    total_def_remaining = 0
+    terminal_counts: Dict[Tuple[int, int], int] = {}
+
+    for _ in range(n_sim):
+        att_force = _build_force(attacker_units, catalog)
+        def_force = _build_force(defender_units, catalog)
+
+        round_idx = 0
+        while att_force and def_force and (rounds is None or round_idx < rounds):
+            round_idx += 1
+            att_hits = _roll_hits(att_force, "attack", catalog, rng)
+            def_hits = _roll_hits(def_force, "defense", catalog, rng)
+
+            def_force = _apply_hits(def_force, att_hits, casualty_order)
+            att_force = _apply_hits(att_force, def_hits, casualty_order)
+
+        att_left = len(att_force)
+        def_left = len(def_force)
+        total_att_remaining += att_left
+        total_def_remaining += def_left
+        terminal_counts[(att_left, def_left)] = terminal_counts.get((att_left, def_left), 0) + 1
+
+        if att_left > 0 and def_left == 0:
+            att_wins += 1
+        elif def_left > 0 and att_left == 0:
+            def_wins += 1
+        else:
+            draws += 1
+
+    p_att = att_wins / n_sim
+    p_def = def_wins / n_sim
+    p_draw = draws / n_sim
+    avg_att = total_att_remaining / n_sim
+    avg_def = total_def_remaining / n_sim
+
+    summary = (
+        f"Combat odds - attacker win: {p_att:.2%}, defender win: {p_def:.2%}, "
+        f"draw: {p_draw:.2%}, avg survivors (A/D): {avg_att:.2f}/{avg_def:.2f}"
+    )
+    detail = {
+        "method": "simulation",
+        "n_sim": n_sim,
+        "seed": seed,
+        "terminal_distribution": {
+            k: v / n_sim for k, v in sorted(terminal_counts.items(), key=lambda x: x[1], reverse=True)
+        },
+    }
+    return CombatResult(
+        attacker_wins=round(p_att, 6),
+        defender_wins=round(p_def, 6),
+        draw=round(p_draw, 6),
+        avg_att_remaining=round(avg_att, 3),
+        avg_def_remaining=round(avg_def, 3),
+        summary=summary,
+        detail=detail,
+    )
+
+
+def ti_odds(
+    #validated using https://ti4battle.com/
+    attacker: Dict[str, int],
+    defender: Dict[str, int],
+    n_sim: int = 10_000,
+    rounds: int | None = None,
+    seed: int | None = None,
+    output: str = "summary",
+):
+    """Estimate Twilight Imperium 4 combat odds with simulation.
+
+    Parameters
+    ----------
+    attacker, defender : dict
+        Unit dictionaries, e.g. {'Dreadnought': 1, 'Cruiser': 2, 'Fighter': 4}.
+    n_sim : int
+        Number of Monte Carlo simulations.
+    rounds : int or None
+        Optional max combat rounds. None means fight until one side is gone.
+    seed : int or None
+        Optional RNG seed for reproducibility.
+    output : str
+        One of 'summary', 'result', 'dict', 'dataframe'.
+    """
+    casualty_order = ["Infantry", "Infantry+", "Fighter", "Fighter+", "Destroyer", "Destroyer+", "Cruiser", "Cruiser+", "Carrier", "Dreadnought", "War Sun"]
+    result = _simulate_battle(
+        attacker_units=attacker,
+        defender_units=defender,
+        catalog=TI4_UNITS,
+        casualty_order=casualty_order,
+        n_sim=n_sim,
+        rounds=rounds,
+        seed=seed,
+    )
+    result.summary = "TI4 " + result.summary
+    return _format_result(result, output)
+
+
+def aa_odds(
+    attacker: Dict[str, int],
+    defender: Dict[str, int],
+    n_sim: int = 10_000,
+    rounds: int | None = None,
+    seed: int | None = None,
+    output: str = "summary",
+):
+    """Estimate Axis & Allies combat odds with simulation.
+
+    This model uses core attack/defense values and ignores special-case rules
+    (first strike, bombardment, transport restrictions, etc.).
+    """
+    casualty_order = ["Infantry", "Infantry+", "Artillery", "Tank", "Fighter", "Bomber", "Destroyer", "Submarine", "Cruiser", "Carrier", "Battleship"]
+    result = _simulate_battle(
+        attacker_units=attacker,
+        defender_units=defender,
+        catalog=AA_UNITS,
+        casualty_order=casualty_order,
+        n_sim=n_sim,
+        rounds=rounds,
+        seed=seed,
+    )
+    result.summary = "Axis & Allies " + result.summary
+    return _format_result(result, output)
+
+
+def _coerce_risk_armies(value) -> int:
+    if isinstance(value, int):
+        return value
+    if isinstance(value, dict):
+        if "armies" in value:
+            return int(value["armies"])
+        if len(value) == 1:
+            return int(next(iter(value.values())))
+        return int(sum(int(v) for v in value.values()))
+    raise ValueError("For game='risk', attacker/defender should be int or dict with counts")
+
+
+def combat_odds(
+    attacker,
+    defender,
+    game: str = "ti",
+    rounds: int | None = None,
+    n_sim: int = 10_000,
+    seed: int | None = None,
+    output: str = "summary",
+):
+    """Unified combat-odds entrypoint — routes to the right game automatically.
+
+    Parameters
+    ----------
+    attacker, defender
+        For ``game='risk'``: plain integers (number of armies).
+        For ``game='ti'`` / ``game='axis & allies'``: dicts mapping unit name
+        to count, e.g. ``{'Cruiser': 2, 'Fighter': 4}``.
+    game : str
+        Which game rules to use.  Accepted values (case-insensitive)::
+
+            'risk'
+            'ti' / 'ti4' / 'twilight imperium'
+            'axis & allies' / 'aa' / 'axis and allies'
+
+    rounds : int or None
+        Maximum number of combat rounds before stopping (TI / A&A only).
+        ``None`` means fight to the end.
+    n_sim : int
+        Number of Monte Carlo simulations (TI / A&A only; default 10 000).
+    seed : int or None
+        Random seed for reproducible results (TI / A&A only).
+    output : str
+        ``'summary'``, ``'result'``, ``'dict'``, or ``'dataframe'``.
+
+    Examples
+    --------
+    >>> combat_odds(10, 8, game='risk')
+    'Risk odds - attacker win: ..., avg survivors (A/D): ...'
+
+    >>> combat_odds({'Dreadnought': 1, 'Cruiser': 2}, {'Fighter': 5}, game='ti')
+
+    >>> combat_odds({'Infantry': 4, 'Tank': 2}, {'Infantry': 5}, game='axis & allies')
+    """
+    game_key = game.strip().lower().replace("_", " ")
+    if game_key in {"risk"}:
+        a = _coerce_risk_armies(attacker)
+        d = _coerce_risk_armies(defender)
+        return risk_odds(a, d, output=output)
+    if game_key in {"ti", "ti4", "twilight imperium", "twilight imperium 4"}:
+        return ti_odds(attacker, defender, n_sim=n_sim, rounds=rounds, seed=seed, output=output)
+    if game_key in {"axis & allies", "axis and allies", "aa", "a&a"}:
+        return aa_odds(attacker, defender, n_sim=n_sim, rounds=rounds, seed=seed, output=output)
+    raise ValueError("game must be one of: 'risk', 'ti', 'axis & allies'")
+
+
+def plot_combat(result: CombatResult, show: bool = True):
+    """Plot the outcome probabilities of a combat result as a bar chart.
+
+    Typical usage::
+
+        result = risk_odds(8, 6, output='result')   # or ti_odds / aa_odds
+        plot_combat(result)
+
+    The chart shows three bars — attacker wins, defender wins, and draw — each
+    labelled with its probability.  An annotation in the top-right corner shows
+    the average number of units each side has left at the end of the battle.
+
+    Parameters
+    ----------
+    result : CombatResult
+        The :class:`CombatResult` object returned by any ``*_odds`` function
+        called with ``output='result'``.
+    show : bool
+        If ``True`` (default), call ``plt.show()`` immediately.
+        If ``False``, return the :class:`~matplotlib.figure.Figure` object
+        instead — useful for embedding the chart in a larger figure or saving
+        it to a file::
+
+            fig = plot_combat(result, show=False)
+            fig.savefig('combat.png')
+
+    Returns
+    -------
+    matplotlib.figure.Figure or None
+        The figure when *show* is ``False``, otherwise ``None``.
+    """
+    labels = ["Attacker wins", "Defender wins", "Draw"]
+    values = [result.attacker_wins, result.defender_wins, result.draw]
+    colors = ["#2ecc71", "#e74c3c", "#f1c40f"]
+
+    fig, ax = plt.subplots(figsize=(7.5, 4.5))
+    ax.bar(labels, values, color=colors, edgecolor="white", linewidth=0.7)
+    ax.set_ylim(0, max(1.0, max(values) * 1.2 if values else 1.0))
+    ax.set_ylabel("Probability")
+    ax.set_title("Combat outcome odds", fontweight="bold")
+
+    for i, value in enumerate(values):
+        ax.text(i, value + 0.015, f"{value:.1%}", ha="center", va="bottom", fontsize=10)
+
+    ax.text(
+        0.99,
+        0.97,
+        f"Avg survivors (A/D): {result.avg_att_remaining:.2f}/{result.avg_def_remaining:.2f}",
+        transform=ax.transAxes,
+        ha="right",
+        va="top",
+        fontsize=9,
+        bbox={"boxstyle": "round,pad=0.3", "facecolor": "#f8f9fa", "edgecolor": "#7f8c8d", "alpha": 0.9},
+    )
+
+    fig.tight_layout()
+    if show:
+        plt.show()
+        return None
+    return fig
+
+# To do: 
+# - add support for TI4 tech upgrades?
+# - add support for order of battle phases (e.g. A&A first strike, TI4 anti-fighter barrage, etc.)