@capsuleer/dice

Dice roller and randomness module for Capsuleer agents. Roll dice in standard RPG notation, flip coins, and pick random items from lists — with every roll traced so you always know what fate decided.

capsuleer install dice

Genuinely useful. Suspiciously fun.

API

Rolling dice

// Standard RPG notation: NdX[+/-modifier]
const attack = await dice.roll("1d20+5")
// → { notation: "1d20+5", rolls: [14], modifier: 5, total: 19, min: 6, max: 25 }

const damage = await dice.roll("2d6+3")
// → { notation: "2d6+3", rolls: [4, 6], modifier: 3, total: 13, min: 5, max: 15 }

// Just a d20
const check = await dice.roll("d20")

// Handful of d6s
const fireball = await dice.roll("8d6")

Simulations

// Roll the same notation many times and get summary stats
const sim = await dice.rollMany("2d6", 1000)
// → {
//     rolls: [...],          // all 1000 results
//     totals: [7, 4, 11, ...],
//     stats: { mean: 7.02, min: 2, max: 12 }
//   }

Great for probability exploration — ask an agent "what's the average damage of 3d8+5 over 500 attacks?"

Coin flips

// Single flip
const flip = await dice.coin()
// → { flips: 1, results: ["heads"], heads: 1, tails: 0 }

// Many flips
const trial = await dice.coin(100)
// → { flips: 100, results: [...], heads: 53, tails: 47 }

Random selection

// Pick one random item
const winner = await dice.pick(["Alice", "Bob", "Carol", "Dave"])
// → ["Carol"]

// Pick multiple (without replacement)
const team = await dice.pick(["Alice", "Bob", "Carol", "Dave", "Eve"], 3)
// → ["Eve", "Alice", "Carol"]

Observability

{ "ok": true, "op": "dice.roll", "data": { "notation": "2d6+3", "rolls": [4, 6], "modifier": 3, "total": 13, "min": 5, "max": 15 } }
{ "ok": true, "op": "dice.rollMany", "data": { "notation": "2d6", "times": 1000, "stats": { "mean": 7.02, "min": 2, "max": 12 } } }
{ "ok": true, "op": "dice.coin", "data": { "flips": 100, "heads": 53, "tails": 47 } }
{ "ok": true, "op": "dice.pick", "data": { "from": 4, "count": 1, "result": ["Carol"] } }

Notation reference

| Notation | Meaning | |---|---| | d20 | One twenty-sided die | | 2d6 | Two six-sided dice, summed | | 1d20+5 | One d20 plus a +5 modifier | | 4d6-1 | Four d6s minus 1 | | 100d1 | Deeply philosophical |

Limits: 1–1000 dice, 2–10000 sides, modifier is any integer.

Policy

const capsule = await Capsule({
  policy: {
    dice: {
      roll: true,
      rollMany: true,
      coin: true,
      pick: true,
    }
  }
})

See the policy docs for the full rule syntax.