RuneQuest Glorantha system for Foundry Virtual Table Top

Installing

Paste this into Foundry VTT Install System -> Manifest URL https://github.com/sun-dragon-cult/fvtt-system-rqg/releases/latest/download/system.json

You will also need the wiki content module that can be installed with https://github.com/sun-dragon-cult/fvtt-module-wiki-rqg/releases/latest/download/en-module.json

Effects with a duration (like protection spells) automatically expire during combat, tracked by combat rounds. Outside of combat, expiry is instead tracked by elapsed game time - this only advances if something is actively advancing it, so you'll need a module such as a calendar (e.g. Calendaria) that ticks world time forward between sessions/scenes.

Usage

See the Documentation for more details.

Development

Written in typescript with the help of the fantastic League of Foundry Developers Foundry VTT Types.

Prerequisites

• Node.js (LTS recommended)
• pnpm
• A local Node.js installation of Foundry VTT (with a valid license), see https://foundryvtt.com/article/installation/

Quick start

1. Install dependencies: pnpm i
2. Build once: pnpm build
3. Create local config: copy .env.example to .env.local
4. Edit .env.local and set your local Foundry paths (FOUNDRY_V13_* / FOUNDRY_V14_*)
5. Create a symlink from foundrydata/Data/systems/rqg to this repository's dist folder

Then choose one workflow:

1. Build workflow (compiled/minified output)

• Build the system: pnpm build
• Start Foundry (example v14): pnpm foundry 14
• Open the Foundry localhost URL for the configured port

2. Dev workflow (hot reload + non-minified code)

• Start Foundry (example v14): pnpm foundry 14
• In another terminal, run dev mode (example v13): pnpm dev 13 (opens your browser automatically, usually at http://localhost:30001/game)

If you omit the version argument, the scripts use your default values from .env.local.

If you like to remove the system from foundry then remove the file system softlink.

E2E tests (Playwright)

Playwright is included as a development dependency in this repository.

Before running E2E tests, add E2E settings to .env.local (or export them as environment variables):

E2E_FOUNDRY_WORLD=e2e-playwright
E2E_GM_USER=gamemaster
E2E_GM_PASSWORD=
E2E_FOUNDRY_ADMIN_PASSWORD=123
E2E_RQG_ACTOR=Vasana

World prerequisites:

• The configured world must exist (E2E_FOUNDRY_WORLD).
• The configured GM user must exist and be enabled (E2E_GM_USER).
• At least one actor must exist in the world.
• For attack-dialog coverage, the actor configured in E2E_RQG_ACTOR should exist and have at least one weapon attack (default: Vasana).

After installing dependencies, install Playwright browsers once:

pnpm exec playwright install

On Linux, if required, also install OS dependencies:

pnpm exec playwright install --with-deps

Run E2E tests with:

pnpm test:e2e

Or use the Playwright UI mode:

pnpm test:e2e:ui

Development in Windows

Recommended: use WSL for day-to-day development on Windows.

Conventional Commit message standard

The changelog of this project is autogenerated from the commit messages. To make this work they must follow the conventional commit standard. There is a pre-commit hook to check if the commit message follows the rules so if you get an error when committing this could be the cause. The most common types of commits are additions of new features: feat: add quantity to all items and fixing of bugs: fix: dropping items generates a NPE.

Prettier formatting

The code should be formatted with Prettier and a pre-commit hook will autoformat the code you commit. It is recommended to install a formatter in your IDE to format your code on the fly.

Editing compendium Yaml files

To make it easier to edit the yaml files that is used to create to compendium packs, there is a JSON Schema generated for each item/actor type, one file per type, under src/data-model/json-schemas/generated/{item,actor}/<type>.schema.json (see manifest.json in that folder for the full list). These are generated straight from the real defineSchema() DataModel definitions in src/data-model/** by pnpm generate:schemas (see buildScripts/generate-schema.ts), so they stay in sync with the actual system data. Run pnpm generate:schemas after changing a DataModel's schema and commit the regenerated files — pnpm check:schemas (part of pnpm check:ci) fails the build if the committed files are stale.

Visual Studio Code

To enable yaml validation in vs code, you first need to install this YAML plugin and then configure it to map each compendium yaml file to its type's schema, use the setting below (adjust the glob patterns to how your yaml source files are organized).

{
  "yaml.schemas": {
    "https://raw.githubusercontent.com/sun-dragon-cult/fvtt-system-rqg/master/src/data-model/json-schemas/generated/item/skill.schema.json": "**/skill/*.yaml"
  }
}

For details see this article: https://dev.to/brpaz/how-to-create-your-own-auto-completion-for-json-and-yaml-files-on-vs-code-with-the-help-of-json-schema-k1i

Jetbrains Idea

Open a yaml file and click "No JSON Schema" at the bottom left. Choose "+ New Schema Mapping" and paste https://raw.githubusercontent.com/sun-dragon-cult/fvtt-system-rqg/master/src/data-model/json-schemas/generated/item/skill.schema.json (pick the file matching the item/actor type you're editing) into the "Schema file or URL" input field. Name the schema, and set the schema version to 2020-12.

Releasing

Prepare

1. Prepare a new documentation for the release in the sun-dragon-cult repo
2. Draft a new release on Github
3. Select a new tag like "v7.3.2" and click "Create new tag"
4. Set Release title to "7.3.2 (2028-01-02)"
5. Add Release notes: "See release notes https://sun-dragon-cult.github.io/release-notes/rqg-v7.3.2"
6. Check "Set as a pre-release"
7. Click Publish release (The release github action runs, adding release artifacts)

Verify

1. Install the system from the release link
2. Manually test that it works

Publish

1. Push the documentation in the sun-dragon-cult repo
2. Set the release as "latest"
3. Fill in the information on the admin Foundry page
4. Notify in Discord
5. Mark the milestone in Github as [done] and close it

Pre-releases

Foundry's own version comparison (isNewerVersion) is not full semver-aware: a version like 6.0.0-alpha0 is treated as newer than the eventual 6.0.0, not older, so GMs who installed the alpha would never see the real 6.0.0 as an update.

To avoid this, pre-releases for an upcoming major must use a lower major version number than the target release, with an alphaN label naming the targeted major version followed by an incrementing numeric segment, e.g. 5.alpha6.0, 5.alpha6.1, ... 5.alpha6.10 for an upcoming 6.0.0. The leading 5 keeps every alpha build safely below any real 5.x.y or 6.0.0 release, and the trailing numeric segment is compared numerically, so it sorts correctly even past single digits (unlike a suffix like -alpha10, which would be compared as a string and sort incorrectly against -alpha9).

Always tag these as a GitHub pre-release (never "latest"), so stable users never receive them automatically. Testers install manually via the specific tag's manifest URL, not the latest manifest. Never reuse an already-published version string for different code — always bump it (e.g. 5.alpha6.0 → 5.alpha6.1), even for small fixes, or Foundry won't detect the change as an update either. These alpha versions are for testing only and are not documented in the release notes.

Project Status

Actively maintained, with an official release expected in the future.

Credits and Attributions