Register

Build-a-Bonus

An Add-on Module for Foundry Virtual Tabletop

Author: Zhell Project Source: Project URL Version 10 Last Updated 1 week, 1 day ago

2022 Package Jam winner of the 'Most Polished' category and runner-up for 'Best Package'

A module for the Foundry dnd5e system. After installing this module, you can find a 'Build-a-Bonus' application in any actor's Special Traits, in the header of any item, or in the header of any Active Effect. This gives you the ability to apply a bonus to any attack roll, damage roll, saving throw DC, saving throw, or hit die roll, for bonuses that should apply only under specific circumstances. If a bonus is embedded in an item or effect, they transfer with the item/effect if placed on another actor.

Any bonuses you create will automatically be calculated when you perform an attack roll, damage roll, when you use an item that has a saving throw, when you perform a saving throw yourself, or when you roll a hit die. For example:

The Build-a-Bonus has countless options for how or what to apply and when. Scroll down to the bottom for the full list.

How to Use

Open any actor's sheet, then find the Special Traits (on the main tab of the actor sheet if using the core dnd5e sheet) and find the Build-a-Bonus workshop. For an item or effect, click the otter icon in the header. Choose the type of bonus you want to create (attack roll, damage roll, save dc, saving throws, or hit die rolls), then fill out the name, description, and the bonus. Then start narrowing down when and how the bonus should apply, using the available filters and configurations that you can pick and choose from on the left and right.

If you need additional hints, hover over any of the labels to get tooltips. Not all filters are available for each type of bonus. Below is an example using the artificer's Alchemical Savant feature.

Once you are done creating the bonus, save it, and your actor should now have their bonus apply when they perform the relevant roll, given that they match the filters of the bonus.

Bonus Creation and Configuration

This is the full array of configurations, filters, and choices you can make in the Build-a-Bonus. For any fields that support roll data (such as bonuses or comparison fields detailed below), you can use the roll data of the target as well as your own; use roll data as you normally would, and for targets simply prefix with @target.

Required Fields

Name. The human-readable name of the bonus (you can put anything you like here). The ID shown next to it is the unique identifier that the module uses to refer to the bonus, which is also used in several API methods (see below).

Description. A blurb of your choosing describing the bonus.

Bonuses. Depending on the type you choose, Build-a-Bonus can add on top of the value or roll, or even several kinds at once. For example, for attack rolls, you can add bonuses on top of the roll itself, but also increase the critical range and the fumble range. This can be roll data, such as @abilities.int.mod, or just integers or dice expressions.

Aura and Template Configuration

You can set the bonus to act as an aura within a set range or within a template created by an item, and define if the aura should apply to allied targets, enemy targets, or all within range or within the template, and whether it applies to the owner or not.

The bonus is applied when another token actor makes a relevant roll. The module never makes use of token movement to calculate ranges, so the usage of auras and templates is incredibly lightweight.

In the Build-a-Bonus, you can configure a list of effect status ids that prevent the aura from affecting targets and the owner (such as if the source of the aura is dead or unconscious). This blocking feature does not apply to templates, however. A 'status id' is a hidden and unique identifier that any status condition has, and the Keys button in the builder will help you pick it out. The field itself is not validated; if you are able to give an effect a status id of your own choosing, that is respected as well.

Item-Specific Bonuses

Alternatively, for any bonus created on an item (spell, feature, weapon, etc.), if that bonus does not produce a valid aura of any kind, you may toggle it in the Build-a-Bonus to only apply to that item in question. This is good for any unique weapons for example that have certain properties that should apply only to themselves.

Optional Bonuses and Consumption

If the bonus additively affects an attack roll, damage roll, or saving throw (adding a bonus on top), the bonus can be toggled to be optional. Other types of bonuses will reply regardless. The actor will then have the choice when adding the bonus, which is shown in the roll configuration dialog when making an attack roll, damage roll, or saving throw.

If the bonus is not an aura of any kind, is optional as described above, and if the item on which the bonus is embedded has either limited uses or a quantity (such as a quiver of arrows), the bonus can also be configured to consume these when choosing to add the optional bonus. You can configure the minimum required consumption, as well as the maximum if the bonus should scale.

For example, if you create an item with 10 limited uses, a bonus of "+1d6", and configure that the bonus is optional, consumes between 2 and 6 uses when opted into, the actor making the roll can easily add between 2d6 and 6d6 in the roll configuration dialog, and the expended uses are automatically subtracted.

Available Filters

These are the available filters that narrow down if the bonus should apply when making a roll.

Abilities. Filter the bonus to only apply to items that have set the used ability to be one of these types. This respects items set to use defaults, such as spells using the spellcasting ability, or finesse weapons. This is the ability set in the item just below its Action Type in the Details tab.

Actor Conditions. Filter the bonus to only apply if the actor is affected by a specific status condition. This uses the status id string stored in status conditions, as detailed above.

Arbitrary Comparisons. An arbitrary comparison you can use for anything that is not covered in the Build-a-Bonus natively. This supports numbers, roll data, and strings. If you enter strings, you can use the inequalities to match substrings. It will otherwise attempt to determine numeric values after replacing roll data with the roll data of the item and actor. For example, you can have a bonus apply only when the actor is below half health with @attributes.hp.value <= @attributes.hp.max. Unlike other filters, you can add this filter to the builder multiple times.

Attack Types. Filter the bonus to only apply if the item used to perform the roll has an attack roll of that specific kind.

Available Spell Slots. Filter the bonus to apply only if the actor performing the roll has more than the set minimum amount of spell slots available and/or less than the set maximum amount of spell slots available. Not both fields are required.

Base Weapons. Filter the bonus to only apply if the item is a weapon with one of these base weapon types, such as 'battleaxe' or 'blowgun'.

Creature Types. Filter the bonus to only apply if you are targeting an enemy belonging to one of the given creature types, such as 'undead', 'fey', or 'humanoid'.

Custom Scripts. A blank text field for users to write any JavaScript code they like. The script must be synchronous and return true or false. The available variables declared for the script will vary by the roll type, but actor, item, and token are always provided if possible.

Damage Types. Filter the bonus to only apply if the item used to perform the roll has a damage formula with this kind of damage type.

Item Requirements. An available filter to check whether the item should require being equipped or attuned to for the bonus to be active. This filter is only available when creating a bonus on an item that can be either of these things.

Item Types. The type of item the bonus should apply to. For example if you want to increase the save DC globally but only for equipment type items, not spells. This filter is only available for attack roll, damage roll, and save DC bonuses.

Save Ability. Filter the bonus such that it only applies if the DC is set using a specific ability. This respects spellcasting abilities in case the item has its save DC set using 'Spellcasting'.

Saving Throw Types. The type of saving throw the bonus should apply to. Any ability score as well as death saving throws. If you are using the module Concentration Notifier, you can also apply a bonus specifically to saves for maintaining concentration.

Spell Components. Filter the bonus to only apply if the item is a spell that has any one (or all) of the given components.

Spell Levels. Filter the bonus to only apply if the item is a spell and is or was cast at one of the given levels.

Spell Schools. Filter the bonus to only apply if the item is a spell belonging to one of the given spell schools.

Preparation Modes. Filter the bonus to only apply if the spell being used is one of a few particular preparation modes, such as pact magic or innate.

Target Conditions. Filter the bonus to only apply if the target (of the client performing the roll) is affected by a specific status condition. Same details as above.

Weapon Properties. Filter the bonus to only apply if the item is a weapon that has at least one from a set of required weapon properties (if any) while having none of the unfit properties (if any).

API

An API can be accessed at game.modules.get("babonus").api or through the global namespace babonus. The parameter object below refers to an Actor, ActiveEffect, Item, or MeasuredTemplateDocument. The methods are currently:

In addition, if needed, the migration functions used to migrate bonuses in your world to Babonus v10.2.0 exposed in the migration object of the API.

Compatibility

You should not expect this module to work with modules that overhaul or destroy core roll behaviour, particularly WIRE and MIDI. These modules are unsupported, and any compatibility is nothing but a happy accident.

Supported Game Systems

  1. DnD5e

    Latest Version: Version 2.1.5 Last Updated 1 week, 1 day ago

Categories

Available Versions

  1. Version 10.4.6

    Compatible Foundry Versions: 10 - 10.291 Installation Link: Manifest URL Update Notes: Read Notes
  2. Version 10.4.5

    Compatible Foundry Versions: 10 - 10.291 Installation Link: Manifest URL Update Notes: Read Notes
  3. Version 10.4.4

    Compatible Foundry Versions: 10 - 10.291 Installation Link: Manifest URL Update Notes: Read Notes
  4. Version 10.4.3

    Compatible Foundry Versions: 10 - 10.291 Installation Link: Manifest URL Update Notes: Read Notes
  5. Version 10.4.2

    Compatible Foundry Versions: 10 - 10.291 Installation Link: Manifest URL Update Notes: Read Notes
  6. Version 10.4.1

    Compatible Foundry Versions: 10 - 10.291 Installation Link: Manifest URL Update Notes: Read Notes
  7. Version 10.4.0

    Compatible Foundry Versions: 10 - 10.291 Installation Link: Manifest URL Update Notes: Read Notes
  8. Version 10.3.6

    Compatible Foundry Versions: 10 - 10.291 Installation Link: Manifest URL Update Notes: Read Notes
  9. Version 10.3.5

    Compatible Foundry Versions: 10 - 10.291 Installation Link: Manifest URL Update Notes: Read Notes
  10. Version 10.3.4

    Compatible Foundry Versions: 10 - 10.291 Installation Link: Manifest URL Update Notes: Read Notes
  11. Version 10.3.3

    Compatible Foundry Versions: 10 - 10.291 Installation Link: Manifest URL Update Notes: Read Notes
  12. Version 10.3.2

    Compatible Foundry Versions: 10 - 10.291 Installation Link: Manifest URL Update Notes: Read Notes
  13. Version 10.3.1

    Compatible Foundry Versions: 10 - 10.291 Installation Link: Manifest URL Update Notes: Read Notes
  14. Version 10.3.0

    Compatible Foundry Versions: 10 - 10.291 Installation Link: Manifest URL Update Notes: Read Notes
  15. Version 10.2.3

    Compatible Foundry Versions: 10 - 10.291 Installation Link: Manifest URL Update Notes: Read Notes
  16. Version 10.2.2

    Compatible Foundry Versions: 10 - 10.291 Installation Link: Manifest URL Update Notes: Read Notes
  17. Version 10.2.1.2

    Compatible Foundry Versions: 10 - 10.290 Installation Link: Manifest URL Update Notes: Read Notes
  18. Version 10.2.1.1

    Compatible Foundry Versions: 10 - 10.290 Installation Link: Manifest URL Update Notes: Read Notes
  19. Version 10.2.1

    Compatible Foundry Versions: 10 - 10.290 Installation Link: Manifest URL Update Notes: Read Notes
  20. Version 10.2.0.2

    Compatible Foundry Versions: 10 - 10.290 Installation Link: Manifest URL Update Notes: Read Notes
  21. Version 10.2.0.1

    Compatible Foundry Versions: 10 - 10.290 Installation Link: Manifest URL Update Notes: Read Notes
  22. Version 10.2.0

    Compatible Foundry Versions: 10 - 10.290 Installation Link: Manifest URL Update Notes: Read Notes
  23. Version 10.1.0

    Compatible Foundry Versions: 10 - 10.288 Installation Link: Manifest URL Update Notes: Read Notes
  24. Version 10.0.9.2

    Compatible Foundry Versions: 10 - 10.288 Installation Link: Manifest URL Update Notes: Read Notes
  25. Version 10.0.9.1

    Compatible Foundry Versions: 10 - 10.288 Installation Link: Manifest URL Update Notes: Read Notes
  26. Version 10.0.9

    Compatible Foundry Versions: 10 - 10.288 Installation Link: Manifest URL Update Notes: Read Notes
  27. Version 10.0.8.2

    Compatible Foundry Versions: 10 - 10.287 Installation Link: Manifest URL Update Notes: Read Notes
  28. Version 10.0.8.1

    Compatible Foundry Versions: 10 - 10.287 Installation Link: Manifest URL Update Notes: Read Notes
  29. Version 10.0.8

    Compatible Foundry Versions: 10 - 10.287 Installation Link: Manifest URL Update Notes: Read Notes
  30. Version 10.0.7

    Compatible Foundry Versions: 10 - 10.287 Installation Link: Manifest URL Update Notes: Read Notes
  31. Version 10.0.6

    Compatible Foundry Versions: 10 - 10.285 Installation Link: Manifest URL Update Notes: Read Notes
  32. Version 10.0.5

    Compatible Foundry Versions: 10 - 10.285 Installation Link: Manifest URL Update Notes: Read Notes
  33. Version 10.0.4

    Compatible Foundry Versions: 10 - 10.285 Installation Link: Manifest URL Update Notes: Read Notes
  34. Version 10.0.3

    Compatible Foundry Versions: 10 - 10.284 Installation Link: Manifest URL Update Notes: Read Notes
  35. Version 10.0.2

    Compatible Foundry Versions: 10 - 10.283 Installation Link: Manifest URL Update Notes: Read Notes
  36. Version 10.0.1

    Compatible Foundry Versions: 10 - 10.283 Installation Link: Manifest URL Update Notes: Read Notes
  37. Version 10.0.0

    Compatible Foundry Versions: 10 - 10.279 Installation Link: Manifest URL Update Notes: Read Notes