Skip to main content

Hosting a resource-only repository (GitHub Pages)

A resource-only repository is a repo you can share with friends (or the community) that contains pre-made content (resource instances like monsters, spells, items, feats, etc.), hosted online so the RPG Companion App can download it.

This functionality is amazing for Game Masters, as it allows them to ship custom content to the apps of their players in an easy and semi-automated fashion. What's more, it can be easily updated and players will get the new resource instantly as soon as they hit the "Fetch resource" button in the app.

This guide explains everything end-to-end:

  1. How to create the repository contents (systems + resources)
  2. How to build the hosted output (Dev Tool → output folder)
  3. How to host it for free (GitHub Pages)
  4. How to add it to the community registry so it shows up in https://repositories.rpg-companion.app

What your hosted repository should look like​

When you click Create Release Package in the Dev Tool, it generates a folder that looks like this:

  • systems.json
  • systems.rpg
  • One or more system folders like 5e/, 5e2024/, etc.

The contents of that output folder must be hosted at the root of your site.

/
  systems.json
  systems.rpg
  5e/
  5e2024/

Part A — Create your repository contents​

Step A1 — Start from an existing system repo (recommended)​

If your content is for 5e or 5.5e, you can clone the 5e and 5.5e systems repository:

https://github.com/blastervla/rpg-companion-app-systems

Use the systems/ folder as your workspace input for the Dev Tool.

Step A2 — Clean up unnecessary content​

Delete any systems or resources you do not plan to ship. Resources can be found under the resource_instances folder inside the particular system folders. Keeping your pack minimal makes it easier to maintain and faster to download.

Part B — Create and export resources from the app​

Step B1 — Create resources​

  1. Open the RPG Companion App
  2. Select the target system (e.g. 5e2024)
  3. Go to Resources (orange button)
  4. Select your desired resource from the dropdown at the top
  5. Create entries by tapping on the '+' button in the lower-right corner

Step B2 — Export resources​

  1. Open the RPG Companion App
  2. Go to the app settings
  3. Enabled developer mode
  4. Go back to the main menu
  5. Select the target system (e.g. 5e2024)
  6. Go to Resources (orange button)
  7. In the Resources screen, select your desired resource from the dropdown at the top
  8. Tap the Share / Export button in the top-left corner
  9. This will generate a .gzip file with all the resources in your app for that particular resource type you selected. Make sure to share it with yourself, via email, Google Drive or any other service you prefer.
  10. Download and unzip the exported file on your computer

You will get multiple .rpg.json files.

Part C — Add exported resources to your system​

Place exported files under:

system/<system_id>/resource_instances/

Example:

systems/5e/resource_instances/
  spell_fireball.rpg.json
  monster_goblin.rpg.json

You should choose only the resources you updated or created to do this.

Part D — Build the hosted output​

  1. Open the Dev Tool
  2. Click Select Input Folder and select your workspace (the systems folder you now have)
  3. Click Create Release Package
  4. Choose an empty output folder

The content of that folder is what you will host.

Part E — Uploading files to the GitHub repository root (VERY IMPORTANT)​

This is the most common place people make mistakes. Follow this exactly.

Step E1 — Create the GitHub repository​

  1. Go to https://github.com
  2. Log in (or create an account)
  3. Click your profile icon → Your repositories
  4. Click New
  5. Fill in:
    • Repository name: my-rpg-resource-pack
    • Visibility: Public
    • ✅ Check Add a README file
  6. Click Create repository

Step E2 — Upload files using the GitHub website (recommended)​

  1. Open your new GitHub repository
  2. Click Add file → Upload files
  3. Open your output folder on your computer
  4. Select everything inside it:
    • systems.json
    • systems.rpg
    • all system folders (5e/, 5e2024/, etc.)
  5. Drag those items directly onto the upload area

⚠️ Make sure you are uploading the contents, not the folder itself.

Step E3 — Verify BEFORE committing​

Before clicking Commit changes, your file list should show:

systems.json
systems.rpg
5e/
5e2024/

If you see:

output_folder/

❌ STOP — remove the files and try again.

Step E4 — Commit the upload​

  1. Scroll down
  2. Click Commit changes
  3. Wait for the upload to finish

Part F — Enable GitHub Pages​

  1. In your GitHub repository, click Settings
  2. In the left sidebar, click Pages
  3. Under Build and deployment:
    • Source: Deploy from a branch
    • Branch: main
    • Folder: /(root)
  4. Click Save

GitHub will show a URL like:

https://YOUR_USERNAME.github.io/YOUR_REPO_NAME/

Part G — Verify your hosted repository​

  1. Open your GitHub Pages URL in a browser
  2. You should see:
    • systems.json
    • systems.rpg
    • system folders

If you see a 404:

  • Wait 30–60 seconds and refresh
  • Re-check Pages settings
  • Confirm files are at repo root

Part H — Add your repo to the Community Registry​

To make your pack visible in the app directory, open a Pull Request to:

https://github.com/blastervla/rpg-companion-community-registry/blob/master/registry.json

Step H1 — Fork the registry repo​

  1. Open the link above
  2. Click Fork
  3. Create the fork under your account

Step H2 — Add your entry​

Edit registry.json and add (please fill in this template, changing only the values of the fields, which are all of the texts after colons and before commas):

{
  "id": "IdForYourRepository",
  "name": "Some descriptive name",
  "description": "What does this repository contain?",
  "tags": [
    "put",
    "your",
    "tags",
    "here",
    "check",
    "available-tags",
    "in-other-entries",
    "if-what-you-need-is-not-there-create-your-own"
  ],
  "repo_url": "The URL you got from github pages (e.g: https://YOUR_USERNAME.github.io/YOUR_REPO_NAME)",
  "github_repo": "YourGithubUsername/YourGithubRepositoryId",
  "stars": 0
}

⚠️ Do not forget the commas. If your entry will come after another entry in the json, you should make sure that the entry before has a comma , after the final curly brace }. If your entry comes before another entry, you should ensure you add a comma after your final curly brace.

e.g:

{
   // Some existing entry
}, <------
{
   // Your entry
}

or

{
   // Your entry
}, <------
{
   // Some existing entry
}

Step H3 — Open a Pull Request​

  1. Commit your change
  2. Click Contribute → Open pull request
  3. Submit the Pull Request for review

Once merged, your repository will appear at:

https://repositories.rpg-companion.app

Step I​

Now you can head to the RPG Companion App's settings and add your repository (the URL with github.io) to the app as a new repository, hit "Fetch systems & resources" and your content will be instantly added to the app! This works for anyone, so be sure to share your repository link with other people :)

Need help?​

Email Vlad at feedback@blastervla.com and include:

  • Your GitHub Pages URL
  • Your GitHub repository link
  • Any error messages shown in the app
  • Any extra information you think will be useful

Vlad will get back to you ASAP and is always happy to lend a hand!