From e4e2122d816791bcc20d29917e51b188bacc1e0f Mon Sep 17 00:00:00 2001 From: jeff Date: Sat, 22 Aug 2020 23:51:51 +0000 Subject: [PATCH] Update readme about the fork. --- README.md | 83 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 46 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 9e94cd6..7fb13bb 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,18 @@ # axfive-matrix-dicebot -Just a simple dicebot for matrix written in Rust. It might have some sort of -stability issues. I haven't seen it die in the wild, but it's mostly -hacked-together code that has been pretty lightly tested and reviewed, and I'm -certain that some things are still left undone, like interacting properly with -rate-limiting, and dealing with any sort of sporadic error (like being suddenly -deauthenticated and having to reauthenticate). - -This was mostly built as a fun way of - -* Experimenting with writing an async program in Rust that does something real -* Experimenting with writing a bot for Matrix -* Experimenting with writing a simple parser using [nom](https://github.com/Geal/nom) - -All of which was new territory for me. +This is a fork of the +[axfive-matrix-dicebot](https://gitlab.com/Taywee/axfive-matrix-dicebot) +with basic support for the Chronicles of Darkness 2E Storytelling +System, with future plans to extend the codebase further to support +variables and perhaps character sheet management. ## Usage -To use it, you can invite the bot (@axfive-dicebot:matrix.org) to any room you -want, and it will automatically jump in. Then you can simply give a dice -expression as such: +To use it, you can invite the bot to any room you want, and it will +automatically jump in. Then you can simply give a dice expressions for +either the Storytelling System or more traditional RPG dice rolls. + +The commands `!roll` and `!r` can handle arbitrary dice roll expressions. ``` !roll 4d6 @@ -27,11 +20,31 @@ expression as such: !r 3d12 - 5d2 + 3 - 7d3 + 20d20 ``` -And the dicebot should reply with the result in short order. +The commands `!pool` (or `!rp`) and `!chance` are for the Storytelling +System, and they use a specific syntax to support the dice system. The +simplest version of the command is `!pool ` to roll a pool of the +given size using the most common type of roll. -You can also run it yourself by creating a bot account, building the dicebot -program (either from this repo or by running `cargo install -axfive-matrix-dicebot`, and creating a config file that looks like this: +The type of roll can be controlled by adding `n`, `e`, or `r` after +the number, for 9-again, 8-again, and rote quality rolls. The number +of successes required for an exceptional success can be controlled by +`s`, e.g. `s3` to only need 3 successes for an exceptional +success. + +Examples: + +``` +!pool 8 //regular pool of 8 dice +!pool 8n //roll 8 dice, 9-again +!pool 8ns3 //roll 8 dice, 9-again with only 3 successes for exceptional +!pool 5rs2 //5 dice, rote quality, 2 successes for exceptional + +``` + +## Running the Bot +You can run the bot by creating a bot account, building the dicebot +program (either from this repo, and creating a config file that looks +like this: ```ini [matrix] @@ -43,24 +56,20 @@ type = 'm.login.password' user = 'axfive-dicebot' ``` -Of course replacing all the necessary fields. Then you can run the "dicebot" -binary pointing at that, and it will log in and hum along and do its thing. +Of course replacing all the necessary fields. Then you can run the +"dicebot" binary pointing at that, and it will log in and hum along +and do its thing. -You can also just run it on the command line with the `dicebot-cmd` command, -which expects you to feed it one of the command expressions as shown above, and -will give you the plaintext response. +You can also just run it on the command line with the `dicebot-cmd` +command, which expects you to feed it one of the command expressions +as shown above, and will give you the plaintext response. ## Future plans -None, really. This is not a very serious project and I'm not planning on doing -much heavy maintenance or anything of the sort. This was mostly for fun. If I -get some motivation to work it up, I might at some point do some things like: +The most basic plans are: -* Actually have it handle rate-limiting and other errors properly. -* Add more syntax to the dice expressions, maybe making it possibly have more - features that [Avrae](https://avrae.io/commands#roll) offers. -* Potentially add more commands. - -I would happily accept any sort of pull requests for extra functionality or more -robustness if anybody wants to actually use it. The code is built to hopefully -be relatively easy to extend (with things like new commands). +* To add support for simple per-user variable management, e.g. setting + a name to a value (`gnosis = 3`) and then using those in dice rolls. +* Perhaps some sort of character sheet integration. But for that, we + would need a sheet service. +* Robustness fixes if necessary, which will be sent upstream.