User Manual

Effects Reference

The complete catalogue of the effects JSON schema — every key you can put in a custom item's Advanced effects (JSON) box, a custom feature's mechanical effects, or a buff. One schema serves all three; only when it applies differs:

Where the blob lives	When its effects apply
Custom item (My Items → Bonuses tab)	While the item is equipped — and attuned, if it requires attunement
Class feature (Feature Creator → Effects/Defenses)	Always, or only while toggled on if `isToggleable` is set
Active buff (Add Buff → Effects)	While the buff is active

Conventions: ability keys are lowercase three-letter codes (str dex con int wis cha); damage types and conditions are lowercase words (fire, charmed); dice are strings ("1d4") and may carry a flat tail ("1d4+1"), be negative for a malus ("-1d4" — Bane), or fake a flat bonus ("2d1" always rolls 2); every key is optional — include only what the effect grants.

Ability Scores & Saving Throws

Key	Type	Example	What it does
`abilityBonuses`	object	`{"con":2,"int":1}`	Adds to ability scores. Saves, skills, attacks, and AC all follow the modifier.
`abilityOverrides`	object	`{"str":21}`	Sets a score outright ("your Strength is 21"). Doesn't stack; the highest wins, and it loses to a naturally higher score.
`savingThrowProficiencies`	list	`["int","wis"]`	Grants proficiency in those saving throws.
`savingThrowBonusFlat`	number	`1`	Flat bonus to every saving throw (Cloak of Protection).
`savingThrowBonusByAbility`	object	`{"wis":2}`	Flat bonus to one ability's saves only.
`savingThrowBonus`	dice string	`"1d4"`	A die that rides every saving throw and is rolled with it (Bless, Resistance).

Proficiencies, Skills & Languages

Key	Type	Example	What it does
`skillProficiencies`	list	`["arcana","history"]`	Grants skill proficiency.
`skillExpertise`	list	`["stealth"]`	Grants expertise (double proficiency).
`armorProficiencies`	list	`["Light armor","Shields"]`	Armor training.
`weaponProficiencies`	list	`["Simple weapons","Longsword"]`	Weapon training (categories or single weapons).
`toolProficiencies`	list	`["Thieves' tools"]`	Tool training.
`languages`	list	`["Draconic"]`	Languages understood.

Defences

Key	Type	Example	What it does
`damageResistances`	list	`["fire","nonmagical bludgeoning"]`	Half damage of those types. Shows in Resistances & Immunities and auto-applies in the combat tracker.
`damageImmunities`	list	`["poison"]`	No damage of those types.
`damageVulnerabilities`	list	`["fire"]`	Double damage — mostly for DM-built NPCs.
`conditionImmunities`	list	`["charmed","frightened"]`	Cannot suffer those conditions.
`acBonus`	number	`1`	Flat AC bonus — for features and buffs (a fighting style, Shield of Faith). An item's AC bonus belongs in its AC Bonus field on the Bonuses tab, not here.

Attacks & Combat

Key	Type	Example	What it does
`attackRollBonus`	dice string	`"1d4"`	A die that rides every attack roll (Bless). Offered in the roll dialog; unticking a source really removes its die.
`spellAttackBonusFlat`	number	`1`	Flat bonus to spell attack rolls (Wand of the War Mage). For items, prefer the Bonuses-tab field.
`extraAttacks`	number	`1`	Extra attacks per Attack action (1 = two attacks total).
`advantageOnAttacks`	bool	`true`	Advantage on your attack rolls (Reckless Attack, Greater Invisibility). Pre-selects advantage in the roll dialog, named as its source.
`disadvantageOnAttacks`	bool	`true`	The same against you (poisoned, Bestow Curse).
`advantageOnChecks`	list	`["str"]`	Advantage on that ability's checks — including its skills, since a skill check is an ability check. Not attacks, not saves.
`disadvantageOnChecks`	list	`["dex"]`	The same against you.

Movement, Senses & Body

Key	Type	Example	What it does
`speedBonus`	number	`10`	Adds to walking speed (Monk's Unarmored Movement, Mobile).
`grantedSpeeds`	object	`{"fly":60,"swim":40}`	Grants a movement mode at that speed. A granted mode replaces, never adds — don't encode Fly as a speedBonus.
`darkvision`	number	`60`	Grants or extends darkvision to that range.
`hpPerLevel`	number	`1`	Bonus HP per character level (Tough, Draconic Resilience).
`initiativeBonus`	number	`5`	Flat initiative bonus (Alert).
`passivePerceptionBonus`	number	`5`	Flat bonus to passive Perception (Observant).
`passiveInvestigationBonus`	number	`5`	Flat bonus to passive Investigation.
`carryingCapacityMultiplier`	number	`2`	Multiplies carrying capacity (Powerful Build, Bull's Strength).

Toggles (features only)

Key	Type	Example	What it does
`isToggleable`	bool	`true`	The feature gets an on/off switch (Rage, Bladesong); its effects apply only while on.
`toggleLabel`	string	`"Rage"`	What the toggle button says.

conditionalWeaponDamage — extra damage offered at the roll

A list of objects; each becomes a tick box in the attack's damage roll (Dragon Slayer's 3d6 vs dragons, Crimson Rite, the Gloves of Soul Catching):

Field	Example	Meaning
`label`	`"Dragon Slayer"`	Name shown on the tick box.
`dice`	`"3d6"`	The extra damage. May also be a token `"{resource:Hemocraft Die}"` that resolves to a named scaling resource's current die.
`damageType`	`"force"`	Damage type; empty string means "the weapon's own type".
`note`	`"vs dragons"`	When it applies — shown as the tooltip.
`scope`	`"self"`	`"self"` = only this item's own attack rows (weapon enchantments); `"unarmed"` = unarmed strikes only; omit = every weapon attack the character makes.

Example: {"conditionalWeaponDamage":[{"label":"Dragon Slayer","dice":"3d6","damageType":"","note":"vs dragons","scope":"self"}]}

transferable — points the wearer re-routes

A pool of points shifted between uses (see Custom Items for the play-side controls):

Field	Example	Meaning
`amount`	`2`	Pool size. Omit on a weapon to mean "its own magic bonus" (a Defender's +3).
`targets`	`[{"target":"abilityBonuses","key":"str","rate":2},"darkvision"]`	Where points may sit, addressed by the schema's own keys from this reference. Scalar keys go bare (`"darkvision"`, rate 1) or named (`{"target":"darkvision","rate":30}`). Dictionary-valued keys take a `key`: `{"target":"abilityBonuses","key":"str"}`, `{"target":"grantedSpeeds","key":"fly","rate":60}`, `{"target":"savingThrowBonusByAbility","key":"wis"}`. Two documented specials: `attack` (the weapon's own bonus) and `ac`. Valid scalar targets: `speedBonus darkvision initiativeBonus passivePerceptionBonus passiveInvestigationBonus savingThrowBonusFlat spellAttackBonusFlat`. (Older spellings — bare ability codes, rate maps — are still read but never written back.)
`mode`	`"single"`	`"single"` = all points to one target (swap menu on the equipment row); `"split"` = spread freely (stepper dialog). Omitted: split when attack/ac are involved, single otherwise.
`label`	`"Essence"`	What the controls call the pool.

What does NOT go in this JSON

An item's flat weapon bonus, AC bonus, spell attack bonus, or save bonus — those are proper fields on the item's Bonuses tab.

Charges, recharge, and attached spells — the Charges and Spells tabs own those.

Healing — potions are read from their description by the Use button.

Anything requiring an action to activate — that's description text; the sheet models passive, always-on (or toggled) effects.

On seeded items, a curated effects blob replaces the imported 5etools data entirely — if you curate one, it must carry everything the item does, not just the part you're adding.