Created Triggers (markdown)

Triggers.md

@@ -0,0 +1,83 @@
+Triggers are macros that are run when specific situations occur during play. It's an advanced feature that requires a fair bit of user knowledge in the same way that writing a macro would. The main intent is for triggers to handle various odd features that aren't practical to add in a directly integrated way within the system.
+
+# Overview
+Triggers can be set up on any **Action** in their `Triggers` tab. They consist of the following components:
+- `Command`: The macro code of the trigger. All triggers are run in the context of the action, which is to say `this` is the action data within the macro.
+- `Context`: Additional data parameters that are available for use within the macro context.
+- `Returns`: The **optional**, expected structure for the trigger to return. 
+- `Trigger Type`: The specific situation in which the trigger's command will be run. These are enumerated in the next section.
+- `Triggering Actor Type`: Filtering which actors the trigger cares about. This can be `All`, `Self` or `Other`.
+
+An important note is that you should **-not-** perform any resource updates on the actor within the trigger. Resource updates should always be returned from the trigger so that they are synchronized and counted with the action itself.
+
+# Trigger Lifecycle
+Triggers are registered in a custom js Map structure in `game.system.registeredTriggers`. Triggers can only ever by registered if the action they are tied to exists on an Actor. So loose features in the world of compendiums can never be active. Furthermore, trigger registration differs between Characters and other actors.
+### Characters
+Characters in the world always have their triggers registered and active. They are assumed to always be relevant as they're always part of the story.
+### Others
+Adversaries and others only have their triggers registered if they have a token present on the current foundry scene. If they are removed from the scene or if the scene is swapped, they are unregistered to prevent unwanted trigger activation.
+### Scene Environments
+These environments have their triggers registered while the scene they are tied to is active. They are unregistered if the scene switches. 
+(This functionality is not released yet)
+
+# Trigger Types
+## Duality Roll
+This trigger occurs when a duality roll is made.
+
+### Context
+- this: [Action](https://github.com/Foundryborne/daggerheart/blob/main/module/data/action/baseAction.mjs) - The Action (Note that this is only the BaseAction data model. The actual action's data will be one of the many extending action types based on this one). 
+- roll: [DhRoll](https://github.com/Foundryborne/daggerheart/blob/main/module/data/action/baseAction.mjs) - The Roll (DhRoll's main properties of interest should be `roll.config`. The data model for that is best seen in the linked `BaseAction.prepareBaseConfig`),  
+- actor: [DhCharacter](https://github.com/Foundryborne/daggerheart/blob/main/module/data/actor/character.mjs) - The Character performing the roll.
+
+### Returns
+`{ updates: [{ key: string, value: number, clear?: bool }] }`
+The trigger can optionally return an array of resource updates to increase or decrease hope, stress or other actor resources.
+- The key is one of the various resource keys on the actor.
+- The value is the signed amount the resource should be modified
+- Clear is an optional flag that will reset the resource to 0.
+**EX**: `returns { updates: [{
+   key: 'stress',
+   value: -1,
+}]}` 
+
+## Fear Roll
+This trigger occurs when a duality roll is made with Fear.
+
+### Context
+- this: [Action](https://github.com/Foundryborne/daggerheart/blob/main/module/data/action/baseAction.mjs) - The Action 
+- roll: [DhRoll](https://github.com/Foundryborne/daggerheart/blob/main/module/data/action/baseAction.mjs) - The Roll
+- actor: [DhCharacter](https://github.com/Foundryborne/daggerheart/blob/main/module/data/actor/character.mjs) - The Character performing the roll
+
+### Returns
+`{ updates: [{ key: string, value: number, clear?: bool }] }`
+The trigger can optionally return an array of resource updates to increase or decrease hope, stress or other actor resources.
+- The key is one of the various resource keys on the actor.
+- The value is the signed amount the resource should be modified
+- Clear is an optional flag that will reset the resource to 0.
+**EX**: `returns { updates: [{
+   key: 'stress',
+   value: -1,
+}]}` 
+## After Damage Reduction
+This trigger occurs when damage is being dealt to an actor - after all damage reduction has taken place.
+
+### Context
+- this: [Action](https://github.com/Foundryborne/daggerheart/blob/main/module/data/action/baseAction.mjs) - The Action
+- damageUpdates: ResourceUpdates ([{ key: string, value: number}]) - The current resource changes about to happen to the actor 
+- actor: [DhActor](https://github.com/Foundryborne/daggerheart/blob/main/module/data/actor/base.mjs) - The actor being damaged. (Not that this is only the base Actor. The actual actor being damaged will be one of the subtypes)
+
+### Returns
+`{ updates: [{ originActor: this.actor, updates: [{ key, value, total }] }] }`
+The trigger can optionally return an array of resource updates to increase or decrease hope, stress or other actor resources.
+- originActor is the actor the update pertains to. It is probably most commonly `this.actor`
+- The inner updates is the array of resources updates on the originActor
+- The key is one of the various resource keys on the actor.
+- The value is the signed amount the resource should be modified
+- Clear is an optional flag that will reset the resource to 0.
+**EX**: `returns { updates: {
+   originActor: this.actor,
+   updates: [{
+      key: 'hitPoints',
+      value: -1,
+   }]
+}`