Gloomhaven Secretariat

Latest Online Version

Scenario 1 of Gloomhaven with starting classes of different editions

Introduction

Gloomhaven Secretariat is a companion app for Gloomhaven-based board games. The app supports all official editions, namely Gloomhaven, Frosthaven, Jaws of the Lion, Forgotten Circles and Button & Bugs, the community editions The Crimson Scales and Trail of Ashes as well as Solo scenarios and custom content.

GHS is a complete replacement for the abandoned Gloomhaven Helper app (by Esoteric Software®), enhanced with more tracking and automation features. As a single-screen web application, GHS helps manage scenario play by tracking character and monster turns, automatically setting up monsters separately for each room or section, assisting with scenario-specific rules, attack modifiers, loot deck, and much more. GHS also tracks your progress on the Character, Party and Campaign sheets, allowing you to buy and equip items, loot treasures, apply all scenario rewards, register scenario unlocks and manage your outpost. For a more detailed feature list, including a comparison of some popular applications, see Comparison of Companion Apps.

Multiple clients are supported by a server component Gloomhaven Secretariat Server with a public instance available at gloomhaven-secretariat.de.

Since GHS is a web application, no installation is required and it runs in any modern browser, even on mobile devices, but it can also be installed for offline use.

Gloomhaven Secretariat is open-source software built with Angular and is open for the community to actively contribute ideas, suggestions and of course feedback and bug fixes.

A basic user guide is available online.

SPOILER WARNING: The label-spoiler folder in the data folders, and therefore the final edition data files in the releases in the ./assets/data folder, contain spoilers by including the appropriate label.

More information about spoilers in this repository

Support me

☕ Buy me a coffee? (or Donate directly via PayPal)

Current Features

• Base feature complete for GH, FH, JOTL, FC and CS (all need testing, so please contribute!), for details see Data Progression
• Tracking:
  • Initiative sorting
  • Health automatic exhaust/dead, max values for each level
  • Conditions auto expire + auto apply (wound, wound_x, regen, bane, poison, poison_x, ward, brittle)
  • Level, Loot, Experience of characters
  • Character Progression level, loot, experience, items, battle goals, perks, masteries
  • Character Attack Modifier Deck including Perks & CS Oak Cards
  • Elements automatic update status
  • Monster Stats
  • Monster Standees automatically adds standees for scenario rooms/sections, special rules and random monster cards
  • Monster Modifier Deck Adding Blessings and Curses, auto-shuffling
  • Monster Ability Cards auto-shuffling, calculated values (separate for normal and elite), add stats values
  • Character Summons
  • Scenarios and Sections with automatic level calculation, displays and applies special rules, and applies scenario results to character progression
  • Party Sheet
  • Campaign Management (some special rules for CS are missing)
  • Markers
  • Treasures
  • Character Items (must be enabled in Settings!) manage state of items during a scenario
  • Battle Goals (must be enabled in Settings!)
• Elimination of the following physical components
  • Monster ability cards
  • Monster stat cards
  • Monster attack modifier deck
  • Damage tokens
  • Condition tokens
  • Element board, elemental disc, round tracker, initiative trackers
  • Character HP/XP dials
  • Character boards
  • Character sheets
  • Character attack modifier deck
  • Loot deck
  • Town guard deck
  • Party/Campaign sheet
  • Item Cards
  • Battle Goals
  • Building deck (partly!)
  • World Map (GH/FH)

• Other features:

  • i18n support (currently en, de, fr and ko, more translations needed. Many thanks to the contributors of french and korean)
  • PWA for installation on all devices!
  • Synchronise state (+ settings) with GHS Server
  • Manage permissions for different clients with GHS Server
  • Keyboard Shortcuts
  • Load custom JSON edition data for custom content!
  • Edit monster attack modifier and monster ability decks (support for Diviner class mechanics): reveal cards, remove cards, rearrange cards
  • Support for Frosthaven loot deck (including enhancements) and town guard deck

  • special ability automation for some characters

    SPOILER WARNING:

    > Enable song to automatically gain 1 XP at start of turn
    SPOILER WARNING:

    > Enable overhealing up to 26 HP > Toggle immunity for all conditions
    SPOILER WARNING:

    > Automatically add/remove time tokens at start of round after defining slow/fast before
    SPOILER WARNING:

    > Toggle Mode Token for summons (inactive if Mode Token set)
    SPOILER WARNING:

    > Mech Suit (+5 HP, Heal 10)
  • Random Dungeons
  • Scenario Flow Chart
  • Monster data editor (https://gloomhaven-secretariat.de/editor/monster)
  • Includes Solo scenarios
  • Includes the Seeker of Xorn campaign: can be enabled under Data Management.
  • Includes the Satire's Extended Battle Goals: can be enabled under Data Management.
  • Includes Ice Rift: can be enabled under Data Management.
  • Includes Blood and Sand campaign: can be enabled in Data Management (Thanks to /u/Calm_Construction131 for contribution)
  • Manage multiple campaigns
  • Show errata hints (must be enabled in Settings)
  • SPOILER WARNING: Envelope X (and V)

    > To add Envelope X (or V for ToA), enable it under *Data Management*, then enter the full name in the *Character Filter* (not case sensitive).

Planned next

• Support for event cards (draw, manage, apply rewards)

Long term plans

• Support for managing character ability cards

Install

Install as App

You can always install any hosted version as an App (PWA) if your OS/Browser supports PWA installation. For example, here is the Latest Online Version.

Instructions for different devices/browsers:

• Chrome: Computer/Android
• Safari: iOS
• Firefox: Android
• other: search for "install PWA"

Standalone

An Electron application is available for Linux, Mac and Windows. Download the appropriate files from the latest release assets.

Linux AppImage only tested for now

Self-hosting

To self-host Gloomhaven Secretariat on your web server, simply download the zip file from the latest release and unzip it on your web server.

The base url for this build is set to root. To use a different base URL, please build your own package.

Build and run with Docker

If you want to use docker to run on port 80, run the following

docker pull gloomhavensecretariat/ghs
docker run --rm -p 80:80 --name ghs gloomhavensecretariat/ghs

For use with docker compose, just run docker compose up -d.

Building from source

If you want to create your own custom build (e.g. for self-hosting), prepare a development setup. Then run npm run build (available options) and access the build at ./dist/gloomhavensecretariat.

Development

Prerequisite:

• Current Node.js and npm version

Check out the source with git clone https://github.com/Lurkars/gloomhavensecretariat.git.

Install the dependencies with npm install.

Then run npm run start to create a development server at http://localhost:4200.

To develop with docker, install docker compose and run docker compose -f docker-compose.dev.yaml up -d.

Contributing

Feel free to file a new issue for bugs, features, and improvements, or start a new new discussion for help or feedback.

All game data is located in the data folder with subfolders for each release. A third-party review of all data would be great. As all files are JSON data, they should easily be human-readable. Each character, monster, and monster deck has its own file, so it should be easy to check. Each edition folder will be concatenated into a single edition data file on build.

Pull requests are also welcome!

Please note: all files in the data subfolder will be automatically formatted and added to each commit. If you have made local changes to these files and do NOT want to commit those changes, please use the --no-verify parameter for your git commit and git push commands.

Thanks to everyone who has already contributed, you're awesome!

Archive

All older versions are also available on gloomhaven-secretariat.de, for example the first version v0.0.1 is available at v0-0-1.gloomhaven-secretariat.de. All available tags are listed under Releases, just replace all . with - for a proper url. This is meant as a showcase for the evolution of GHS, but also as a fallback, if a release breaks something important, you can always fall back to a previous version.

Please note that there is no history of the server component. So connecting to the current server with older clients may not work properly!

Privacy

This application does NOT collect any personal data. Everything runs and stays in your browser/local memory. For details on the server component please go to Gloomhaven Secretariat Server#Privacy.

Copyright / License

Gloomhaven and all related properties, images and text are owned by Cephalofair Games.

Assets/Data used:

• Creator Pack by Isaac Childres CC BY-NC-SA 4.0
• Worldhaven
• Nerdhaven Images
• X-haven Assistant
• Gloomhaven Item DB
• Virtual Gloomhaven Board
• some other used assets are licensed under public domain

Source code is licensed under AGPL

Personal disclaimer

This is a hobby project I do in my spare time. The software fills a practical need due to the demise of the original Gloomhaven Helper application, so I am following the Quick'n'Dirty approach to get things done quickly. This of course leads to a lack of quality and testing and the code base is definitely not in line with my professional work.