ferransalguero / gloomhavensecretariat

A Gloomhaven / Frosthaven Companion App

Gloomhaven Secretariat

Latest Online Version

Gloomhaven Secretariat is a Gloomhaven/Frosthaven companion app and does bookkeeping of all entities values to gain more focus on gameplay. It is an open source web app made with Angular.

As GHS is a web application no installation is required and it runs in every modern browser even on mobile, still it can also be installed for offline usage.

For usage with multiple clients sharing the same game, the server component Gloomhaven Secretariat Server is required. A public instance is available under gloomhaven-secretary.de port 8443 with secure option. (I also manage a public server list, so please contact me, if you're running a public instance yourself.)

GHS is based on the look&feel of the original Gloomhaven Helper (by Esoteric Software®). Since GHH is discontinued and not available anymore, GHS should become a well maintained successor, implementing all functionality of GHH, many improvements and many more features. For a comparison of some popular apps, see Comparison of Companion Apps.

As open source software this is meant for the community to actively contribute with ideas, suggestions and of course feedback. As I am not capable of good design/UX also feel free to contribute better assets.

If you need help using the app take a look at the help page. It is not complete but should help with all general steps to use GHS properly.

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

Support me

☕ Buy me a coffee? (or Direct Donation via PayPal)

Current Features

• Feature complete for GH, FH, JOTL, FC and CS (all needs testing, so please contribute!)
• Tracking:
  • initiative sorting
  • health automatic exhausting/dead, max values for every level
  • conditions automatic expire + automatic apply (wound, wound_x, regenerate, bane, poison, poison_x, ward, brittle)
  • level, loot, experience of Characters
  • Character Progress level, loot, experience, items, battlegoals, perks, masteries
  • Character Attack Modifier Deck including perks
  • Elements automatic update state
  • Monster Stats
  • Monster Standees automatic add standees for scenario rooms/sections and special rules (rooms/sections data WIP)
  • Monster Modifier Deck addition of Blesses and Curses, auto-shuffling
  • Monster Ability Cards auto-shuffling, calculated values (separated for normal and elite)
  • Character Summons
  • Scenarios and Sections with automatic level calculation, remind and apply special rules and scenario finish for applying character progress
  • Party Sheet
  • Campaign Management (special Rules for CS and FH missing)
  • Markers
• Eliminating the following physical components:
  • monster ability cards
  • monster stats sheets
  • monster attack modifier deck
  • damage tokens
  • condition tokens
  • element board, element discs, round tracker, initiative tracker
  • character HP/XP dials
  • character boards
  • character sheets
  • character attack modifier deck
  • loot deck
  • party sheet
• Other features:

  • i18n support (currently en, de, fr and ko, more translations required. Big thanks to contributers of french and korean)

  • PWA for installation on all devices!

  • Synchronize state (+ settings) with GHS Server

  • Permission management for different clients with GHS Server

  • 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, re-order cards

  • FH Loot Deck support incl. Enhancements

  • Monster data editor

  • includes Solo Scenarios for GH, FC and CS

  • includes Blood and Sand campaign: can be enabled under Data Management (Big thanks to /u/Calm_Construction131 for contribution)

  • includes Seeker of Xor campaign: can be enabled under Data Management

  • manage multiple parties (on party sheet while no active scenario set)

  • SPOILER WARNING: Envelope X

    To add Envelope X, add the following Edition Data Url under Data Management ./assets/data/gh-envx.json and enable it.

Short term plans

• validation of all existing data
• room/section/standee data for all scenarios!
• add Trail Of Ashes edition data

Long term plans

• support for managing character ability cards

Install

Install as App

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

Instructions for various devices/browser:

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

Standalone

An Electron app is provided for Linux, Mac and Windows. Download the corresponding files from the latest release assets.

only tested Linux AppImage for now

Selfhost

To selfhost Gloomhaven Secretariat on your webserver, simple download the zip file from the latest release and unzip to your webserver.

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

Build and run using Docker

Build and run using Docker

If you want to use docker for running on port 80 execute following:

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

For usage with docker compose, simple run docker compose up -d.

Build from source

If you want to create you own custom build (for example to selfhost), prepare a development setup. Afterwards run npm run build (available options) and access build under ./dist/gloomhavensecretariat.

Development

Prerequisite:

• up-to-date Node.js and npm version

Checkout the source code with git clone https://github.com/Lurkars/gloomhavensecretariat.git.

Install dependencies with npm install.

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

For development 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, improvements, help or feedback.

All game data is inside the data folder with subfolders for every edition. A review of all data by a third person would be awesome. As all files are JSON data it should be easily human readable. Every character, monster and monster deck has it's own file, so it should be easy to check. Every edition folder get concatenated to a single edition data file on build.

Also pull requests are welcome!

Privacy

This app does NOT collect ANY personal data. Everything runs and stays in your browser/local storage. For usage of 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
• Frosthaven spoiler images (u/Juar99)
• Nerdhaven Images
• X-Haven Assistant
• Gloomhaven Item DB
• Virtual Gloomhaven Board
• some other assets used are public domain licensed

Source code is licenced under AGPL

Personal disclaimer

This is a hobby project I do in my free-time. The software provides a practical need due to the end of the original Helper app and so I completely follow the Quick'n'Dirty approach to get things fast done. This leads of course to a lack of quality and testing and the code base does definitely not comply with my profession.