DFMA HTML 5 Map Viewer

Home for development of a new HTML5 Map Viewer for Dwarf Fortress.

Please read the architecture page for details about how the viewer works; and how to set it up in a larger project.

Local Developer Setup

Clone this repo, then run:

npm install

To start the parcel server, and view the map viewer, run:

npm start
open http://localhost:1234/index.html

Testing

When developing locally; please run:

npm run lint && npm test -s

These tests will be run on commit, and as part of PR testing.

There are also integration tests that can run locally - they use a headless browser and perform a pixel diff of the rendered map with known good state.

The tests can be run using:

npm run test:integration

PR / Contribution Guidelines

We have a project page for site wide improvements that you may be able to help with, and a forum post that you can follow to discuss ideas. Otherwise raise an issue on this repo and we'll get in touch.

Github actions are set up to run linting and tests against branches and PRs. You can and should run tests locally before submitting a PR.

When forking, or raising a PR please keep the PR in Draft until you're ready to merge, the project team will be notified in order to provide a code review before merging to master.

Please ensure that tests pass; and that you've added adequate testing around any new functionality introduced to the code base.

Deployment Pipeline

The master branch is protected; the default action for merge to master is to build and deploy the viewer to the /xdfmadev/parcel/ folder on the DFMA website.

Creating a release

When you have a working tested, ready to release, version of the map viewer...

Update the version number in package.json using semver
Commit with the message Prepare v{major}.{minor}.{patch} for release
Go and draft a new release with the tag in the syntax v{major}.{minor}.{patch}
Use the tag version as the title i.e. v{major}.{minor}.{patch}
Add a short and informative description about the release
Submit the Publish release button

This will trigger a deployment pipeline to upload the compiled files to:

https://mkv25.net/dfma/viewer/js/$RELEASE_VERSION

Credits

Credit where credit due:

Thanks to Jacob Blomquist for his original and continued work on the HTML version of the map viewer
p5.js - for a fantastic canvas interface
pako - for a fantastic zlib implementation

Contributions

Jacob Blomquist - original implementation of a HTML based decoder and renderer
John Beech - refactor and redesign to work with DFMA (original author of historic Flash viewer)
Max Heisinger - remove pixelDensity call to support high-resolution fonts

maximaximal/dfma-html5-map-viewer