Skip to content

Latest commit

 

History

History
executable file
·
151 lines (111 loc) · 10.6 KB

README.md

File metadata and controls

executable file
·
151 lines (111 loc) · 10.6 KB
Raw

D&D Battle Tracker

D&D Battle Tracker is an initiative and combat tracker tool for Dungeons & Dragons 5th Edition (D&D 5e). Track the initiative and status of all creatures involved in combat with this D&D combat tracker!

ko-fi

Feature ideas and general feedback welcome on Ko-fi. Bugs can be reported through Github issues.

Use

The D&D Battle Tracker is a web application designed to run in a browser but does not require an internet connection.

First, access the live D&D Battle Tracker. The application will then be saved in your browser for offline use. If your mobile or desktop browser supports it you can install the Battle Tracker as a Progressive Web App on your device so you can easily access it whenever you need to.

You can also download a specific release of D&D Battle Tracker below and open it in your favourite browser. This will be necessary if you have downloaded an in-progress battle that is no longer compatible with the live application:

For a particular release download the file dnd-battle-tracker.zip under Assets, unzip it and open the file index.html in a browser. For older releases you can download and open the dnd-battle-tracker.html file directly.

Motivation

As a new DM I found that I was frequently making mistakes during combat, such as:

  • Forgetting who's turn it was or skipping a creature's turn altogether.
  • Forgetting what conditions creatures were under.
  • Doing maths wrong when applying damage to creatures (!)

It was clear that some automation would be helpful. There's a number of browser-based combat trackers out there at the time of writing, in no particular order:

Many of these systems are very feature rich and aim to provide tools beyond the combat tracker itself, which is great. However that does mean that they come with a learning curve and several are gated-off behind login screens.

This D&D Battle Tracker simply aims to automate the process of tracking combat using a pen and paper. It attempts to do this in a way that is as straight-forward and easy to use as possible. As such it does not do things like provide custom character creation tools, battle map creation tools or provide content from the Player's Hand Book. Instead it focuses on automating the smaller things that are prone to error and often distract a DM from the combat itself.

Features

  • Core DM features work entirely offline.
  • Create a list of creatures who are involved in combat by adding a name, initiative score and health points for each one.
  • Track creature status pre- and post-battle so active conditions carry into battle and persist when its over.
  • Automatically order creatures by their initiative.
  • Keep track of who's turn it is as combat progresses as well as what the current round is and how long combat has lasted.
  • Keep track of creature conditions and any additional notes and how long they have been applied.
  • Make it obvious when conditions or notes have been applied to help the DM not to forget to take them into account.
  • Provide links to D&D Beyond's list of condition descriptions and monsters.
  • Manage the health points of enemy creatures or NPCs allowing HP to be added and removed whilst supporting adding PCs to the creature list without HP.
  • Allowing creatures to be killed/made unconscious and making it obvious to the DM that this has happened.
  • Creatures can be added to or removed from the list at any time, even after combat has started.
  • Save and load battles in case they continue into another session.
  • Share your battle with your players so they can see the initiative order and follow along. Requires internet access.

License and Credits

Icons

Fonts

Development

Checkout and install

 $ git clone [email protected]:Paul-Ladyman/dnd-battle-tracker.git
 $ cd dnd-battle-tracker
 $ npm install

To run

 $ npm start

To test

Unit and integration tests:

 $ npm test

End to end tests:

 $ npx playwright install --with-deps
 $ npm run test:e2e

Architecture

D&D Battle Tracker architecture

Deployment Pipeline

  • Following a Continuous Integration workflow, all commits to master will trigger the execution of automated tests and a build of the project
  • Commits to master that successfully pass the CI step will result in the build artefact being deployed to the staging environment
  • Commits to master that include a change in the package version and have successfully passed the CI and stage deploy steps will be deployed to the production environment
  • In this way, a Continuous Delivery workflow can be followed by increasing the version in the same commit as the code is modified. If a manual testing step is called for, the version can be left as it is and the change tested on the stage environment. A version change can then be committed seperately to promote the change to production
  • Each version successfully deployed to production results in a Github release being created with the build artefact dnd-battle-tracker.html attached. This ensures the current version of the project can be easily downloaded for use offline and all previous versions are available

Dependabot

  • The project's dependencies are automatically kept up to date using Dependabot, which creates pull requests for each update
  • Commits to pull requests also trigger the CI step of the pipeline and this step must execute successfully before the PR can be merged