diff --git a/.github/workflows/publish-wiki.yml b/.github/workflows/publish-wiki.yml new file mode 100644 index 0000000000..5578dbd1e4 --- /dev/null +++ b/.github/workflows/publish-wiki.yml @@ -0,0 +1,18 @@ +name: Publish wiki +on: + push: + branches: [master] + paths: + - wiki/** + - .github/workflows/publish-wiki.yml +concurrency: + group: publish-wiki + cancel-in-progress: true +permissions: + contents: write +jobs: + publish-wiki: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: Andrew-Chen-Wang/github-wiki-action@v4 diff --git a/README.md b/README.md index a9766e3c0a..b78010e2ee 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,9 @@ If you wish to manually install the system, you must clone or extract it into th may do this by cloning the repository or downloading a zip archive from the [Releases Page](https://github.com/foundryvtt/dnd5e/releases). +## Frequently Asked Questions +Check the [Wiki](../../wiki) for answers to our most [frequently asked questions](../../wiki/faq) + ## Community Contribution See the [CONTRIBUTING](/CONTRIBUTING.md) file for information about how you can help this project. diff --git a/wiki/Advancement-Type:-Hit-Points.md b/wiki/Advancement-Type:-Hit-Points.md new file mode 100644 index 0000000000..c3c1edbda7 --- /dev/null +++ b/wiki/Advancement-Type:-Hit-Points.md @@ -0,0 +1,46 @@ +![Up to date as of 2.0.3](https://img.shields.io/static/v1?label=dnd5e&message=1.6.3&color=informational) + +The Hit Points advancement type keeps track of hit point choices for each level of a class. This advancement can only be added to classes and each class can only have a single advancement of this type. + +## Configuration + +![Hit Point Configuration](https://github.com/foundryvtt/dnd5e/assets/86370342/f7f21d1c-7160-4139-8f79-5a9f403fba59) + +The Hit Points advancement requires no configuration. It will take a custom title and icon like all other advancement types, but everything else is handled automatically including fetching the hit dice type from the class to which it was added. + +## Usage + +![Hit Points - Usage, Initial Level](https://github.com/foundryvtt/dnd5e/assets/86370342/1b5b6218-2fe0-4468-845c-4b75f3286417) + +Using the Hit Points advancement is almost as simple as setting it up. At the character's first level there are no options to choose because all level one characters get the maximum hit points allowed by their hit dice. The character's constitution modifier will automatically be added with the hit points, so be sure it is set before adding the first class. + +![Hit Points - Usage, Higher Level](https://github.com/foundryvtt/dnd5e/assets/86370342/7e520414-c503-459f-b2c5-510802768c94) + +At higher levels you are given an option between taking the average hit points (half the max + 1) or rolling for hit points. If the "Take Average" option is selected, it will be remembered at future levels but can be changed at any point. + +## API + +The original proposal for the Hit Points advancement can be [found here](https://github.com/foundryvtt/dnd5e/issues/1402). + +### Configuration Schema + +None + +### Value Schema + +The Hit Points advancement stores decisions as an object with an entry for each class level. For the initial character level it will store `max` indicating the maximum hit points were awarded automatically. For other levels it stores either `avg` indicating that the average was taken or a number indicating what was rolled. + +```javascript +{ + 1: "max", + 2: 5, + 3: "avg", + 4: 2 +} +``` + +*Note:* The advancement does not keep track of the constitution modifier added at any given level. + +### Methods + +- `HitPointsAdvancement#total`: Total hit points provided by this advancement across all awarded levels. diff --git a/wiki/Advancement-User-Guide.md b/wiki/Advancement-User-Guide.md new file mode 100644 index 0000000000..b9f26ec463 --- /dev/null +++ b/wiki/Advancement-User-Guide.md @@ -0,0 +1,126 @@ +# Class Items + +1.6 has added the ability to easily define what items should be granted to an actor when it is levelled up in a given class or subclass. This initial release covers a majority of users' needs for streamlining the level up process, however it does not cover all use cases currently, and improvements will be made with subsequent releases. This guide will assist you in creating your own custom classes, as well as provide tips and tricks for navigating the current state of the implementation. + +There is a new option in the System Settings to disable this feature for all players in a world by using the "Disable level-up automation" option in the 5e system settings. To avoid running advancements on an individual character, any advancements should be removed from the class, subclass, or background before it is dropped on the character sheet. + +Note that once the Advancement process has been started, any manual changes to the actor or items added to the actor manually will be reverted once the Advancement workflow is completed. + +# Class Item Updates +The following section will discuss changes made to the Class item type. +## The Details tab +- **Identifier field**: this will allow you to configure the name of the class that can be used to reference it in roll formulas (useful for classes with spaces, or localizing the class to other languages). The class identifier may only contain letters, numbers, hyphens (`-`), and underscores (`_`). +- **Level field**: has been removed, class levels will be managed from the actor sheet, see the second screenshot below. + +![Class Details](https://github.com/foundryvtt/dnd5e/assets/86370342/1dfac30f-cdcb-4d3e-a71a-694f119b0dc7) + +![Class Level Dropdown](https://github.com/foundryvtt/dnd5e/assets/86370342/57d98381-8eaf-40e1-914c-402926bd54f6) + +## The Advancement tab +This is where you will configure the Advancement items for this class. +- Add a new Advancement item with the + button, edit an existing item with the [pen] icon, or delete an existing advancement item with the [trash] icon. + - (Note: deleting one Hit Point or Scale Value advancement item will delete all of that type for the class). +- **Configuration Disabled/Enabled** - This will only display when the class is placed on an actor, it can be toggled to enable or disable making modifications to the advancement items. +- **Modify Choices** - This will only display when the class is placed on an actor, and if Configuration is disabled, this allows a user to change any choices they made for that level. +- Advancement items are sorted within each level alphabetically by type in the following order: Hit Points, Item Grant, Scale Value. + +![Advancement Example](https://github.com/foundryvtt/dnd5e/assets/86370342/4b2dbd4d-01fa-4015-9253-54fc3a682776) + +# Advancement Item Types +There are currently 3 types of Advancement Items that can be added to a Class item: Hit Points, Item Grant, and Scale Value. +All Advancement Items have the following fields: +* **Custom Title**: Choose what you would like the title of this advancement item to display on the Advancement tab. +* **Custom Icon**: Choose an icon to represent this item on the Advancement tab. +* **Class Restriction**: + * All Classes - These items should be granted in any case. + * Original Class Only - Only if this class is the initial class. + * Multiclass Only - Only if this class is chosen as a multiclass. + +![Basic Advancement Configuration](https://github.com/foundryvtt/dnd5e/assets/86370342/e89f215e-8048-4aa1-a051-1632fbcd970f) + +## Hit Points +This advancement item will prompt for the user to Roll for HP or use the average, using the Hit Die noted in the Details tab of the Class item. + +![Hit Points Advancement Configuration](https://github.com/foundryvtt/dnd5e/assets/86370342/36435978-2bb9-4098-b992-c2dcecc1535e) + +## Item Grant +This advancement can grant another item on level up (e.g. Class Features, Equipment). It should not be used for Class Spellcasting as a separate Advancement type is planned for that. It can be used for Racial Spellcasting, however. + +This Advancement Type also contains the following options: +* **Level**: Select the level that these features should be granted at. +* **Optional**: If you want to give the user the option to decline any items granted by this Advancement, check this box, otherwise all items will be granted automatically. +* **Items**: Drag and drop an item into this section for that item to be granted when an actor has reached the appropriate level in this class. + +![Item Grant Advancement Configuration](https://github.com/foundryvtt/dnd5e/assets/86370342/0121c15c-6a3d-4f16-957f-3c9b81b9674d) + +## Scale Value +This can be used to track when features get extra uses (e.g. Wild Shape or Channel Divinity), or the die value of a feature increases (e.g. Sneak Attack or Martial Arts) +This Advancement Type also contains the following options: +* **Scale Type**: This determines the values accepted on the Level sections on the right hand side +* Anything - Allows an arbitrary input including text and numbers + +![Scale Value: Anything](https://github.com/foundryvtt/dnd5e/assets/86370342/3d20ec17-a88d-4398-b60a-bc7dda5a9fc0) + +* Dice - Allows a configuration of number of die and die size (options include d2, d3, d4, d6, d8, d10, d12, and d20). It is recommended for features that can use a variable number of these dice to leave the count blank, and define the number used in the feature, (e.g. `1@scale.monk.martial-arts`, `2@scale.monk.martial-arts`) this will ensure accurate values if used in the damage field and critical damage is rolled. Values that are a consistent number of die can have the value column populated (e.g. Sneak Attack) + +![Scale Value: Dice](https://github.com/foundryvtt/dnd5e/assets/86370342/80e49db5-8128-4edc-b2a9-3277ad7d8144) + +* Numeric - Allows a configuration of a number value in the level options + +![Scale Value: Numeric](https://github.com/foundryvtt/dnd5e/assets/86370342/f687de1a-c92e-4834-ac00-3170451b7129) + +* Distance - Allows for numerical values in the level options, you can choose the units of Feet, Miles, Meters, and Kilometers + +![Scale Value: Distance](https://github.com/foundryvtt/dnd5e/assets/86370342/496109c8-caa7-4185-97f4-bb84ab3a12eb) + +* **Identifier**: Defines the identifier to be used in a formula. +* **1-20**: Used to define the scale value at a given level + +# Managing Class Levels on an Actor +## Adding a Class to an Actor + +https://github.com/foundryvtt/dnd5e/assets/86370342/7c6004a3-d13d-4c5b-8385-160538115345 + + +1. Drag a Class item onto your Actor's Features tab. + - Note: You can cancel the advancement process at any time by clicking the dialog's `X Close` button. +2. You will be prompted to first accept the Hit Points advancement (HP for your original class at level one is always the maximum hit die value plus your Constitution modifier). Click the Next button to advance to the next advancement item. +3. You will then be prompted for any additional advancement items, clicking on the name of the feature will allow you to preview the item that will be added to the actor, if an advancement item is set to optional, the user will be able to select the check box to determine if that item should be added or not. Once the user is ready to advance, click Continue. +4. On any subsequent step you will have a Restart button, this will return you to the beginning of the Advancement process. +5. On the final advancement item you will have a Complete button, click it to apply the changes to your actor. The HP values will adjust, and the items will be added to your character at this time. + +## Leveling Up + +https://github.com/foundryvtt/dnd5e/assets/86370342/ca2669ac-acbb-4b60-a33f-b425a2ca099f + +1. On your Actor's Features tab, find the Level option for your class, click it to open the drop down and select the level you would like to advance to. +2. The appropriate advancement items will be presented to you, use the steps as described above to move through the process. + +## Modifying a previous advancement choice + +https://github.com/foundryvtt/dnd5e/assets/86370342/5e2cae50-1012-4f8e-b2b4-1b25e02798ff + +1. If you made a mistake on a previous level up, such as selecting the wrong item or accidentally deselecting an item, navigate to the Features tab of your actor, and click the Edit icon for their Class item. +2. In the Advancements tab, make sure the Configuration is disabled, then find the level to modify and click the Modify Choices button +3. The system will walk you through all of the advancement items for that level to adjust any choices made for that level. + +## Leveling Down or Removing a Class + +https://github.com/foundryvtt/dnd5e/assets/86370342/ef5a3522-ffcf-4628-ae23-6b3ce0ea4de0 + +1. On your Actor's Features tab, find the Level option for your class, click it and select the level you would like to revert to from the drop down, or click the Trash can icon to completely remove the class or subclass. +2. The system will display a dialog to confirm the change and provide a toggle to remove any advancement items that have been earned up to this level, leaving the box checked will ensure items granted from previous level ups will be removed from the actor. + +# Managing Subclasses +Presently the Subclass advancement type is not available in this release, and will be introduced in a later release. This advancement type will allow the triggering of the advancement workflow if an added item has advancement items attached to it. + +The current recommended process is to manually drag and drop the subclass onto the actor after completing the Advancement process for the given level, which will prompt for the appropriate advancements for the character's level in the parent class. + +https://github.com/foundryvtt/dnd5e/assets/86370342/dc961225-38f6-4272-9595-17a79425d1ca + +# Updating Advancements for an owned Class item +If you are building your own custom class, or modifying an existing class record, once a class is added to an actor it is owned by that actor and is separate from the parent class item in the items sidebar or compendium. For example, if you built a class item with advancements to level 5 and added it to an actor, then later updated the class in the compendium to add advancements to level 10, dragging and dropping that class item onto the actor will not provide the new advancement items to the owned class item. + +You will need to manually update the owned class item with the new advancement items, separate from the compendium class item. + +In an upcoming release, a process to update advancement items from the 'master copy' class item to an owned class item will be added to the system. diff --git a/wiki/Advancement.md b/wiki/Advancement.md new file mode 100644 index 0000000000..4ea0671c78 --- /dev/null +++ b/wiki/Advancement.md @@ -0,0 +1,100 @@ +![Up to date as of 1.6.3](https://img.shields.io/static/v1?label=dnd5e&message=1.6.3&color=informational) + +## Advancement System + +The advancement system is a new system in 5e that allows classes, subclasses, and backgrounds to make modifications to the character when they are added and when a character levels up. + +This page provides an overview of the system and its API. For more specific guides, please visit one of the following pages: + +- [Advancement User Guide](Advancement-User-Guide) +- [Custom Class Example](Custom-Class-Example) + +#### Disabling Advancements + +The advancement system can be disabled for all players in a world by using the `"Disable level-up automation"` option in the 5e system settings. To avoid running advancements on an individual character, any advancements should be removed from the class, subclass, or background before it is dropped on the character sheet. + + +## Advancement Types +### Grant Items +The [[grant items advancement|Advancement-Type:-Grant-Items]] defines a list of features, spells, or other items that are added to the actor at a certain level. + +### Hit Points *(class only)* +The [[hit points advancement|Advancement-Type:-Hit-Points]] keeps track of hit point values for each level of a class. The player will have an option for rolling their hit points or taking the average value. + +### Scale Value *(class or subclass only)* +[[Scale values|Advancement-Type:-Scale-Value]] are formula values that change arbitrarily depending on the level of the class or subclass to which they belong. These values are then made available to be used in roll formulas or elsewhere in the system. A few examples of this include a Bard's inspiration die size, a Rogue's sneak attack value, or a Cleric's channel divinity uses. + +### Proposed Types +These advancement types are still under development, links point to the proposal pages for each type: +- [Ability Score Improvement](https://github.com/foundryvtt/dnd5e/issues/1403) +- [Choose Items](https://github.com/foundryvtt/dnd5e/issues/1401) +- [Equipment](https://github.com/foundryvtt/dnd5e/issues/1871) +- [Subclass](https://github.com/foundryvtt/dnd5e/issues/1407) +- [Trait](https://github.com/foundryvtt/dnd5e/issues/1405) + + +## Advancement Hooks + +Details of the hooks that the advancement system provides can be found on [the hooks page](Hooks#advancement). + + +## Custom Advancement Types + +For module authors who want to expand beyond the advancement types offered in the system, it is a simple task to create and register custom advancement types. + +**Note**: The advancement API is brand new and some changes may be made in upcoming releases of 5e. Be aware that changes to the API in 1.7 may break any custom advancements in future versions. + +### Authoring + +#### `Advancement` Class + +All custom types should subclass the abstract `Advancement` type. This class contains all of the base configuration of the advancement, details on its data structure, and methods for displaying it within the advancement list on items and performing changes to the actor when the advancement is applied. + +##### Ordering + +The `order` value in the `Advancement#metadata` object determines in which order this advancement type appears. Here are the values for built-in types: + +* `10` - Hit Points +* `20` - Ability Score Improvement *(in progress)* +* `30` - Traits *(in progress)* +* `40` - Grant Items +* `50` - Item Choice *(in progress)* +* `60` - Scale Value +* `70` - Subclass *(in progress)* +* `100` - (base advancement class) + +You can set your ordering value between any of these numbers to position your advancement in the list. + +#### `AdvancementConfig` Class + +A subclass of `AdvancementConfig` is needed when a custom advancement type needs to present custom configuration options to the user. If no custom config application is provided, the default config window will be shown to allow for customization of the advancement's base settings. + +Any custom config templates should contain the base advancement controls partial so those controls are always available: + +```html +{{> "systems/dnd5e/templates/advancement/parts/advancement-controls.html"}} +``` + +#### `AdvancementFlow` Class + +The controls presented within the advancement process are defined within a subclass of `AdvancementFlow`. This will always be rendered as a sub-application of the surrounding `AdvancementManager`. + +#### Namespacing + +Custom advancements introduced by modules should be uniquely namespaced for that module to ensure that future advancement types introduced by the system or other modules do not conflict. + +### Registering + +The only step required to register a custom advancement type with 5e is to add the new `Advancement` class to the `game.dnd5e.advancement.types` object. + +```javascript +Hooks.once("init", () => { + game.dnd5e.advancement.types.MyModuleCustomAdvancement = MyModuleCustomAdvancement; +}); +``` + +Advancements are looked up by their type. For example, an advancement of type 'MyModuleCustom' will be loaded by the `MyModuleCustomAdvancement` class, if it can be found. + +Advancement registration should be done during a module's `"init"` or `"setup"` hooks to ensure that the custom type is available during item preparation. + +If at any point a module that introduces a custom advancement is disabled, the system will simply skip preparing that advancement while retaining the underlying data in case the advancement is ever re-added. diff --git a/wiki/Custom-Class-Advancement.md b/wiki/Custom-Class-Advancement.md new file mode 100644 index 0000000000..832dd61ccd --- /dev/null +++ b/wiki/Custom-Class-Advancement.md @@ -0,0 +1,23 @@ +Content that may have been modifying the old `CONFIG.DND5E.classFeatures` object in order to add feature progression for custom classes should instead configure advancements directly on those class items using the new system. Since this data is stored on the class item itself, it can be placed directly inside a compendium and requires no additional script support to plug-into the system. + +### Features +To add features to a class, go to the class' 'Advancement' tab, click the '+' sign to add a new advancement, and select the 'Item Grant' advancement. + +![Item Grant Advancement](https://github.com/foundryvtt/dnd5e/assets/86370342/ae9bba77-f58e-4808-a795-40233cf6cca6) + +Select the level at which these features are gained, then drag-and-drop the feature items to the bottom section of the sheet. + +![Adding features](https://github.com/foundryvtt/dnd5e/assets/86370342/f35c6ca1-fe4b-499d-984d-89ed56be1127) + +**Note:** These items are referenced by UUID so do not use world-level items if you intend this class to be portable between worlds. If you wish to store the class in a compendium to be transferred between worlds, you should also store the features in a compendium (it can be the same one as the class item) and make sure to drag-and-drop from that compendium onto the Item Grant Advancement configuration. + +Repeat this process for each level that features are gained in this class. + +### Subclasses +Classes and subclasses are linked together by their identifiers. In order to create a subclass for a given class, first locate the class identifier. + +![Class Identifier](https://github.com/foundryvtt/dnd5e/assets/86370342/c82fd84c-6c20-4dc3-b3e8-58396bea67f5) + +Then create the new subclass item and input the parent class' identifier. + +![Subclass Identifier](https://github.com/foundryvtt/dnd5e/assets/86370342/eaf86dcd-a1b4-467b-b0b1-cbdd05a412ac) diff --git a/wiki/Dynamic-Module-Art.md b/wiki/Dynamic-Module-Art.md new file mode 100644 index 0000000000..d11307777b --- /dev/null +++ b/wiki/Dynamic-Module-Art.md @@ -0,0 +1,46 @@ +![Up to date as of 2.1.0](https://img.shields.io/static/v1?label=dnd5e&message=2.1.0&color=informational) + +## Configuring a Module +Modules that wish to provide portrait and/or token art for creatures in compendia may do so with special flags in their module manifest. This tells the dnd5e system where to find art to attach to the creature dynamically, that will then be present when the creature is imported into the world. + +### `module.json` +```json +{ + "flags": { + "moduleId": { + "dnd5e-art": "modules/moduleId/map-dnd5e.json", + "dnd5e-art-credit": "Creature Artwork by Foo Bar." + } + } +} +``` + +The `dnd5e-art` key can point to any JSON file available within your module's directory. The file's name is not important, but its contents must be formatted in a specific way, see below. The optional `dnd5e-art-credit` string is dynamically appended to the biographies of each Actor that uses your module's art. + +### `map-dnd5e.json` +```json +{ + "dnd5e.monsters": { + "M4eX4Mu5IHCr3TMf": { + "actor": "modules/moduleId/tokens/BanditP.webp", + "token": "modules/moduleId/tokens/BanditT.webp" + } + }, + "dnd5e.heroes": { + "bzlxBO5km3zCQA8G": { + "actor": "modules/moduleId/tokens/GnomeP.webp", + "token": { + "texture": { + "src": "modules/moduleId/tokens/GnomeT.webp", + "scaleX": 0.8, + "scaleY": 0.8 + } + } + } + } +} +``` + +The top-level object keys in the file must be the fully-qualified pack IDs of the compendia that your module wishes to provide art for. The keys within those pack objects are the IDs of the Actor entries inside that pack. + +The `actor` key will then be used for the Actor's portrait art. The above example demonstrates two ways to provide token art: Either providing a string as the `token` value, or providing an object. If a string is provided, it is treated as the URL to the token's image. If an object is provided, its contents is merged with the Actor's `prototypeToken` object. This allows you to adjust more than just the token's image, including scale, rotation, tint, etc. diff --git a/wiki/FAQ.md b/wiki/FAQ.md new file mode 100644 index 0000000000..379ffd5a00 --- /dev/null +++ b/wiki/FAQ.md @@ -0,0 +1,14 @@ +# Frequently Asked Questions + +## How to Wildshape +To use the built-in Wild Shape feature, open the character sheet of the actor that you would like to transform, then drag the actor they should transform into onto that character sheet (e.g. open the Druid's character sheet and drag the Wolf actor onto it). In the resulting pop-up dialog, click the Wild Shape button. This must be done by the Gamemaster, unless the System Setting "Allow Polymorphing" is enabled, the player must also have "Observer" access to the actors they can transform into and the permissions to "Create New Actors" and "Create New Tokens". To exit Wild Shape, open the actor sheet and click the Restore Transformation button in the sheet's title bar. Because Players cannot have permissions to delete actors, if used by a player the transformed actor will remain, if used by the Gamemaster the transformed actor will be deleted. +Unsoluble has a great video guide available here https://www.youtube.com/watch?v=YjcugG_akk4 +(Note that as of 2.1.0 Unlinked Tokens can use the Restore Transformation feature, this video was recorded prior to version 2.1.0) + +## How to create Spell Scrolls +To create a Spell Scroll, drag a spell item onto an Actor's Inventory tab. The system will create a spell scroll for the level of the spell provided. The system appends the text of the spell into the Spell Scroll items in the Items (SRD) compendium. + +## What are the plans for the upcoming OneDnD release? +There is no decision on this and cannot be one until such a time as OneD&D is officially released for play. Due to potential licensing restrictions, lack of official clarity on what specific changes are being made in the final product, and a whole host of other issues, any speculation on support for One D&D at this point is fruitless. +Most of the changes that we have seen so far are not entirely difficult to implement on your own in the current system, if you would like to implement rules, features, items, spells, or anything else you've seen so far in the playtest, hop in the discord and our helpers there would be happy to assist you. + diff --git a/wiki/Home.md b/wiki/Home.md new file mode 100644 index 0000000000..3c3c279a36 --- /dev/null +++ b/wiki/Home.md @@ -0,0 +1,12 @@ +# Welcome to the DnD5e FoundryVTT Wiki + +- [Advancement Overview](Advancement) + - [Advancement User Guide](Advancement-User-Guide) + - [Custom Class Example](Custom-Class-Example) + - [Grant Item Advancement](Grant-Item-Advancement) + - [Hit Points Advancement](Hit-Points-Advancement) + - [Scale Value Advancement](Scale-Value-Advancement) +- [Dynamic Module Art](Dynamic-Module-Art) +- [Hooks](Hooks) +- [Roll Formulas](Roll-Formulas) +- [Frequently Asked Questions](FAQ) diff --git a/wiki/Hooks.md b/wiki/Hooks.md new file mode 100644 index 0000000000..b9705e0528 --- /dev/null +++ b/wiki/Hooks.md @@ -0,0 +1,428 @@ +![Up to date as of 2.1.0](https://img.shields.io/static/v1?label=dnd5e&message=2.1.0&color=informational) + +## Actor + +### `dnd5e.preRollAbilityTest` + +Fires before an ability test is rolled. Returning `false` will prevent the normal rolling process. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| actor | Actor5e | Actor for which the ability test is being rolled. | +| config | D20RollConfiguration | Configuration data for the pending roll. | +| abilityId | string | ID of the ability being rolled as defined in `DND5E.abilities`. | + +### `dnd5e.rollAbilityTest` + +Fires after an ability test has been rolled. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| actor | Actor5e | Actor for which the ability test has been rolled. | +| roll | D20Roll | The resulting roll. | +| abilityId | string | ID of the ability being rolled as defined in `DND5E.abilities`. | + +### `dnd5e.preRollAbilitySave` + +Fires before an ability save is rolled. Returning `false` will prevent the normal rolling process. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| actor | Actor5e | Actor for which the ability save is being rolled. | +| config | D20RollConfiguration | Configuration data for the pending roll. | +| abilityId | string | ID of the ability being rolled as defined in `DND5E.abilities`. | + +### `dnd5e.rollAbilitySave` + +Fires after an ability save has been rolled. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| actor | Actor5e | Actor for which the ability save has been rolled. | +| roll | D20Roll | The resulting roll. | +| abilityId | string | ID of the ability that was rolled as defined in `DND5E.abilities`. | + +### `dnd5e.preRollDeathSave` + +Fires before a death saving throw is rolled. Returning `false` will prevent the normal rolling process. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| actor | Actor5e | Actor for which the death saving throw is being rolled. | +| config | D20RollConfiguration | Configuration data for the pending roll. | + +### `dnd5e.rollDeathSave` + +Fires after a death saving throw has been rolled, but before updates have been performed. Returning `false` will prevent updates from being performed. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| actor | Actor5e | Actor for which the death saving throw has been rolled. | +| roll | D20Roll | The resulting roll. | +| details | object | | +| details.updates | object | Updates that will be applied to the actor as a result of this save. | +| details.chatString | string | Localizable string displayed in the create chat message. If not set, then no chat message will be displayed. | + +### `dnd5e.preRollSkill` + +Fires before a skill check is rolled. Returning `false` will prevent the normal rolling process. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| actor | Actor5e | Actor for which the skill check is being rolled. | +| config | D20RollConfiguration | Configuration data for the pending roll. | +| skillId | string | ID of the skill being rolled as defined in `DND5E.skills`. | + +### `dnd5e.rollSkill` + +Fires after a skill check has been rolled. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| actor | Actor5e | Actor for which the skill check has been rolled. | +| roll | D20Roll | The resulting roll. | +| skillId | string | ID of the skill that was rolled as defined in `DND5E.skills`. | + +### `dnd5e.preRollHitDie` + +Fires before a hit die is rolled. Returning `false` will prevent the normal rolling process. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| actor | Actor5e | Actor for which the hit die is to be rolled. | +| config | DamageRollConfiguration | Configuration data for the pending roll. | +| denomination | string | Size of hit die to be rolled. | + +### `dnd5e.rollHitDie` + +Fires after a hit die has been rolled, but before updates have been applied. Returning `false` will prevent updates from being performed. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| actor | Actor5e | Actor for which the hit die has been rolled. | +| roll | DamageRoll | The resulting roll. | +| updates | object | | +| updates.actor | object | Updates that will be applied to the actor. | +| updates.class | object | Updates that will be applied to the class. | + +### `dnd5e.preRollClassHitPoints` + +Fires before hit points are rolled for a character's class. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| actor | Actor5e | Actor for which the hit points are being rolled. | +| item | Item5e | The class item whose hit dice will be rolled. | +| rollData | object | | +| rollData.formula | string | The string formula to parse. | +| rollData.data | object | The data object against which to parse attributes within the formula. | +| messageData | object | The data object to use when creating the message. | + +### `dnd5e.rollClasshitPoints` + +Fires after hit points haven been rolled for a character's class. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| actor | Actor5e | Actor for which the hit points have been rolled. | +| roll | Roll | The resulting roll. | + +### `dnd5e.preRollNPCHitPoints` + +Fires before hit points are rolled for an NPC. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| actor | Actor5e | Actor for which the hit points are being rolled. | +| rollData | object | | +| rollData.formula | string | The string formula to parse. | +| rollData.data | object | The data object against which to parse attributes within the formula. | +| messageData | object | The data object to use when creating the message. | + +### `dnd5e.rollNPChitPoints` + +Fires after hit points are rolled for an NPC. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| actor | Actor5e | Actor for which the hit points have been rolled. | +| roll | Roll | The resulting roll. | + +### `dnd5e.preRollInitiative` + +Fires before initiative is rolled for an Actor. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| actor | Actor5e | The Actor that is rolling initiative. | +| roll | D20Roll | The pre-evaluated roll. | + +### `dnd5e.rollInitiative` + +Fires after an Actor has rolled for initiative. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| actor | Actor5e | The Actor that rolled initiative. | +| combatants | Combatant[] | The associated Combatants whose initiative was updated. | + +### `dnd5e.preShortRest` + +Fires before a short rest is started. Returning `false` will prevent the rest from being performed. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| actor | Actor5e | The actor that is being rested. | +| config | RestConfiguration | Configuration options for the rest. | + +### `dnd5e.preLongRest` + +Fires before a long rest is started. Returning `false` will prevent the rest from being performed. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| actor | Actor5e | The actor that is being rested. | +| config | RestConfiguration | Configuration options for the rest. | + +### `dnd5e.preRestCompleted` + +Fires after rest result is calculated, but before any updates are performed. Returning `false` will prevent updates from being performed. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| actor | Actor5e | The actor that is being rested. | +| result | RestResult | Details on the rest to be completed. | + +### `dnd5e.restCompleted` + +Fires when the actor completes a short or long rest. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| actor | Actor5e | The actor that just completed resting. | +| result | RestResult | Details on the completed rest. | + +### `dnd5e.transformActor` + +Fires just before a new actor is created during the transform process. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| actor | Actor5e | The original actor before transformation. | +| target | Actor5e | The target actor being transformed into. | +| data | object | The merged data that will be used to create the newly-transformed actor. | +| options | TransformationOptions | Options that determine how the transformation is performed. | + +## Advancement + +### `dnd5e.preAdvancementManagerRender` + +Fires when an `AdvancementManager` is about to be processed. Returning `false` will prevent the normal rendering process. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| advancementManager | AdvancementManager | The advancement manager about to be rendered. | + +### `dnd5e.preAdvancementManagerComplete` + +| Name | Type | Description | +| ---- | ---- | ----------- | +| advancementManager | AdvancementManager | The advancement manager. | +| actorUpdates | object | Updates to the actor. | +| toCreate | object[] | Items that will be created on the actor. | +| toUpdate | object[] | Items that will be updated on the actor. | +| toDelete | string[] | IDs of items that will be deleted on the actor. | + +### `dnd5e.advancementManagerComplete` + +Fires when an `AdvancementManager` is done modifying an actor. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| advancementManager | AdvancementManager | The advancement manager that just completed. | + +### Document Modification Context + +All of the normal 'pre' and 'post' hook events for document modification when an advancement manager flow finishes (Actor Update, Item Creation, Item Update, and Item Deletion) have a custom flag on them: `isAdvancement`. This allows a hook listener to react differently to advancement-created hook events vs normal ones. + +```js +Hooks.on('updateActor', (actor, change, options) => { + if ( options.isAdvancement ) { + // do something special + } +}) +``` + +## Item + +### `dnd5e.preUseItem` + +Fires before an item usage is configured. Returning `false` will prevent item from being used. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| item | Item5e | Item being used. | +| config | ItemUseConfiguration | Configuration data for the item usage being prepared. | +| options | ItemUseOptions | Additional options used for configuring item usage. | + +### `dnd5e.preItemUsageConsumption` + +Fires before an item's resource consumption has been calculated. Returning `false` will prevent item from being used. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| item | Item5e | Item being used. | +| config | ItemUseConfiguration | Configuration data for the item usage being prepared. | +| options | ItemUseOptions | Additional options used for configuring item usage. | + +### `dnd5e.itemUsageConsumption` + +Fires after an item's resource consumption has been calculated but before any changes have been made. Returning `false` will prevent item from being used. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| item | Item5e | Item being used. | +| config | ItemUseConfiguration | Configuration data for the item usage being prepared. | +| options | ItemUseOptions | Additional options used for configuring item usage. | +| usage | object | | +| usage.actorUpdates | object | Updates that will be applied to the actor. | +| usage.itemUpdates | object | Updates that will be applied to the item being used. | +| usage.resourceUpdates | object[] | Updates that will be applied to other items on the actor. | + +### `dnd5e.preDisplayCard` + +Fires before an item chat card is created. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| item | Item5e | Item for which the chat card is being displayed. | +| chatData | object | Data used to create the chat message. | +| options | ItemUseOptions | Options which configure the display of the item chat card. | + +### `dnd5e.displayCard` + +Fires after an item chat card is created. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| item | Item5e | Item for which the chat card is being displayed. | +| card | ChatMessage\|object | The created ChatMessage instance or ChatMessageData depending on whether options.createMessage was set to `true`. | + +### `dnd5e.useItem` + +Fires when an item is used, after the measured template has been created if one is needed. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| item | Item5e | Item being used. | +| config | ItemUseConfiguration | Configuration data for the roll. | +| options | ItemUseOptions | Additional options for configuring item usage. | + +### `dnd5e.preRollAttack` + +Fires before an attack is rolled for an Item. Returning `false` will prevent the attack from being rolled. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| item | Item5e | Item for which the roll is being performed. | +| config | D20RollConfiguration | Configuration data for the pending roll. | + +### `dnd5e.rollAttack` + +Fires after an attack has been rolled for an Item. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| item | Item5e | Item for which the roll was performed. | +| roll | D20Roll | The resulting roll. | + +### `dnd5e.preRollDamage` + +Fires before a damage is rolled for an Item. Returning `false` will prevent the damage from being rolled. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| item | Item5e | Item for which the roll is being performed. | +| config | DamageRollConfiguration | Configuration data for the pending roll. | + +### `dnd5e.rollDamage` + +Fires after a damage has been rolled for an Item. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| item | Item5e | Item for which the roll was performed. | +| roll | DamageRoll | The resulting roll. | + +### `dnd5e.preRollFormula` + +Fires before the other formula is rolled for an Item. Returning `false` will prevent the formula from being rolled. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| item | Item5e | Item for which the roll is being performed. | +| config | object | Configuration data for the pending roll. | +| config.formula | string | Formula that will be rolled. | +| config.data | object | Data used when evaluating the roll. | +| config.chatMessage | boolean | Should a chat message be created for this roll? | + +### `dnd5e.rollFormula` + +Fires after the other formula has been rolled for an Item. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| item | Item5e | Item for which the roll was performed. | +| roll | Roll | The resulting roll. | + +### `dnd5e.preRollRecharge` + +Fires before the Item is rolled to recharge. Returning `false` will prevent the recharge from being rolled. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| item | Item5e | Item for which the roll is being performed. | +| config | object | Configuration data for the pending roll. | +| config.formula | string | Formula that will be used to roll the recharge. | +| config.data | object | Data used when evaluating the roll.| +| config.target | number | Total required to be considered recharged. | +| config.chatMessage | boolean | Should a chat message be created for this roll? | + +### `dnd5e.rollRecharge` + +Fires after the Item has rolled to recharge, but before any changes have been performed. Returning `false` will prevent the changes from being performed. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| item | Item5e | Item for which the roll was performed. | +| roll | Roll | The resulting roll. | + +### `dnd5e.preRollToolCheck` + +Fires before a tool check is rolled for an Item. Returning `false` will prevent the tool check from being rolled. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| item | Item5e | Item for which the roll is being performed. | +| config | D20RollConfiguration | Configuration data for the pending roll. | + +### `dnd5e.rollToolCheck` + +Fires after a tool check has been rolled for an Item. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| item | Item5e | Item for which the roll was performed. | +| roll | D20Roll | The resulting roll. | + +## Item Sheet + +### `dnd5e.dropItemSheetData` + +Fires when some useful data is dropped onto an `ItemSheet5e`. Returning `false` will prevent the normal drop handling. + +| Name | Type | Description | +| ---- | ---- | ----------- | +| item | Item5e | The Item5e. | +| sheet | ItemShee5e | The ItemSheet5e application. | +| data | object | The data that has been dropped onto the sheet. | diff --git a/wiki/Roll-Formulas.md b/wiki/Roll-Formulas.md new file mode 100644 index 0000000000..9f54a608cb --- /dev/null +++ b/wiki/Roll-Formulas.md @@ -0,0 +1,319 @@ +![Up to date as of 2.1.2](https://img.shields.io/static/v1?label=dnd5e&message=2.1.2&color=informational) + +## Actor Properties + +### Abilities + +`@abilities.str` - Strength + +`@abilities.dex` - Dexterity + +`@abilities.con` - Constitution + +`@abilities.int` - Intelligence + +`@abilities.wis` - Wisdom + +`@abilities.cha` - Charisma + +***Note:** Replace the `*` in the following formulas with the three-letter code from above.* + +`@abilities.*.value` - Ability score + +`@abilities.*.mod` - Base ability modifier + +`@abilities.*.dc` - Feature DC based on this ability, equals `8 + modifier` + +`@abilities.*.bonuses.check` - Formula for ability-specific check bonuses (applies to generic ability checks and saves that use this ability) + +`@abilities.*.checkBonus` - Flat ability check bonus, combining ability-specific bonuses with global check bonuses + +`@abilities.*.checkProf` - Ability check [proficiency](Roll-Formulas#proficiency) details + +`@abilities.*.save` - Flat ability save modifier (without any dice bonuses) + +`@abilities.*.bonuses.save` - Formula for ability-specific saving throw bonuses + +`@abilities.*.saveBonus` - Flat ability save bonus, combining ability-specific bonuses with global save bonuses + +`@abilities.*.saveProf` - Ability save [proficiency](Roll-Formulas#proficiency) details + + +### Attributes + +#### Armor Class + +`@attributes.ac.calc` - Calculation mode that its used for determining `attributes.ac.base` + +`@attributes.ac.formula` - Custom formula that will be used to determine `attributes.ac.base` if `calc` is set to `custom` + +`@attributes.ac.flat` - Value that will be used as final `value` if `flat` calculation is set, or as `base` with `natural` calculation + +`@attributes.ac.armor` - Base value of equipped armor or `10` if no armor is worn + +`@attributes.ac.dex` - Actor's dexterity modifier capped by any max dexterity allowed by equipped armor + +`@attributes.ac.base` - Base AC, result of the selected AC formula + +`@attributes.ac.shield` - AC bonus provided by an equipped shield + +`@attributes.ac.bonus` - Additional bonuses to AC provided by spells or magic items + +`@attributes.ac.cover` - Any cover effects for the actor, must be set by active effects or modules + +`@attributes.ac.value` - Final AC value, result of adding `ac.base + ac.shield + ac.bonus + ac.cover` + + +#### Attunement + +`@attributes.attunement.value` - Number of currently attuned items + +`@attributes.attunement.max` - Maximum number of attunement slots + +#### Death Saves + +`@attributes.death.success` & `.failure` - Death save successes & failures + +#### Encumbrance + + +#### Hit Points + +`@attributes.hp.min` & `.max` - Minimum & maximum hit points (not including any changes from temporary max) + +`@attributes.hp.value` - Current hit points (not including temp) + +`@attributes.hp.temp` - Temporary hit points + +`@attributes.hp.tempmax` - Temporary changes to max hit points + +#### Initiative + +`@attributes.init.mod` - Actor's base initiative modifier + +`@attributes.init.prof` - Initiative [proficiency](Roll-Formulas#proficiency) details + +`@attributes.init.bonus` - Any extra arbitrary bonus (active effects or the initiative config window) + +`@attributes.init.total` - Final initiative modifier + +#### Movement + +`@attributes.movement.burrow` - + +`@attributes.movement.climb` - + +`@attributes.movement.fly` - + +`@attributes.movement.swim` - + +`@attributes.movement.walk` - + +`@attributes.movement.units` - + +`@attributes.movement.hover` - + + +#### Senses + +`@attributes.senses.blindsight` - + +`@attributes.senses.darkvision` - + +`@attributes.senses.tremorsense` - + +`@attributes.senses.truesight` - + +`@attributes.senses.units` - + +`@attributes.senses.special` - + + +#### Other Attributes + +`@attributes.exhaustion` - Current exhaustion level + +`@attributes.hd` - Currently available hit dice + +`@attributes.inspiration` - Whether the actor has inspiration + +`@attributes.prof` - Base, numerical proficiency value (does not reflect options like Proficiency Dice) + +`@attributes.spellcasting` - Spellcasting ability (three-letter code, not the modifier) + +`@attributes.spelldc` - Spell save DC based on the selected spellcasting ability + +`@attributes.spellmod` - Base ability modifier for the actor's selected spellcasting ability + +### Bonuses + +#### Ability + +`@bonuses.abilities.check` - Global ability check bonuses (added to base ability checks and skills checks) + +`@bonuses.abilities.save` - Global ability save bonuses + +`@bonuses.abilities.skill` - Global skill check bonuses + +#### Attacks + +`@bonuses.msak` - Melee spell attack + +`@bonuses.mwak` - Melee weapon attack + +`@bonuses.rsak` - Ranged spell attack + +`@bonuses.rwak` - Ranged weapon attack + +***Note:** Replace the `*` in the following formulas with the four-letter code from above.* + +`@bonuses.*.attack` - Global bonus to attack rolls + +`@bonuses.*.damage` - Global bonus to damage rolls + +#### Spell + +`@bonuses.spell.dc` - Global bonus to spell save DC + + +### Classes + +***Note:** Replace the `*` in the following formulas with `identifier` specified on the class item.* + +`@classes.*.levels` - + +`@classes.*.hitDice` - + +`@classes.*.hitDiceUsed` - + +`@classes.*.isOriginalClass` - + +`@classes.*.spellcasting.progression` - + +`@classes.*.spellcasting.ability` - + + +### Currency + +`@bonuses.currency.pp`, `.gp`, `.sp`, `.ep`, `.cp` - Amount of each type of current held by actor + + +### Details + +`@details.level` - Overall character level + +`@details.xp.value` - Actor's total XP earned + +`@details.xp.min` & `.max` - XP range for the actor's current level + +`@details.xp.pct` - Progress towards the next level + + +### Proficiency + +`@prof` - Actor proficiency + +`@prof.term` - Either flat proficiency value or dice, depending on whether `"Proficiency Dice"` settings is set in system settings + +`@prof.flat` - Flat proficiency value, regardless of settings + +`@prof.dice` - Dice-based proficiency value, regardless of settings + + +### Resources + +`@resources.primary`, `.secondary`, `.tertiary` - Three resource slots + +***Note:** Replace the `*` in the following formulas with one of the slots above.* + +`@resources.*.value` - + +`@resources.*.max` - + +`@resources.*.sr` - + +`@resources.*.lr` - + +`@resources.*.label` - + + +### Scale + + +### Skills + +`@skills.acr` - Acrobatics + +`@skills.ani` - Animal Handling + +`@skills.arc` - Arcana + +`@skills.ath` - Athletics + +`@skills.dec` - Deception + +`@skills.his` - History + +`@skills.ins` - Insight + +`@skills.itm` - Intimidation + +`@skills.inv` - Investigation + +`@skills.med` - Medicine + +`@skills.nat` - Nature + +`@skills.prc` - Perception + +`@skills.prf` - Performance + +`@skills.per` - Persuasion + +`@skills.rel` - Religion + +`@skills.stl` - Slight of Hand + +`@skills.ste` - Stealth + +`@skills.sur` - Survival + +***Note:** Replace the `*` in the following formulas with the three-letter code from above.* + +`@skills.*.ability` - Three letter code for the ability associated with this skill by default + +`@skills.*.mod` - Ability modifier from the default ability + +`@skills.*.prof` - Skill [proficiency](Roll-Formulas#proficiency) details + +`@skills.*.bonuses.check` - Bonus formula for this skill's modifier + +`@skills.*.bonus` - Flat skill check bonus, combining skill-specific bonus, ability check bonus, and global skill bonus + +`@skills.*.total` - Total skill check modifier (without any dice bonuses) + +`@skills.*.bonuses.passive` - Bonus formula for this skill's passive score (cannot contain dice) + +`@skills.*.passive` - Passive skill value equalling `10 + total + bonuses.passive` + + +### Spells + +`@spells.spell1`, `.spell2`, `.spell3`, etc. - Normal spell slot levels + +`@spells.pact` - Pact slots + +***Note:** Replace the `*` in the following formulas with one of the spell slots above.* + +`@spells.*.value` - The currently available slots at this level + +`@spells.*.max` - Maximum number of slots at this level + +`@spells.*.override` - This value overrides the calculated `max` slots + +`@spells.*.level` - Spell slot level (for pact slots only) + + +### Traits + +`@traits.size` - Actor size