Creatures#

This page shows how to change what a creature is and how it defends itself, using two files: the profile in creatures.json and the rules in creature-rules.json.

Worked example: the golem#

A profile is the entry of one creature family in creatures.json. A definition is a named bundle of modifiers and listeners in creature-rules.json. A profile points to definitions by name. The shipped golem shows the whole chain.

Goal: make the golem a heavy, armoured creature that never dodges.

First the profile, from creatures.json. Only the fields that matter here are shown, so this snippet is partial.

{
  "golem": {
    "trait": "armored",
    "armorWeight": "heavy",
    "dodge": 0,
    "ruleIds": ["armored-hide"]
  }
}

Then the definition, in creature-rules.json. Again this is an extract, not a whole file.

{
  "definitions": {
    "armored-hide": {
      "modifiers": [{ "hook": "defense.armorClass", "op": "add", "value": 0 }]
    }
  },
  "traits": { "armored": ["armored-hide"] }
}

The modifier on its own is a normal modifier, so you can check it like any other:

[
  { "hook": "defense.armorClass", "op": "add", "value": 0 }
]

• dodge is the raw dodge chance in percentage points, from 0 to 100. A single creature can carry its own value instead.
• armorWeight is light, medium or heavy. It scales the dodge. A profile without a weight counts as light.
• The golem reaches armored-hide twice, through ruleIds and through its trait. The rule is still granted only once.

Which file holds what#

Any other top-level key in creature-rules.json is refused when the game loads.

Traits#

A trait is a label on a profile ("trait": "armored"). The traits section maps each trait to a list of definitions, so every creature with that trait gets them. Use a trait when many families share a behaviour.

Abilities#

An ability is the special power of a family, such as fury or shockwave. The abilities section maps an ability kind to definitions. The shipped fury entry points to fury-recovery: a creature that just used its power is easier to hit.

[{ "hook": "defense.armorClass", "op": "add", "value": -2, "when": { "selfRecovering": true } }]

States#

A state is a temporary condition of the creature. The states section accepts four keys: lit, slowed, bound and poisoned. A definition under a state is active only while the creature is in it. Being lit or poisoned gives no defence bonus by itself: only the definitions you write do.

{
  "definitions": {
    "lit-glare": {
      "modifiers": [{ "hook": "defense.armorClass", "op": "add", "value": 1 }]
    }
  },
  "states": { "lit": ["lit-glare"] }
}

This extract is for reading: the game checks the states key when it loads. The key bound covers both frozen and entangled creatures.

Elites#

An elite is a creature that rolled extra affixes when its floor was generated. The elites section sets how many it gets (count, 0 to 10), the odds that a creature is elite (chance) and the pool of affixes.

Goal: elites get two affixes from this pool, with a 3% chance per floor of depth, capped at 25%.

{ "count": 2, "chance": { "base": 0, "perDepth": 0.03, "max": 0.25 }, "affixes": { "elite-evasive": { "name": "CREATURE_AFFIX_EVASIVE", "value": { "min": 2, "max": 4 } }, "elite-hardened": { "name": "CREATURE_AFFIX_HARDENED", "stackable": true } } }

The definition behind elite-evasive reads the rolled number with $value:

[{ "hook": "defense.dodge", "op": "add", "value": "$value" }]

Variants and magic resistance#

A variant is a named version of a family, such as frost or runic. variants lists the names. variantMagicResistances gives a variant a fraction from 0 to 1 of spell damage it absorbs. A variant not listed there has no resistance.

Goal: make cursed creatures resist a quarter of spell damage, on top of the shipped values.

{
  "creatureRules": {
    "variantMagicResistances": { "ash": 0.5, "frost": 0.5, "runic": 0.5, "cursed": 0.25 }
  }
}

The snippet shows only the part of creature-rules.json to change; the other sections stay as they are.

Another example: skeletons that dodge arrows#

Goal: skeletons dodge arrows better, and nothing else.

{ "hook": "defense.dodge", "op": "add", "value": 20, "when": { "kind": "ranged", "resource": "arrows" } }

Put this modifier in a new definition, skeleton-arrow-dodge, then add its name to the ruleIds of the skeleton profile. A creature is its own subject, so you do not need to filter by family.

• Only attacks that roll a die can be dodged. Area effects, traps, poison and burning cannot.
• Drop resource to cover every ranged attack, including shots fired by creatures.

Hearing and terrain#

Each profile has a hearingRadius. How far a noise carries is that radius times the noise intensity, capped at 12 in the shipped settings. The distance in a straight line must be within that reach.

Terrain then reduces the reach. Each cell between the noise and the listener multiplies it by its dampensSound factor divided by 100. A wall gives 0.05, a closed door 0.40, so two closed doors give 0.16. A cell without that component lets everything through, and opening a door restores it. See Terrain.

What the validator refuses#

The game stops at the first error and names the file and the key. The usual causes:

• a ruleIds, trait, ability or state entry that names an unknown definition;
• a dodge outside 0 to 100, or an armorWeight that is not light, medium or heavy;
• a listener using an action that only works for the player, such as gainResource, giveGold or restoreSatiety;
• $value in a definition outside the elite pool;
• a state key other than the four above.

The exact messages and fixes are in Troubleshooting.

• Terrain

  What a cell can contain and do.

• Magic

  The spells that variants resist.