docs: add comprehensive REFERENCE.md for pipeline, formulas, and config - #25
Merged
Merged
Conversation
Three files had drifted out of ruff format compliance on master. Pure formatting changes (line-wrap normalization in error messages and comments); no behavioural change. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
A single reference doc that explains every calculation in the 15-stage pipeline — with file:line links to source for every formula — and documents all ~70 WorldConfig parameters plus the in-code constants that shape map output. Includes a colour-coded mermaid flowchart of the pipeline. README gets a one-line pointer. Closes the gap between user-facing setup docs (README.md) and the original spec (worldgen_plan.md): neither covers "how does this number in config.py actually affect the map" or "what's the formula behind orographic moisture / road slope cost / lake spillway routing". Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The original 'config.py:42-113' range endpoint was off-by-one against unmerged origin/master (which has it at line 114) due to a one-line formatter shift. Dropping the endpoint makes the citation correct in both states; the link target #L42 is stable either way. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a consolidated reference document intended to explain the full worldgen pipeline, formulas, and WorldConfig parameters, and links it from the README. Includes a small ruff-format-only cleanup in a few existing files.
Changes:
- Add
docs/REFERENCE.mdcovering pipeline stages, algorithms/formulas, config parameters, constants, outputs, and glossary. - Add a short README pointer to the new reference doc.
- Apply
ruff formatnormalization to a few existing Python/test files (no behavioral changes intended).
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
worldgen/core/config.py |
Formatting-only changes (line wrap/indent normalization in config + validation error message). |
tests/test_settlements.py |
Formatting-only changes (assert line wrapping). |
tests/test_road_cost.py |
Formatting-only changes (assert message wrap). |
README.md |
Adds a link near the top pointing readers to docs/REFERENCE.md. |
docs/REFERENCE.md |
New comprehensive reference doc for the pipeline, formulas, and configuration. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| **Algorithm** | ||
|
|
||
| Eight phases, top to bottom in |
| incoming = mean(atm[upwind neighbours]) or 1.0 if none upwind | ||
| lift = max(0, hex.elevation - sea_level) | ||
| fraction = min(1, lift * orographic_strength) | ||
| hex.moisture = incoming * fraction |
Comment on lines
+622
to
+624
| river-tagged neighbour at `≤` its own elevation. This builds a wider | ||
| moisture corridor along big rivers, especially in valleys, but never | ||
| uphill. Re-normalised after the passes. |
Comment on lines
+1042
to
+1049
| **Stochastic placement** uses the **Gumbel-max trick** | ||
| ([village_placement.py:80–81](../worldgen/stages/village_placement.py#L80)): | ||
| ``` | ||
| u = uniform_random per candidate | ||
| order = sort by -u^(1/weight) descending | ||
| ``` | ||
| This is equivalent to drawing weighted samples without replacement. Then | ||
| the stage walks `order` and accepts a candidate iff it is `>= 3` hexes |
| - **Coordinates:** axial `(q, r)`, flat-top hexagons. | ||
| Neighbours, distance, ranges, and pixel conversion live in | ||
| [worldgen/core/hex_grid.py](../worldgen/core/hex_grid.py). | ||
| Hex distance is the standard cube-distance halved: |
Owner
Author
|
@copilot apply changes based on the comments in this thread |
Agent-Logs-Url: https://github.com/countercheck/worldgen/sessions/3ecf7792-6de2-483d-b3a5-90137dd234bc Co-authored-by: countercheck <4325443+countercheck@users.noreply.github.com>
Contributor
Implemented all requested review-thread fixes in docs/REFERENCE.md and pushed in commit |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/REFERENCE.md(~1,400 lines) — a single reference covering the 15-stage pipeline, every calculation, and all ~70WorldConfigparameters with defaults, ranges, and effectsfile:linelink into the sourcestyle: apply ruff formatcommit fixing pre-existing formatter drift in 3 unrelated files (line-wrap normalisation, no behavioural change)What's in the doc
WorldState,Hex(every field with range and writer), enums, tag vocabularyWorldConfigparameter, cross-linked to the §3 stages that consume themWorldConfig(erosion_MAX_STEPS, mountain elev cap>0.8, habitability weights, dense-forest threshold(wet_moist+1)/2, hardcoded village separation3, etc.)worldgen generatewritesWhy
README.mdcovers usage andworldgen_plan.mdis the original spec, but neither answers "how does this number in config.py actually affect the map?" or "what's the formula behind orographic moisture / road slope cost / lake spillway routing?" — anyone tuning a world or extending a stage today has to read source. This doc closes that gap, and is structured so a config-tuner can land in §4 and skip the math while a code-extender can read §3 top-to-bottom.Test plan
python3 -m ruff check .— passespython3 -m ruff format --check .— passes (52 files clean)python3 -m pytest— 210 passedworldgen/core/config.pycli.py:58–74docs/REFERENCE.mdon GitHub and verify the mermaid flowchart renders🤖 Generated with Claude Code