HeroQuest Tool

HeroQuest Battle Simulator

Build two opposing warbands, test combat odds, add spells, gear, or consumable items, and run repeatable encounters from simple duels to team fights.

Custom JSON is read locally in your browser. Nothing is uploaded to or saved on the server. Use Save Configuration to download your current setup for later.

Ready the Dice

Run Simulation

Fast setup

Choose how many iterations to run. More iterations give steadier averages, but larger console logs take longer to render.
Pick a starting distance. Adjacent begins in melee range. Short, medium, and long let movement, ranged weapons, and movement spells affect the fight.
Select a result format. Text is best for reading on the page. CSV and TSV are best for copying into a spreadsheet.
Set the log buffer. A smaller buffer updates the console more often. A larger buffer can feel smoother for big runs.
Build each team, then click Run. Console shows every encounter. Results shows the aggregate outcome.

Building teams

Team 1 and Team 2 can each contain one or more combatants. Use the template dropdown at the top of each team to add heroes, monsters, mercenaries, named characters, or a custom entry. The first card stays open. Extra cards start collapsed to keep long rosters easier to scan.

Each card can still be edited after it is added. Change the template to replace that card, edit the name, switch Hero or Minion, adjust stats, pick skills, and choose equipment.

Combatant fields

Hero or Minion decides which shield blocks damage. Heroes defend with white shields. Minions defend with black shields.
Move is a fixed movement value. It is used when Move Dice is 0.
Move Dice rolls red dice for movement. Base game heroes use 2 red dice.
Attack is the number of combat dice rolled for a normal attack.
Defense is the number of combat dice rolled when blocking an attack.
Body is health. A combatant is defeated at 0 Body Points.
Mind is used by effects such as Sleep.

Skills and spells

Templates can preselect proper spell groups, but any combatant can use any listed skill or spell. This is meant for testing unusual matchups and house-rule ideas. Each skill has a priority and simple AI rule, so the simulator chooses usable skills before a normal attack.

Most spells are once per battle for each combatant. Healing spells target the most wounded living ally. Attack spells target the weakest living enemy. Movement spells trigger when the current target is out of range. Hover or focus on the question mark beside a skill to see its source, range, target, and effect.

Equipment

Equipment can change attack dice, defense dice, movement dice, or attack range. For example, a crossbow gives a ranged attack, armor can add defense, and heavier armor can change movement dice. Selected equipment updates the live final stat line on the card, and changed stats are marked beside the affected field.

Items and potions

Items are consumables, not permanent equipment. Use the Qty field to give a combatant one or more copies of an item. For example, setting Potion of Healing to 2 lets that combatant use two healing potions during each simulated encounter. Item quantities reset at the start of every iteration.

Healing items are used when their AI rule sees a useful moment, such as missing Body Points. Heroic Brew is used before an attack when the combatant has a valid target in range. Hover or focus on the question mark beside an item to see its source and effect.

How turns resolve

Each encounter resets both teams to full Body Points, unused skills, starting positions, and clean status effects.
Team 1 acts first each round, followed by Team 2. Combatants act in the order shown in each roster.
The active combatant targets the living enemy with the lowest current Body Points. Ties use roster order.
The simulator can use a valid consumable item, then tries a valid skill or spell. If no action-ending skill is used, the combatant moves toward the target when out of range.
If the target is in range after movement, the combatant may use a before-attack item such as Heroic Brew, then attacks. Attack log lines name the weapon or attack source used.
An encounter ends when one team is defeated or when the round limit is reached.

Reading the output

Console records every encounter, round, movement step, spell use, item use, attack roll, damage result, and winner. Movement lines show the distance to the target, the movement roll when red dice are used, the number of squares moved, and the remaining distance. Attack lines show the weapon or attack source used. Results gives totals across all iterations, including average rounds, team wins, draws, and average Body Points lost.

Clear Console removes the detailed log. Clear Results removes the aggregate table. Reset restores the default Barbarian versus Orc scenario.

Advanced JSON configuration

The simulator data is split into JSON files so new quest packs, homebrew items, and custom spells can be added without rewriting the battle engine. Each file uses a root object with schemaVersion and a named array. Uploaded custom files should follow the same shapes as the built-in files.

Custom JSON files are loaded locally in the visitor's browser. They are not sent to CI4 and are not saved on the server. Use the Add JSON buttons on the page to merge custom character templates, skills, equipment, or items into the current session.

Use stable lowercase IDs with dots or hyphens, such as fire.ball_of_flame or weapon.broadsword. The simulator uses these IDs to connect combatant templates to skills, equipment, and items. If an uploaded entry uses an existing ID, the uploaded entry replaces that entry for the current browser session.

Shared skill and item fields

id is the unique key used by combatants and saved setups.
name is the label shown in the character card and console.
source names the quest pack, expansion, or homebrew set.
timing controls when the entry can be used. Current values are action and before_attack.
target controls target choice. Current values are self, enemy, and ally_or_self.
range is measured in squares. Use 0 for self-only effects.
priority helps the simulator choose between usable options. Higher numbers are tried first.
oncePerBattle marks a skill or spell as single-use for each encounter.
consumesAction tells the turn engine whether normal movement and attacks should stop after use.
ai.useWhen controls basic usage. Current values are always, enemy_alive, has_attack_target, out_of_range, ally_missing_body, self_missing_body, and not_buffed.

Supported effect types

direct_damage_with_combat_save deals damage that can be blocked by combat dice. Use damage, saveDice, and saveSymbol.
status_modifier adds temporary stat or movement changes. Supports attackBonus, defenseBonus, moveMultiplier, ignoreBlocking, ignoreTerrain, duration, and stacking.
miss_turns makes a target miss one or more future turns. Use turns.
sleep_with_mind_save applies Sleep unless a Mind die meets the saveTarget.
heal_body restores Body Points up to the combatant maximum. Use amount.
next_attack_dice makes a special attack with a fixed number of combat dice. Use dice.
extra_attack grants extra normal attacks this turn. Use attacks.
set_attack_dice, add_defense_dice, set_attack_range, and set_movement_dice are equipment modifiers.
blocks_equipment_slot marks a blocked slot in item text. The current UI displays it, but does not yet enforce slot conflicts.

Skill or spell template

{
  "schemaVersion": 1,
  "skills": [
    {
      "id": "homebrew.shadow_bolt",
      "name": "Shadow Bolt",
      "school": "dread",
      "source": "Homebrew Pack",
      "type": "spell",
      "timing": "action",
      "target": "enemy",
      "range": 12,
      "priority": 68,
      "oncePerBattle": true,
      "consumesAction": true,
      "ai": {
        "useWhen": "enemy_alive"
      },
      "effects": [
        {
          "type": "direct_damage_with_combat_save",
          "damage": 2,
          "saveDice": 1,
          "saveSymbol": "whiteShield"
        }
      ]
    }
  ]
}

Equipment template

{
  "schemaVersion": 1,
  "equipment": [
    {
      "id": "weapon.elven_spear",
      "name": "Elven Spear",
      "slot": "weapon",
      "source": "Homebrew Pack",
      "effects": [
        {
          "type": "set_attack_dice",
          "value": 3
        },
        {
          "type": "set_attack_range",
          "value": 2
        }
      ]
    },
    {
      "id": "armor.bronze_helm",
      "name": "Bronze Helm",
      "slot": "head",
      "source": "Homebrew Pack",
      "effects": [
        {
          "type": "add_defense_dice",
          "value": 1
        }
      ]
    }
  ]
}

Consumable item template

{
  "schemaVersion": 1,
  "items": [
    {
      "id": "potion.minor_healing",
      "name": "Minor Healing Potion",
      "source": "Homebrew Pack",
      "type": "potion",
      "timing": "action",
      "target": "self",
      "range": 0,
      "priority": 80,
      "oncePerBattle": false,
      "consumesAction": true,
      "ai": {
        "useWhen": "self_missing_body"
      },
      "effects": [
        {
          "type": "heal_body",
          "amount": 2
        }
      ]
    }
  ]
}

Combatant defaults

Combatants can preselect skills, spell groups, equipment, and item quantities. Spell groups match the school field in skills.json. Item quantities use item IDs as keys.

{
  "schemaVersion": 1,
  "combatants": [
    {
      "id": "homebrew-ranger",
      "name": "Ranger",
      "label": "Ranger",
      "source": "Homebrew Heroes",
      "type": "hero",
      "stats": {
        "move": null,
        "movementDice": 2,
        "movementLabel": "2 red dice",
        "attack": 2,
        "defense": 2,
        "body": 6,
        "mind": 4
      },
      "defaultSkills": [
        "homebrew.shadow_bolt"
      ],
      "defaultSkillGroups": [],
      "defaultEquipment": [
        "weapon.elven_spear"
      ],
      "defaultItems": {
        "potion.minor_healing": 2
      },
      "tags": [
        "hero",
        "homebrew"
      ]
    }
  ]
}

Local uploads and saved configurations

Add Character Templates JSON expects a root combatants array.
Add Skills/Spells JSON expects a root skills array. A root spells array is also accepted and treated as skills.
Add Equipment JSON expects a root equipment array.
Add Items JSON expects a root items array.
Loaded entries appear immediately in existing combatant cards and any new cards added afterward.
Save Configuration downloads a JSON file containing the current controls, teams, selected skills, selected equipment, item quantities, and any custom data currently loaded.
Load Configuration reads that saved file locally and rebuilds the setup. It does not send the file to the server.

Common upload checks

Use valid JSON with double quotes around keys and strings.
Keep IDs unique inside each category.
Use IDs in templates that actually exist in the uploaded skill, equipment, or item data.
Use known effect types until a new effect handler has been added to the JavaScript engine.
Set priorities thoughtfully. A healing item with priority 95 will usually be considered before an attack spell with priority 60.
Test a new file with one custom entry first, then add the rest of the pack.

HeroQuest Battle Simulator

Add JSON and Save Setups

Heroes

Monsters

Run Simulation

Console

Results

HeroQuest Battle Simulator

Run Simulation

Console

Results

Your privacy matters