Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/mikron-ia/rpg-hub

An hub for RPG players and GMs, intended for storing and presenting campaign/epic information
https://github.com/mikron-ia/rpg-hub

php83 rpg tabletop tabletop-rpgs yii2

Last synced: 19 days ago
JSON representation

An hub for RPG players and GMs, intended for storing and presenting campaign/epic information

Awesome Lists containing this project

README 

          
# RPG hub



This project is a system for role-playing game story/campaign/epic management.



## Licensing



The project's main license is `GNU General Public License v3.0` - see the `LICENSE.md` file for the text. The `yii2`

framework is `BSD 3-Clause "New" or "Revised" License` - see the `LICENSE-yii.md` file for the text. Libraries can have

their own licenses; see the Attributions section of this file for details.



## Project state



The project is being still maintained and (occasionally) developed since it is quite useful for me in its main purpose

(keeping my own campaign data), but due to its age (it started in 2016), state of the `yii2` framework (effectively

limited to maintenance with the release of `yii3`, with version 2.2.x being uncertain), and overall effort that would be

required to bring the codebase to a decent standard (immense yet not very practical), it is firmly in its legacy stage.



## Background



Role-playing games are a vastly diverse concept that ranges from very simplistic systems that fit on one page up to

extremely complex systems spanning hundreds of books, with a whole spectrum in-between; see

the [Wikipedia definition](https://en.wikipedia.org/wiki/Role-playing_game) for details. What they do have in common,

though, is the presence of a story - one can play a game without mechanics, but even a simple dungeon crawl is going to

have some story. Managing this story, its cast, threads, and mechanical components is the main role of this project.



The project itself was originally thought of as a learning experience and a coding exercise. Unfortunately, due to

changes in the technological landscape (primarily change in popularity of frameworks and shifting design philosophies)

can no longer fulfill those goals. It is now maintained mostly for its practical uses and minor coding experiments.



## Set up instructions



1. Make sure you have the proper stack installed; the current requirements are:

    - PHP 8.4+

        - Due to PHP maintaining most of its backwards compatibility, the project also works up to PHP 8.5

    - MySQL 5.6+ database or MariaDB equivalent

        - The current project was tested and found working up to MySQL 8.0 and MariaDB 11.0

1. If you have no composer, install it via [instructions from here](https://getcomposer.org/download/)

1. Clone the project into the desired directory

1. Run `composer install`

    - for a production deployment, add `--no-dev` option to avoid adding unnecessary libraries

1. Copy `.env.example` to `.env` and fill it with configuration data

    - Database access data is mandatory -- without that the hub will fail to start

    - Language configuration and key generators can be left on their default values -- change them only if you have a

      good reason to

    - API key must be set up to make API accessible from outside and can be ignored if API is not used

    - the URIs are needed -- without them the mailing will fail and a few redirects may not work

    - mailing data and invitation validity are optional, but their lack will make inviting users via e-mail impossible

1. [optional] Run `./yii config/check-env` to see whether configuration variables are set properly

    - note that this only checks the less obvious variables: the database connection string and mailing data are not

      verified

1. [optional] If you wish to add data, create the `console/migrations/data.sql` file with SQL inserts that should be

   loaded into the database; this is intended for development/test work on larger data sets and is not needed for

   normal, initial deployment of a fresh project

1. Initialise the project

    - For development: `./init --env=Development --overwrite=All`

    - For production: `./init --env=Production --overwrite=All`

1. [on an empty database] Run `./yii migrate/up`; `data.sql` will be automatically loaded if present

1. [on an empty database] Run `./yii rbac/init`; this will set up the access rights for the roles

1. [on an empty database] Run `./yii install/add-administrator` to add the administrator user

1. Set up the periodic tasks; this is technically optional, but the system expects at least the importance recalculation

   to be run relatively often, or it will not display some objects on the presentation page

    - Fill the `config.shlib` file with values appropriate for your hosting environment

        - `runner` is the PHP executable; while many hosting environments will work with `php` alone, there might be

          some version issues

        - `yii` is the path to the `yii` script; using an absolute path may solve some issues

        - `log` is the path to the log directory; make sure the directory exists and is writable

    - set up cron tasks in your system with the content of `scripts/`

1. Access the entry points as needed:

    - `backend/web` for the content management page (administrators and operators only)

    - `frontend/web` for the presentation page (any user)



## Upgrading between versions



1. Update the code base from an archive pack or a git tag

    - If you are feeling adventurous, use the `master` branch, but its content, while usually free of breaking bugs, is

      not guaranteed to work at all times; moreover, the migrations are now per-release, which means they can change

      before given release tag is set; to be safe, use the released/tagged code only

1. Run `composer install`

1. Ensure your `.env` file is up to date, based on `.env.example`

    - `./yii config/check-env` can be helpful here as well since it should include checks for recently introduced

      mandatory variables

1. Run migrations with `./yii migrate/up`

1. Run `./yii rbac/v*` sequentially to get up to a proper version

    - Note: there is, to date, no record on which RBAC migration was run last; running any of those "migrations" twice

      will cause an error - it will not damage anything, though, just break the execution



## Project structure



As mentioned in the setup instructions, the project is composed of several modules:



- `frontend` - the presentation and the only part the players should be accessing; can be used by Game Masters for

  convenience

- `backend` - the content management system, intended for Game Masters' and admins use only

- `console` - administrative and auxiliary tools that should not be commonly used except for setup, deployment, and

  `cron` calls

- `common` - components used by other three modules



## Basic functionalities/components



The hub allows handling of the following:



- `Epic` - the basic container, representing the campaign / epic and containing virtually everything else that is not an

  user

- `Story` - an adventure, plot, etc. - in other words, a time-limited element of the `Epic`

- `Recap` - a description of events, intended to keep the players up to date

    - It can encompass any number of sessions

- `Game` - a discrete gaming session, often associated with a `Recap`

- `Character` - a character (either a Player Character or an NPC) present in the story, most often described from the

  perspective of the players

- `CharacterSheet` - a detailed set of mechanical data on `Character`, usually in a form of numbers and traits

    - This is still a very underdeveloped component, requiring using a dedicated and undocumented data format to display

      properly

    - It is linked to a single `Character` from a list of `Character`s that have it set as their sheet

- `Group` - a group of `Character`s - a party, an organization, or anything that justifies putting a few `Character`s

  together; can have other `Groups` as members as well

- `Location` - a place present in the story

- `Project` - a less structured, more distributed, and usually player-driven set of events and actions, usually

  resulting in a creation of something or accomplishment of a goal independently of a story

- `Scenario` - a plan for events for a `Story`

    - This is the only "large" component that exists solely on the Game Master side and cannot be displayed on the

      presentation/front side

- `Article` - miscellaneous texts

- `Announcement` - news, information, and other OOC updates directed at users

- `PointInTime` - auxiliary information, used to put in-story date/time on descriptions

- `Secret` - auxiliary information, used to put in-story secrets in texts

- `Image` - a set of links to an image file that can in turn be embedded in most text fields

- `User` - as the name suggests, this is the user, i.e. person accessing the hub; no further explanation should be

  needed



All the other components serve auxiliary roles only and are not directly editable.



Use of most components is optional; for example, an `Epic` can be conceivably run with the use of `Recap`s and `Game`s

only or just with `Character` gallery. There are, of course, limits to that - for example, the `Group` functionality is

limited (but not unusable) without any `Character`s. Still, most elements can be used entirely independently of each

other.



## Versioning



The project uses [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) to number its releases, treating its

list of functionalities as the public API. This means that the major version will likely be incremented only if one of

the major functionalities is removed, repurposed, or modified beyond recognition.



## Attributions



What follows is a list of libraries used in the project; only those included directly are listed.



All the following libraries are licensed under `BSD-3-Clause license` or a derivative, unless stated otherwise.



- [The yii framework](https://github.com/yiisoft/yii2) is the basis of this project, including:

    - [yii2-bootstrap](https://github.com/yiisoft/yii2-bootstrap)

    - [yii2-swiftmailer](https://github.com/yiisoft/yii2-swiftmailer)

    - [yii2-debug](https://github.com/yiisoft/yii2-debug)

    - [yii2-gii](https://github.com/yiisoft/yii2-gii)

- Tools made by [Kartik Visweswaran](https://github.com/kartik-v/), including:

    - [yii2-krajee-base](https://github.com/kartik-v/yii2-krajee-base)

    - [yii2-widget-select2](https://github.com/kartik-v/yii2-widget-select2)

    - [yii2-password](https://github.com/kartik-v/yii2-password)

    - [strength-meter](https://github.com/kartik-v/strength-meter)

    - [yii2-widget-datepicker](https://github.com/kartik-v/yii2-widget-datepicker)

    - [yii2-widget-datetimepicker](https://github.com/kartik-v/yii2-widget-datetimepicker)

- [phpunit](https://github.com/sebastianbergmann/phpunit)

- [phpdotenv](https://github.com/vlucas/phpdotenv)