Monster special attacks

Functionality added in https://github.com/CleverRaven/Cataclysm-DDA/pull/19702

Definitions

Monster attacks can be specified in two ways: named and inline.

Named

Named attacks need to be specified in two places: first as attack definition, then usage by monsters.

Hardcoded attacks (currently denoted by ALL_CAPS named) are by definition named attacks.

Attack definition

Attack definitions have a "monster_attack" type, "attack_type" set to one of actor types, and an "id" (set to value that isn't taken yet). For compatibility "attack_type" defaults to the same value as "type". For example, specifying "type": "gun" will internally be treated as "type": "monster_attack", "attack_type": "gun". This will be removed in the future, so all new definitions should specify "type": "monster_attack".

Actor types are "leap", "melee", "bite", and "gun".

Hardcoded attacks do not have json definitions, but are implemented in C++. It is possible to treat hardcoded attacks as actor types, but there is no reason to do so as they have no variables to configure.

Example

[
  {
    "type": "monster_attack",
    "attack_type": "melee",
    "id": "spam_bite",
    "cooldown": 1
  }
]

Usage by monsters

There are two ways to use named attacks: array (used mostly with hardcoded attacks) and object.

Usage by monsters must NOT specify "attack_type" or the usage will be treated as inline definition instead.

Array

Array definitions are in the form [ "NAME", cooldown ]. Cooldown must be specified.

"id": "mon_alpha_razorclaw",
"type": "MONSTER",
...
"special_attacks": [
  [ "SHRIEK_ALERT", 6 ],
  [ "SHRIEK_STUN", 1 ]
]

Object

Object definitions are more complete than array definitions, as they allow overriding variables. They are also more verbose, as each field has to be named.

See individual attack docs (currently in /docs/MONSTERS.md, TODO: Move here) for information about specific attacks.

"type": "MONSTER",
...
"special_attacks": [
  {
    "id": "spam_bite",
    "cooldown": 5
  }
],

Inline

Inline definitions are definitions and usage combined into one.

Inline definitions need the "attack_type" field set to a valid hardcoded attack type. Setting "type" will also work (for now!).

Inline definitions generally do not need to specify "id". The only exception is when one monster needs to have two or more attacks with the same "attack_type" - in such a case "id" of each attack defaults to "attack_type", which would cause a collision and erase one of the attacks. Explicitly specifying "id" will prevent that from happening.

Example

"type": "MONSTER",
...
"special_attacks": [
  {
    "attack_type": "bite",
    "cooldown": 2
  }
],