Active Effects

Overview

New to v3, the active_effects field is an optional array property of Active Effect objects (described below) that can be added to the following data objects:

• Actions (including embedded actions on items)
• Frame Traits
• Core Powers (active and passive)
• Mech and Pilot Equipment
• Mech Weapons
• Core Bonuses
• Reserves
• Talent Ranks

The Active Effect object is a bundle of optional properties that are handled mechanically by COMP/CON. These are not required, but will allow for more complete automation in COMP/CON's active mode. Not including an active_effect array will not prevent the item from being used, but users will have to manually track effects in the COMP/CON UI.

You'll note that nearly all of the properties of Active Effects are available on actions. Actions should be used when an effect has an activation cost (even if that cost is free). Active Effects should be used when an effect is passive, has no activation cost (but might have activation rules), occurs outside of the activation flow.

Definition

active_effect: {
  "name": string,
  "detail": string,
  "condition"?: string,
  "frequency"?: string,
  "duration"?: EffectDuration,
  "bonus_damage"?: string,
  "damage"?: IDamageData,
  "range"?: IRangeData,
  "add_status"?: IStatusEffectData[],
  "add_resist"?: IResistanceData[],
  "add_special"?: ISpecialStatusData[],
  "remove_special"?: string[],
  "add_other"?: IOtherEffectData[],
  "save"?: IEffectSaveData,
  "attack"?: "melee" | "ranged" | "tech",
  "pilot"?: boolean,
  "mech"?: boolean
}

Required Fields

name

The name of the effect. This string will be displayed in the active effect chip UI and the modal header. This will often, but not necessarily, be the same as the parent item's name.

detail

The description of the effect. Detail strings can include HTML.

Because the Active Effects are only displayed within the Active Mode UI, COMP/CON recommends the following guidelines:

• Use <br> tags to separate distinct sentences or clauses, rather than multiple paragraphs when possible
• Use <b> tags to highlight keywords or important phrases
• Use <i> tags for flavor text or non-mechanical information that is not essential to understanding the action
• The detail field should not include activation cost, frequency, duration, or conditions. These should be handled by the relevant fields of the Active Effect object.
• The detail field should include all rules text, even if it duplicates rules text elsewhere on the item or action.
• The detail field should always be written in the second person present tense ("You gain...", "Your mech...", "When you...").
• The detail field should be written in a way that makes sense when read in isolation, without context of the parent item or action, and should reflect the source text as closely as possible.
• Origin of the effect (item name, action name, etc.) should not be included in the detail field, as this is automatically furnished by COMP/CON on object hydration.

Optional Fields

condition

A string that defines when the effect is active. This is not mechanically handled by COMP/CON but should be used to communicate rules that cannot be automated.

frequency

How often the effect can be activated. This can be one of:

• unlimited (default)
• 1/round
• 1/turn
• 1/scene
• 1/encounter (alias for 1/scene)
• 1/mission

if the effect can be activated multiple times per round, this field should be omitted or set to unlimited.

duration

When the effect expires. This can be one of:

• next_turn_start_self
• next_turn_end_self
• next_turn_start_target
• next_turn_end_target
• round_start_X (where X is the round number the effect expires on)
• round_end_X (where X is the round number the effect expires on)

If the effect does not expire or lasts the entire encounter, this field should be omitted.

bonus_damage

A dice string of the form XdY+Z or XdY or Z, where:

• X is the number of dice (optional, defaults to 1)
• Y is the die type (eg. 6 for a d6, 20 for a d20)
• Z is a flat bonus (optional, defaults to 0)

NB: At the time of this writing this is not used in COMP/CON but exists in data to furnish VTT requirements

damage

An IDamageData object that defines damage dealt by the effect. This should only be used to represent damage that is dealt by the effect itself, not damage modified by the effect or damage from its origin item or action.

Including a damage object here will cause COMP/CON to display a "deal damage" interface within the Active Effect modal.

range

An IRangeData object that defines the range of the effect. This should only be used to represent range of the effect itself, not range modified by the effect or range from its origin item or action.

NB: At the time of this writing this is not used in COMP/CON but exists in data to furnish VTT requirements

add_status

An array of StatusEffect objects referencing Statuses/Conditions that are applied by the effect. These are represented by the following data structure:

IStatusEffectData: {
  "id": string,
  "duration"?: EffectDuration,
  "save"?: 'hull' | 'agi' | 'sys' | 'eng'
  "aoe"?: string | boolean
  "target"?: 'self' | 'ally' | 'enemy'
}

• id (required): The ID of the status effect being applied. This must match the ID of a status effect in core data or a loaded LCP statuses.json.
• duration (optional): When the status effect expires. If omitted, the status effect will last until the end of the encounter or when deactivated by a player. See Effect Duration.
• save (optional): If the status effect allows a saving throw, this defines which attribute is used for the save. If omitted, no save is allowed. See Saving Throws.
• aoe (optional): If the status effect is applied to an area of effect, this defines the area. This can be a string (e.g. "burst 2", "cone 3") or true to indicate an unspecified area of effect. If omitted or false, the status effect is applied to a single target. A truthy value here will cause COMP/CON to display a multiple target selection UI within the Active Effect modal.
• target (optional): Defines the default target selection sorting within the Active Effect modal. This can be self, ally, or enemy. If omitted, defaults to enemy.

Including add_status here will cause COMP/CON to display a "apply status" interface within the Active Effect modal.

add_resist

An array of Resistances/Vulnerabilities/Immunities that are applied by the effect. These are represented by the following data structure:

IResistanceData: {
  "immunity"?: DamageType | StatusType,
  "resistance"?: DamageType,
  "vulnerability"?: DamageType,
  "target"?: 'self' | 'ally' | 'enemy'
}

resistance, vulnerability, and immunity are mutually exclusive; exactly one must be defined per object. These must match one of the following:

• kinetic
• energy
• explosive
• heat
• burn
• aoe (area of effect damage)
• all (all damage types)

immunity can also match any Status or Condition ID defined in core data or a loaded LCP statuses.json.

• target (optional): Defines the default target selection sorting within the Active Effect modal. This can be self, ally, or enemy. If omitted, defaults to self.

Including add_resist here will cause COMP/CON to display a "apply resistance" interface within the Active Effect modal.

add_special

A "Special Status" is a freeform string that represents a special rule or condition that is not otherwise mechanically represented in the data model. These are represented by the following data structure:

ISpecialStatusData: {
  "attribute": string,
  "detail"?: string,
  "target"?: 'self' | 'ally' | 'enemy'
  "duration"?: EffectDuration,
}

attribute (required): The name of the special status being applied. This must fit within a single line in the Active Mode UI sidebar, so should be kept as terse as possible detail (optional): A description of the special status. This cannot include HTML and should be written in the second person present tense ("You gain...", "Your mech...", "When you..."). This will be displayed while hovering over the special status in the Active Mode UI sidebar. target (optional): Defines the default target selection sorting within the Active Effect modal. This can be self, ally, or enemy. If omitted, defaults to enemy. duration (optional): When the special status expires. If omitted, the special status will last until the end of the encounter or when deactivated by a player. See Effect Duration.

Including add_special here will cause COMP/CON to display a "apply special status" interface within the Active Effect modal.

remove_special

An array of strings representing special statuses to be removed by the effect. These strings that must match the attribute field of a target applied special status (case sensitive).

Including remove_special here will cause COMP/CON to display a "remove special status" interface within the Active Effect modal.

add_other

An array of OtherEffect objects representing miscellaneous effects that are not otherwise mechanically represented in the data model. These are represented by the following data structure:

IOtherEffectData: {
  "type": OtherEffectType,
  "val": any,
  "target"?: 'self' | 'ally' | 'enemy'
  "aoe"?: string | boolean,
}

type may be one of the following

Type	Description
overshield	Grants the target {VAL} overshield.
hp	Grants {VAL} HP to the target. Cannot exceed target's maximum HP
repair	Grants {VAL} repair points to the target. Cannot exceed target's max Rep Cap
cover	Assigns cover to the target. VAL must be one of soft

val is dependent on the type. Overshield, HP, and Repair can take a number or a number string that can include bonus syntax, such as {grit} + 4. Cover must be one of the strings soft, hard, or none.

target (optional): Defines the default target selection sorting within the Active Effect modal. This can be self, ally, or enemy. If omitted, defaults to ally.

aoe (optional): If the effect is applied to an area of effect, this defines the area. This can be a string (e.g. "burst 2", "cone 3") or true to indicate an unspecified area of effect. If omitted or false, the effect is applied to a single target. A truthy value here will cause COMP/CON to display a multiple target selection UI within the Active Effect modal.

Including add_other here will cause COMP/CON to display an appropriate interface within the Active Effect modal.

save

An object representing a saving throw that the target must make when the effect is applied. A top-level save will negate the entire effect of the Active Effect. If an effect would eg. negate a status but deal half damage on a save, two save properties on the add_status and damage properties should be used instead. Top-level saves are represented by the following data structure:

IEffectSaveData: {
  "stat": 'hull' | 'agi' | 'sys' | 'eng',
  "aoe"?: string | boolean,
}

save may also be represented by a string that is one of 'hull' | 'agi' | 'sys' | 'eng', which is shorthand for { stat: string, aoe: false }.

stat (required): The attribute used for the saving throw. This must be one of hull, agi, sys, or eng.

aoe (optional): If the effect is applied to an area of effect, this defines the area. This can be a string (e.g. "burst 2", "cone 3") or true to indicate an unspecified area of effect. If omitted or false, the save applies to a single target. A truthy value here will cause COMP/CON to display a multiple target selection UI within the Active Effect modal.

attack

Like save, but populates an alternate attack UI. Value may be one of:

• melee (1d20 + grit +- accuracy vs. target evasion)
• ranged (1d20 + grit +- accuracy - engaged - cover vs. target evasion)
• tech (1d20 + tech vs e-def).

if save and attack are both present on an active effect, save takes precedence.

pilot

Limits this active effect to Pilots only -- these effects will only populate UI if the active mode selection is on the pilot and not their active mech. This is automatically set to true for Pilot Weapons, Pilot Gear, and Pilot Armor.

mech

Like pilot, this is automatically set to true for everything that isn't a piece of pilot equipment. mech can be used to override this, for creating pilot equipment that populates mech-level active effects

Examples

from lancer-data/lib/core_bonuses.json

"active_effects": [
  {
    "name": "Armory-Sculpted Chassis",
    "condition": "You Overcharge.",
    "duration": "next_turn_start_self",
    "detail": "You gain soft cover until the start of your next turn.",
    "add_status": [{ "id": "cover", "val": "soft", "target": "self" }]
  }
]

from lancer-data/lib/frames.json

"active_effects": [
  {
    "name": "Expose Power Cells",
    "condition": "The next time you exceed your Heat Cap this scene",
    "detail": "Clear all heat and vent a burst 3 cloud of burning matter from your mech.<br>Until the start of your next turn, all characters within the affected area count as Invisible to everyone except you, and characters other than you take 2 burn and 2 heat when they start their turn in the area or enter it for the first time in a round. Once this effect ends, characters within the affected area receive soft cover (which you ignore) until the start of your following turn, at which point the cloud disperses.",
    "damage": [
      { "val": "2", "type": "Burn", "aoe": true },
      { "val": "2", "type": "Heat", "aoe": true }
    ],
    "add_status": [
      {
        "id": "invisible",
        "duration": "next_turn_start_self"
      }
    ]
  }
],

from lancer-data/lib/systems.json

"active_effects": [
  {
    "name": "Rapid Burst Jump Jet System",
    "condition": "You Boost.",
    "detail": "You can fly when you Boost; however, you must end the movement on the ground or another solid surface, or else immediately begin falling."
  }
]