Whether you're a seasoned tabletop veteran or brand new to dice rolling, this guide will get you up and running with Alchemy's dice system. We'll start simple and build up to the more powerful features.

To roll dice, just type /roll (or /r for short) followed by your dice notation:

The format is pretty straightforward: the number before the "d" is how many dice you're rolling, and the number after is how many sides each die has. So 2d6 means "roll two six-sided dice."

You can add, subtract, multiply, and do all sorts of math:

Alchemy uses the rpg-dice-roller library under the hood, which supports a ton of advanced dice mechanics. Here are a few highlights:

- Exploding dice: (roll again on max value): 1d6! — Learn more

- Reroll certain values: 2d6r1 (reroll 1s) — Learn more

- Keep highest/lowest: 4d6kh3 (roll 4, keep highest 3) — Learn more

- Drop highest/lowest: 4d6dl1 (roll 4, drop lowest 1) — Learn more

For the full list of what you can do, check out the complete notation guide.

Here's where things get fun. If you have a character selected, you can pull values directly from your character sheet into your rolls using square brackets and the `$attribute()`, `$skill()`, and `$tracker()` functions.

Use `$attribute()` to reference your character's attribute values in rolls:

If you want the modifier (the +2 or -1 you'd add to a roll) instead of the raw score, use the `useModifier` option:

Use `$skill()` to reference your character's skills:

Here's something neat: by default, `$skill()` gives you just the skill value on its own. But if a skill is linked to an ability (like Athletics is linked to Strength), you can include that linked attribute automatically:

This adds your Athletics bonus _and_ your Strength value together in one go.

Want the linked attribute's _modifier_ instead of its raw value? There's an option for that too:

And just like attributes, you can grab a skill's modifier/bonus value:

If your character sheet has custom attributes, you can use those too:

Here's where it gets really powerful. Attributes and skills don't have to be plain numbers — they can be dice themselves. If your game system uses a die rating instead of a flat bonus (like "Strength: d8" instead of "Strength: 14"), Alchemy handles that automatically.

When an attribute or skill has a die assigned to it, using it in a roll will roll that die:

If your Strength is set to a d8, this just rolls 1d8. No need to type out the dice notation yourself.

You can combine these with other dice too:

If Might is a d10 and Agility is a d6, this rolls 1d10 + 1d6 and adds them together.

This works great for systems where characters have die ratings that improve over time — just update the die on your character sheet, and all your rolls automatically use the new value.

You can mix dice-based attributes with regular modifiers:

If Athletics has a d6 assigned, that second roll becomes 1d20 + 1d6. The system figures out what to roll based on what's on your sheet.

You can pull values from your character's trackers (health bars, pip trackers, clocks, etc.) directly into your rolls using the `$tracker()` function.

Use the tracker's `Automation ID` to grab its current value:

If your HP tracker is at 15, the first example rolls 1d20+15.

Need the tracker's maximum instead of its current value? Use the `useMaximum` option:

If your HP tracker has a max of 30, this rolls 1d20+30.

Two-state pip trackers are a little special. Each pip can be empty, half-filled, or fully filled. When you reference one in a roll, Alchemy adds up all the pip states (empty = 0, half = 0.5, full = 1) to get a total value.

Since dice rolls need whole numbers, fractional totals get rounded down by default:

If your stress tracker has 5 pips set to: full, full, half, empty, empty — that's 1 + 1 + 0.5 + 0 + 0 = 2.5, which rounds down to **2**.

Want to round up instead? Use the `roundUp` option:

That same 2.5 would round up to **3**.

You can also explicitly say round down if you want to be clear about it:

If you have multiple trackers with the same name but different types, you can specify which type you mean:

Tag picker trackers work a bit differently. By default, referencing one returns the total number of tags:

If you have 3 conditions applied, this rolls 1d20-3.

You can count how many times a specific tag appears:

If "weary" appears twice in your conditions, this rolls 1d20-2.

Or count only unique tags (ignoring duplicates):

Sometimes you don't know what bonus to add until you roll. Maybe it depends on the situation, or maybe you want to pick which skill to use on the fly. That's what prompts are for.

Add `[$prompt]` anywhere in your roll, and you'll be asked to enter a value when you use it:

When you run this, a little dialog pops up asking for a number. Whatever you enter gets plugged into the roll.

Want to pick a skill or attribute from a dropdown instead of typing a number? Use these:

When you roll, you'll get a dropdown menu showing all your character's skills (or attributes) to choose from.

You can give your prompts labels and constraints to make them clearer:

- `name` — what to call it in the prompt dialog

- `min` and `max` — limit what numbers can be entered

- `default` — the starting value

You can combine these however you like:

When you're building actions (the buttons on your character sheet), there's a special variable called $current that makes your actions reusable across multiple skills or attributes.

Here's the idea: instead of hardcoding a specific skill or attribute name into an action's roll, you can use `$current` and it will automatically resolve to whichever skill or attribute triggered the action. This means you can write one action and attach it to many different skills or attributes without duplicating anything.

Use `$current` inside an action's roll expression, and it gets replaced with the skill or attribute the action was triggered from:

1d20+[$current]

If this action is triggered from your Athletics skill, it becomes

1d20+[$skill(athletics)]

If triggered from your **Strength** attribute, it becomes

1d20+[$attribute(strength)]

Use $currentMod to get the modifier value instead of the raw value:

1d20+[$current(attributeORskill, {useModifier: true})]

For more control, you can use the function notation form of `$current`, which lets you specify whether you're referencing the skill or the attribute and pass options:

1d20+[$current(skill)]

1d20+[$current(attribute)]

1d20+[$current(skill, {useAttachedAttribute: true})]

1d20+[$current(attribute, {useModifier: true})]

1d20+[$current(skill, {useAttachedAttributeMod: true})]

This is useful when an action is triggered from a skill row but you need to reference both the skill and its linked attribute separately, or you specifically need the modifier form.

A reusable "Skill Check" action:

1d20+[$current(skill, {useAttachedAttributeMod: true})]

Attach this to Athletics, Stealth, Perception — whatever. When triggered, it automatically rolls 1d20 plus that skill's value and its linked attribute's modifier.

Combining $current with prompts:

[$current]+[$prompt(value, {name: "Bonus/Penalty Dice"})]

This grabs the current skill or attribute value and asks for a situational modifier on top.

Using $current in computed dice counts:

([$current]+1)d6

If the triggering attribute has a value of 3, this rolls 4d6.

If an action using `$current` is triggered without a skill or attribute context (for example, from a standalone action button), $current and $currentMod resolve to 0. The intent for $current is to be used in conjunction with custom systems via the System Builder section of the app in the GAME tab via the Skills Panel that reference Attribute and Skill blocks.

Using this command in anything but those will always result in an evaluation of 0!

Some game systems don't just add up dice — they count how many dice hit a target number. Alchemy handles this with comparison operators.

Roll some dice and see how many meet a threshold:

This rolls 4 six-sided dice and counts how many show 5 or higher. If you rolled 3, 5, 6, 2, the result would be **2 successes** (the 5 and the 6).

You've got options:

| Operator | Meaning | Example |

| -------- | --------------------- | -------- |

| `>=` | Greater than or equal | `4d6>=5` |

| `>` | Greater than | `4d6>4` |

| `<=` | Less than or equal | `4d6<=2` |

| `<` | Less than | `4d6<3` |

| `=` | Exactly equal | `4d6=6` |

Need to calculate your target number? You can do math on it:

This sets the target to 6 (since 8-2=6), then counts successes against that.

Sometimes you need to roll different dice together and compare the result as a group. That's where curly braces `{}` come in.

Wrap dice in braces with `+` between them to add their results before comparing:

This rolls a d6 and a d8, adds them together, and checks if the total is 10 or higher. You get one success or zero — it's all or nothing.

You can include modifiers too:

Use commas instead of plus signs to check each die separately:

This rolls all three dice, then checks each one individually against the target. If the d4 shows 2, the d6 shows 5, and the d8 shows 7, you'd get **2 successes** (the 5 and 7 beat 4, but the 2 doesn't).

This is great for games where you roll a pool of mixed dice and count how many succeed.

If your game uses non-standard dice — like Fate dice, stress dice, or anything with custom faces — you can define them in the **System Builder** under the **Dice** tab and give each one a name. Once you've done that, you can use them in any roll with the `c()` notation.

The format is just like regular dice, but with `c(diceName)` instead of a number of sides:

The number before `c` is how many of that die to roll, and the name in parentheses matches whatever you called the die in System Builder. So `3c(stress)` means "roll three stress dice."

Custom dice work anywhere a regular die would. You can combine them with standard dice, modifiers, character sheet references — all of it:

Custom dice work in actions too, including with `$current`:

If you haven't set up your custom dice yet, head to the Game tab, open System Builder, and check out the Dice tab to create them.

Want to label your roll so everyone knows what it's for? Just add text after your dice notation:

The description shows up alongside your roll result, so it's clear what you were rolling for.

Here are some examples combining multiple features:

/roll 1d20+[$attribute(strength, {useModifier: true})]+[$prompt(value, {name: "Situational Bonus"})] Melee attack

Once you get the hang of it, you can build rolls for just about any game system. Happy rolling!