Skip to content
Back

Mechanics

Some records carry a nested mechanics block: structured effects the app applies on its own. It has the same shape in every type that has a mechanics field.

Shape

Each mechanic is an object with the mechanic type, an optional level and a config that depends on the mechanic type.
{
  "type": "string",
  "level": 1,
  "config": {}
}

Rules

  • On update the mechanics list is replaced as a whole: send every mechanic you want to keep.
  • Service fields (ids, owner, timestamps) are not allowed inside mechanics and are rejected.
  • The type value must be a mechanic type known to the server; a record with an unknown mechanic is skipped with a per-record error.

Mechanic types

add

Adds a value to a character property.
  • keyrequired
    Property key from `keys` (only keys with kind "number" or "damage")
  • valuerequired
    Integer, a single "{expression}" string, or (for the `damage` key only) a damage string - see `keys`
  • vault
    When true, the mechanic also applies while the card is in the vault (owned but not in the loadout), not only while it is in the loadout. Without it a vault card's mechanic does not work. Only for add, set and dice.
  • penalty
    When true, the mechanic is a penalty (a rules-text "-N to ..." from equipment or a feature). Penalties are not applied while the character has `ignorePenalties`. Only for add and set; not allowed on the `ignorePenalties` key.
  • condition
    Condition (expression string); the mechanic applies and is shown only while it is true. Empty or absent means always.

set

Sets a character property to a value.
  • keyrequired
    Property key from `keys`
  • valuerequired
    Value of the kind the key expects (see `keys`)
  • vault
    When true, the mechanic also applies while the card is in the vault (owned but not in the loadout), not only while it is in the loadout. Without it a vault card's mechanic does not work. Only for add, set and dice.
  • penalty
    When true, the mechanic is a penalty (a rules-text "-N to ..." from equipment or a feature). Penalties are not applied while the character has `ignorePenalties`. Only for add and set; not allowed on the `ignorePenalties` key.
  • condition
    Condition (expression string); the mechanic applies and is shown only while it is true. Empty or absent means always.

res

A resource with dots/uses the player tracks on the sheet; also covers numbered point tracks (Favor, Focus) when given `key`/`slots`/`ui`. Stores a per-character integer.
  • valuerequired
    Number of uses: integer or a single "{expression}" string; -1 means unlimited (the UI shows N filled slots plus one trailing empty slot that grows the track); "EDITABLE" lets the player set the maximum on the sheet (e.g. after rolling 1d6 charges)
  • time
    When the resource restores (resets): SHORT/LONG rest, SESSION, or null (never)
    Allowed values: SHORT, LONG, SESSION,
  • key
    Name of the resource: a custom `_camelCase` key, e.g. "_favor" or "_focus". Read with PROP(key) and used as the log name. One resource per key; the same key must not also be written by add/set.
  • min
    Lowest allowed value; defaults to 0. Must not exceed a finite `value`.
  • rest
    Optional restore rules: { "SHORT"?: <added on short rest>, "LONG"?: <added on long rest>, "SESSION"?: <added on session rest> }. Each value is an integer or a single "{expression}" added to the resource when that rest is applied. Omit a mode to leave the resource unchanged on that rest.
  • ui
    Info tracker look: { "label": { "en", "ru" }, "color": <palette token> }. `color` is a token name from `resourceWidgets.colors` (rendered as var(--color-<token>)), never raw CSS.
  • condition
    Condition (expression string); the mechanic applies and is shown only while it is true. Empty or absent means always.
  • slots
    Where the resource renders: a string or a non-empty array of strings from `resourceWidgets.slots`. Default "card" (the card/feature it belongs to). "info" additionally renders it as a tracker on the info page, under HP/Stress/Armor; "project" renders it as a tracker in the footer of the "Work on a project" rest move (no card). Both require `ui.label` and a non-EDITABLE `value`.
    Allowed values: card, info, project

craft

A crafting recipe producing a dh-items item.
  • valuerequired
    What the craft produces: a dh-items id visible to you (created at once), a non-empty array of such ids or -1 (all items) to pick one from a list, or the string "index" to pick from the items sharing a table position (dh-items `index`) chosen with a counter.
  • filter
    Restricts the items offered by an array, -1 or "index" value. Keys: `type` - non-empty array of dh-items types, e.g. ["consumable"].
  • limit
    Integer >= 1: the most copies of the item that may sit in the inventory at once; crafting is blocked while the inventory holds this many. `1` makes the craft unique.
  • condition
    Condition (expression string); the mechanic applies and is shown only while it is true. Empty or absent means always.
  • slots
    Where the craft is offered: a non-empty array of unique values from `card` (instant hold-to-craft button, default), `rest` (any rest: short and long), `long-rest` (long rest only), `session` (session rest); rest slots add an entry with the card name and a checkbox to the rest moves list, crafted when the rest is applied. Rest slots work on domain cards in the loadout.
    Allowed values: card, rest, long-rest, session

dice

An extra die added to the character's dice.
  • valuerequired
    "<count>d<die>", count is an integer or "{expression}", e.g. "2d8" or "{PROF}d6"
  • vault
    When true, the mechanic also applies while the card is in the vault (owned but not in the loadout), not only while it is in the loadout. Without it a vault card's mechanic does not work. Only for add, set and dice.
  • condition
    Condition (expression string); the mechanic applies and is shown only while it is true. Empty or absent means always.

pool

A set of dice of one type whose values the player remembers on the sheet (e.g. Prayer Dice, a moon phase): each die holds a value 1..die and can be marked spent. The player sets the values; a rest matching `time` clears them.
  • valuerequired
    "<count>d<die>", die is one of 4, 6, 8, 10, 12, 20, count is an integer >= 1 or "{expression}", e.g. "{SC}d4" or "1d6"
  • time
    On which rest the values reset (the player sets them again): SHORT/LONG rest, SESSION, or null (never, default)
    Allowed values: SHORT, LONG, SESSION,
  • color
    Color of the dice: a palette token from `resourceWidgets.colors` (rendered as var(--color-<token>)), never raw CSS. Default: primary.
    Allowed values: hope, fear, error, warning, t-1, t-2, t-3, domain-1, domain-2, domain-3, domain-4, domain-5, domain-6, domain-7, domain-8, domain-9, marker-1, marker-2, marker-3, marker-4, marker-5, marker-6, marker-7, marker-8, marker-9, marker-10
  • condition
    Condition (expression string); the mechanic applies and is shown only while it is true. Empty or absent means always.
  • slots
    Where the dice render: "card" (default) or "info" (also shows the dice on the info page with the feature name).
    Allowed values: card, info

text

Free-text fields the player fills in on the sheet (e.g. three sayings). The compact card shows the filled lines as text; the card drawer shows one input per field. Stored per character, not restored by rests.
  • valuerequired
    Number of text fields: an integer from 1 to 10
  • condition
    Condition (expression string); the mechanic applies and is shown only while it is true. Empty or absent means always.
  • slots
    Where the text fields render: "card" (default; compact card shows the filled lines, drawer the inputs) or "info" (also lists the filled lines on the info page; editing stays in the card drawer).
    Allowed values: card, info

entity

A template for an entity (Dreadnought, a summon) the player creates from the Entities section while the card is in the loadout. The created entity is a snapshot stored on the character and survives the card leaving the loadout. Only the `stats` listed here are rendered on the entity.
  • namerequired
    Default entity name: { "en", "ru" }, both non-empty; the player can rename the created entity
  • description
    Rules text shown on the entity: { "en"?, "ru"? } plain strings
  • stats
    Parameters shown on the entity; absent ones are not rendered. Keys: hp, stress, armor (positive integer slot counts), evasion (integer), thresholds ({ "major", "severe" } positive integers), experiences (array of { "name"?: string, "value": integer })
  • expire
    Array of when the entity disappears, any combination: REST (after any rest), LONG (after a long rest), SESSION (after a session rest), HP_ZERO (when all HP are marked), MANUAL (by hand only). Empty or absent means manual. The player can always delete an entity by hand
    Allowed values: REST, LONG, SESSION, HP_ZERO, MANUAL
  • unique
    When true, creating an entity from this template replaces the previous one made from it (after confirmation)
  • condition
    Condition (expression string); the mechanic applies and is shown only while it is true. Empty or absent means always.

list

A list of entries from a custom collection (martial stances, Rift creatures) the character picks from: which entries are known, which are active, the limits, the activation cost and how many are chosen at creation and level-up. One list per collection schema per character (the first active mechanic wins).
  • collectionrequired
    Key of a collection schema visible to you, e.g. "martial_stances"
  • known
    Known entries: { "limit"?, "filter"?, "create"?: { "count", "filter"? }, "levelup"? }. `limit` is the most known entries (integer or one "{expression}", default unlimited). `filter` is a condition that picks the entries the character may know; it reads entry fields as {ENTRY.<field key>} and the character as usual variables, e.g. "{ENTRY.tier}<={TIER}". `create`: exactly `count` entries are picked at character creation, optionally narrowed by its own `filter`. `levelup`: the number of entries picked on each level-up (integer >= 1).
  • active
    Active entries: { "limit"?, "cost"?: { "key", "value" } }. `limit` is the most active entries at once (integer or one "{expression}", default 1). `cost` is paid when an entry is activated; `key` is either a built-in resource - `hp`, `stress`, `armor` (paying marks that many slots, so it needs free slots) or `hope` (paying spends that much Hope) - or the `_camelCase` key of a `res` mechanic: an existing one (e.g. `_focus`, `_favor`) or your own, which you create as a `res` mechanic with that key on the same card or feature (the character must have it active). `value` is an integer or one "{expression}" that may read {ENTRY.<field key>}. Default: free.
  • ui
    Block look: { "label": { "en", "ru" } } - the heading of the list on the card
  • condition
    Condition (expression string); the mechanic applies and is shown only while it is true. Empty or absent means always.

Common fields

condition

Condition (expression string); the mechanic applies and is shown only while it is true. Empty or absent means always.
Applies to: add, set, res, craft, dice, pool, text, entity, list

penalty

When true, the mechanic is a penalty (a rules-text "-N to ..." from equipment or a feature). Penalties are not applied while the character has `ignorePenalties`. Only for add and set; not allowed on the `ignorePenalties` key.
Applies to: add, set

slots

Where the mechanic renders: a string or a non-empty array of unique values from `registry`. Default "card". Each type accepts only its own subset (`types`).

Property keys

Keys accepted by the add and set mechanics.
  • hpnumber
    Hit point slots. `set` replaces the base, `add` adds to it - see `syntax`.
  • stressnumber
    Stress slots. `set` replaces the base, `add` adds to it - see `syntax`.
  • evasionnumber
    Evasion. `set` replaces the base, `add` adds to it - see `syntax`.
  • armornumber
    Armor score. `set` replaces the base, `add` adds to it - see `syntax`.
  • threshold1number
    Major damage threshold. `set` replaces the armor/modifier base, `add` adds to it, and the character's level is always added on top of either - see `syntax`.
  • threshold2number
    Severe damage threshold. `set` replaces the armor/modifier base, `add` adds to it, and the character's level is always added on top of either (doubled only when un-armored and un-set) - see `syntax`.
  • profnumber
    Proficiency (number of damage dice). `set` replaces the base, `add` adds to it - see `syntax`.
  • hopeMaxnumber
    Maximum Hope. `set` replaces the base, `add` adds to it - see `syntax`.
  • restStressnumber
    Extra Stress cleared on the SHORT rest Clear Stress move, capped at marked Stress slots
  • restArmornumber
    Extra Armor cleared on the SHORT rest Repair Armor move, capped at marked armor slots
  • restHopenumber
    Extra Hope gained on a rest's Prepare move
  • experiencesnumber
    Bonus to one experience (the player picks which)
  • experiencesCountnumber
    Extra character Experiences (class feature section, modifier +2 each), usable only with add: a non-negative integer or a single "{expression}". Does not change the companion's Experiences
  • loadoutnumber
    Loadout size. `set` replaces the base, `add` adds to it - see `syntax`.
  • domainsCardsnumber
    Domain cards picked per level. `set` replaces the base, `add` adds to it - see `syntax`.
  • damagedamage
    Damage bonus, usable only with add: an integer, a single "{expression}" evaluating to a number, or a damage string of +/- separated terms, each an integer or "<count>d<die>" (count is an integer or "{expression}", die letter d/D/к/К, normalized to d on save)
  • attacknumber
    Attack roll bonus
  • spellcastnumber
    Spellcast roll bonus
  • companionOptionsnumber
    Extra companion upgrade options
  • beastEvolvednumber
    Offers an evolved beast form of this rank
  • beastHybridnumber
    Offers a hybrid beast form of this rank
  • downtimeMovesnumber
    Extra downtime moves per rest
  • hasCompanionboolean
    Enables the companion sheet
  • ignoreBurdenboolean
    Two-handed weapons do not take the secondary slot
  • ignorePenaltiesboolean
    Mechanics marked `penalty: true` (equipment/feature penalties) are not applied. `condition` and `value` must not use PROP(...)
  • beastformboolean
    Enables Beastform
  • unarmedWeaponIdweaponId
    Replaces the unarmed attack with this dh-weapons weapon (usually with condition "!{IS.ARMED}")
  • STRnumber
    Strength trait. `set` replaces the base, `add` adds to it - see `syntax`.
  • AGLnumber
    Agility trait. `set` replaces the base, `add` adds to it - see `syntax`.
  • FNSnumber
    Finesse trait. `set` replaces the base, `add` adds to it - see `syntax`.
  • INSnumber
    Instinct trait. `set` replaces the base, `add` adds to it - see `syntax`.
  • PREnumber
    Presence trait. `set` replaces the base, `add` adds to it - see `syntax`.
  • KNWnumber
    Knowledge trait. `set` replaces the base, `add` adds to it - see `syntax`.

Custom keys

Any add/set key of the form "_camelCase" (underscore, lowercase latin letter, then latin letters and digits) is a custom prop: it needs no registration, expects a number and is read elsewhere with PROP(key). As an add/set target it only exists while some active mechanic sets it. The same form is also the `key` of a `res` mechanic; a resource key is a stored player-adjustable value, not a computed prop, and must not also be written by add/set.
_powerCount, _stacks, _rageLevel, _favor, _focus

Resource slots and colors

Closed lists for the resource `slots` and `ui`. `slots` is where it renders (card: on the card/feature, default; info: tracker on the info page; project: tracker in the footer of the project rest move). `colors` are palette token names rendered as var(--color-<token>) - never raw CSS; `colorLabels` says which color each token is (`marker-1`..`marker-10` are the note colors). New slots ship with a frontend release.
Slots: card, info, project
Colors: hope, fear, error, warning, t-1, t-2, t-3, domain-1, domain-2, domain-3, domain-4, domain-5, domain-6, domain-7, domain-8, domain-9, marker-1, marker-2, marker-3, marker-4, marker-5, marker-6, marker-7, marker-8, marker-9, marker-10

Expression variables

  • STR
    Strength trait value
  • AGL
    Agility trait value
  • FNS
    Finesse trait value
  • INS
    Instinct trait value
  • PRE
    Presence trait value
  • KNW
    Knowledge trait value
  • PROF
    Proficiency (final value, including `add`/`set prof` mechanics)
  • LVL
    Character level
  • TIER
    Character tier (1-4)
  • SC
    Spellcast trait value (final value of whichever trait is the character's spellcasting trait)
  • HP.MAX
    Available HP slots
  • HP.MARKED
    Marked HP slots
  • STRESS.MAX
    Available Stress slots
  • STRESS.MARKED
    Marked Stress slots
  • HOPE.MAX
    Maximum Hope
  • HOPE.MARKED
    Current Hope
  • HOPE.BLOCKED
    Blocked Hope slots
  • ARMOR.MAX
    Available armor slots
  • ARMOR.MARKED
    Marked armor slots
  • FAVOR.MARKED
    Current Favor points (0 without a Favor resource)
  • FOCUS.MARKED
    Current Focus points (0 without a Focus resource)
  • EVASION
    Final Evasion (including `add`/`set evasion` mechanics)
  • THRESHOLD.MAJOR
    Final major damage threshold
  • THRESHOLD.SEVERE
    Final severe damage threshold
  • IS.ARMORED
    Boolean: armor is equipped
  • IS.ARMED
    Boolean: a primary or secondary weapon is equipped
  • IS.TOUCHED
    Boolean: 4 or more cards in the loadout belong to the same domain as the domain card carrying the mechanic (including mechanics of its nested features); the domain and threshold are implicit. Always false outside domain cards
  • IS.BEASTFORM
    Boolean: the character is currently in Beastform
  • IS.TWOHANDED
    Boolean: the equipped primary weapon is two-handed
  • PRIMARY.RANGE
    String: range of the equipped primary weapon ("melee", "veryclose", "close", "far", "veryfar") or "none"
  • PRIMARY.EQUIPPED
    Boolean: a weapon is equipped in the primary slot
  • SECONDARY.EQUIPPED
    Boolean: a weapon is equipped in the secondary slot
  • DOMAIN.COUNT
    Number of cards in the loadout that share the domain of the domain card carrying the mechanic (including mechanics of its nested features); 0 outside domain cards

Expression functions

  • MAX
    MAX(a, b) - larger value
  • MIN
    MIN(a, b) - smaller value
  • FLOOR
    FLOOR(x) - round down
  • CEIL
    CEIL(x) - round up
  • MOD
    MOD(x) - signed modifier text; also written as "X|MOD"
  • PROP
    PROP(key) - final value of a character prop: a system key from `keys` or a custom `_camelCase` key collected from add/set mechanics, or the current stored value of a `res` mechanic's `key`; 0 when nothing sets it, booleans read as 1/0. An add/set mechanic must not reference its own key. Resource keys are player-adjustable storage, not computed - reading them never cycles.

Expression syntax

  • Expressions are wrapped in braces: "{PROF}", "{MAX(AGL, 1)}", "{CEIL(LVL/2)}".
  • A numeric value given as an expression must be exactly one "{...}" block; text around it is not allowed.
  • Arithmetic: + - * / and parentheses; comparisons: == != > >= < <=.
  • Pipe notation: "{AGL|MOD}" is the same as "{MOD(AGL)}".
  • Suffix "?desc" inside the braces shows a description next to the value in text: "{PROF*2?desc}".
  • Resource and boolean variables carry fields accessed with a dot, e.g. "{HP.MARKED}", "{IS.ARMORED}" - see `variables`.
  • Conditions use braces around variables and may combine them: "{HOPE.MARKED}>1", "{IS.ARMED}", "!{IS.ARMED}" (negation), "{IS.ARMORED} && {HOPE.MARKED}>=2", "{PRIMARY.RANGE}==\"melee\"". && / || / and / or / not are all accepted.
  • Domain "-Touched" cards (active while 4+ cards of the card's own domain are in the loadout) use the condition "{IS.TOUCHED}"; do not put a domain name in the variable.
  • For a registry stat key (hp, stress, prof, hopeMax, armor, evasion, threshold1, threshold2, loadout, domainsCards, STR/AGL/FNS/INS/PRE/KNW): an active `set` mechanic on the key replaces its base value (class/character/level-up/armor/beastform); otherwise the base is used. Either way, every active `add` mechanic on the key is then summed onto the result. The matching expression variable (e.g. PROF for prof, HP.MAX for hp) always reads this same final value; a mechanic whose `value`/`condition` references such a variable is applied after every mechanic that sets its key.
  • Exception: threshold1/threshold2 always add the character's level on top of the result above, even when `set` is active - per SRD, level always contributes to damage thresholds. threshold2 doubles the level contribution only when un-armored and no `set threshold2` mechanic is active.
  • Old flat variable names (HP, STRESS, HOPE, HOPEMAX, ARMOR, ARMORMAX, ARMORED, ARMED, TOUCHED, PRIMARYRANGE) are rejected; use the dotted name named in the rejection reason instead.
  • PROP(key) reads a prop collected from add/set mechanics: "{PROP(_powerCount)}", "{PROP(evasion)?desc}". Mechanics that use PROP are applied after the ones that set the referenced keys; a cycle between props reads as 0.
  • Accumulating a custom prop: set _powerCount = 1, then add _powerCount = 1 with condition "{TIER>=3}" on another feature.
  • Custom prop as dice count: dice "{PROP(_powerCount)}d6"; as a resource: res "{MAX(PROP(_powerCount), 1)}"; as a condition: "{PROP(_powerCount) >= 2}".
  • Printing a prop in card or feature text: "Roll {PROP(_powerCount)}d6", "{PROP(evasion)?desc}".
  • Only the variables and functions listed here are allowed. In the `filter` fields and `cost.value` of a `list` mechanic the entry being tested is also available as {ENTRY.<field key>}, e.g. "{ENTRY.tier}<={TIER}".
  • Vault mechanics: a mechanic works only while its card is in the loadout, unless its config has "vault": true (add, set, dice only) - then it also works while the card sits in the vault. For a card that permanently grants a bonus once placed in the vault use { "type": "add", "config": { "key": "loadout", "value": 1, "vault": true } }. On a card in the vault only mechanics with vault: true apply; loadout-dependent variables ({IS.TOUCHED}, {DOMAIN.COUNT}) still count loadout cards only.

Mechanics examples

Favor: unbounded growing resource (value -1) shown on the info page, rest restore from the spellcast trait.
{
  "type": "res",
  "config": {
    "value": -1,
    "key": "_favor",
    "min": 0,
    "slots": [
      "info"
    ],
    "rest": {
      "SHORT": "{SC}",
      "LONG": "{SC}"
    },
    "ui": {
      "label": {
        "en": "Favor",
        "ru": "Милость"
      },
      "color": "fear"
    }
  }
}
Focus: fixed-length resource of 6 shown on the info page, spent to shift into martial stances.
{
  "type": "res",
  "config": {
    "value": 6,
    "key": "_focus",
    "min": 0,
    "slots": [
      "info"
    ],
    "ui": {
      "label": {
        "en": "Focus",
        "ru": "Фокус"
      },
      "color": "domain-9"
    }
  }
}
Martial stances: know level+1 stances of the character's tier or lower, two tier-1 stances at creation, one more on each level-up, one active stance at a time for 1 Focus.
{
  "type": "list",
  "config": {
    "collection": "martial_stances",
    "known": {
      "limit": "{LVL+1}",
      "filter": "{ENTRY.tier}<={TIER}",
      "create": {
        "count": 2,
        "filter": "{ENTRY.tier}<=1"
      },
      "levelup": 1
    },
    "active": {
      "limit": 1,
      "cost": {
        "key": "_focus",
        "value": 1
      }
    },
    "ui": {
      "label": {
        "en": "Stances",
        "ru": "Стойки"
      }
    }
  }
}

Where to put a mechanic

Put a mechanic in the entity's own `mechanics` when it is an unnamed effect of the entity itself (e.g. armor that adds +1 evasion, a potion that is a craft recipe). When the effect is a named ability with its own description text - something the player sees as a separate block (e.g. "Reliable", "Heavy") - create it as a feature (inline in `features`) and put the mechanics on that feature.

Example

A filled-in mechanics object:
{
  "type": "add",
  "level": 1,
  "config": {
    "key": "evasion",
    "value": 1
  }
}