Walked every tab on desktop and phone, clicked every link and button:
- Colours: new map inks and page colours, checked with simulated
protanopia/deuteranopia/tritanopia (worst pair ~12 CIEDE2000, was 1.4 for
Red/Green on the map and 9.7 for Orange/Brown on the page). Map label text
is always dark ink; dragon colour goes on borders. docs/COLOURS.md and
research/python/check_colours.py.
- Valley map: dragons get a paper halo and a visibility floor (faded ones never
drop below 0.3; bonding dragons start at 0.5); "no shadow" roll labelled
correctly.
- Wording: methods updated (strata, the newer form's questions, missing
answers, a new section on the solver, The Odds cards and genuine attempts);
findings use readable factor names and no longer claim a date adjustment;
'Load a newer route export above'; code links include solver.js and
explorer.js; The Odds shows 93% instead of '1 in 1'.
- Deep Dive route map treats all six dragons alike ('Bond a dragon' row,
default 'Bond any dragon'; rare sightings separate).
- Phone: Deep Dive no longer overflows (sections and selects can shrink).
- scripts/qa/crawl.js and mapcheck.js for future release checks.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UCzTd31GphpMXDhQqWrCMQ
118 lines
6.2 KiB
Markdown
118 lines
6.2 KiB
Markdown
# Threshing Atlas
|
||
|
||
Route probabilities and path finding for the Dragonkind threshing: which choices lead to which
|
||
dragon, how often, how sure we can be, and (in progress) the best route to each colour.
|
||
|
||
Unofficial fan project. Not affiliated with Dragonkind or the Fourth Wing publishers.
|
||
|
||
## Layout
|
||
|
||
```
|
||
apps/atlas/ the web page. The Valley (explorer.js: the map, the dragons, routes on demand; dragons.js:
|
||
original silhouettes), The Odds, The Dragons, Deep Dive, Data & Methods
|
||
packages/core/ @threshing-atlas/core, no dependencies, runs in Node and the browser:
|
||
src/engine.js coding rules and statistics for the community form
|
||
src/graph.js the shared route graph: scene graph, decision-variable graph,
|
||
bot-to-form crosswalk, Beta credible intervals
|
||
src/solver.js best decisions per dragon colour (history-dependent decision tree,
|
||
empirical-Bayes back-off, two objectives) + the bot advisor
|
||
packages/ingest/ @threshing-atlas/ingest: DragonKind bot importer (fingerprints and choice text only)
|
||
research/python/ independent Python implementation of the coding rules and statistics
|
||
tests/ JS/Python parity tests (they fail loudly if the two disagree)
|
||
scripts/build-site.js assembles the static site into dist/
|
||
scripts/build-graph.js combines every source into data/public/graph.json
|
||
scripts/build-policy.js solves for every colour -> data/public/policy.json; policy-report.js -> docs/POLICY.md
|
||
data/raw/ source exports (form .xlsx; the register export stays local, git-ignored)
|
||
data/public/ what the page loads: form_responses.json, register.json, graph.json
|
||
data/sources.json where the community spreadsheets and the PDF are downloaded from
|
||
data/derived/ coded runs (runs_clean.csv)
|
||
data/bot/ anonymised DragonKind bot runs, added by pull request
|
||
docs/ ROADMAP.md, BOT_DATA_PROTOCOL.md, REDDIT_POST.md
|
||
```
|
||
|
||
## Run it locally
|
||
|
||
Requirements: Node 18+, Python 3.9+ (`pip install -r research/python/requirements.txt`).
|
||
|
||
```
|
||
npm run dev # builds dist/ and serves it at http://localhost:8000
|
||
npm test # JS engine + Python reference + parity checks
|
||
```
|
||
|
||
## New data from the community sources
|
||
|
||
A GitHub Action (`.github/workflows/update-sources.yml`) runs every day. It downloads the Threshing Routes
|
||
responses, the Dragon Register and the route PDF, and if anything changed it rebuilds the data, runs the
|
||
tests and opens a pull request that says what changed: new responses, new or renamed questions, and for
|
||
the PDF the pages and lines that are new. The PDF itself is never committed, only a fingerprint
|
||
(`data/derived/pdf_fingerprint.json`). If a link stops working, the Action opens an issue. You can also
|
||
run it by hand from the Actions tab, or locally with `npm run check-sources`.
|
||
|
||
## Best routes (the solver)
|
||
|
||
`npm run policy` rebuilds `data/public/policy.json` and the readable `docs/POLICY.md` (about 2.5 minutes:
|
||
200 posterior draws for two data samples). For every colour it gives the best decision at every point under two
|
||
objectives: the chance of bonding that colour on this attempt, and the chance the account eventually ends on that
|
||
colour when you die on purpose whenever a run goes wrong. Chance events (which dragon appears, whether the shadow
|
||
shows) may depend on earlier choices; how much is learned from the data. See the top of
|
||
`packages/core/src/solver.js` for the model and `docs/BOT_INTEGRATION.md` for how the bot uses it.
|
||
|
||
## Bot data
|
||
|
||
The private DragonKind bot's files are converted locally, and only the anonymised result is committed:
|
||
|
||
```
|
||
DK_ACCOUNT_SALT=... npm run import-bot -- --bot /path/to/DragonKind --tag 2026-11-01
|
||
npm run graph
|
||
```
|
||
|
||
This writes `data/bot/scenes.json` and `data/bot/trajectories-<tag>.jsonl`: scene fingerprints, short labels,
|
||
choice text and outcomes, with no game prose and no account names. The importer refuses to write anything that
|
||
looks like prose. See `docs/BOT_DATA_PROTOCOL.md` for what the bot should log.
|
||
|
||
## Updating with new form data by hand
|
||
|
||
In the browser: open the page and use **Load a newer export** with the responses spreadsheet
|
||
(Google Sheets → File → Download → Microsoft Excel). Everything recomputes. Questions are matched by
|
||
wording; a renamed question is listed as "not found", and then `COLUMN_KEYS` in
|
||
`packages/core/src/engine.js` and `research/python/clean.py` need updating.
|
||
|
||
To update the bundled snapshot, put the new export in `data/raw/form/`, then:
|
||
|
||
```
|
||
cd research/python
|
||
python export_raw.py ../../data/raw/form/NEW_EXPORT.xlsx ../../data/public/form_responses.json
|
||
python clean.py ../../data/raw/form/NEW_EXPORT.xlsx
|
||
cd ../..
|
||
npm test
|
||
```
|
||
|
||
## Changing a coding rule
|
||
|
||
Every rule lives in `codeRow()` in `packages/core/src/engine.js` and `code_row()` in
|
||
`research/python/clean.py`. Change both and run `npm test`.
|
||
|
||
## Statistics in one paragraph
|
||
|
||
Rates use 95% Wilson score intervals. Each answer is compared with the other answers to the same
|
||
question by odds ratio (Woolf CI, +0.5 Haldane correction for zero cells) and Fisher's exact test, with
|
||
Benjamini–Hochberg q-values. Because Blue- and Black-chasers report rare sightings far more often than
|
||
players who log every run, key outcomes are also modelled with ridge-penalised logistic regression
|
||
(λ = 1) that includes data source and chase goal, and route rankings use a Mantel–Haenszel odds ratio
|
||
stratified by the same factors. The page's Methods section has the details.
|
||
|
||
## Licences
|
||
|
||
Code: MIT (`LICENSE`). Data produced by this project: CC BY 4.0 (`DATA_LICENSE.md`), which also lists
|
||
third-party sources that keep their own terms.
|
||
|
||
## Release checks
|
||
|
||
```
|
||
npm test # parity and unit tests
|
||
python research/python/check_colours.py # dragon colours stay distinguishable (docs/COLOURS.md)
|
||
npm run build && python3 -m http.server 8765 -d dist &
|
||
node scripts/qa/crawl.js /tmp/qa # every tab on desktop and phone: text, links, buttons, errors, overflow
|
||
node scripts/qa/mapcheck.js /tmp/qa # every dragon's routes: off-map labels, overlaps, too-faint dragons
|
||
```
|