{"id":21434062,"url":"https://github.com/bernardo-mg/dice-notation-java","last_synced_at":"2025-10-03T18:54:49.819Z","repository":{"id":28701411,"uuid":"32221798","full_name":"Bernardo-MG/dice-notation-java","owner":"Bernardo-MG","description":"Tools and parsers for handling Dice/RPG notation using Java","archived":false,"fork":false,"pushed_at":"2024-01-07T23:01:24.000Z","size":2178,"stargazers_count":16,"open_issues_count":8,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-11-13T15:54:44.263Z","etag":null,"topics":["antlr4","dice","dice-notation","dice-roller","parser"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Bernardo-MG.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":"2015-03-14T16:46:44.000Z","updated_at":"2024-08-04T16:56:55.000Z","dependencies_parsed_at":"2024-11-13T21:01:46.366Z","dependency_job_id":null,"html_url":"https://github.com/Bernardo-MG/dice-notation-java","commit_stats":null,"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bernardo-MG%2Fdice-notation-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bernardo-MG%2Fdice-notation-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bernardo-MG%2Fdice-notation-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bernardo-MG%2Fdice-notation-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Bernardo-MG","download_url":"https://codeload.github.com/Bernardo-MG/dice-notation-java/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225980898,"owners_count":17554919,"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":["antlr4","dice","dice-notation","dice-roller","parser"],"created_at":"2024-11-22T23:32:58.727Z","updated_at":"2025-10-03T18:54:44.780Z","avatar_url":"https://github.com/Bernardo-MG.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Dice Notation Tools for Java\n\nThis project aims to make the dice notation readable by Java applications, and for this it offers both a model representing it and a parser which can instantiate the model from dice notation expressions.\n\nCreated on the late 70s for Dungeons \u0026 Dragons, the dice notation has become a standard on tabletop games as it allows generating random values in concrete distributions with the help of simple formulas such as '2d6+5', which means \"roll two dice, add their values and then add the number five to the result\".\n\nWith the pass of years it has evolved, and while it never underwent a formal standardization process a core set of rules is kept among all the variations, mostly representing dice in a format such as '1d6', and the use of algebra operations like addition and subtraction.\n\nIts usefulness is very clear, it allows working with specific random values distributions. And while this is no feat for a machine, which has better tools for it, the aim of the project is not actually handling those distributions, but giving a way for applications to work with the same tools a board game would have.\n\n[![Maven Central](https://img.shields.io/maven-central/v/com.bernardomg.tabletop/dice.svg)][maven-repo]\n\n## Features\n\n- ANTLR4 grammar\n- Model for dice and dice notation, along classes to generate values from them\n- Parser to create model instances from the notation\n- Allows custom random number generation\n- Arithmetic operations (addition, subtraction, multiplication, integer division)\n- Parenthesis support\n\n## Limitations\n\n- Currently only the most basic operations (dice, numbers and additions or subtractions) are supported\n\n## ANTLR4 grammars\n\nThe grammar is included among the [ANTLR4 sample grammars][antrl-grammars].\n\n## Related projects\n\n- [Dice Notation Tools CLI][dice-notation-java-cli], a CLI to roll expressions through line command\n\n## Documentation\n\nThe documentation site sources come along the source code (as it is a Maven site), so it is always possible to generate them using the following Maven command:\n\n```\nmvn verify site\n```\n\nThe verify phase is required, as otherwise some of the reports won't be created.\n\n## Usage\n\nThe application is coded in Java, using Maven to manage the project.\n\n### Prerequisites\n\nJDK 8 or higher is required. All other dependencies are handled through Maven, and noted in the included POM file.\n\n### Installing\n\nThe recommended way to install the project is by setting it up as a dependency. To get the configuration information for this check the [Maven Central Repository][maven-repo].\n\nIt is always possible installing it by using the usual Maven command:\n\n```\nmvn install\n```\n\n### Usage example\n\nThe project includes model, BNF grammar and parsers, which allow working with the most common dice notation expressions.\n\nYou may parse an expression, and generate a random value, like this:\n\n```java\nfinal DiceParser parser;\nfinal RollHistory rolls;\nfinal DiceInterpreter\u003cRollHistory\u003e roller;\n\nparser = new DefaultDiceParser();\nroller = new DiceRoller();\n\nrolls = parser.parse(\"1d6+12\", roller);\n\n// Prints the final result\nSystem.out.println(rolls.getTotalRoll());\n```\n\nFor more examples and details check the documentation.\n\n## Collaborate\n\nAny kind of help with the project will be well received, and there are two main ways to give such help:\n\n- Reporting errors and asking for extensions through the issues management\n- or forking the repository and extending the project\n\n### Issues management\n\nIssues are managed at the GitHub [project issues tracker][issues], where any Github user may report bugs or ask for new features.\n\n### Getting the code\n\nIf you wish to fork or modify the code, visit the [GitHub project page][scm], where the latest versions are always kept. Check the 'master' branch for the latest release, and the 'develop' for the current, and stable, development version.\n\n## License\n\nThe project has been released under version 2.0 of the [Apache License][license].\n\n[antrl-grammars]: https://github.com/antlr/grammars-v4\n[maven-repo]: http://mvnrepository.com/artifact/com.bernardomg.tabletop/dice\n[issues]: https://github.com/Bernardo-MG/dice-notation-java/issues\n[license]: http://www.apache.org/licenses/LICENSE-2.0\n[scm]: http://github.com/Bernardo-MG/dice-notation-java\n\n[dice-notation-java-cli]: https://github.com/Bernardo-MG/dice-notation-java-cli\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbernardo-mg%2Fdice-notation-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbernardo-mg%2Fdice-notation-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbernardo-mg%2Fdice-notation-java/lists"}