projectmoon
938107feae
Instead of using an Arc Mutex for state management embedded directly into the bot, utilize actor pattern, with the idea that this will be much more useful than simply logging a message once in the future. This also refactors the bot code so that instead of a single run_bot function, the DiceBot struct now has a run() method attached to it. This also necessitated changes and cleanup to the dicebot main, which is for the better anyhow. The error and config types are also now in their own files, and implemented for more in-depth use cases. |
||
---|---|---|
.github/workflows | ||
src | ||
.dockerignore | ||
.gitignore | ||
Cargo.lock | ||
Cargo.toml | ||
Dockerfile | ||
LICENSE | ||
README.md |
README.md
matrix-dicebot
This is a fork of the 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.
Features
matrix-dicebot
is a basic dice rolling bot. It currently has the
following features:
- Rolling arbitrary dice expressions (e.g. 1d4, 1d20+5, 1d8+1d6, etc).
- Rolling dice pools for the Chronicles of Darkness 2E Storytelling System.
- Works in encrypted or unencrypted Matrix rooms.
Building and Installation
Docker Image
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.
The latest
tag always points to the most recent successfully built
master commit and is considered unstable, while individual tags are
considered stable.
- Unstable:
docker pull ghcr.io/projectmoon/chronicle-dicebot:latest
- Stable:
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.
Build from Source
Precompiled executables are not yet available. Clone this repository
and run OLM_LINK_VARIANT=dylib cargo install
.
Building the project requires:
- Basic build environment (
build-essential
on Ubuntu,base-devel
on Void and Arch, etc). - Rust 1.45.0 or higher.
- OpenSSL/LibreSSL development headers installed.
olm-sys
crate dependencies: cmake, libstdc++, libolm and its development headers.- glibc.
Note: The olm-sys
crate must be built in dynamic linking mode until
a bug in its build process is fixed.
Why doesn't it build on musl libc?
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.
Usage
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
its capabilities.
The commands !roll
and !r
can handle arbitrary dice roll
expressions.
!roll 4d6
!r 4d7 + 3
!r 3d12 - 5d2 + 3 - 7d3 + 20d20
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 <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 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<num>
, 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
The easiest way to run the bot is to use the official Docker image, although you can also run the binary directly.
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 client state after initial sync. That
should be mounted at /cache/
in the container.
Configuration File
The configuration file is a TOML file with two sections.
[matrix]
home_server = 'https://example.com'
username = 'thisismyusername'
password = 'thisismypassword'
[bot]
oldest_message_age = 300
The [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.
The [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).
Running Binary Directly
If you have built the application from source,
you can invoke the dice bot directly instead of using Docker by
running 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 dicebot-cmd
, which
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
commands locally.
Future plans
The most basic plans are:
- 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. This lays the foundation for character sheet integration. - Perhaps some sort of character sheet integration. But for that, we would need a sheet service.
- Use environment variables instead of config file in Docker image.