Custom System
A game system is what gives Encounter+ its shape. The app itself has no notion of a creature, a spell or a stat block — it loads one system at a time and builds its entire content model, library, editors and detail views from the JSON files that system contains.
That means a whole ruleset can be authored without writing a line of app code. This section is the developer’s guide to doing that.
What a system is
Section titled “What a system is”A system is a folder on disk, identified by a short lowercase id such as dnd5e. It lives under
Documents/systems/<id>/ and is fully visible in the Files app, so it can be edited on the device
or on a computer.
Inside that folder, a handful of JSON files answer a handful of questions:
| Question | Answered by |
|---|---|
| What content types exist? | entities.json |
| What are their fixed value sets? | types.json, collections.json |
| How is each type edited? | forms/*.json |
| How is each type displayed? | views/*.json |
| What does it look like? | themes/*.json |
| How does the library filter and group? | filters.json |
| How does the app behave for this ruleset? | config.json |
| What text is shown, in which language? | lang/*.json |
| How does old content catch up? | migrations/*.js |
Everything else in the folder — icons, images, fonts, web assets — is supporting material those files point at.
What a system is not
Section titled “What a system is not”A system carries definitions, not content. Creatures, spells and items are user content: they live in modules and campaigns and merely record which system they belong to. The bundled D&D 5E system, for example, ships the definitions for a 5E creature but no creatures.
This separation is what lets a system be updated independently of the content authored against it.
The development loop
Section titled “The development loop”1. Create a skeleton
Section titled “1. Create a skeleton”The System Manager (reached from the main screen’s system button) has a Create button. It
asks for a name, short name, version and system id, and writes a minimal system folder containing
config.json, entities.json, types.json, filters.json, a default theme and a starter set of
icons.
Starting from an existing system is often faster. Install one, then copy its folder under a new id
and change the id in system.json.
2. Edit the files
Section titled “2. Edit the files”Open Documents/systems/<id>/ in the Files app, or over a file share on a Mac, and edit the JSON
directly. Any text editor works.
3. Reload
Section titled “3. Reload”The system button on the main screen offers Reload System. It re-reads every definition file without restarting the app, so the usual loop is save → reload → look.
Reloading also happens automatically when you save system settings, and when a system is installed or made primary.
4. Read the errors
Section titled “4. Read the errors”A form, view or theme file that fails to decode does not crash the app and does not silently disappear — it is replaced with an error definition that renders the decoder’s message where the form or view would have been. If a screen shows a wall of Swift decoding text, that is a malformed JSON file telling you which key it choked on.
Setting "debug": true at the top of a view or theme definition turns on layout debugging for
that file.
Where to look things up
Section titled “Where to look things up”This section is the guide. The exhaustive, generated list of every key and every enum value in every definition file lives in the schema reference — in particular:
When this guide and the schema reference disagree, the schema reference is right — it is generated from the app’s own data model.
Where to go next
Section titled “Where to go next”- System Structure — every file and folder, and the order they load in.
- Entity Definitions — declaring content types and their data.
- Forms — building the editors.
- Views — building the detail screens.