{"id":17033489,"url":"https://github.com/morgul/rpgdice","last_synced_at":"2025-03-22T17:31:18.112Z","repository":{"id":26927111,"uuid":"30389332","full_name":"Morgul/rpgdice","owner":"Morgul","description":"A generic RPG dice roller syntax and library.","archived":false,"fork":false,"pushed_at":"2023-01-25T00:49:08.000Z","size":1018,"stargazers_count":28,"open_issues_count":3,"forks_count":1,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-13T17:11:16.798Z","etag":null,"topics":["dice-notation","dice-rolls","javascript","parse","pegjs","roll-dice","rpg"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Morgul.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-02-06T01:53:03.000Z","updated_at":"2025-02-08T09:20:10.000Z","dependencies_parsed_at":"2023-02-14T03:16:47.117Z","dependency_job_id":null,"html_url":"https://github.com/Morgul/rpgdice","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Morgul%2Frpgdice","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Morgul%2Frpgdice/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Morgul%2Frpgdice/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Morgul%2Frpgdice/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Morgul","download_url":"https://codeload.github.com/Morgul/rpgdice/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244995091,"owners_count":20544285,"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":["dice-notation","dice-rolls","javascript","parse","pegjs","roll-dice","rpg"],"created_at":"2024-10-14T08:34:59.655Z","updated_at":"2025-03-22T17:31:17.738Z","avatar_url":"https://github.com/Morgul.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RPGDice\n\n![Build Status](https://travis-ci.org/Morgul/rpgdice.svg) [![Language grade: JavaScript](https://img.shields.io/lgtm/grade/javascript/g/Morgul/rpgdice.svg?logo=lgtm\u0026logoWidth=18)](https://lgtm.com/projects/g/Morgul/rpgdice/context:javascript)\n [![Total alerts](https://img.shields.io/lgtm/alerts/g/Morgul/rpgdice.svg?logo=lgtm\u0026logoWidth=18)](https://lgtm.com/projects/g/Morgul/rpgdice/alerts/) [![](https://data.jsdelivr.com/v1/package/npm/rpgdicejs/badge)](https://www.jsdelivr.com/package/npm/rpgdicejs)\n\nThis project is an opinionated dice syntax and roller library designed to be used for any dice-based RPG system. Its\nmain goal is to use a straightforward, easy to use grammar that has enough flexibility to allow players to easily\ncodify their dice rolls. One of its central features, the ability to use variables, exists to facilitate a 'write once'\nphilosophy of dice rolls.\n\n## Dice are Hard\n\nThe single largest complaint I ever hear about a given RPG system is that the dice are \"too complicated\", or \"I can\nnever remember how to roll that\", or \"I keep forgetting my bonuses.\" This is why RPGDice exists: computers are amazing\nat calculations; humans aren't. That's why we let the computer do the hard work of keeping track of everything, and the\nuser just gets to see the results of what they told it to roll.\n\n## Opinionated\n\nThere is a semi-formal [dice notation][] floating around. I personally find its syntax clunky, difficult to use, and\nnearly impossible to extend. Instead, I've created a syntax that is, in essence, mathematical operations, plus\nfunctions,  variables, and `XdY` syntax. I feel my version is easy enough to learn for veterans and newbies alike, while\nleveraging some basic programing concepts, like the [principal of least surprise][pola].\n\n[dice notation]: http://en.wikipedia.org/wiki/Dice_notation\n[pola]: http://en.wikipedia.org/wiki/Principle_of_least_astonishment\n\n## Usage\n\n### Getting RPGDice\n\nOur recommended way is via npm:\n\n```bash\n$ npm install --save rpgdicejs\n```\n\nOr with `yarn`:\n\n```bash\n$ yarn add rpgdicejs\n```\n\nNow, if you want to use this in a browser, any of the major bundlers should be able to handle this module just fine. It \nshould be noted that as this is still a CJS module, you may be required to do some work, but it has no dependencies, \nand works in both node and the browser, so bundling it should be easy.\n\nWe used to provide a bundled version but have removed it in an interest of maintainability. In the future the code base \nwill be converted to typescript, and at that time we'll provide UMD, CJS and ESM module versions for easy consumption.\n\n### Syntax Summary\n\n`d20 + floor(level / 2) + floor(('strength.score' - 10) / 2) + proficiency + 'Weapon Enhancement' + [Misc.Attack.Bonus]`\n\nAs you can see, the syntax is very nearly a super-simplified version of javascript. It supports standard order of\noperations, `XdY` for rolls, function calls, and variables. (This particular roll is the formula for a D\u0026D 4e attack, \nwith the added pathology of showing all the various ways of escaping variables.)\n\nWhen you make a roll, you will pass in a `scope` object, which RPGDice will use to look up all variables and functions.\nBy default, we provide several mathematical functions, such as `min()`, `max()`, `floor()`, `ceil()`, `round()`. \nAdditionally, we provide some common RPG rules: `explode()`, `dropLowest()`, `dropHighest()`, `reroll()`.\n\nIf you set a variable on the `scope` to a function, but reference it without parenthesis, RPGDice will call it, passing\nin no arguments. Ex: `3d8 + strMod`, where `strMod` was defined as:\n\n```javascript\nfunction strMod()\n{\n    return Math.floor((scope.strength - 10) / 2);\n} // end strMod\n```\n\nThis gives you a lot of power in how you define your scope. You can additionally extend the functionality to support any\nrule set your heart desires, without needing explicit support in the syntax. For example, let's say you wanted to play\nwith loaded dice. There's no special syntax support for that, but you can add it yourself:\n\n```javascript\nfunction rollLoaded(sides)\n{\n    var roll = Math.floor(Math.random() * sides) + 1;\n\n    // We make ourselves 3 times as likely to roll max, and impossible to roll the minimum.\n    // Simply returning the max might look suspicious. :-p\n    if(roll \u003c sides/3)\n    {\n        return sides;\n    } // end if\n\n    return roll;\n} // end strMod\n```\n\nNow, you can roll your loaded dice like such:\n\n`3(rollLoaded(6)) + 4`\n\nThis expression calls `rollLoaded(6)` three times, and then adds `4`. It's the equivalent to `3d4`, except the dice\nrolling logic has been replaced by your loaded dice rules. Functions get the full results object, which includes the\nparse tree for each expression they get as an argument, which means functions can be incredibly powerful.\n\n_If you would like to dive further into the syntax, please check out our \n[Syntax Documentation](https://github.com/Morgul/rpgdice/wiki/Syntax-Documentation)._\n\n### API\n\nThe API for rolling dice is super simple. There are exactly 2 functions, `rpgdice.parse()` and `rpgdice.eval()`. Each\ntake a dice string to parse, and only differ in what they output; `parse()` simply returns you the tokenized roll as a \nparse tree, while `eval()` will return you a populated version of the parse tree. (The final result is in the `value`\nproperty of the root node.) Additionally, `roll()` can take a parse tree (such as the results of `parse()`) not just a \nstring. This allows for a small optimization by only needing to tokenize the expression once, and calling `eval()` \nmultiple times.\n\nHere's a few examples:\n\n```javascript\n// Roll a simple equation\nvar results = rpgDice.roll('3d6 + 4');\n\n// Render the results as a string\nconsole.log('Results:', results.render());\n\n// Print the final result:\nconsole.log('Total:', results.value);\n\n//----------------------------------------------------------------\n\n// Evaluate an expression\nvar eval = rpgDice.parse('3(4d10 - 2)')\n\n// Maybe do something with the evaluated expresion\n\n// Now, get the results for this roll\nvar results = rpgDice.roll(eval);\n```\n\n#### Expression API\n\nThe results of `rpgdice.parse()` and `rpgdice.eval()` are `Expression` objects. These represent the parse tree of the \nexpression. While for a general use case you won't need the power they provide, they do expose a few useful functions:\n\n* `render()` - Renders a parse tree to a string. If the parse tree has been evaluated, it includes the intermediate results.\n* `eval()` - Evaluates the parse tree from this node down. (This is the same as passing the `Expression` object to `rpgdice.eval()`.\n\n\n_For more details on the API, please check out our \n[API Documentation](https://github.com/Morgul/rpgdice/wiki/API-Documentation)._\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmorgul%2Frpgdice","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmorgul%2Frpgdice","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmorgul%2Frpgdice/lists"}