Programming d20 Combat: the Core Function

I defined the Combatant object in a previous post. Here is the core function that utilizes it:

function combatantAttacksCombatantOnce(
    Combatant $attacker, 
    Combatant $defender, 
    ProbabilitySet $probabilitySet
): SingleAttackResultIsSuccess|SingleAttackResultIsFailure|SingleAttackResultNotAttack
{
    ...
}

Although this function handles a single attack, all the input parameters contain the data for all attacks. I did this intentionally with an eye on how it will be invoked. The first time combatantAttacksCombatantOnce() is called, it will resolve the first attack. A second call will resolve the second attack, if it is defined.

The function returns one of three possible outcomes: success, failure, or not-attack. This last one is crucial as combatantAttacksCombatantOnce() could be inadvertently called again despite no more defined attacks. Rather than throw an Exception that must be caught, I utilize a defined third value that can simply be checked for or ignored.