{"id":24529251,"url":"https://github.com/emdienn/dice-note","last_synced_at":"2025-03-15T17:46:04.483Z","repository":{"id":90851371,"uuid":"430909837","full_name":"emdienn/dice-note","owner":"emdienn","description":"Dice notation interpreter","archived":false,"fork":false,"pushed_at":"2021-11-23T00:56:16.000Z","size":90,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-22T07:37:54.584Z","etag":null,"topics":["d20","dice","notation","roller"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/dice-note","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/emdienn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-11-23T00:35:23.000Z","updated_at":"2022-12-10T16:52:10.000Z","dependencies_parsed_at":null,"dependency_job_id":"266c1d08-b383-44ed-940d-54ae1fdb457b","html_url":"https://github.com/emdienn/dice-note","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emdienn%2Fdice-note","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emdienn%2Fdice-note/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emdienn%2Fdice-note/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emdienn%2Fdice-note/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/emdienn","download_url":"https://codeload.github.com/emdienn/dice-note/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243769949,"owners_count":20345215,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["d20","dice","notation","roller"],"created_at":"2025-01-22T07:35:38.357Z","updated_at":"2025-03-15T17:46:04.477Z","avatar_url":"https://github.com/emdienn.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Dice Note\n\nDice notation interpreter, for all your digital dice rolling needs (except the\nactual rolling).\n\n## Installation\n\nInstall any way you normally get node packages onto your computer. I tend to use:\n```sh\nnpm i dice-note\n```\n\n## What even is this?\n\nDice Note is fundamentally a string parser, designed to abstract away needing to\nthink too hard about the outcomes of dice rolls when making games or\napplications that require such things. Think: table-top role-play games, but\nonline.\n\n## What does it do\n\nDN accepts a string representation of a dice roll, eg. `d6`, `4d8+4` or\n`2d20kH+3`.\n\nThese can be quite complex at times, given various games require semantics like\n\"roll with advantage\" or \"drop lowest `n` values\", etc.\n\nAs output, the initial `prepare()` function will provide a list of dice your\napplication needs to \"roll\" (by whatever mechanism you care to use), and a\n`result() `function into which those raw dice results can be put, which will\nthen itself return the final numeric result(s).\n\nIt will also validate a string for you\u0026mdash;tell you whether or not it's valid\nnotation.\n\n## What doesn't it do\n\nSpecifically, DN does *not* roll dice for you. That's left to the application's\ndiscretion, because you may want to use a random number generator, a THREE.js\ndice roller, or fudge the numbers in any given circumstance.\n\n## How does it work?\n\nLess tell, more show:\n\n```ts\nimport { prepare } from 'dice-note'\n\n// A simple example to start: two d6 die\nconst { dice, result } = prepare('2d6')\n// dice = [ \"d6\", \"d6\" ]\n\n// Let's fudge those numbers, but we could use RNG to get this result.\n\n// Remember that it's important that the INDEX of the result matches that of\n// the dice from the `dice` array\nconst weRolled = [ 2, 6 ]\n\nconst outcome = result(weRolled)\n// outcome = [ 8 ]\n```\n\nDice Note expects the following constraints on the array input into the `result`\nfunction:\n - all array elements are numbers\n - the length of the array matches that of `dice`, given from the `prepare`\n   function\n - each element in the roll results array (`weRolled`, above) must positionally\n   match the die for which it was rolled, ie. their index in the array must be\n   the same\n\n\nYou may notice that the \"preparation step\" and the \"execution step\" have been\nseparated. This is on purpose, one of the benefits of which is that you can\nrun the same roll more than once without having to redo the execution-plan step.\n\nTo that end, if certain rolls are going to be executed frequently, for\nperformance it would be beneficial for your application to cache the execution\nplan, rather than recompute it every time.\n\n## More complex examples\n\n### Selective results\n\nDropping or keeping certain results within a roll is common (eg. to roll with\nadvantage or disadvantage). While supporting every possible variant notation\nisn't possible, the following quasi-standard notations should provide enough\nflexibility to support most scenarios.\n\nTo **drop** dice, the following notations are supported:\n - `-(n)H` (eg. 4d6-2H) - drop the highest 2 results\n - `-(n)L` (eg. 4d6-L) - drop the lowest 1 (implied) result\n - `dL(n)` (eg. 4d6dL2) - drop the lowest 2 results (`n` can be omitted if 1)\n - `dH(n)` (eg. 4d6dH1) - drop the highest 1 result (`n` can be omitted if 1)\n\nTo **keep** dice, the following notations are supported:\n - `+(n)L` (eg. 4d6+2L) - keep the lowest 2 results\n - `+(n)H` (eg. 4d6+H) - keep the highest 1 (implied) result\n - `kH(n)` (eg. 4d6kH2) - keep the highest 2 (`n` can be omitted if 1)\n - `kL(n)` (eg. 4d6kL1) - keep the lowest 1 (`n` can be omitted if 1)\n\n```ts\nimport { prepare } from 'dice-note'\n\nconst rollWithDisadvantage = '2d20dH'\nconst rollWithAdvantage = '2d20+H'\n\nconst dis = prepare(rollWithDisadvantage)\nconst adv = prepare(rollWithAdvantage)\n// dis.dice = adv.dice = [ \"d20\", \"d20\" ]\n\nconst roll = [ 19, 4 ]\n\nconst disOutcome = dis.result(roll)\n// disOutcome = [ 4 ]\n\nconst advOutcome = adv.result(roll)\n// advOutcome = [ 19 ]\n```\n\n### Player's choice\n\nIn some games, the player can choose which value they want to apply, rather\nthan sum the results. For Dice Note, this is represented with a suffix of 'c'\non the dice notation, eg. `2d20c`.\n\nUsing the choice option should be used sparingly, and on not-too-complicated\nrolls; the more complicated a roll, the more likely players will wonder how the\nresults they got were derived, and whether or not your application is cheating.\n\n_Note that it is not possible with Dice Note to combine 'c' with 'k' or 'd'._\n\n```ts\nimport { prepare } from 'dice-note'\n\nconst { dice, result } = prepare('2d20c+4')\n// dice = [ \"d20\", \"d20\" ]\n\nconst outcome = result([ 17, 3 ])\n// if there were no 'c' term, the 17 and 3 would be summed; instead, the +4 is\n// applied to each roll before being included in the output\n// outcome = [ 21, 7 ]\n```\n\nThis feature can also be used to emulate situations such as Dungeons \u0026amp;\nDragons' \"Magic Bullet\" spell, where 3 or more dice are rolled, but all the\ndice values are used separately:\n\n```ts\nimport { prepare } from 'dice-note'\n\nconst { dice, result } = prepare('3d4c+1') // magic bullet cast at level 1\n// dice = [ \"d4\", \"d4\", \"d4\" ]\n\nconst outcome = result([ 4, 2, 3 ])\n// outcome = [ 5, 3, 4 ]\n```\n\n### Arithmetic\n\nDice Note supports basic addition and substraction of modifiers. Multiplication\nand division are not supported.\n\n#### Adding a modifier\n```ts\nimport { prepare } from 'dice-note'\n\nconst { dice, result } = prepare('d20+7')\n// dice = [ \"d20\" ]\n\nconst outcome = result([ 11 ])\n// outcome = [ 18 ]\n```\n\n## Validation\n\nThe `validate` function is intended as a lightweight (as in, per-keystroke)\nmeans to prevent invalid notations hitting the more complex\u0026mdash; and thus\nslower\u0026mdash;logic.\n\n```ts\nimport { validate } from 'dice-note'\n\nconst valid = validate('4+2d20-2')\n// valid = true\n```\n\n## Licence\n\nMIT\n\n## Bugs and Issues\n\nPlease use GitHub's issue tracker to report bugs.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femdienn%2Fdice-note","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Femdienn%2Fdice-note","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femdienn%2Fdice-note/lists"}