Creating a Combat Effect

What is a Combat Effect

Combat Effects are integral to designing comprehensive Abilities.

Types of Combat Effects

• AddPhaseEffect
  • When triggered, this effect adds a specific phase to the current turn.
• RemovePhaseEffect
  • When triggered, this effect removes a specific phase from the current turn.
• DispelCombatEffect
  • When triggered, this effect removes all other Effects of a given class.
• FlatResourceEffect
  • When triggered, this effect increases or decreases a combat resource by the given amount
• LevelResourceEffect
  • When triggered, this effect increases or decreases a combat resource proportional to the player's level
• ProportionalResourceEffect
  • When triggered, this effect increases or decreases a combat resource by a percentage of its maximum value

Combat Effect Properties

Required Properties

• class_name (String)
  • The type of Combat Effect you're creating. Note that you may not include spaces in this field. For example, DispelCombatEffect.
• properties (Array[String])
  • An array of strings. The contents of this array will vary from Combat Effect to Combat Effect. For more information, refer to the wiki entry of the specific Combat Effect you'd like to implement.

Optional Properties

• duration (int) (1)
  • The number of turns that the Combat Effect should trigger before being removed.
  • To make a Combat Effect last forever, set this value to -1.
• trigger_phase (String) (ACTION)
  • The phase in which this Effect should trigger on its owner's turn.
  • Available trigger_phase options are: TURN_START, PRE_ACTION, ACTION, POST_ACTION, END_OF_TURN
• trigger_message (String) ("")
  • The message to be printed whenever this effect triggers
• cleanup_message (String) ("")
  • The message to be printed whenever this effect reaches its maximum number of triggers.

Notes

• These fields may appear in any order within the actual JSON object.
• The value adjacent to each listed field is its default value and is applied whenever that field is omitted.

Examples

Proportional Resource Effect

If you'd like to increase an entity's Health by 10% for three turns, you would use a Proportional Resource Effect.

  {
      "class_name" : "ProportionalResourceEffect",
      "duration"  : 3,
      "trigger_phase" : "PRE_ACTION",
      "trigger_message" : "{OWNER} had 10% of its Health Restored.",
      "cleanup_message" : "",
      "properties": ["Health", "0.10"]
   }

Notice how we set duration to 3. This means that this Combat Effect can trigger up to 3 times before it is removed.

To decrease an entity's Mana by 50% for a single turn, you could use an effect like this:

   {
      "class_name" : "ProportionalResourceEffect",
      "duration"  : 1,
      "trigger_phase" : "PRE_ACTION",
      "trigger_message" : "{OWNER} lost 50% of its health!",
      "cleanup_message" : "",
      "properties": ["Health", "-0.50"]
   }

Note that this doesn't reduce Health by 50% of its current value, it reduces it by 50% of its max value. So, if you had 31/100 Health, this effect would end up performing the following calculation:

31 + (100 * -0.50) = 31 - 50 = -19. Since Combat Resources cannot have negative values, Health is then set to 0.

Flat Resource Effect

Say you want to create a Combat Effect that simulates a burn. One way of doing this would be to hurt the owner of the Combat Effect by 10 Health every turn. Flat Resource Effect is the perfect fit for this situation. Here's an example:

 {
      "class_name" : "FlatResourceEffect",
      "duration"  : 5,
      "trigger_phase" : "PRE_ACTION",
      "trigger_message" : "{OWNER} is hurt by its burn!",
      "cleanup_message" : "{OWNER}" is no longer burned.,
      "properties": ["Health", "-10"]
  }

This effect triggers during its owner's Pre-Action phase for five turns, reducing its owner's Health by 10 each time it triggers.

Remove Phase Effect

Perhaps you've created an Ability that stuns its target. You can accomplish this by giving the Ability a Remove Phase Effect.

{
      "class_name" : "RemovePhaseEffect",
      "duration"  : 1,
      "trigger_phase" : "TURN_START",
      "trigger_message" : "{OWNER} is stunned and cannot act!",
      "cleanup_message" : "{OWNER} is no longer stunned!",
      "properties": ["ACTION"]
 }

Notice that is Combat Effect skips its owner's Action Phase.

This effect triggers once. It removes the Action phase from its owner's turn. This means that the turn this effect triggers, its owner cannot make a choice for what to do during its turn--effectively what being stunned would do.

NOTE that in order for this to work, the effect has to trigger before the Action phase--after all, removing the phase after you've passed through it would not accomplish anything.

Dispel Combat Effect

Perhaps you would like to remove all other effects tied to a given character. Dispel Combat Effect is perfect for this job.

{
  "name" : "Cleanse",
  "target_mode" : "SINGLE_FRIENDLY",
  "description" : "Remove all effects on target ally.",
  "use_text" : "{CASTER} calls a shimmering light from above upon {TARGET}. {TARGET}'s ailments are cured.",
  "effects" : [
    {
      "class_name" : "DispelCombatEffect",
      "trigger_phase": "TURN_START",
      "trigger_message" : "{OWNER} is no longer effected by anything from before Cleanse",
      "properties": ["FlatResourceEffect"]
    },
    {
      "class_name" : "DispelCombatEffect",
      "trigger_phase": "TURN_START",
      "properties": ["LevelResourceEffect"]
    },
    {
      "class_name" : "DispelCombatEffect",
      "trigger_phase": "TURN_START",
      "properties": ["ProportionalResourceEffect"]
    },
    {
      "class_name" : "DispelCombatEffect",
      "trigger_phase": "TURN_START",
      "properties": ["AddPhaseEffect"]
    },
    {
      "class_name" : "DispelCombatEffect",
      "trigger_phase": "TURN_START",
      "properties": ["RemovePhaseEffect"]
    },
    {
      "class_name" : "DispelCombatEffect",
      "trigger_phase": "TURN_START",
      "properties": ["DispelCombatEffect"]
    },
    {
      "class_name" : "DispelCombatEffect",
      "trigger_phase": "ACTION",
      "trigger_message" : "{OWNER} is no longer effected by anything from before Cleanse",
      "properties": ["FlatResourceEffect"]
    },
    {
      "class_name" : "DispelCombatEffect",
      "trigger_phase": "ACTION",
      "properties": ["LevelResourceEffect"]
    },
    {
      "class_name" : "DispelCombatEffect",
      "trigger_phase": "ACTION",
      "properties": ["ProportionalResourceEffect"]
    },
    {
      "class_name" : "DispelCombatEffect",
      "trigger_phase": "ACTION",
      "properties": ["AddPhaseEffect"]
    },
    {
      "class_name" : "DispelCombatEffect",
      "trigger_phase": "ACTION",
      "properties": ["RemovePhaseEffect"]
    },
    {
      "class_name" : "DispelCombatEffect",
      "trigger_phase": "ACTION",
      "properties": ["DispelCombatEffect"]
    }
  ]
}

This ability removes all effects from an entity as soon as possible then dispels itself.

The first 6 effects dispel each group of combat effects on TURN_START phase, and the second group of 6 effects does the same but on ACTION phase. To trigger as soon as possible, the effect must be placed on the first phase after cast. Depending on whether the ability is cast on another or self the first phase can vary. When cast on another TURN_START phase is fastest but when cast on ACTION phase is fastest. Since Dispel Combat Effect can dispel even itself, the function will not repeat for whichever phase would happen second.

Note: There is no duration because the default duration is 1.