Magic items and consumables

This page shows how to write homebrew magic items, potions, charged items that recharge at dawn and anything whose uses come back on a rest, field by field, for 5e and 5.5e.

For: Game Masters · Plan: Pro · 29 minutes

A magic item is gear with something extra: a cloak that turns fire, a wand with charges, a potion that heals. In a homebrew pack it's one row in the items list, like a weapon, and its extras are written as effects (changes to the character's numbers), actions (buttons that roll), uses (charges that run out) and rest rules (how the uses come back). Once you, the Game Master (GM), bind the pack to a game, players add the item to their sheet and RollQuest does the bookkeeping: the bonus applies while it's equipped, the charge is spent when they press the button, and the charges come back when someone presses Dawn. Everything here works for 5e (the 2014 rules, SRD 5.1) and 5.5e (the 2024 rules, SRD 5.2.1); where the two differ, the page says so.

Every example on this page is a complete pack that RollQuest accepts as it stands. Paste one into Check and create to try it (see Your first homebrew pack, step by step), or copy the object inside items into a pack of your own. The fields every item shares, such as key, name, price and weight, are explained in Weapons and armour; this page covers what makes an item magic.

A magic item with an effect

The Cloak of the Ember Ward gives +1 to AC (armour class, how hard the character is to hit) and resistance to fire damage while it's worn:

{
  "slug": "my-ember-ward",
  "name": "Cloak of the Ember Ward (homebrew magic item)",
  "system": "5.5e Compatible",
  "derivedFrom": "5-5e-core",
  "category": "addon",
  "version": "1.0.0",
  "license": "USER_HOMEBREW",
  "source": "My table's homebrew.",
  "attribution": "",
  "description": "",
  "requiredDecisions": [],
  "items": [
    {
      "kind": "inventoryItem",
      "key": "ITEM_CLOAK_OF_THE_EMBER_WARD",
      "spec": {
        "subType": "item",
        "id": "ITEM_CLOAK_OF_THE_EMBER_WARD",
        "name": "Cloak of the Ember Ward",
        "meta": {
          "rarity": "Rare",
          "attunement": true,
          "type": "Wondrous Item",
          "description": "While you wear this cloak you gain +1 AC and resistance to fire damage."
        },
        "actions": [],
        "effects": [
          {
            "id": "EMBER_WARD_AC",
            "target": "AC_MISC_BONUS",
            "op": "add",
            "value": 1,
            "condition": "",
            "trigger": ""
          },
          {
            "id": "EMBER_WARD_FIRE",
            "target": "RESIST_FIRE",
            "op": "setMin",
            "value": 1,
            "condition": "",
            "trigger": ""
          }
        ]
      }
    }
  ]
}

In play, a player adds the cloak with + From pack on their sheet (in the Items panel it's on the Items tab). It arrives unequipped and does nothing yet. Once they click Equipped, their AC goes up by 1 straight away, on the open sheet and on their token, and fire damage that reaches them is halved. Unequipping it takes both away.

With the cloak on, 10 fire damage from the GM takes 5 off a character with 12 hit points. The hit's pop-up and its line in chat show the damage that landed, not the 10 asked for: 5, and HP going from 12 to 7.

The item's fields:

Field	What it does	Allowed values	Checked?
spec.subType	item puts it on the Items tab and makes its effects count only while it's equipped.	item for magic items, potions, wands and gear; weapon for a magic weapon (below).	Yes.
meta.rarity	Shown on the item's row on the sheet, such as Rare, and on its reference card. Nothing depends on it.	Any text: Common, Uncommon, Rare, Very Rare, Legendary, Artifact.	No.
meta.attunement	Shown on the item's reference card as Attunement: Required (only when rarity is set). Nothing else reads it (see below).	true or false. 5e items may use text instead, such as requires attunement by a cleric.	No.
meta.type	Shown at the top of the reference card.	Any text, such as Wondrous Item, Ring, Wand or Potion.	No.
meta.description	The item's text, shown when it's opened, on the builder's card and in the Items panel.	Any text.	No.
meta.notes	A short line: shown when you hover over the item in the Items panel's + From pack list, and in the Items panel's Notes.	Any text.	No.
spec.effects	The changes the item makes while it's equipped.	A list of effects (below).	Yes.

Each effect is one change:

Field	What it does	Here
id	The effect's ID. Write one for every effect, unique in the pack: an effect without one breaks a later re-stamp of the sheet.	EMBER_WARD_AC
target	The value or roll it changes.	AC_MISC_BONUS (a bonus added to AC) and RESIST_FIRE (the character's fire resistance).
op	How it changes it. add adds; setMin makes it at least the value.	add 1 and setMin 1
value	The number.	1
condition	Empty for always; otherwise a formula starting with = that's on when it isn't 0.	""
trigger	Empty for an effect that's always on. A rest's name for one that happens when a rest button is pressed (see A charged item that recharges at dawn, below).	""

RESIST_FIRE is a tier: 1 is resistance (half damage), 2 is immunity (none), and -1 is vulnerability (double). setMin is used so that two sources of resistance don't add up to immunity: the highest one wins. Every effect, target and op is in Effects: what an item can change.

Attunement

RollQuest doesn't track attunement. meta.attunement is a label: there's no limit of three items, nothing checks a class restriction, and an item's effects count as soon as it's equipped, attuned or not. Write the requirement in the description, and keep track at the table.

More magic items

A ring of protection is two add effects: AC and every saving throw.

{
  "slug": "my-emberglass-ring",
  "name": "Emberglass Ring (homebrew magic item)",
  "system": "5.5e Compatible",
  "derivedFrom": "5-5e-core",
  "category": "addon",
  "version": "1.0.0",
  "license": "USER_HOMEBREW",
  "source": "My table's homebrew.",
  "attribution": "",
  "description": "",
  "requiredDecisions": [],
  "items": [
    {
      "kind": "inventoryItem",
      "key": "ITEM_EMBERGLASS_RING",
      "spec": {
        "subType": "item",
        "name": "Emberglass Ring",
        "meta": {
          "rarity": "Rare",
          "attunement": true,
          "type": "Ring",
          "description": "While you wear this ring you gain +1 AC and +1 to saving throws."
        },
        "actions": [],
        "effects": [
          {
            "id": "EMBERGLASS_RING_AC",
            "target": "AC_MISC_BONUS",
            "op": "add",
            "value": 1,
            "condition": "",
            "trigger": ""
          },
          {
            "id": "EMBERGLASS_RING_SAVES",
            "target": "SAVE_MISC_BONUS",
            "op": "add",
            "value": 1,
            "condition": "",
            "trigger": ""
          }
        ]
      }
    }
  ]
}

An effect can depend on the character's sheet. These boots add 10 ft of Speed, but not while the character wears heavy armour (heavy armour sets IS_WEARING_HEAVY_ARMOR to 1):

{
  "slug": "my-cinderstep-boots",
  "name": "Cinderstep Boots (homebrew magic item)",
  "system": "5.5e Compatible",
  "derivedFrom": "5-5e-core",
  "category": "addon",
  "version": "1.0.0",
  "license": "USER_HOMEBREW",
  "source": "My table's homebrew.",
  "attribution": "",
  "description": "",
  "requiredDecisions": [],
  "items": [
    {
      "kind": "inventoryItem",
      "key": "ITEM_CINDERSTEP_BOOTS",
      "spec": {
        "subType": "item",
        "name": "Cinderstep Boots",
        "meta": {
          "rarity": "Uncommon",
          "attunement": false,
          "type": "Wondrous Item",
          "description": "While you wear these boots and no heavy armour, your Speed increases by 10 feet."
        },
        "actions": [],
        "effects": [
          {
            "id": "CINDERSTEP_SPEED",
            "target": "SPEED",
            "op": "add",
            "value": 10,
            "condition": "=IF(IS_WEARING_HEAVY_ARMOR=0, 1, 0)",
            "trigger": ""
          }
        ]
      }
    }
  ]
}

The condition formula is worked out from the character's own values, again whenever they change. It can't mention a weapon or a spell ("while wielding a sword"), only numbers on the sheet. Words instead of a formula, such as while not in heavy armour, are refused.

A magic weapon with an extra damage die

The Frostbite Blade is a +1 longsword that also deals 1d6 cold damage on a hit, and gives resistance to cold while it's equipped:

{
  "slug": "my-frostbite",
  "name": "Frostbite Blade (homebrew magic weapon)",
  "system": "5.5e Compatible",
  "derivedFrom": "5-5e-core",
  "category": "addon",
  "version": "1.0.0",
  "license": "USER_HOMEBREW",
  "source": "My table's homebrew.",
  "attribution": "",
  "description": "",
  "requiredDecisions": [],
  "items": [
    {
      "kind": "inventoryItem",
      "key": "WEAPON_FROSTBITE_BLADE",
      "spec": {
        "subType": "weapon",
        "id": "WEAPON_FROSTBITE_BLADE",
        "name": "Frostbite Blade, +1",
        "weight": {
          "unit": "lb",
          "value": 3
        },
        "meta": {
          "rarity": "Rare",
          "attunement": true,
          "category": "Martial Melee",
          "damage": "1d8",
          "damageType": "slashing",
          "properties": "Versatile (1d10)",
          "description": "A +1 longsword rimed with frost. On a hit it deals an extra 1d6 cold damage.",
          "targets": {
            "max": 1
          },
          "applies": [
            {
              "kind": "damage",
              "formula": "=1d8+STR_MOD+1",
              "damageType": "slashing"
            },
            {
              "kind": "damage",
              "formula": "=1d6",
              "damageType": "cold",
              "actionId": "DMG_COLD"
            }
          ]
        },
        "actions": [
          {
            "id": "ATK",
            "label": "Attack",
            "formula": "=1d20+PROF*W_MARTIAL+STR_MOD+1",
            "damageType": "",
            "tag": "ATK_ROLL"
          },
          {
            "id": "DMG",
            "label": "Damage",
            "formula": "=1d8+STR_MOD+1",
            "damageType": "slashing",
            "tag": "DMG_ROLL"
          },
          {
            "id": "DMG_COLD",
            "label": "Frost damage",
            "formula": "=1d6",
            "damageType": "cold",
            "tag": "DMG_ROLL"
          }
        ],
        "effects": [
          {
            "id": "FROSTBITE_COLD_RESIST",
            "target": "RESIST_COLD",
            "op": "setMin",
            "value": 1,
            "condition": "",
            "trigger": ""
          }
        ]
      }
    }
  ]
}

How it's built:

• It's a weapon, so it sits on the Weapons tab with its own buttons. (For a magic weapon that can be any weapon, see Weapons and armour.)
• The +1 is written into the Attack and Damage formulas, so it counts whether or not the blade is equipped.
• A third button, Frost damage, rolls the cold damage. Its applies entry carries "actionId": "DMG_COLD", which ties the entry to that button: pressing it after picking a target lands 1d6 cold on the target, and the target's cold resistance applies to it alone.
• RESIST_COLD is an effect, so it counts only while the blade is equipped.

Bonuses as effects instead

The +1 and the extra die can also be effects on the weapon. "scope": "self" limits each one to rolls made with this weapon; without it, the bonus would apply to every attack and damage roll the character makes, spells included.

{
  "slug": "my-searing-dagger",
  "name": "Searing Dagger (homebrew magic weapon)",
  "system": "5.5e Compatible",
  "derivedFrom": "5-5e-core",
  "category": "addon",
  "version": "1.0.0",
  "license": "USER_HOMEBREW",
  "source": "My table's homebrew.",
  "attribution": "",
  "description": "",
  "requiredDecisions": [],
  "items": [
    {
      "kind": "inventoryItem",
      "key": "WEAPON_SEARING_DAGGER",
      "spec": {
        "subType": "weapon",
        "name": "Searing Dagger, +1",
        "weight": {
          "unit": "lb",
          "value": 1
        },
        "meta": {
          "rarity": "Uncommon",
          "attunement": false,
          "category": "Simple Melee",
          "range": "5 ft",
          "damageType": "piercing",
          "properties": "Finesse, Light",
          "description": "A +1 dagger. On a hit it deals an extra 1d4 damage.",
          "targets": {
            "max": 1
          },
          "applies": [
            {
              "kind": "damage",
              "formula": "=1d4+MAX(STR_MOD,DEX_MOD)",
              "damageType": "piercing"
            }
          ]
        },
        "actions": [
          {
            "id": "ATK",
            "label": "Attack",
            "formula": "=1d20+PROF*W_SIMPLE+MAX(STR_MOD,DEX_MOD)",
            "damageType": "",
            "tag": "ATK_ROLL"
          },
          {
            "id": "DMG",
            "label": "Damage",
            "formula": "=1d4+MAX(STR_MOD,DEX_MOD)",
            "damageType": "piercing",
            "tag": "DMG_ROLL"
          }
        ],
        "effects": [
          {
            "id": "SEARING_DAGGER_ATK",
            "target": "ATK_ROLL",
            "op": "add",
            "value": 1,
            "condition": "",
            "trigger": "",
            "scope": "self"
          },
          {
            "id": "SEARING_DAGGER_DMG",
            "target": "DMG_ROLL",
            "op": "add",
            "value": 1,
            "condition": "",
            "trigger": "",
            "scope": "self"
          },
          {
            "id": "SEARING_DAGGER_DIE",
            "target": "DMG_ROLL",
            "op": "bonusDie",
            "value": "1d4",
            "condition": "",
            "trigger": "",
            "scope": "self"
          }
        ]
      }
    }
  ]
}

The difference matters at the table:

• Effects count only while the weapon is equipped, so the +1 and the extra 1d4 do nothing until the player equips the dagger. Bonuses written into the formulas always count.
• The extra die from bonusDie is added to the Damage roll, so it has the weapon's damage type (piercing here). For a different type, such as cold, use a separate button, as the Frostbite Blade does.
• A bonus die isn't doubled on a critical hit.
• The rolls that Target and Resolve make count the same effects as the buttons, so a creature hit through Target takes the +1 and the extra die too.

An effect aimed at DMG_ROLL (damage rolls) or HEAL_ROLL (healing rolls) is only accepted when your pack has an action with that tag, such as this dagger's Damage button. A ring that adds 1 to every damage roll, in a pack with no weapon in it, is refused.

Consumables

A potion is an item with one use. The Draught of Quickening heals 3d4+3 Hit Points:

{
  "slug": "my-quickening",
  "name": "Draught of Quickening (homebrew potion)",
  "system": "5.5e Compatible",
  "derivedFrom": "5-5e-core",
  "category": "addon",
  "version": "1.0.0",
  "license": "USER_HOMEBREW",
  "source": "My table's homebrew.",
  "attribution": "",
  "description": "",
  "requiredDecisions": [],
  "items": [
    {
      "kind": "inventoryItem",
      "key": "ITEM_DRAUGHT_OF_QUICKENING",
      "spec": {
        "subType": "item",
        "id": "ITEM_DRAUGHT_OF_QUICKENING",
        "name": "Draught of Quickening",
        "price": {
          "groupId": "coinage",
          "minor": 7500
        },
        "weight": {
          "unit": "lb",
          "value": 0.5
        },
        "maxUses": 1,
        "uses": 1,
        "meta": {
          "rarity": "Uncommon",
          "attunement": false,
          "type": "Potion",
          "description": "Drink as a Bonus Action to regain 3d4+3 Hit Points.",
          "applies": [
            {
              "kind": "heal",
              "formula": "=3d4+3"
            }
          ],
          "targets": {
            "max": 1
          }
        },
        "actions": [
          {
            "id": "HEAL",
            "label": "Drink",
            "formula": "=3d4+3",
            "damageType": "healing",
            "tag": "HEAL_ROLL"
          }
        ],
        "effects": []
      }
    }
  ]
}

What's new here:

• maxUses and uses give the item one use. They must be equal: uses is how many are left, and an item that arrives with fewer than its maximum starts part spent.
• The Drink action is tagged HEAL_ROLL and has the damage type healing.
• The applies entry is heal, so the player can give the potion to someone else: click Target, pick who drinks it, and click Resolve. The healing is added to their hit points.

Pressing Drink (or Resolve) spends the use. This potion then stays on the sheet at 0 of 1 uses, and RollQuest says it's out of uses if it's pressed again: delete it from the Items panel once it's drunk, or write it so it leaves the sheet by itself (below). + From pack doesn't offer an item the character already has, so a character can't carry two of the same potion this way: use doses (below), and remove an empty potion before taking a new one.

A potion that's gone once it's used

Add "consumeOnEmpty": true to meta, and the item leaves the sheet when its last use is spent, instead of waiting at 0. RollQuest's own 5.5e potions, such as Potion of Healing, are written this way. The Phial of Embersalve heals 2d4+2 Hit Points once, then it's gone:

{
  "slug": "my-embersalve",
  "name": "Phial of Embersalve (homebrew potion)",
  "system": "5.5e Compatible",
  "derivedFrom": "5-5e-core",
  "category": "addon",
  "version": "1.0.0",
  "license": "USER_HOMEBREW",
  "source": "My table's homebrew.",
  "attribution": "",
  "description": "",
  "requiredDecisions": [],
  "items": [
    {
      "kind": "inventoryItem",
      "key": "ITEM_PHIAL_OF_EMBERSALVE",
      "spec": {
        "subType": "item",
        "name": "Phial of Embersalve",
        "price": {
          "groupId": "coinage",
          "minor": 5000
        },
        "weight": {
          "unit": "lb",
          "value": 0.5
        },
        "maxUses": 1,
        "uses": 1,
        "meta": {
          "rarity": "Common",
          "attunement": false,
          "type": "Potion",
          "consumeOnEmpty": true,
          "description": "Smear the salve on a wound as a Bonus Action to regain 2d4+2 Hit Points. The phial is used up.",
          "applies": [
            {
              "kind": "heal",
              "formula": "=2d4+2"
            }
          ],
          "targets": {
            "max": 1
          }
        },
        "actions": [
          {
            "id": "HEAL",
            "label": "Apply",
            "formula": "=2d4+2",
            "damageType": "healing",
            "tag": "HEAL_ROLL"
          }
        ],
        "effects": []
      }
    }
  ]
}

• consumeOnEmpty needs a use budget: maxUses above 0 and an equal uses. Without one the pack is refused with CONSUME_ON_EMPTY_INVALID.
• The value must be true. Text such as "yes" is refused the same way, because RollQuest would read it as no.
• An item that gets its uses back on a rest is never used up, so a rest effect on SELF.uses beside the flag is refused too.
• Use it for things that are used up: a potion drunk, a scroll read, a flask thrown. Leave it off an item that only waits, such as a wand that recharges, or one that's still there once its magic is spent, such as a ring after its last wish.
• When the character has a stack of the item, one comes off the stack and the next starts full. The last one leaves the sheet, and a re-stamp doesn't hand it back.
• Adding or removing the flag in a new revision reaches the copies already on sheets when you move the game to it and re-stamp.

Three doses

A flask with three doses is the same item with "maxUses": 3 and "uses": 3. Each press spends one, and the row counts down: Common · 3/3, 2/3, 1/3.

{
  "slug": "my-ember-tea",
  "name": "Flask of Ember Tea (homebrew consumable)",
  "system": "5.5e Compatible",
  "derivedFrom": "5-5e-core",
  "category": "addon",
  "version": "1.0.0",
  "license": "USER_HOMEBREW",
  "source": "My table's homebrew.",
  "attribution": "",
  "description": "",
  "requiredDecisions": [],
  "items": [
    {
      "kind": "inventoryItem",
      "key": "ITEM_FLASK_OF_EMBER_TEA",
      "spec": {
        "subType": "item",
        "name": "Flask of Ember Tea",
        "price": {
          "groupId": "coinage",
          "minor": 2500
        },
        "weight": {
          "unit": "lb",
          "value": 1
        },
        "maxUses": 3,
        "uses": 3,
        "meta": {
          "rarity": "Common",
          "attunement": false,
          "type": "Potion",
          "description": "Three doses. Drink one as a Bonus Action to regain 1d4+1 Hit Points.",
          "applies": [
            {
              "kind": "heal",
              "formula": "=1d4+1"
            }
          ],
          "targets": {
            "max": 1
          }
        },
        "actions": [
          {
            "id": "HEAL",
            "label": "Drink",
            "formula": "=1d4+1",
            "damageType": "healing",
            "tag": "HEAL_ROLL"
          }
        ],
        "effects": []
      }
    }
  ]
}

A potion that lasts a minute

An applies entry of kind effect puts an effect on the target's sheet for a number of rounds. This tonic gives the drinker resistance to fire for 10 rounds (1 minute). targets is { "self": true }, so Target picks the drinker and no one else, and the item needs no action: Target and Resolve are enough.

{
  "slug": "my-emberproof-tonic",
  "name": "Emberproof Tonic (homebrew potion)",
  "system": "5.5e Compatible",
  "derivedFrom": "5-5e-core",
  "category": "addon",
  "version": "1.0.0",
  "license": "USER_HOMEBREW",
  "source": "My table's homebrew.",
  "attribution": "",
  "description": "",
  "requiredDecisions": [],
  "items": [
    {
      "kind": "inventoryItem",
      "key": "ITEM_EMBERPROOF_TONIC",
      "spec": {
        "subType": "item",
        "name": "Emberproof Tonic",
        "price": {
          "groupId": "coinage",
          "minor": 10000
        },
        "weight": {
          "unit": "lb",
          "value": 0.5
        },
        "maxUses": 1,
        "uses": 1,
        "meta": {
          "rarity": "Uncommon",
          "attunement": false,
          "type": "Potion",
          "description": "For 1 minute after you drink this tonic, you have resistance to fire damage.",
          "targets": {
            "self": true
          },
          "applies": [
            {
              "kind": "effect",
              "target": "RESIST_FIRE",
              "op": "setMin",
              "value": 1,
              "durationRounds": 10
            }
          ]
        },
        "actions": [],
        "effects": []
      }
    }
  ]
}

In a battle the resistance ends after 10 rounds. Outside a battle the rounds run on the game's world clock instead: at 6 seconds a round (or whatever A battle round is worth says in the game's settings), 10 rounds is one minute of game time. While the clock isn't running, the minute waits, and it starts counting once the clock runs. Drinking another one renews it rather than adding a second.

A charged item that recharges at dawn

The Wand of Sparks has 5 charges. Each press of Spark spends one and rolls 2d6 lightning; at dawn it regains 1d4+1:

{
  "slug": "my-wand-of-sparks",
  "name": "Wand of Sparks (homebrew charged item)",
  "system": "5.5e Compatible",
  "derivedFrom": "5-5e-core",
  "category": "addon",
  "version": "1.0.0",
  "license": "USER_HOMEBREW",
  "source": "My table's homebrew.",
  "attribution": "",
  "description": "",
  "requiredDecisions": [],
  "items": [
    {
      "kind": "inventoryItem",
      "key": "ITEM_WAND_OF_SPARKS",
      "spec": {
        "subType": "item",
        "id": "ITEM_WAND_OF_SPARKS",
        "name": "Wand of Sparks",
        "maxUses": 5,
        "uses": 5,
        "meta": {
          "rarity": "Uncommon",
          "attunement": false,
          "type": "Wand",
          "description": "5 charges. Spend 1 to loose a spark (2d6 lightning). Regains 1d4+1 charges at dawn."
        },
        "actions": [
          {
            "id": "DMG",
            "label": "Spark",
            "formula": "=2d6",
            "damageType": "lightning",
            "tag": "DMG_ROLL"
          }
        ],
        "effects": [
          {
            "id": "WAND_OF_SPARKS_DAWN",
            "target": "SELF.uses",
            "op": "addRandom",
            "value": "1d4+1",
            "condition": "",
            "trigger": "sunrise"
          }
        ]
      }
    }
  ]
}

The recharge is an effect with a trigger:

Field	Here	What it means
target	SELF.uses	This item's own uses.
op	addRandom	Give back a rolled number of uses, never more than maxUses.
value	"1d4+1"	The roll: dice, or dice plus or minus a number, or a plain number. No formulas.
trigger	sunrise	Happens when someone presses Dawn.

Dawn isn't automatic: when morning comes in the story, a player or the GM presses Dawn on the sheet (in the Hit Points block of the Form View, the sheet's standard tabbed layout, or the Items panel's header; see Form and Canvas views). A preview shows what will happen, with Wand of Sparks uses rolled (1d4+1) and a Rolled on rest tag for the wand, and the button confirms it. A toast then says how many uses were rolled, and the open sheet shows the new count. The wand recharges even if it isn't equipped. See Hit points and rests.

The trigger names are the game system's rest buttons, and four moments RollQuest notices by itself:

Trigger	When it happens	Systems
longRest	The Long Rest button	5e and 5.5e
shortRest	The Short Rest button	5e and 5.5e
sunrise	The Dawn button	5e and 5.5e
sunset	The Dusk button	5.5e only: a 5e pack that uses it is refused
turnStart	On its own, when the character's turn starts in a battle	Every system
dayStart	On its own, when the game's world clock passes midnight: once for each day that goes by, and no more than seven at a time	Every system
onCast	On its own, when the character casts a spell	Every system
levelUp	On its own, when the character finishes a Level Up	Every system

The four automatic triggers need nothing pressed. A wand that recharges at midnight, rather than when someone presses Dawn, uses dayStart; dayStart only happens in a game whose world clock is running (see World clock). Each one posts a line in chat saying what changed, as a rest button does.

A wand with a saving throw

save in the applies entry makes each target roll a saving throw first. dc fixes the number they need, as wands do; leave it out and the character's own Spell Save DC is used (a character who doesn't cast spells has none, and the GM decides). onSuccess is half (half damage on a success) or negate (none).

{
  "slug": "my-wand-of-cinders",
  "name": "Wand of Cinders (homebrew charged item)",
  "system": "5.5e Compatible",
  "derivedFrom": "5-5e-core",
  "category": "addon",
  "version": "1.0.0",
  "license": "USER_HOMEBREW",
  "source": "My table's homebrew.",
  "attribution": "",
  "description": "",
  "requiredDecisions": [],
  "items": [
    {
      "kind": "inventoryItem",
      "key": "ITEM_WAND_OF_CINDERS",
      "spec": {
        "subType": "item",
        "name": "Wand of Cinders",
        "maxUses": 7,
        "uses": 7,
        "meta": {
          "rarity": "Rare",
          "attunement": true,
          "type": "Wand",
          "description": "7 charges. Spend 1 to spray cinders at a creature: DC 13 Dexterity save, 3d6 fire damage, half on a success. Regains 1d6+1 charges at dawn.",
          "targets": {
            "max": 1
          },
          "applies": [
            {
              "kind": "damage",
              "formula": "=3d6",
              "damageType": "fire",
              "save": {
                "ability": "DEX",
                "onSuccess": "half",
                "dc": 13
              }
            }
          ]
        },
        "actions": [
          {
            "id": "DMG",
            "label": "Cinders",
            "formula": "=3d6",
            "damageType": "fire",
            "tag": "DMG_ROLL"
          }
        ],
        "effects": [
          {
            "id": "WAND_OF_CINDERS_DAWN",
            "target": "SELF.uses",
            "op": "addRandom",
            "value": "1d6+1",
            "condition": "",
            "trigger": "sunrise"
          }
        ]
      }
    }
  ]
}

The target rolls the save on their own sheet, or the GM rolls it for a monster; see Spells and casting for the save card.

Limited uses refreshed on a rest

The same pattern gives any item or feature a number of uses that come back on a rest. Second Breath is a feat that heals once, and comes back on a short or a long rest:

{
  "slug": "my-second-breath",
  "name": "Second Breath (homebrew limited-use feat)",
  "system": "5.5e Compatible",
  "derivedFrom": "5-5e-core",
  "category": "addon",
  "version": "1.0.0",
  "license": "USER_HOMEBREW",
  "source": "My table's homebrew.",
  "attribution": "",
  "description": "",
  "requiredDecisions": [],
  "items": [
    {
      "kind": "inventoryItem",
      "key": "FEAT_SECOND_BREATH",
      "spec": {
        "subType": "feat",
        "id": "FEAT_SECOND_BREATH",
        "name": "Second Breath",
        "maxUses": 1,
        "uses": 1,
        "meta": {
          "category": "General Feat",
          "passive": false,
          "description": "Bonus Action: regain 1d8 + your level Hit Points. Once per Short or Long Rest.",
          "applies": [
            {
              "kind": "heal",
              "formula": "=1d8+LEVEL"
            }
          ],
          "targets": {
            "self": true
          }
        },
        "actions": [
          {
            "id": "HEAL",
            "label": "Heal",
            "formula": "=1d8+LEVEL",
            "damageType": "healing",
            "tag": "HEAL_ROLL"
          }
        ],
        "effects": [
          {
            "id": "SECOND_BREATH_SR",
            "target": "SELF.uses",
            "op": "reset",
            "value": "",
            "condition": "",
            "trigger": "shortRest"
          },
          {
            "id": "SECOND_BREATH_LR",
            "target": "SELF.uses",
            "op": "reset",
            "value": "",
            "condition": "",
            "trigger": "longRest"
          }
        ]
      }
    }
  ]
}

• reset fills the uses back up to maxUses. There's one row for each rest that refills them.
• meta.targets is { "self": true }: Target picks the character's own token, and Resolve adds the healing.
• LEVEL in the formula is the character's level.
• meta.passive is false, because the feat has a button.

Any item with maxUses shows a counter in the Resources block on the Form View's Main tab, named after the item, such as 5/5 between − and +. − marks a use spent and + gives one back, without rolling anything. For an item on the Items tab, the Items panel shows the same count in its Charges / Uses column.

Uses that grow with the character

This charm has uses equal to the proficiency bonus, regains one on a short rest and all on a long rest:

{
  "slug": "my-emberheart-charm",
  "name": "Emberheart Charm (homebrew limited-use item)",
  "system": "5.5e Compatible",
  "derivedFrom": "5-5e-core",
  "category": "addon",
  "version": "1.0.0",
  "license": "USER_HOMEBREW",
  "source": "My table's homebrew.",
  "attribution": "",
  "description": "",
  "requiredDecisions": [],
  "items": [
    {
      "kind": "inventoryItem",
      "key": "ITEM_EMBERHEART_CHARM",
      "spec": {
        "subType": "item",
        "name": "Emberheart Charm",
        "maxUses": 2,
        "uses": 2,
        "meta": {
          "rarity": "Uncommon",
          "attunement": false,
          "type": "Wondrous Item",
          "description": "Add 1d4 to an ability check or saving throw. Uses equal to your Proficiency Bonus; regain one on a Short Rest and all on a Long Rest."
        },
        "actions": [
          {
            "id": "BONUS",
            "label": "Add 1d4",
            "formula": "=1d4",
            "damageType": "",
            "tag": ""
          }
        ],
        "effects": [
          {
            "id": "EMBERHEART_MAX_LR",
            "target": "SELF.maxUses",
            "op": "setToVF",
            "value": "PROF",
            "condition": "",
            "trigger": "longRest"
          },
          {
            "id": "EMBERHEART_SR",
            "target": "SELF.uses",
            "op": "increment",
            "value": 1,
            "condition": "",
            "trigger": "shortRest"
          },
          {
            "id": "EMBERHEART_LR",
            "target": "SELF.uses",
            "op": "reset",
            "value": "",
            "condition": "",
            "trigger": "longRest"
          }
        ]
      }
    }
  ]
}

• SELF.maxUses with setToVF sets the maximum from one of the character's values, here PROF. Put it before the reset row, so the refill uses the new maximum.
• increment with 1 gives back one use; reset gives back all of them.
• Write maxUses and uses as the value at level 1 (a proficiency bonus of 2). The maximum rises as the character does.

setToVF only reads values RollQuest keeps up to date for this purpose: LEVEL, PROF, an ability modifier such as WIS_MOD, a class level such as CLERIC_LEVEL, or a value whose ID ends in _POOL. Anything else is refused.

Uses, charges and rests, field by field

Field	What it does	Allowed values	Checked?
spec.maxUses	How many uses the item has. Shows a counter in Resources.	A whole number. 0 or left out: no uses, the item never runs out.	Yes, with uses.
spec.uses	How many are left when it reaches a sheet.	The same number as maxUses.	Yes: different from maxUses, or missing, is refused.
An effect on SELF.uses	Changes this item's uses when a rest button is pressed.	op: reset (all back), increment (that many back), setTo (exactly that many left), addRandom (a rolled number back). value: a number, or dice for addRandom. A trigger is required.	Yes.
An effect on SELF.maxUses	Changes the maximum when a rest button is pressed.	op: setToVF (from a value), setTo, increment, addRandom.	Yes.

Using an item spends one use per press: on the Form View, the first press each time it's opened. Tick Don't consume resource before the first press to use the item without spending a use.

Two things the check can't fix later:

• The uses printed on a sheet are kept. Once a player has the item, changing maxUses in the pack doesn't change their copy, even after a re-stamp. Only a rest effect on SELF.maxUses moves it. Get the number right before you bind the pack.
• Uses only come back through an effect. An item with maxUses and no rest effect is spent once for good.

5e and 5.5e

Everything on this page works the same in both, except:

• 5e has no Dusk button: sunset is refused in a 5e pack.
• Extra hit points per level are HP_MISC_BONUS in 5e and HP_MAX in 5.5e. A pack that uses the other edition's name is refused.
• 5e (2014) items may write attunement as text, such as "requires attunement". It's shown the same way.

Mistakes that get a pack refused

Code	What you wrote	Fix
USE_BUDGET_INCOHERENT	maxUses with no uses, or a different number.	Make them equal.
TRIGGER_NOT_DECLARED	A trigger that isn't a rest button or one of the four automatic triggers, such as dawn. The message lists the automatic ones as alternatives.	Use sunrise for Dawn (see the table above).
CONSUME_ON_EMPTY_INVALID	consumeOnEmpty on an item with no uses, on one that gets its uses back on a rest, or written as anything but true or false.	Give the item maxUses and an equal uses, remove the rest effect, or remove the flag.
EFFECT_TRIGGER_TARGET_MISMATCH	SELF.uses without a trigger, or a trigger on a plain value such as AC_MISC_BONUS.	Rest effects target SELF.uses or SELF.maxUses and have a trigger; always-on effects target a value and have none.
EFFECT_OP_NOT_ON_CHANNEL	add on SELF.uses.	Use increment.
EFFECT_VALUE_UNPARSEABLE	Dice in an add ("1d4"), or a formula in a rest effect ("=PROF").	Use a number. For a die on a roll, use bonusDie; for a value that changes, use setToVF on SELF.maxUses.
SCALING_SOURCE_UNPUBLISHABLE	setToVF from a value RollQuest doesn't keep up to date, such as MY_USES.	Use PROF, LEVEL, an ability modifier, a class level, or an ID ending in _POOL.
EFFECT_TARGET_UNRESOLVED	A target that doesn't exist, or DMG_ROLL in a pack with no damage button.	Check the ID; give your pack an action tagged DMG_ROLL.
EFFECT_CONDITION_PROSE	A condition in words.	A formula starting with =, or empty.
APPLIES_KIND_UNRECOGNISED	An applies kind such as healing.	damage, heal, condition or effect. A fifth kind, check, puts a test to the target, for systems whose tests are rolled against a number, such as Ashfall.

Every code is explained in When a pack is refused.

Mistakes the check lets through

• No rest effect. The uses never come back.
• Effects on an item that isn't equipped. They don't count until the player clicks Equipped. Tell your players.
• A misspelt rarity or type. It's shown as you wrote it.
• No applies. The item rolls, but there's no Target button and nothing reaches a creature: the Wand of Sparks above only rolls into chat.

Good to know

• As the GM, you can give an item to a character straight away: press Ctrl+K (Cmd+K on a Mac) and type /item with the item's name and the character's, such as /item "Wand of Sparks" @Mara. It finds gear (item and weapon rows) in RollQuest's own packs, in the packs bound to the game, at the revision the game is pinned to, and in the game's own system. An item with choices can't be given this way. See the command palette.
• An item on a sheet is a copy. Pack edits reach it only when you move the game to the new revision and re-stamp, and uses never change that way (see Put your pack on a table).

Related

Weapons and armour · Effects: what an item can change · Spells · Hit points and rests · Inventory and money