Advancement
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:
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.
Ability score improvement allows for improving a character's ability scores by either a fixed amount or based on user choice. When added to a class, it also optionally allows for selecting a feat instead of improving abilities.
The grant items advancement defines a list of features, spells, or other items that are added to the actor at a certain level.
The hit points advancement 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 values 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.
The size advancement stores a list of sizes that can be selected when selecting a race.
The item choice advancement defines a list of features, spells, or other items that the player can choose to add to the actor at a certain level.
The trait advancement grants the character certain traits such as weapon proficiencies, skill expertise, or damage resistances. It presents the player with a list of options if a choice needs to be made.
These advancement types are still under development, links point to the proposal pages for each type:
Details of the hooks that the advancement system provides can be found on the hooks page.
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.
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.
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 -
25- Size -
30- Trait -
40- Grant Items -
50- Item Choice -
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.
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:
{{> "dnd5e.advancement-controls"}}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.
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.
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.
Hooks.once("init", () => {
CONFIG.DND5E.advancementTypes.MyModuleCustom = 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.