Commlink

Commlink is a manager for characters and campaigns for various table top role playing games. Originally written as a character builder for Shadowrun 5E, it later expanded to a GM tool allowing the game master to keep details about the campaign together in one place.

Commlink can operate either as a standalone web site for building and maintaining characters, or it can integrate with chat services to operate as a dice roller. It can be used in Slack, Discord, and/or IRC. If a campaign is registered to multiple chat channels, rolls can be broadcast to other channels. For example, if your Shadowrun campaign is using both Slack and Discord, users can roll dice in Slack and have the results appear in Discord, and vice versa.

Supported systems

Commlink is very much a work in progress, and each of the systems has varying levels of completeness.

• Alien
• Avatar Legends
• Blister Critters
• Capers
• Cyberpunk Red
• Dungeons & Dragons 5th Edition
• The Expanse
• Shadowrun 5th Edition
• Shadowrun 6th Edition
• Star Trek Adventures
• Stillfleet
• Subversion
• The Transformers RPG 2nd Edition

Running Commlink locally

Commlink was originally built and run directly on a bare-metal Linux machine, and there may still be some corner cases where something doesn't work when run locally (like the various chat bots). However, most of the web frontend works when run via Docker Desktop.

$ docker compose up -d

Containers

• php - Application server. Most likely what you'll be interacting with.
• web - Nginx web server. Passes traffic from http://localhost:8337 to the PHP server for processing.
• mongo - Mongo document server. Stores character objects. Available locally on port 8339.
• mysql - MySQL database server. Stores all non-character data. Available locally on port 8336.
• redis - Stores ephemeral state, such as initiatives.
• mailhog - Mailhog instance captures local email. Available at http://localhost:8338.

Setting up Commlink

Commlink requires Composer and is built on Laravel. Assuming you have Composer in your path:

$ composer install
$ ./artisan migrate
$ ./artisan db:seed

or for Docker:

$ docker compose exec php composer install
$ docker compose exec php php artisan migrate
$ docker compose exec php php artisan db:seed

Much of data powering the API is proprietary and requires a licensing relationship with the various owners of the intellectual property, so it is not included with the project. Creating your own data files to return data from the API involves filling out the various PHP arrays in the data directory of the RPG's module. We've included example data only for supported systems.

Commlink requires both MySQL (for general application data) and MongoDB (for characters).

Creating a user

Creating an admin user can be done with a command line script:

$ ./artisan commlink:create-user

Starting the queue

Passing events between various chat systems and the web requires running Laravel's queues. Start them with:

$ ./artisan queue:work

Running the Discord bot

Assuming you've registered the bot with Discord and configured its token:

$ ./artisan commlink:discord-run

Running the IRC bot

By default, the IRC bot will try to name itself whatever APP_NAME is set to in your .env file. You can pass a new nickname with the --nickname parameter. Similarly, by default it will connect to the standard IRC port 6667, but you can change it with the --port parameter. The server's name is required, and might be something like chat.freenode.net for Freenode. Finally, you can have it auto-join channels by passing one or more --channel arguments.

$ ./artisan commlink:irc-run [server]

Running tests and static analysis

All of the automated tests can be run through composer:

$ composer all

If you'd like to run an individual check:

• coverage - Build a PHPUnit code coverage report that will be available in "public/coverage" or on your site at "/coverage/index.html".
• infection - Run Infection on the App directory.
• lint - Run PHP-Parallel-Lint across the entire codebase.
• lint-openapi - Run Redocly to lint the OpenAPI specification.
• phpcs - Run PHP Code Sniffer on the entire codebase.
• php-cs-fixer - Run PHP-CS-Fixer's dry run on the entire codebase.
• phpstan - Run PHPstan's highest level across the entire codebase.
• psalm - Run Psalm across the entire codebase.
• static - Run lint, PHPStan, and Psalm targets.
• style - Run both phpcs and php-cs-fixer.
• test - Run PHPUnit tests without generating a code coverage report.

Credits

• Favicon: https://commons.wikimedia.org/wiki/File:Sixsided_Dice_inJapan.jpg
• All of the game systems supported are trademarked by their respective owners, and Commlink is not affiliated with any of them in any way.