|projectmoon 0f35c1932b||2 weeks ago|
|.github/workflows||6 months ago|
|src||2 weeks ago|
|.dockerignore||8 months ago|
|.drone.yml||2 weeks ago|
|.gitignore||6 months ago|
|Cargo.lock||2 weeks ago|
|Cargo.toml||2 weeks ago|
|Dockerfile||2 weeks ago|
|LICENSE||8 months ago|
|README.md||5 months ago|
This is a dice rolling bot for facilitating roleplaying games on the Matrix messaging platform. It currently has basic support for the Chronicles of Darkness 2E Storytelling System and Call of Cthulhu, with plans to extend the codebase further to support other systems and character sheet management.
matrix-dicebot is a basic dice rolling bot. It currently has the
The easiest way to run the dice bot is to use the official Docker image. It is distributed on GitHub Container Registry by a CI pipeline.
latest tag always points to the most recent successfully built
master commit and is considered unstable, while individual tags are
docker pull ghcr.io/projectmoon/chronicle-dicebot:latest
docker pull ghcr.io/projectmoon/chronicle-dicebot:X.Y.Z
This image is based on Void Linux. To build
the image yourself, run
docker build -t chronicle-dicebot . in the
root of the repository.
After pulling or building the image, see instructions on how to use the Docker image.
Precompiled executables are not yet available. Clone this repository
Building the project requires:
base-develon Void and Arch, etc).
olm-syscrate dependencies: cmake, libstdc++.
As far as I can tell, the project doesn't build on musl libc. It certainly doesn't build a static binary out of the box using the rust-musl-builder. This appears to be due to a transitive dependency of the Rust Matrix SDK.
Any PRs to get the project or Matrix SDK to properly be built into a static binary using musl would be very useful.
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 bot supports a
!help command for basic help information about
!r can handle arbitrary dice roll
!roll 4d6 !r 4d7 + 3 !r 3d12 - 5d2 + 3 - 7d3 + 20d20
This system does not yet have the capability to handle things like D&D 5e advantage or disadvantage.
!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 <num> to roll a pool of the
given size using the most common type of roll.
The type of roll can be controlled by adding
the number, for 9-again, 8-again, and rote quality rolls. The number
of successes required for an exceptional success can be controlled by
s3 to only need 3 successes for an exceptional
success. All modifiers should come before the number, with a
!pool 8 //regular pool of 8 dice !pool n:8 //roll 8 dice, 9-again !pool ns3:8 //roll 8 dice, 9-again with only 3 successes for exceptional !pool rs2:5 //5 dice, rote quality, 2 successes for exceptional
!cthadv are for
the Call of Cthulhu system.
!cthroll are for rolling
percentile dice against a target number. A
bb: can be
prepended to get one or two bonus dice.
!cthadv are for skill advancement.
!cthRoll 50 //roll against a target of 50 !cthRoll bb:60 //roll against a target of 60 with 2 bonus dice !cthARoll 30 //advancement roll against a target of 30
Users can store variables for use with the Storytelling dice pool system. Variables are stored on a per-room, per-user basis in the database (currently located in the cache directory if using the Docker image).
!set myvar 5 //stores 5 for this room under the name "myvar" !get myvar //will print 5
Variables can be referenced in dice pool rolling expressions, for
!pool myvar or
A typical docker run command using the official Docker image should look something like this:
# Run unstable version of the bot VERSION="latest" docker run --rm -d --name dicebot \ -v /path/to/dicebot-config.toml:/config/dicebot-config.toml:ro \ -v /path/to/cache/:/cache \ ghcr.io/projectmoon/chronicle-dicebot:$VERSION
The Docker image requires two volume mounts: the location of the
config file, which should be mounted at
/config/dicebot-config.toml, and a cache directory to store the
database and client state after initial sync. That should be mounted
/cache/in the container.
The configuration file is a TOML file with three sections.
[matrix] home_server = 'https://example.com' username = 'thisismyusername' password = 'thisismypassword' [database] path = '/path/to/database/directory/' [bot] oldest_message_age = 300
[matrix] section contains the information for logging in to the
bot's matrix account.
home_server: The URL for the Matrix homeserver the bot should log in to. This should be the proper hostname of the homeserver that you would enter into the login box, which might be different than the server name that is displayed to other users.
username: Bot account username.
password: Bot account password.
[database] section contains information for connecting to the
embedded database. Note: you do not need this if you are using the
path: Path on the filesystem to use as the database storage directory.
[bot] section has settings for controlling how the bot operates.
This section is optional and the settings will fall back to their
default values if the section or setting is not present.
oldest_message_age: the oldest time (in seconds) in the past that a message can be before being ignored. This prevents the bot from processing out-of-context old commands received while offline. The default value is 900 seconds (15 minutes).
If you have built the application from source,
you can invoke the dice bot directly instead of using Docker by
dicebot /path/to/config.toml. By default, the user account
cache is stored in a platform-dependent location. If you want
to change the cache location on Linux, for example, you can run
export XDG_CACHE_HOME=/path/to/cache before invoking the bot.
Installing the application directly also installs
allows you to run arbitrary bot commands on the command line. This
does not connect to a running instance of the bot; it just processes
The most basic plans are:
This was orignally a fork of the axfive-matrix-dicebot, with support added for Chronicles of Darkness and Call of Cthulhu.