{
  "schema": "leumas.docs.page/1",
  "id": "adapter:domain/dice",
  "slug": "adapters/domain/dice",
  "kind": "capabilities",
  "bucket": "package",
  "title": "dice — TTRPG randomness pack",
  "name": "dice",
  "eyebrow": "TTRPG randomness pack",
  "chip": null,
  "summary": "TTRPG randomness pack: parse and roll dice notation (3d6+2, 2d20, 1d100/d%, 4d6kh3, 2d20kl1) with keep/drop highest/lowest, multiple terms and modifiers; advantage/disadvantage rolls; ability-score...",
  "keywords": [
    "dice",
    "ttrpg",
    "2d20",
    "1d100",
    "4d6kh3",
    "lowest",
    "advantage",
    "ability-score"
  ],
  "audience": "both",
  "funnel": {
    "product": null,
    "cta": null
  },
  "body": "# dice — TTRPG randomness pack\n\nA self-contained dice roller and tabletop random-helper adapter system. Pure JS, zero deps.\n\n## What it is\n\nParse and roll standard dice notation, generate ability scores, flip coins, pick/shuffle,\ndraw from weighted loot tables, and roll up a simple RPG creature stat block. Every rolling\ntool accepts an optional numeric `seed` for reproducible results (mulberry32); omit it for\n`Math.random()`.\n\n## Tools\n\n| Tool | Args | Returns |\n|---|---|---|\n| `roll` | `{ notation, seed? }` | `{ total, rolls, notation, breakdown }` |\n| `rollAdvantage` | `{ seed?, modifier? }` | 2d20 keep highest + modifier |\n| `rollDisadvantage` | `{ seed?, modifier? }` | 2d20 keep lowest + modifier |\n| `rollStats` | `{ method='4d6kh3', count=6, seed? }` | ability-score array + detail |\n| `coinFlip` | `{ count=1, seed? }` | one flip or an array + heads/tails counts |\n| `randomPick` | `{ items:[], count=1, seed? }` | sample without replacement |\n| `shuffle` | `{ items:[], seed? }` | Fisher-Yates shuffled array |\n| `lootTable` | `{ table:[{item,weight}], rolls=1, seed? }` | weighted random draw(s) |\n| `statBlock` | `{ level?, seed? }` | a simple creature stat block |\n\n## Notation\n\n`roll` understands multiple terms, modifiers, percentile dice, and keep/drop:\n\n- `3d6+2`, `2d20`, `1d100`, `d%` (== d100)\n- `4d6kh3` — roll 4d6, keep highest 3 (classic ability score)\n- `2d20kl1` — keep lowest 1 (disadvantage); `2d20kh1` is advantage\n- `dh`/`dl` — drop highest / drop lowest\n- `2d6+1d4+3` — any number of dice terms and flat modifiers\n\n## Usage\n\n```js\nimport dice from './index.js';\n\ndice.adapters.roll({ notation: '3d6+2' });\n// { total: 14, rolls: [4,5,3], notation: '3d6+2', breakdown: [...] }\n\ndice.adapters.roll({ notation: '4d6kh3' });\n// rolls 4 dice, keeps the highest 3\n\ndice.adapters.lootTable({ table: [{ item: 'gold', weight: 10 }, { item: 'sword', weight: 1 }], rolls: 3 });\n```\n\n## DRY boundary\n\n**dice owns randomness** for the ecosystem — random draws, shuffles, weighted picks, and dice.\nThe `array` pack stays deterministic (chunk/flatten/unique/rotate never randomize). If you need\na random shuffle or a weighted draw, call `dice`; reach for `array` only for structural transforms.\n",
  "source": {
    "path": "shared/engines/adapters/domain/dice/README.md",
    "blobSha": "",
    "commit": "",
    "committedAt": "",
    "provenance": "no-git",
    "bytes": 2411,
    "hash": "bb4f196007f7155323179a5559a1463329f5a512"
  },
  "urls": {
    "html": "/p/adapters/domain/dice",
    "json": "/docs/adapters/domain/dice.json",
    "md": "/docs/adapters/domain/dice.md"
  },
  "links": {
    "composes": [],
    "usedBy": [],
    "product": [],
    "howTo": [],
    "skills": []
  }
}