path: root/features/readme.md

# Features Format

Many features are complex. Here we lay out the format used when writing a feature.

The overall structure of a feature is a dictionary as follows:

 * "name": NAME
 * "text": TEXT
 * "subfeatures": SUBFEATURES

In addition to the hardcoded data provided in the feature, certain variables may be given at runtime.

## Variables

Many features are very similar between creatures except for certain variables. When instantiated programatically, the feature is given the following:

 * NAME: The name of the creature with this feature
 * V0, V1, ... VN: Zero-indexed list of integer variables

Certain portions of features accept these as parameters, either inline as in TEXT, or in the place of hardcoded variables for conditions or effects.

In addition to these, certain attributes of the creature having this feature may be probed such as:
 * STR
 * DEX
 * CON
 * INT
 * WIS
 * CHA
 * PROF
 * MAXHP
 * MOVESPEED
 * SPELLDC

The above attributes by default apply to self (i.e., self.STR), however, they may also be used for another creature (i.e., creature.STR).

Finally, simple math can be provided in postfix notation surounded by parentheses. For example, to set a save DC equal to 8+int+prof: (8,INT,PROF,+,+).

## TEXT

This is explanatory text. It accepts embedded variables in the form {VARNAME}. For example, the text "The {NAME}'s weapon attacks are magical. When the {NAME} hits with any weapon, the weapon deals an extra {V0}d{V1} radiant damage.", when applied to a "deva" with runtime variables (4, 8), we get:

"The deva's weapon attacks are magical. When the deva hits with any weapon, the weapon deals an extra 4d8 radiant damage."

## Subfeatures

Each feature consists of a list of "subfeatures", which are treated as independent features in the game, but are grouped together for clear organization.

Each subfeature is a dictionary with the following elements:

 * "trigger": TRIGGER
 * "conditions": CONDITIONS
 * "effects": EFFECTS
 * "recharge": RECHARGE

Several of the elements accept various nouns.

## NOUNS

Nouns embedded into subfeature elements may be any of:

 * "self"
 * "creature"
 * "object"
 * "structure"
 * "target"
 * "point in space"
 * NAME

Where NAME is interpreted by the game as a specific creature or object with a matching name.

### TRIGGER

TRIGGER is a list containing any of the following followed by nouns corresponding to instances of N:

 * "passive" (evaluated on initialization)
 * "action"
 * "bonus action"
 * "free action"
 * "legendary action costing X"
 * "N start of turn"
 * "N end of turn"
 * "N takes damage" (pushes damage amount, damage type to variables list)
 * "N moves"
 * "N makes check against N" (pushes ROLLCLASS to variables list)
 * "N forces N to save" (pushes ROLLCLASS to variables list)
 * "N rolls a d20" (pushes ROLLCLASS to variables list)
 * "N targets N by a spell" (pushes spell name to variables list)
 * "N attacks N"
 * "N hits N"
 * "N touches N"

Where ROLLCLASS is any of:
 * "attack"
 * "grapple"
 * "escape grapple"
 * "shove"
...

### CONDITIONS

CONDITIONS is a list of lists, all of which must evaluate True for effects to be applied. Each condition list is formatted [ CONDITION, variables ] where CONDITION is any of the following, prepend "not " to invert:

 * "N has property PROPERTY = VALUE"
 * "N is hostile to N"
 * "N is allied to N"
 * "N wishes it to be so"
 * "N succeeds dc X ABILITY save by at least X" (0 is a success)
 * "N fails dc X ABILITY save by at least X" (0 is a fail)
 * "N is within radius X of N"
 * "N can see N"
 * "N has completed >= X turns"
 * "N has COND X hp" (COND any of ">=", ">", "<=", "<", "==")
 * "Damage received >= X"
 * "Damage received was a critical hit"
 * "Damage received was type TYPE"
 * "N has condition CONDITION"
 * "N has condition CONDITION given by N"
 * "N and N are on same plane of existence"
 * "N is on plane PLANE"
 * "N moved X distance straight toward N"
 * "N has X movement remaining"
 * "N made attack ATTACK"
 * "N has underside exposed"
 * "First time N uses feature on N during turn"
 * "N is flying"
 * "N is under effects of spell SPELL"
 * "N has spell from school SCHOOL cast on it"
 * "N is on terrain TERRAIN"
 * "N is inside an object"
 * "N is in lighting LIGHTING" (sunlight, dim light, darkness, magical darkness)
 * "N can understand >= X languages"
 * "N and N share a language"
 * "N has >= X heads"
 * "N has X spell slots remaining"
 * "N had advantage" 
 * "N had disadvantage"
 * "N used a weapon"
 * "N is surprised"
 * "N is bound by N"
 * "N is aware of N"
 * "N and N are in the same web"
 * "N == N"
 * "N is in AOE" where AOE is denoted in any of the following:
   * "line LENGTH WIDTH"
   * "cone LENGTH"

### EFFECTS

EFFECTS is a list of dictionaries containing the following:

 * "target": NOUN
 * "effect": [EFFECT, variables]
 * "effect conditions": [[ CONDITION, variables ]]
 * "duration": DURATION

Where EFFECT is any of the following (UNDER CONSTRUCTION DENOTED BY x):

 * Terrain in X ft radius is difficult
 * Set movement speed to X
 * Move up to X ft toward N
x * Increase movement speed by X
x * Increase jump distance by X
x * Increase jump height by X
 * Acquire condition CONDITION
x * End condition CONDITION
 * Set property PROPERTY to X
x * Death
x * Surprised
x * Pushed X feet in DIRECTION direction
x * Immune to feature FEATURE
x * Immune to spells with trait SPELL\_TRAIT
 * Impose disadvantage
 * "Impose disadvantage on TYPE" (any of "attack rolls", "ability checks", "saving throws")
 * Grant advantage
 * Grant critical hit
x * Advantage on rolls ROLL\_CLASS
x * Automatic fail on rolls ROLL\_CLASS
x * Automatic succeed on rolls ROLL\_CLASS
x * Move X distance
x * Deal X damage
 * Inflict XdX TYPE damage
 * Inflict XdX TYPE damage, dc X ABILITY save halves
 * Deal +X weapon die damage
 * Damage dealt is magical
 * Take action ACTION
x * Disable other feature
x * Know distance/direction to creature/object within X distance
 * Reduce incoming damage by X
 * Regain X hp
x * Weapon/armor corrodes
x * Ignite flammable objects
x * Expend spell slot
x * Special movement
x * Plane shift
x * Grant spell effect
x * Transparency (perpetual hidenness?)
x * Prescribed actions (randomized), any of:
x   - Nothing
x   - Moves in random direction
x   - Attacks random creature within reach
x * Telepathic command
x * Learns creature's desires
x * Spell storing
x * Creates X diameter tunnel

The conditions on an effect may be omitted if not applicable, and are the same as conditions for a trigger.

The duration of an effect may be omitted for instantaneous effects and is any of the following:

 * "End of turn"
 * "Start of next turn"
 * "End of next turn"
 * "Until action is taken to end"
 * TIME (formatted "X units", where units is any of sec, min, hr, day, month, year)
x * Repeated saves???
x * Repeated saves at advantage/disadvantage with condition???
x * Until certain spell is cast???
x * Until other effect expires???

### RECHARGE

The recharge of a feature may be omitted to indicate that it is unlimited. Otherwise, it is a list of the following two items:

 * Integer indicating number of times the feature can be used
 * Any of "turn", "long rest", "short rest", "X-Y" (for integers X and Y) indicating when spent uses are restored