Proposal: Multiple Activities on Items

[arbron]

For awhile there has been a need to represent multiple different actions that can be handled by a single item. Some of this is currently hardcoded into the system (aka Normal vs. Versatile damage), some of it has been handled by modules (such as Roll Groups and Items with Spells), and sometimes we just recommend users create two identical items with slightly different properties.

This proposal is a way to add different activities to an item in a way that is easy to use, powerful, and fully extensible by modules. It is build around a system similar to the way that the Advancement system is currently build, a series of pseudo-documents stored within the item representing different things the item can do. Some of these activity types would be things that are handled currently like Attack, Saving Throw, or Healing while others would add new functionality such as Cast a Spell or Change State. Modules could define their own activity types with their own data structures, interface, and chat actions. So my module Arbron's Summoning could define a "Summon" activity type that would behave very similar to the how the module does now, but be fully integrated into the item.

Activity Types

Attack

This would handle all attack actions. It would have configuration defining whether it is a "melee" or "ranged" attack, and whether it is "unarmed", "weapon", or "spell". It could also have additional configuration two assist with automatically determining display name and attack values such as whether it is a "one handed", "two handed", "off hand", or "thrown" attack. Like the existing attack action the user will be able to select an associated ability (or set it to automatic or flat), define a to-hit bonus, and define multiple damage formulas.

The damage formula format would be modified to allow for richer data, including adding custom critical damage to specific damage types rather than to the attack as a whole. It would also potentially support damage conditions, which would allow for a weapon such as a Flame-tongue Longsword to only do its fire damage if it is in the "Burning" state.

Saving Throw

This would allow for defining what ability is used to set the DC and what is needed to save and define multiple damage formulas. What occurs when the save succeeds would be specified in a way that modules like MidiQOL could easily read, but wouldn't force any sort of automation into core.

In addition to damage, it would also be able to specify a condition that is applied to the target when they fail the save.

Ability Check

Allows for defining an ability check against a fixed DC or a challenge against the person using the item. So for example a "Grapple" activity could be created that would be a challenge of the attacker's "Strength (Athletics)" vs. the defenders "Strength (Athletics) or Dexterity (Acrobatics)". This would be an expansion of the current ability to define Ability Checks on an item adding support for associating skills with the check as well as supporting multiple ability or skills in a single activity.

Cast a Spell

This would allow for linking to another spell item that could then be cast through the item. The DC could be set to a fixed value, the base casting level could be changed, and it could use per-spell uses or item uses with support for increasing the number of uses consumed if the spell is upcast.

Change State

An activity that allows for tracking item state and modifying it when used. The state could then be read by other activities and either whole activities or damage parts could be toggled on or off depending on the state. This would allow implementing something like a Flame-tongue Longsword which has a "Burning" state, only doing extra fire damage when it is burning. A module could even tie in to the Change State action to modify the token's light upon activation so the sword wielder illuminates their surroundings automatically.

Utility

Would contain just a message to be displayed in chat when used, as well as emit hooks for other modules to use. This would be useful for things that cannot be easily represented by the system, such as a Staff of the Woodland's "Tree Form" ability.

Activity Flow

The player activates the activity from the character sheet, bringing up the ability activation dialog like it does currently. This initial activation will be responsible for handling resource consumption and upcasting by default, and can have additional controls added by individual activity types (for example, attack activity on a weapon might add the ability to select "One-Handed" or "Two-Handed" modes for versatile weapons).

A potential additional option here is merging in other steps if possible. So attack activities could also display the attack roll being prepared with options to roll with advantage or add bonuses. The limitation of this is it will make it harder for abilities that are activated once but might attack multiple times (e.g. Eldritch Blast or Scorching Ray).

Hooks & Scripts: The activation step would provide all the same books that are currently used during item activation with associated activity scripts for direct customization.

This then creates the chat message with the activation details and additional controls specified by the activity. Data stored here includes links back to the originating activity and any configuration data from the first dialog.

The buttons here would be specified by the activity and can trigger arbitrary actions on the activity document, so for attack there would be an "Attack" button that would trigger the AttackActivity#rollAttack method, with details from the activation chat message passed along.

At this point any additional steps of the workflow is handled by the specific activity, calling any hooks and scripts it defines and calling back to the base activity to trigger any followup activities.

Uses & Resource Consumption

Activities will have their own pool of uses with their own recovery details. When an activity is activated, it can modify any combination of: its own uses, the uses of its item or another item, or any standard actor resource (hit dice, spell slots, etc).

Each consumption target should be able to define how that consumption scales if the item is "upcast". In this case "upcasting" refers to any ability that can consume additional resource, not just for spells. So an ability could be based on consuming hit dice, and for each hit die you expend it increases the damage by 2d6. Base consumption should be set to 1 hit die with a scaling value of 1, and the activity's damage configuration would set the scaling value of 2d6. When activated the player will see the option to scale up the activity in the activation dialog and that information would be stored in the subsequent chat message.

A maximum scaling can also be set, to indicate that an activity can never be scale by more than a certain number of steps.

Follow-up Activities

This is a system for defining, in a standardized way, how one activity leads into another. These follow up activities specified to always occur, allowing multiple activity types to be linked together, or they can be conditional on the result of the first activity. For example, a spell like Ice Knife could have a Saving Throw activity that always follows up the Attack activity, to represent the initial attack with the knife and the explosion of shards. A weapon like the Mace of Disruption would have the initial Attack activity, and a Saving Throw follow up triggered by successful hit.

These follow-ups are not automated, but will display in chat messages with a button allowing for the user to easily activate the next action in the chain. So if you attack with your Mace of Disruption the attack chat message will contain a button for the saving throw with text indicating that this only occurs on a successful hit. It is the up to the user to activate the next step if they deem it necessary. For modules like MidiQOL this would give an abundance of rich data that can be used to improve automation.

Example Items

• Club: A very simple item that only has a single activity for Attack.
• Longsword: Since this allows for one-handed or two-handed attacks, this would contain two Attack activities.
• Spear: Two melee Attack activities for one-handed and two-handed, as well as a third ranged one for when it is thrown.
• Necklace of Fireballs: Contains a single Cast a Spell activity with a fixed DC 15 save. The necklace would have a set of charges and the activity would consume one charge, plus one additional charge for each level upcast.
• Necklace of Prayer Beads: Contains seven Cast a Spell activities, one for each spell with one charge each. The "Cure Wounds" activity would be set to auto-cast at 2nd level. Because the number of beads is rolled, this would need to be customized by the user, removing activities for which they don't have beads and changing the charges for ones they have multiples of.
• Staff of the Woodlands: This would contain a pair of Attack activities for the normal staff attacks, as well as a series of Cast of Spell activities for each of the different spells it contains. It would also contain a Utility activity for "Tree Form".
• Ice Knife: This would have an Attack activity for the initial ranged spell attack, and a Saving Throw activity with a custom radius for the subsequent explosion of ice shards. Because the shards always occur regardless of whether you hit or miss, the Saving Throw activity would be a follow up of the Attack activity that always triggered.
• Dagger of Venom: This base Attack activity and a Change State activity with a single charge per long rest allowing you to poison the blade. When in the "Poisoned" state, the weapon would also have a Saving Throw activity that follows up the Attack activity to do the additional poison damage, which would always follow up with another trigger of the Change State activity reverting it to its non-poisoned state.

Data Structure Details

Base Activity Data

• _id
• type (attack, savingThrow, abilityCheck, etc)
• name - Display name, like advancement this isn't required and will be auto-generated if absent
• img - Icon, also not required
• description - Description of the functionality for this specific activity, helpful for items with lots of different activities to make it clear what this one in particular does
• activation - Any details on how the activity is activated such as activation time & quantity (action, 10 minutes, etc) and condition (for reactions). If not set, this information will be inferred from the containing item if present
• consumption - Any details on resource consumption and scaling. All of this information will be removed from the item itself and be only available here
• uses - Pool of activity-specific uses and how they recover
• scripts - Any activity scripts that are called at specific points in the process to enable enhanced functionality
• followup - Other activities that might be activated if certain conditions are met

Attack Activity Data

• type - Is this a melee or ranged attack and is this a weapon or spell attack (necessary for calculating bonuses, inferred from item if possible)
• ability - Ability used to calculate to hit and damage
• damage - What sort of damage does it do?

Summoning Activity Data

This is a theoretical activity based on Arbron's Summoning

• summons - Array of different potential summoned creatures with UUIDs, counts, and display names
• limitRange - Is the summons restricted by the range of the containing feature?

[RossGosling]

This duplicates an outdated Issue #461, if you could close that ticket

I had been fleshing out a proof-of-concept this week for it, so if at all useful / relevant I have a whole load of info here: PR #1963

[arbron]

This duplicates an outdated Issue #461, if you could close that ticket

I'd say this is a proposal for a specific implementation of #461, so probably not a true duplicate.

[Ikaguia]

It would be nice if this supported 'states' from the actor itself. I.E: Player uses 'xyz smite' spell, actor get's a xyz-smite state that will modify melee weapon attacks I.E²: Player uses Great Weapon Master feature, actor get's a great-weapon-master state that will modify both the attack and damage rolls of melee weapon attacks (-5 to hit, +10 to damage) (automatically removing these states should probably be left for automation modules like midi or dae)

[maxobremer]

With the latest update and reading that this was in the what's next part of the update, I decided to make a little mock up on how it could look. My suggestion would be to either have these actions only be visible when you have the item equipped or have the item kinda open like a drop down menu and show the nested features when the base item/feature is clicked (maybe on a double click have it just roll the base item/feature) and close it whenever you click anywhere else that isn't the base item/feature

[erispre]

I absolutely love this approach! Are there any plans to integrate this with the enchantment system/active effects? I believe that could be very useful. This would allow one item to add activities to another item. One would then be able to fully implement the logic of e.g. the Basic Poison:

• Have two activities: one that has one use and enchants weapons, one that has three uses and enchants ammunition
• The enchantment adds a Saving Throw activity to the target, as a followup to the appropriate Attack activity (in particular, any Attack activity that inflicts slicing or piercing damage) to implement the DC 10 Constitution saving throw, and the additional 1d4 poison damage.
• The enchantment active effect would have a duration so that the added followup activities become unavailable after 10 rounds (60 seconds).

Of course, this requires modifying active effects, and implementing some filtering logic to decide which activities to apply the followup to. But I believe this would be instrumental in implementing items with very complex logic in a universal way.

[Zanderaf]

Yea, 100% would love a way for activities to be added to items via enchantments

[arbron]

Would probably work the same way that "Rider Effects" are handled, where you can define the activity on the enchanting item and then it would be applied to the target item during enchantment.