Configuration
entities.json says what types exist and forms/ and views/ say how they are edited and shown.
config.json says how the app behaves for them.
config.json
Section titled “config.json”Per-entity configuration
Section titled “Per-entity configuration”The entities block is keyed by entity name, with a Default block applying to all of them:
{ "entities": { "Default": { "combatant": { "bars": [ { "attribute": "data.hp", "title": "Common.HitPoints", "label": "Common.HP", "temporary": true } ] } }, "Monster": { "collection": { "detail": "{{data.size|map: 'Size'}}{{data.type|map: 'MonsterType'|prefix: ' '}}{{data.alignment|map: 'Alignment'|prefix: ', '}}" }, "combatant": { "detail": "{{'Common.AC'|l}} {{data.armor}} • {{'Common.PP'|l}} {{data.passivePerception}} • {{'Common.CR'|l}} {{data.cr}}" } }, "NPC": { "role": "neutral" }, "Character": { "role": "friendly", "combatant": { "states": { "defeated": "#{{data.hp.current|default: 1}} <= -{{data.hp.maximum|default: 0}}" } } } }}Values resolve in four layers, each overriding the last: config.json’s Default, the user’s
settings Default, config.json’s entity block, the user’s settings for that entity. That is
what allows a system to ship a sensible default and still let a user change it from the
settings form.
| Key | Meaning |
|---|---|
role |
The side this type joins combat on — friendly, neutral, hostile. |
collection.detail |
Template for the subtitle in library lists. |
collection.image |
Which image a library row shows. |
combatant.detail |
Template for the subtitle in the combat tracker. |
combatant.image |
Which image a combatant row shows. |
combatant.bars |
Tracked value bars — see below. |
combatant.states |
Named state conditions — see below. |
view.renderer |
native (default), html, custom, sheet. |
view.template |
Which views/*.html file the html renderer uses. |
view.updateMode |
load, reload, event, none. |
load |
What loading the type produces — creature, statusEffect, areaEffect. See below. |
collection.detail and combatant.detail are the one-line summaries under a name. They are
ordinary templates over the entity’s context, which means they
can read anything a transform computed — the AC,
passive Perception and CR in the example above are all derived values.
Tracked bars
Section titled “Tracked bars”combatant.bars declares what the combat tracker tracks. Each entry names an attribute holding a
current / maximum (and optionally temporary) group:
"bars": [ { "attribute": "data.hp", "title": "Common.HitPoints", "label": "Common.HP", "temporary": true }]The first bar is the primary one: it backs the defeated and bloodied states and is what the tracker shows most prominently. A system with more than one pool — stamina, stress, sanity — adds further entries.
States
Section titled “States”combatant.states maps a state name to a condition template. defeated is the one the app acts
on:
"states": { "defeated": "#{{data.hp.current|default: 1}} <= -{{data.hp.maximum|default: 0}}" }The leading # makes it a formula. This example is the
D&D 5E instant-death rule; without it, the default rule of reaching zero applies.
Load targets
Section titled “Load targets”loadable in entities.json decides whether a type can be
loaded at all. load decides what loading it produces:
"Spell": { "load": ["statusEffect", "areaEffect"] }| Target | Produces | Needs in the entity data |
|---|---|---|
creature |
A combatant and/or token, following the load mode. | — |
statusEffect |
A status effect on the selected token. | data.duration, data.durationUnit or data.durationType |
areaEffect |
An area effect placed on the map. | data.areaEffectShape |
Without the key a loadable type loads as a creature only, so status and area effects need the type to list them. An entity’s duration or area data alone never makes one. An empty list loads nothing.
The app tries the targets in order: a status effect when a token is selected, then an area
effect, then a creature. An entity that lists effects but has neither the data nor a selected
token is reported as an error instead of being loaded as a creature, unless the list also
includes creature. The combat/map load-mode menu is shown only for types whose list includes
creature.
Status effect menus
Section titled “Status effect menus”"statusEffects": { "menuProvider": ["Rule:condition"] }Each entry names an entity type to offer as status effects, optionally narrowed by a
subtype after a colon. Rule:condition is what makes a 5E system’s conditions appear in the
tracker’s status effect menu — the conditions are ordinary content, not a hardcoded list.
Measurement
Section titled “Measurement”Declares the measurement systems the ruleset uses, their units, display format and conversions:
"measurement": { "imperial": { "default": true, "title": "MeasurementSystem.Imperial", "units": ["ft", "mi", "lb"], "format": "@value @unit.", "conversion": { "metric": { "ft": { "m": "@value * 0.3" }, "mi": { "km": "@value * 1.5" }, "lb": { "kg": "@value * 0.5" } } } }, "metric": { "title": "MeasurementSystem.Metric", "units": ["m", "km", "kg"], "format": "@value @unit", "conversion": { "imperial": { "m": { "ft": "@value / 0.3" }, "km": { "mi": "@value / 1.5" }, "kg": { "lb": "@value * 2" } } } }}Units are listed in matching order across systems, so the first unit of one maps to the first of
another. @value and @unit are the placeholders. The default system applies until the user
picks one in system settings.
Every value passed through the units filter, and every form field with a units key, is
converted accordingly:
{{ data.range | units: 'ft' }}A creature authored in feet displays in metres for a metric user, with no change to the content.
Initiative
Section titled “Initiative”"combat": { "initiative": { "mode": "roll", "rollFormula": "d20 + @entity.data.initiativeBonus", "autoRoll": "hostileAndNeutral", "group": null, "everyRound": false, "sortOrder": "desc" }}| Key | Values |
|---|---|
mode |
roll (default), draw, fixed |
rollFormula |
The expression rolled; defaults to d20 + @entity.data.initiativeBonus |
rollTimes |
How many times to roll |
drawPool |
Highest value in the draw pool, for draw mode (default 20) |
autoRoll |
all, hostile, hostileAndNeutral (default), none |
group |
How ties are grouped |
everyRound |
Re-roll initiative each round |
sortOrder |
desc (default) or asc |
A card-draw system sets "mode": "draw"; a system where initiative is a fixed derived score sets
"mode": "fixed".
Everything here can be exposed to users through the settings form, since settings merge over config.
Game resources
Section titled “Game resources”Counters the table spends and accumulates during play, such as Daggerheart’s Fear:
"resources": [ { "id": "fear", "label": "Fear", "icon": "gi-burning-skull", "min": 0, "max": 12, "visibility": "players" }]resources is always a list, even for a system with a single resource. Each entry becomes a
counter in the game screen’s bottom bar, where the GM changes it with − and +, sets it directly
from a menu on the value, or resets it.
| Key | Values |
|---|---|
id |
Required. Identifies the resource and the value stored for it; keep it stable across system versions |
label |
The name shown with the value; a localization key works here. Defaults to the id, capitalized |
icon |
A gi- game icon name, or the path of an image in the system folder |
type |
counter (default) or countdown |
min |
The lowest value; defaults to 0 |
max |
The highest value; leave it out for no upper limit |
initial |
The starting value; defaults to min |
visibility |
gm (default) or players |
A resource with players visibility is shown on the player display and the web client. One with
gm visibility stays with the GM; its value never leaves the device. The default is gm, so a
resource is only shown to players when the system says so. Players see the max beside the value
(5 / 12) when the resource has one, and the value alone when it does not.
The menu on a counter’s value lists every value from min to max, so the GM can set it in one
step. Without a max it lists min to min + 12; + still goes past that.
A countdown works like a counter for the GM, who sets it and counts it down. Players see it only
while it is running: at 0 it is hidden, at any other value it shows (when its visibility is
players). Daggerheart’s countdowns are a good fit:
{ "id": "countdown", "label": "Countdown", "type": "countdown", "visibility": "players" }Values belong to the campaign. They persist across sessions and never reset on their own, not even
when combat ends. A resource the GM has not changed reads as its initial value, and a value is
always kept within min and max, even after a system update narrows them.
An entry without an id, a repeated id, or a type the app does not know is skipped, so a
system written for a newer app still loads.
View themes
Section titled “View themes”Named looks for the system’s HTML views — pages, entity views rendered with the html renderer,
and tables — that the user picks under Appearance in the system settings:
"viewThemes": [ { "id": "parchment", "label": "Parchment" }, { "id": "clean", "label": "Clean" }]| Key | Values |
|---|---|
id |
Required. Letters, digits, - and _; keep it stable, it is what the user’s choice is saved as |
label |
The name shown in the picker; a localization key works here. Defaults to the id, capitalized |
The app does no styling of its own. It writes the selected id as data-view-theme on <html>,
and your stylesheet does the rest:
:root { --accent: #58180d; --paper: #fdf1dc; }:root[data-view-theme="clean"] { --accent: #1f4e79; --paper: #ffffff; }With no theme picked — the default — there is no data-view-theme, so your base rules are the
default look. Your own templates in views/*.html write the attribute themselves from
env.theme:
<html lang="en" data-kind="{{kind}}"{% if env.theme %} data-view-theme="{{env.theme}}"{% endif %}>The bundled templates already do. A theme that needs more than variables can live in its own file,
linked from your template through {{ env.systemURL }}styles/themes/{{ env.theme }}.css.
Modules with their own look (styles/page.css) and older modules (assets/css/global.css) never
load the system’s styles, so themes do not reach them. A theme is shown everywhere the view is,
the web client included.
Light and dark
Section titled “Light and dark”With no theme picked, views follow the app’s appearance, which the user sets for the whole app.
Declare which schemes your stylesheet supports and write colours with light-dark() (or system
colours such as Canvas), and they follow it:
:root { color-scheme: light dark; }body { color: light-dark(#222, #eee); background: light-dark(#fff, #1e1e1e); }To offer a look that is always light or always dark, make it a theme and force the scheme in CSS.
light-dark(), Canvas, form controls and scrollbars all follow color-scheme:
:root[data-view-theme="night"] { color-scheme: dark; }:root[data-view-theme="parchment"] { color-scheme: light; }@media (prefers-color-scheme: dark) does not follow color-scheme, only the app’s appearance,
so rules written with it ignore a forced theme.
Pico switches its colours on a data-theme="light" or "dark" attribute
rather than on color-scheme, and CSS cannot set an attribute. A Pico-based system writes it in its
own templates, from the theme:
<html lang="en"{% if env.theme == "night" %} data-theme="dark"{% endif %}>Keep data-theme for that alone: Pico reads any value on <html> as a forced scheme, so a theme id
there would turn off its automatic dark mode. That is why the app writes themes as
data-view-theme.

