Skip to content

ResolveBattleRound

Resolve one battle round from one declaration per party member able to act.

Full documentation: ResolveBattleRound. Wire type: resolve_battle_round.

Legal session modes: battle

JSON Schema

{
  "$defs": {
    "BattleDeclaration": {
      "description": "One party member's declared action for a battle round.\n\nYou construct these yourself, one for each member who has to declare, and pass them all\nin one `ResolveBattleRound`.\n`EncounterView.declarers` lists the\nmembers who have to declare this round. To offer only choices the session accepts, read\nthese from the same player view:\n\n- Each group's\n  `front_rank`, the members who can\n  attack it in melee this round without moving, and its\n  `member_distance_feet`,\n  each member's distance to it.\n- Each member's\n  `encounter_rate_feet`, how far\n  they can move this round. A member can close on a group and attack it in the same round\n  when their distance to it is at most that rate plus 5'.\n- `immobile` and `reloading` on the encounter view: who can't move, and who can't fire a\n  reloading weapon this round.\n- `advance_feet` on the encounter view,\n  each member's place on the range track. Two members reach each other when their advances\n  differ by 5' or less. A member needs to reach another to hand them an item, to give them a\n  potion to drink, or to touch them with a staff of healing or a touch spell, like *cure\n  light wounds*.\n\nTo check one member's choice against the choices already made for the round, call\n`preview_battle_round` with them.\n\n`action` decides which other fields apply. Leave the others at their defaults.\n\n- `attack` uses `target_group_id` and, optionally, `weapon_id`, `move`, and `back_stab`.\n  With no `weapon_id`, the member attacks with the wielded weapon that suits the attack,\n  or with bare hands when they wield none. Set `move=\"close\"` to close on the group first\n  and attack it in the same round. Set `back_stab` for a thief's melee attack in the free\n  round the party gets when it surprises the monsters.\n- `cast` uses `spell_id`, `spell_mode`, `reversed`, and `targets`. `spell_id` is a spell\n  id, like `\"sleep\"`. `spell_mode` is the key of one of the spell's modes, and `reversed`\n  picks the spell's reversed form. A caster can't move in the round they cast, so leave\n  `move` at `None`.\n- `move` uses the `move` field, which is `close`, `fighting_withdrawal`, or `retreat`. A\n  `close` moves this member toward the group in `target_group_id`, and nobody else. A\n  `fighting_withdrawal` backs this member away slowly, facing the monsters, and a\n  `retreat` turns and runs. When every member in `declarers` makes the same\n  `fighting_withdrawal` or `retreat`, it's a formation move instead: the whole party moves\n  as one body, and every group's distance changes.\n- `use_item` uses `item_id`. The member drinks a potion, reads a scroll, uses a wand,\n  staff, or rod, or throws a splash weapon, like a flask of oil, at `target_group_id`. The\n  staves of power, striking, and wizardry strike the group in `target_group_id` for a\n  charge, and a strike is a melee attack, so only a member in the group's `front_rank` can\n  strike with one. A staff is slow, so the strike comes after both sides' blocks, as an\n  `attack` with the staff does, and it spends the charge then. A use of the staff of power\n  or wizardry with no `target_group_id` is one of their other powers instead, like the cone\n  of cold: it spends a charge, and its `ItemUsedEvent` has the staff's text in `manual` for\n  the referee to rule on. The staff of\n  striking has no other power, so the session refuses a use of it with no `target_group_id`,\n  and the code is `battle.declaration.unknown_group`. To swing a staff without spending a\n  charge, declare an `attack` with it. To give a potion to another member to drink, or to\n  touch another member with a staff of healing, name that member as the one id in\n  `targets`. The two members have to reach each other once the round's moves are made. It's\n  the action of the member who carries the item, and the potion's effect lands on the\n  drinker.\n- `give_item` uses `item_id` and `targets`. The member hands one item, or one unit of a\n  stack, to the member named as the one id in `targets`. It's the giver's action for the\n  round, and it resolves in the party's magic phase with the round's other item uses. The\n  session checks it as `GiveItems` is checked, and the\n  two members have to reach each other once the round's moves are made. The session refuses\n  the `GiveItems` command in a battle.\n- `turn_undead` uses nothing else. It reaches every living monster in the groups that\n  haven't fled when it resolves. Turning resolves with the spells in the round. A hit\n  can't disrupt it, because it's a class ability, not a spell.\n- `hold` does nothing. A member with no legal action declares it, because every member\n  in `declarers` needs a declaration.\n\nOnly `attack` and `move` take a `move`. The session refuses a `cast` that sets one with\n`battle.declaration.cast_cannot_move`, and a `turn_undead`, `use_item`, `give_item`, or\n`hold` that sets one with `battle.declaration.move_not_combinable`.\n\n`gaze_defense` goes with any action. It guards the member against a petrifying gaze, like\na basilisk's or a medusa's, for this round only. Its values are `avert_eyes` and `mirror`.\n\nFor a fight that opens and runs with declared attacks until it ends, see the\n`ResolveBattleRound` example.",
      "properties": {
        "character_id": {
          "title": "Character Id",
          "type": "string",
          "description": "Whose declaration this is, by\n`MemberView.id`. It has to be one of the ids in\n`EncounterView.declarers`, and each of those\nmembers needs a separate declaration in the same round."
        },
        "action": {
          "enum": [
            "attack",
            "cast",
            "turn_undead",
            "move",
            "use_item",
            "give_item",
            "hold"
          ],
          "title": "Action",
          "type": "string",
          "description": "What this member does. `attack` strikes or shoots at a group, after a `close` when the\ndeclaration sets one, `cast` casts a spell, `turn_undead` presents a holy symbol, `move` moves\nthe member toward the monsters or away from them, `use_item` uses a magic item or throws an\nitem, `give_item` hands an item to another member, and `hold` does nothing. This field\ndetermines which other fields apply, and `hold` needs none of them."
        },
        "target_group_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Target Group Id",
          "description": "Which monster group the action is aimed at, by\n`EncounterGroupView.id` from\n`EncounterView.groups`.\n\nThese declarations need it: an `attack`, a `close`, a thrown item, a wand, staff, or rod\nthat strikes or covers an area, and a `cast` of a spell whose area covers creatures. A use of\nthe staff of power or wizardry without it is one of the staff's other powers, not a strike. An area\nspell aimed at a group isn't placed at a point, because the range track has no positions\ninside a group. It covers the group's living members in the order they were spawned, as many\nas its size and the party's rank width allow.\n\nSome spell modes affect a total number of Hit Dice, like *sleep*'s. Their targeting mode is\n`hd_budget`. A `cast` in such a mode can set either this field or `targets`. With this field,\nthe session collects the group's living members in spawn order. When the mode also has an\narea, like *death spell*'s 60' cube, it collects only the members inside the area, as for any\narea spell. The spell then spends its Hit Dice budget on the members it collected, fewest Hit\nDice first.\n\nThe session refuses a group that isn't in the encounter, or one whose\n`EncounterGroupView.fled` is true, with\n`battle.declaration.unknown_group`."
        },
        "weapon_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Weapon Id",
          "description": "Which wielded weapon to attack with, or `None` to have the session choose one.\n\nName a mundane weapon by its catalog id, or a magic weapon by its per-instance id. The weapon\nhas to be equipped already, so equip it with `EquipItem`\nbefore the fight. The session refuses a weapon that's only carried with\n`battle.declaration.weapon_not_wielded`, and a wielded magic item with no weapon stats, like a\nwand, with `battle.declaration.item_unusable`. Every magic staff is a staff, so a member who\nwields one can attack with it. Whether the attack is melee or missile depends on the\nweapon's qualities and the group's distance.\n\nWith `None`, the member attacks with the wielded weapon that suits the attack. The member's\ndistance to the group decides the attack: melee at 5' or less, and missile beyond 5'. It's the\ndistance when the session accepts the round, after the member's own `close` when the\ndeclaration sets one. So a member who closes into reach with a dagger strikes with it, and a\nmember who stays 20' away throws it. The session chooses the weapon this way:\n\n- It looks through the member's wielded items in the order they were equipped. It takes the\n  first one with the `melee` quality for a melee attack, or the `missile` quality for a\n  missile attack.\n- A real weapon comes before an improvised one, whatever order they were equipped in. An\n  improvised weapon is a gear item, like a torch, that has the `melee` quality. So a member\n  who lit a torch and then drew a sword swings the sword. The torch counts only when nothing\n  else suits the attack.\n- For a missile attack, it takes the first weapon whose long range reaches the group. When\n  none reaches, it takes the first missile weapon, and the session refuses the round with\n  `combat.attack.out_of_range` before any of it resolves.\n- A splash weapon, like a flask of oil or a vial of holy water, never counts, because a\n  `use_item` declaration throws it. A wand, or another magic item with no base weapon, has\n  no weapon stats, so it never counts either.\n- A member with no weapon that suits the attack strikes unarmed.\n\nThe session makes this choice once, when it accepts the round. The attack resolves with that\nweapon even when the distance changes before the attack resolves. The attack's\n`AttackRolledEvent` reports the choice in\n`attack_name`: the weapon's name, `\"improvised\"` for a gear item like a torch, or\n`\"unarmed\"`."
        },
        "spell_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Spell Id",
          "description": "Which spell a `cast` declaration casts, by its id in\n`GameSession.effective_spells`: a\nbuilt-in spell (see the\n[spell id index](https://mmacy.github.io/osrlib-python/reference/content-ids/spells/)) or one\nthe adventure bundles. For a `use_item` that reads a scroll, it's which spell to read off the\nscroll, and `None` reads the first one left. The session refuses a `cast` with no spell named\nwith `battle.declaration.missing_spell`."
        },
        "spell_mode": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Spell Mode",
          "description": "Which of the spell's usages to cast, by that usage's\n`SpellMode.key`. A `cast` declaration has to name one, or\nthe session refuses it with `battle.declaration.missing_spell`. A scroll read can leave it `None` to\ntake the spell's first usage."
        },
        "reversed": {
          "default": false,
          "title": "Reversed",
          "type": "boolean",
          "description": "Cast the reversed form of the spell, on the same terms as\n`CastSpell.reversed`: an arcane caster needs a\nreversed copy memorized, and a divine caster chooses the form here."
        },
        "targets": {
          "default": [],
          "items": {
            "type": "string"
          },
          "title": "Targets",
          "type": "array",
          "description": "The spell's targets, named as in\n`CastSpell.targets`. Each one is a member id, a\nmonster id, or, for a spell that affects a place, a cell reference like\n`cell:crypt:1:3,4` that `cell_ref` builds. Leave it empty\nfor a spell whose area covers creatures, which takes `target_group_id` instead.\n\nFor a mode that affects a total number of Hit Dice (`hd_budget`), you can leave this empty\nand set `target_group_id` instead. The session then collects the targets from the group, as\n`target_group_id` describes. When\nyou set both fields, the session uses this one.\n\nThe session refuses an invisible target with `battle.declaration.invisible_target`. It checks\na spell's range against the distance from the caster to each target: to the group of a\ntargeted monster, or to a targeted member, where that member stands once the round's moves\nare made. A touch spell, like *cure light wounds*, reaches 5', so the session refuses it at a\nmember who moves away from the caster this round with `magic.cast.out_of_range`. A touch\nspell on a monster follows the rule for melee, because the OSE SRD's touch needs a melee\nattack roll. The caster has to stand in the party's front rank toward the monster's group, or\nthe session refuses the cast with `battle.declaration.not_in_front_rank`. The monster has to\nbe one of its group's first living monsters, as many as\n`EncounterView.formation_width`, or the\nsession refuses the cast with `combat.attack.out_of_reach`, whose `target` param is the\nmonster's id.\n\nThree other declarations read one id from this field:\n\n- For a `use_item` of a potion, it's the id of the member who drinks it. Leave it empty, or\n  give the carrier's id, and the carrier drinks. The session refuses an id that isn't a party member's, or\n  more than one id, with `items.use.target_not_allowed`, a member who is dead or turned to\n  stone with `items.use.target_cannot_drink`, and a member out of reach with\n  `battle.declaration.member_out_of_reach`. A member who is asleep or paralysed can be given\n  a potion to drink.\n- For a `use_item` of a staff of healing, it's the id of the creature the staff touches.\n  Leave it empty, and the member using it is healed. The session refuses an id that matches no\n  creature, or more than one id, with `items.use.unknown_target`, a creature that's dead or\n  turned to stone with `items.use.target_cannot_be_healed`, and another member out of reach with\n  `battle.declaration.member_out_of_reach`. A monster's group has to stand within 5' of the\n  member, or the use gets `combat.attack.out_of_reach`. A touch on a monster then follows the\n  rule for melee, as a touch spell's does.\n- For a `give_item`, it's the id of the member who takes the item. The session refuses the giver with\n  `exploration.give.same_member`, an id that isn't a party member's, an empty field, or more\n  than one id with `session.command.unknown_member`, a member who can't act with\n  `session.command.member_incapacitated`, and a member out of reach with\n  `battle.declaration.member_out_of_reach`.\n\n`battle.declaration.member_out_of_reach` has the declaring member's id as its `character`\nparam and the named member's id as `target`."
        },
        "move": {
          "anyOf": [
            {
              "enum": [
                "close",
                "fighting_withdrawal",
                "retreat"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Move",
          "description": "Which movement this member makes this round, with a `move` action or, for `close` only, with an\n`attack`.\n\nA battle measures distance on the range track. Each group stands at a distance from the party\nline, where the party stood when the encounter opened. Each member stands at an advance forward\nof that line, in `EncounterView.advance_feet`,\nand starts the battle on it. A member's distance to a group is the group's distance minus their\nadvance. A member moves at their own encounter movement rate,\n`MemberView.encounter_rate_feet`: a third of\ntheir movement rate after encumbrance, doubled by *haste* on that member.\n\n`close` moves this member toward `target_group_id` at their rate, and nobody else. The member\nstops 5' from that group, and stops sooner rather than come within 5' of another group that's\nstill in the fight. A member already within 5' of the group doesn't move.\n\n- With a `move` action, the member only moves.\n- With an `attack`, the member moves in the party's movement step and attacks in the missile\n  or the melee step of the same round. The session judges the attack as if the move had\n  already happened. The member's distance after the move decides whether it's a melee or a\n  missile attack, and a melee attack needs the member to be within 5' of the group and in its\n  front rank after every move the round declares. A member who can't get that close this round\n  gets `combat.attack.out_of_reach`, with that distance as `distance_feet`, and a member who\n  gets close but finds no place left in the front rank gets\n  `battle.declaration.not_in_front_rank`.\n\nThe monsters can act before the party, and the party's missiles and spells come before its\nmelee. A melee attack resolves only if, at the party's melee step, the group still has a living\nmonster the member can see, and the member stands in the group's front rank within 5' of it.\nA group that has started to flee is the one exception to the position check. A member who stood\nwithin 5' of it when the round was accepted still gets the attack, with the bonus against a\nretreating combatant, unless the group runs out of the battle. Otherwise the member makes no\nattack, and the session reports a\n`DeclarationFizzledEvent` at\n`battle.melee.fizzled`, with the group's id as `group_id`. Its `reason` is one of these:\n\n- `battle.declaration.no_target` when the group has no such monster left, for example\n  because the party's archers or casters killed them earlier in the round. The session\n  checks this first, so the member gets it whether or not they closed, and wherever they\n  stand.\n- `combat.attack.out_of_reach` when the member is farther than 5' from the group, or the\n  group ran out of the battle.\n- `battle.declaration.not_in_front_rank` when the member is within 5' but not in its front\n  rank.\n\n`fighting_withdrawal` and `retreat` take a member away from the monsters, with a `move` action.\nA `fighting_withdrawal` backs away at half the member's encounter rate, facing the monsters, and\na `retreat` turns and runs at the full rate. The member makes no attack that round. Each one is\neither a formation move or a move the member makes alone:\n\n- When every member in `declarers` declares the same one, it's a formation move: the whole\n  party moves as one body. That includes a round with only one declarer. The party moves at the\n  slowest living member's encounter rate, halved for a `fighting_withdrawal`. Every group's\n  distance grows by that much, and no member's advance changes, so members who stand apart\n  stay apart. A formation `retreat` ends the battle. If no monster can pursue the party, the\n  party gets away and the encounter closes. Otherwise the session goes back to `encounter` mode\n  with a pursuit, which `PursuitState` describes. The\n  pursuit's starting gap is the smallest distance from any living member to any group that can\n  follow, after the move. So a member who stood forward of the others starts the chase nearest\n  the pursuers. Send\n  `Wait` to run each round of it, or\n  `EngageBattle` to turn and fight.\n- Otherwise, the member moves back alone, and their advance goes down. It can go below zero,\n  behind the line, because the way the party came is clear. When that leaves every member the\n  monsters can see behind the line, the line moves back to the foremost of them at the end of\n  the movement step. Every advance and every group's distance grow by the same amount, so no\n  distance between a member and a group changes, as\n  `BattleState.advance_feet` describes. Any\n  member can fall back alone, wherever they stand, and nobody else moves. It doesn't end the\n  battle, even when it's a `retreat`. Once the member has moved, the members who are now\n  nearest each group form its front rank.\n\nA member who retreats, alone or with the formation, is easier to hit for the whole round,\nwhichever side acts first. Attackers get +2 against them and ignore the retreating member's\nshield.\n\nThe session refuses a `move` action with no `move` with `battle.declaration.missing_move`, a\n`close` at a group that isn't in the encounter or has fled with\n`battle.declaration.unknown_group`, and any move by a member in\n`EncounterView.immobile` with\n`battle.declaration.cannot_move`. An `attack` takes only `close`, and gets\n`battle.declaration.move_not_combinable` with a `fighting_withdrawal` or a `retreat`. A `cast`\nthat sets any move gets `battle.declaration.cast_cannot_move`, because the OSE SRD says \"The\nspell caster cannot move and cast a spell in the same round\". A `turn_undead`, a `use_item`, a\n`give_item`, or a `hold` that sets any move gets `battle.declaration.move_not_combinable`. Each\nof these two codes has the member's id as its `character` param. The session checks for them\nafter the back-stab checks and before the action's own checks.\n[The adaptations register](https://mmacy.github.io/osrlib-python/adaptations/)\ndescribes these rules in full."
        },
        "replacement_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Replacement Id",
          "description": "A member to trade places with in the marching order, for a `fighting_withdrawal` or a\n`retreat` this member makes alone, by `MemberView.id`.\n\nLeave it `None` for every other declaration, a formation move included. A member who falls\nback alone doesn't need to name anyone. Nobody else moves, and the members who are then nearest\neach group form its front rank.\n\nThe trade changes only the marching order. It happens in the party's movement step, right\nafter the withdrawing member's move, and a\n`MemberWithdrewEvent` reports it. Marching order\ndecides who stands in front among members at the same distance from a group who got there in\nthe same round. So when the withdrawing member steps out of a front rank, naming a member who\nstands at the same distance brings that member to the front. The trade doesn't move the named\nmember. A member who stands farther back reaches the front rank only with a `close` of their\nown. The new marching order stays after the battle.\n\nThe named member has to be in\n`EncounterView.declarers`, can't be the\nwithdrawing member, can't be making a `fighting_withdrawal` or a `retreat` of their own, and\ncan't already be named by a withdrawing member earlier in marching order. Otherwise the session\nrefuses the declaration with `battle.declaration.replacement_unavailable`, with the withdrawing\nmember's id as the `character` param and the named id as `replacement`. A declaration in a\nformation move that sets this field gets the same code, because every member is moving.\n\nThe trade happens only when the withdrawing member's move happens, and only while both members\nare alive. A withdrawing member who can no longer move when the movement step comes stays where\nthey are, and the two keep their places in the marching order."
        },
        "item_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Item Id",
          "description": "Which item a `use_item` declaration uses: a magic item's per-instance id for a potion, a\nscroll, a wand, a staff, or a rod, or a mundane item's catalog id for a splash weapon thrown\nat a group, like a flask of oil or a vial of holy water. The session refuses any other\nmundane item, like a torch or a rope, or a magic item that can't be used in battle, with\n`battle.declaration.item_unusable`. To swing a torch, wield it and declare an `attack`.\n\nFor a `give_item` declaration, it's the item to hand over, named as in\n`GiveItems.item_ids`: a mundane item's catalog id,\nwhich hands over one unit of the stack, or a per-instance id for a magic item, a gem, or a piece\nof jewellery. The session refuses an item the giver doesn't carry, or no item, with\n`exploration.item.not_carried`, and a magic item whose curse has been revealed with\n`items.curse.stuck`."
        },
        "gaze_defense": {
          "anyOf": [
            {
              "enum": [
                "avert_eyes",
                "mirror"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Gaze Defense",
          "description": "How this member guards against a petrifying gaze this round, or `None` for no guard.\n\nA petrifying gaze, like a basilisk's or a medusa's, reaches each member who stands in the\ngazer's group's `front_rank`, within 5' of\nit, once a round. The session rolls a saving throw\nversus paralysis for each member it reaches, with no declaration needed. A member who fails\nturns to stone. The OSE SRD's basilisk entry says \"Unless averting eyes or using\na mirror, characters in melee are affected each round\". This field picks one of those two\nguards:\n\n- `avert_eyes`: the gaze passes the member by, and the session gives them the\n  `averted_eyes` condition for the round. The basilisk's and the medusa's entries set the\n  cost: \"-4 penalty to-hit; the basilisk gains a +2 bonus to attack\". Every attack roll the\n  member makes this round takes \u22124, whatever it's aimed at. Each attack a gazing monster\n  makes on the member this round gains +2. Other monsters' attacks gain nothing, because\n  the OSE SRD gives the bonus only to the gazer.\n- `mirror`: the member fights by watching a mirror, and the gaze passes them by. The\n  basilisk's entry says \"The reflection of a basilisk is harmless. Fighting by looking in a\n  mirror incurs a -1 penalty to attack.\" Every attack roll the member makes this round takes\n  \u22121, whatever it's aimed at, and no monster gains a bonus. The member has to carry a\n  `mirror` from the equipment catalog, or the session refuses the declaration with\n  `battle.declaration.no_mirror`. The OSE SRD also says that a gazer that sees its own\n  reflection saves or turns to stone. osrlib doesn't apply that rule. If your game uses it,\n  your game or the referee decides when it applies and resolves the gazer's save.\n\nYou can set a guard with any `action`. It lasts from when the session accepts the round\nuntil the round ends. It makes no random roll and emits no event. The command log records it\nwith the declaration.\n\nA member outside the gazer's group's front rank doesn't need a guard, because the gaze\ndoesn't reach them.\nNeither does a member who can't act and so doesn't declare, because the gaze passes them by.\n\nA basilisk that surprises the party turns its gaze on every member once as the encounter\nopens, before the party can declare anything, as the OSE SRD's \"Characters surprised by a\nbasilisk meet its gaze\" says. No guard protects against that gaze.\n[The adaptations register](https://mmacy.github.io/osrlib-python/adaptations/) describes the\ngaze in full."
        },
        "back_stab": {
          "default": false,
          "title": "Back Stab",
          "type": "boolean",
          "description": "Make this `attack` a back-stab, or leave it `False` for an ordinary attack.\n\nThe OSE SRD's thief entry says \"When attacking an unaware opponent from behind, a thief\nreceives a +4 bonus to hit and doubles any damage dealt.\" osrlib has no facing in battle, so\nthe session reads an unaware opponent from behind as a monster the party surprised, in the\nround it can't act. Set this field only when all of these are true:\n\n- The action is `attack`.\n- The member's class has the `back_stab` ability, as a thief's does.\n- The monsters can't act this round because the party surprised them. That's the party's\n  free round, while\n  `BattleState.monsters_hold_rounds`\n  is above zero. The session reads it when it accepts the round.\n- The attack is a melee attack. The weapon and the member's distance to the group after their\n  `close`, if the declaration sets one, decide that, as\n  `weapon_id` describes.\n\nA thief can close on a group and back-stab in the same round: declare `attack` with\n`move=\"close\"` and `back_stab=True`. The session judges the back-stab at the distance the move\nwill reach. So a thief reaches a group up to their encounter rate plus 5' away. That's 35' for a\nthief in leather armour under the ruleset's default `basic` encumbrance, and 45' for one in no\narmour. *Haste* doubles the rate. A group farther away can't be back-stabbed in the free round,\nbecause the free round is the only round the monsters are unaware.\n\nAn accepted back-stab hits the same monster an ordinary melee attack would. It gets +4 to\nhit, the defender's shield doesn't count, and its damage is doubled. The bonus and the\ndoubling come from the class's `back_stab` ability. Every attack roll the declaration makes\nin the round is a back-stab, even when the monsters win initiative, and the attack's\n`AttackRolledEvent` has `back_stab` set to true, so\nyour game can say so.\n\nThe session refuses a back-stab with the first of these that applies, in this order. Each\nof the four back-stab codes has the member's id as its `character` param.\n\n1. `battle.declaration.back_stab_not_attack`: the action isn't `attack`. The session checks\n   this before any other check on the declaration.\n2. `battle.declaration.back_stab_no_ability`: the member's class has no `back_stab` ability.\n3. `battle.declaration.back_stab_target_aware`: the monsters aren't surprised this round.\n   That's every round of a battle the party didn't open by surprising the monsters, and\n   every round after the free round.\n4. The checks of an ordinary attack on its group and weapon:\n   `battle.declaration.unknown_group`, `battle.declaration.no_target`,\n   `battle.declaration.weapon_not_wielded`, and `battle.declaration.item_unusable`.\n5. `battle.declaration.back_stab_not_melee`: the attack the session would resolve is a\n   missile attack. That's a missile weapon like a bow, or a weapon that's both melee and\n   missile, like a dagger, aimed at a group more than 5' from the member after their\n   `close`.\n6. The rest of an ordinary melee attack's checks, like\n   `battle.declaration.not_in_front_rank` and `combat.attack.out_of_reach`, judged after the\n   round's declared moves.\n\nA declaration that leaves this field `False` resolves exactly as it would without it.\n[The adaptations register](https://mmacy.github.io/osrlib-python/adaptations/) describes the\nback-stab in full."
        }
      },
      "required": [
        "character_id",
        "action"
      ],
      "title": "BattleDeclaration",
      "type": "object"
    }
  },
  "description": "Resolve one battle round from one declaration per party member able to act.\n\nA battle must be underway (see\n`EngageBattle`). Each round, get a new player\nview from `GameSession.view` and read who has\nto declare from\n`EncounterView.declarers`. Construct a\n`BattleDeclaration` for each of them, and\nsend them all in one command. Repeat until the session leaves `battle`. It moves to\n`exploring` when the battle and its encounter end, to `encounter` when a retreat turns\ninto a pursuit, and to `game_over` when every party member is dead or turned to stone.\n\nThe session accepts or refuses a round as a whole. It checks every declaration before\nit resolves any of them, against where the members will stand once the moves the round\ndeclares are made. If a single declaration is bad, the session refuses the command, and\nthe result lists every rejection found. A refused round costs nothing: no random number,\nno game time, and no change to the session. Fix the declarations and send the round\nagain. To check declarations before you send them, call\n`preview_battle_round`, which runs the same\nchecks without playing the round.\n\nModes:\n    `battle`\n\nRejections:\n    The round as a whole:\n\n    - `session.command.wrong_mode` or `battle.none_active` - no battle is underway.\n    - `battle.declaration.roster_mismatch` - the declarations don't name exactly the\n      members in `EncounterView.declarers`, each once. The session checks this first\n      and reports nothing else when it fails.\n    - `battle.declaration.unknown_action` - an `action` the session doesn't\n      recognize. Constructing a `BattleDeclaration` with one already fails validation.\n\n    Each declaration, by its `action`:\n\n    - Any action: `battle.declaration.no_mirror` when the member declares a\n      `gaze_defense` of `mirror` and carries no mirror. The rejection has the member's\n      id as its `character` param.\n    - Move declarations: `battle.declaration.missing_move`,\n      `battle.declaration.unknown_group`, and `battle.declaration.cannot_move`.\n    - A `move` set on an action that can't take it: `battle.declaration.cast_cannot_move`\n      on a `cast`, and `battle.declaration.move_not_combinable` on a `turn_undead`, a\n      `use_item`, a `give_item`, or a `hold`, and on an `attack` with a `fighting_withdrawal`\n      or a `retreat`. Each has the member's id as its `character` param. The session checks\n      for them after the back-stab checks and before the action's own checks.\n    - `battle.declaration.replacement_unavailable` when a member who makes a\n      `fighting_withdrawal` or a `retreat` alone names a member in `replacement_id` who\n      isn't a declarer, is the withdrawing member, is withdrawing too, or was named by a\n      withdrawing member earlier in marching order. It also comes back for a declaration\n      in a formation move that sets `replacement_id`, because every declarer moves with\n      the formation. It has the withdrawing member's id as its `character` param and the\n      named id as `replacement`.\n    - Attack declarations: `battle.declaration.unknown_group`,\n      `battle.declaration.no_target`, `battle.declaration.weapon_not_wielded`,\n      `battle.declaration.item_unusable` for a wielded magic item with no weapon stats,\n      like a wand, `battle.declaration.cannot_move` for an attack that sets `move=\"close\"` by a member\n      who can't move, `battle.declaration.not_in_front_rank` for a melee attack by a\n      member who won't stand in the group's front rank once the round's moves are made,\n      and the checks of `validate_attack`:\n      `combat.attack.out_of_reach`, `combat.attack.out_of_range`,\n      `combat.attack.reload`, `combat.attack.attacker_incapacitated`, and\n      `combat.attack.attacker_blind`. The session judges an attack at the member's own\n      distance to the group, after the member's `close` if the declaration sets one, and\n      `combat.attack.out_of_reach` has that distance as its `distance_feet` param.\n    - A declaration that sets `back_stab`: `battle.declaration.back_stab_not_attack` on\n      any action but `attack`, before any other check. On an attack,\n      `battle.declaration.back_stab_no_ability` and\n      `battle.declaration.back_stab_target_aware` before the attack checks, and\n      `battle.declaration.back_stab_not_melee` after the group and weapon checks and\n      before the melee checks. A back-stab gets only the first of these that applies,\n      and each has the member's id as its `character` param.\n      `BattleDeclaration.back_stab`\n      gives the order in full.\n    - Cast declarations: `battle.declaration.missing_spell`,\n      `battle.declaration.unknown_group`,\n      `battle.declaration.invisible_target`, and the cast checks\n      `magic.cast.unknown_spell`, `magic.cast.silenced_area`,\n      `magic.cast.unknown_mode`, `magic.cast.unknown_target`,\n      `magic.cast.not_memorized`, `magic.cast.caster_incapacitated`,\n      `magic.cast.caster_restrained`, `magic.cast.anti_magic_shell`,\n      `magic.cast.not_reversible`, `magic.cast.target_count`,\n      `magic.cast.target_must_be_creature`, `magic.cast.out_of_range`. The range is measured\n      from the caster to each target's group, or to each target member where they'll stand\n      once the round's moves are made, and a touch spell reaches 5'. A touch spell on a\n      monster also gets `battle.declaration.not_in_front_rank` when the caster isn't in the\n      party's front rank toward the monster's group, and `combat.attack.out_of_reach` when the\n      monster isn't in its group's front rank.\n    - Turn-undead declarations: `magic.turning.not_a_turner` and\n      `magic.turning.caster_incapacitated`. A turning also gets\n      `battle.declaration.no_target` when no living monster is left in any group that\n      hasn't fled. That never refuses a round, because a battle always has a living\n      monster when the round starts. The session checks the turning again just before it\n      resolves, and a turning that gets `no_target` then fails and has no effect.\n    - Item declarations: `battle.declaration.item_unusable`,\n      `battle.declaration.unknown_group`, `battle.declaration.no_target`,\n      `items.use.not_usable`, `items.device.inert`, `items.scroll.spent`,\n      `items.scroll.no_such_spell`, `items.scroll.wrong_caster`,\n      `exploration.action.requires_light`, and `combat.attack.out_of_reach`. A staff's\n      strike for a charge is a melee attack, so it also gets\n      `battle.declaration.not_in_front_rank` when the member won't stand in the group's\n      front rank once the round's moves are made. A scroll read can also get the cast\n      checks on its spell and targets (`magic.cast.unknown_mode`, `magic.cast.unknown_target`,\n      `battle.declaration.invisible_target`, `magic.cast.target_count`,\n      `magic.cast.target_must_be_creature`, `magic.cast.out_of_range`,\n      `magic.cast.caster_incapacitated`, `magic.cast.caster_restrained`,\n      `magic.cast.anti_magic_shell`). A thrown item can also get the `validate_attack` checks\n      listed for attack declarations. A potion given to another member to drink gets\n      `items.use.target_not_allowed`, `items.use.target_cannot_drink`, and\n      `battle.declaration.member_out_of_reach`. A staff of healing's touch gets\n      `items.use.unknown_target`, `items.use.target_cannot_be_healed` on a creature that's dead\n      or turned to stone, and `battle.declaration.member_out_of_reach` on another member. On a\n      monster, it gets the checks of a touch spell on a monster.\n    - Hand-over declarations, `give_item`: `exploration.give.same_member`,\n      `session.command.unknown_member`, `session.command.member_incapacitated`,\n      `items.curse.stuck`, `exploration.item.not_carried`, and\n      `battle.declaration.member_out_of_reach`, in that order.\n\nEvents:\n    Opening the round:\n    `BattleRoundEvent`, a\n    `SpellDeclaredEvent` per declared\n    cast, and\n    `InitiativeRolledEvent`, which reports\n    which side acts first.\n\n    Movement: a `MemberMovedEvent` each time a\n    member moves by themselves, a\n    `MemberWithdrewEvent` each time a member\n    who falls back alone trades places in the marching order with the member they named,\n    and a `GroupMovedEvent` each time a group's\n    distance from the party line changes, when monsters close or run, and when the whole\n    party moves in a formation move.\n\n    Missiles and melee:\n    `AttackRolledEvent`,\n    `DamageDealtEvent`,\n    `DamageAbsorbedEvent`,\n    `HitPointsReportedEvent`,\n    `SavingThrowRolledEvent`,\n    `EquipmentDestroyedEvent`,\n    `LevelDrainedEvent` with\n    `SpellForgottenEvent` when a drain\n    costs a caster prepared spells, and\n    `DeathEvent`.\n\n    Magic: `SpellCastEvent`,\n    `TargetsSelectedEvent` when the\n    engine picks the spell's targets,\n    `SpellDisruptedEvent`,\n    `DeclarationFizzledEvent` when a\n    device use or a turning fails the check the session makes just before it resolves,\n    and at `battle.melee.fizzled` when a melee attack can't resolve when it comes up,\n    because its group has no monster left to strike or because of where the member stands,\n    `MagicDispelledEvent`,\n    `UndeadTurnedEvent`, and the effects\n    a spell leaves behind\n    (`EffectAttachedEvent`,\n    `EffectReleasedEvent`,\n    `ConditionGainedEvent`,\n    `ConditionRemovedEvent`,\n    `HealingAppliedEvent`).\n\n    Items: `ItemsGivenEvent` for a hand-over,\n    after an `EffectReleasedEvent` for each effect\n    of an equipped magic item handed over, and\n    `ItemUsedEvent`, with\n    `ItemIdentifiedEvent` and\n    `CurseRevealedEvent` the first time an\n    item is used.\n\n    Morale: `MoraleCheckedEvent`,\n    `MonsterFledEvent` for a group that\n    fails its morale check and flees, and\n    `MonstersLeftBehindEvent`\n    when a fleeing group leaves behind members who can't move.\n\n    Closing the round: the clock advances one round, and these events report what\n    that changes:\n    `EffectExpiredEvent`,\n    `EffectTickedEvent`,\n    `MonsterRevivedEvent`,\n    `LightEvent`, and\n    `ProvisionsEvent`.\n\n    A round that ends the battle adds a\n    `BattleEndedEvent` and the events of the\n    encounter's end\n    (`EncounterEndedEvent`,\n    `MonsterDefeatedEvent`s, a\n    `LootDroppedEvent` when the slain leave\n    anything on the floor, and, under the immediate XP timing,\n    `XpAwardedEvent` and\n    `CharacterLeveledUpEvent`),\n    or `GameOverEvent` when every party member is\n    dead or turned to stone.\n\nExamples:\n    A fighter and a cleric meet three goblins 30 feet away. Each round, each member in\n    `declarers` plans an attack with a `close`. A member out of reach closes first, and a\n    member already in reach doesn't move and attacks where they stand. When the preview\n    refuses that plan, because the member can't reach the goblins this round or the front\n    rank toward them is full, the member closes without attacking:\n\n    ```python\n    from osrlib.core.alignment import Alignment\n    from osrlib.core.character import CHARACTER_CREATION_STREAM, create_character\n    from osrlib.core.events import Visibility\n    from osrlib.core.rng import RngStreams\n    from osrlib.core.ruleset import Ruleset\n    from osrlib.crawl.adventure import Adventure, TownSpec\n    from osrlib.crawl.battle import preview_battle_round\n    from osrlib.crawl.commands import (\n        BattleDeclaration,\n        EngageBattle,\n        EnterDungeon,\n        ResolveBattleRound,\n        SessionMode,\n        SpawnMonsters,\n    )\n    from osrlib.crawl.dungeon import DungeonSpec, LevelSpec\n    from osrlib.crawl.party import Party\n    from osrlib.crawl.session import GameSession\n\n    stream = RngStreams(master_seed=1).get(CHARACTER_CREATION_STREAM)\n    members = [\n        create_character(\n            name=name,\n            class_id=class_id,\n            alignment=Alignment.LAWFUL,\n            ruleset=Ruleset(),\n            stream=stream,\n            purchases=[(weapon, 1)],\n            equip_ids=[weapon],\n        ).character\n        for name, class_id, weapon in ((\"Hild\", \"fighter\", \"sword\"), (\"Osric\", \"cleric\", \"mace\"))\n    ]\n    level = LevelSpec(number=1, width=1, height=1, entrance=(0, 0))\n    crypt = DungeonSpec(id=\"crypt\", name=\"The Old Crypt\", levels=(level,))\n    adventure = Adventure(name=\"A First Delve\", town=TownSpec(name=\"Threshold\"), dungeons=(crypt,))\n    session = GameSession.new(Party(members=members), adventure, seed=1)\n    session.execute(EnterDungeon(dungeon_id=\"crypt\"))\n    session.execute(SpawnMonsters(template_id=\"goblin\", count_fixed=3, distance_feet=30))\n    if session.mode is SessionMode.ENCOUNTER:  # the goblins didn't attack first\n        session.execute(EngageBattle())\n\n    while session.mode is SessionMode.BATTLE:\n        encounter = session.view(Visibility.PLAYER).encounter\n        target = next(group for group in encounter.groups if group.count and not group.fled)\n        planned = []\n        for member_id in encounter.declarers:\n            # With no weapon_id, the member attacks with the wielded weapon that suits the attack.\n            declaration = BattleDeclaration(\n                character_id=member_id, action=\"attack\", move=\"close\", target_group_id=target.id\n            )\n            if preview_battle_round(session, [*planned, declaration]).rejections[member_id]:\n                declaration = BattleDeclaration(\n                    character_id=member_id, action=\"move\", move=\"close\", target_group_id=target.id\n                )\n            planned.append(declaration)\n        result = session.execute(ResolveBattleRound(declarations=tuple(planned)))\n        if not result.accepted:\n            # Nothing happened. A front end shows the reasons and asks for new declarations.\n            print([rejection.code for rejection in result.rejections])\n            break\n\n    assert session.battle is None  # the fight is over, won or lost\n    ```",
  "properties": {
    "command_type": {
      "const": "resolve_battle_round",
      "default": "resolve_battle_round",
      "title": "Command Type",
      "type": "string",
      "description": "The name that identifies the command class in serialized data. Each command class fixes\nit to a distinct snake_case string, like `\"move_party\"` or `\"open_door\"`, and constructing\nthe class sets it, so you never pass it yourself.\n`parse_command` and the\n`AnyCommand` union use it to rebuild the right class\nfrom a serialized mapping. A class's value never changes between releases."
    },
    "source": {
      "anyOf": [
        {
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Source",
      "description": "Who or what issued the command on whose behalf: an authored trigger or quest id, or the\nname of one of your game's systems. The engine never reads it, so a command with a\n`source` does exactly what the same command without one does. The session logs and\nreplays it with the command, so the log alone shows why something happened. Leave it\n`None` when there's nothing to record. An empty string fails validation when the command\nis constructed."
    },
    "declarations": {
      "default": [],
      "items": {
        "$ref": "#/$defs/BattleDeclaration"
      },
      "title": "Declarations",
      "type": "array",
      "description": "One `BattleDeclaration` for each member in\n`EncounterView.declarers`, and none for\nanyone else. The session refuses any other set of members\nwith `battle.declaration.roster_mismatch`. If a single declaration is bad, the session\nrefuses the whole command, not only that member's part of the round. The order of the declarations doesn't change\nwho acts first, because initiative and the order of the round's phases do. It doesn't change\nwhere anyone moves either, because each member's move is their own."
    }
  },
  "title": "ResolveBattleRound",
  "type": "object"
}