Tooling

RawContent/World/Templates/Map5.overlay.json

@@ -0,0 +1,48 @@
+{
+  "_comment": "The annotation layer for Map5: a second painting, the same size as the template and registered to it, saying what is *placed on* the finished world rather than what the rock is doing. Paint it in `terrain studio` under the `overlay` tab (or press o), or let `terrain overlay` propose a first draft from a bake. See README.md next to this file, and Docs/Terrain.md.",
+
+  "_comment_blank": "Most of this sheet is nothing, and nothing is alpha rather than a colour: an unpainted pixel is transparent, so no colour has to be spent on the background and an export with a white matte behind it does not turn the world into whatever mark white is nearest. An opaque pixel further than match_distance from every mark below is dropped and counted - `terrain plan` says how many, which is the only way a colour the legend forgot ever shows.",
+
+  "_comment_image": "There is no image yet, and that is the normal way to start: the legend says what the marks mean and the sheet stays empty until the first save from the studio, or until `terrain overlay` writes one. The manifest's planet.overlay is what points at it once it exists.",
+
+  "image": "Map5.overlay.png",
+  "match_distance": 40,
+  "min_area_px": 24,
+
+  "marks": [
+    { "_comment": "The one thing on this layer the generator reads. The waterline roughening exists because a drawn shore is a smooth curve and a real coast is fractal - which is true of a coast nobody thought about and false of one traced off a map on purpose. Paint over the shore you drew by hand and it stays exactly where you put it while the rest of the world is still roughened. Either side of the waterline is enough; a brush stroke along it covers both.",
+      "name": "drawn_coast", "rgb": [255, 0, 255], "coast_jitter": 0,
+      "note": "Coastline as painted. No jitter." },
+
+    { "_comment": "The same knob pointed the other way. A fjord or a ria coast wants more than the planet's own amplitude, not less; at 2.5 the bays are two and a half times as deep and just as wide, which is what makes them fjords rather than scallops.",
+      "_comment_generate": "This mark can also be generated - add \"generate\": { \"kind\": \"coast\", \"coast_km\": 2.5 } and `terrain overlay` will band every shore with it. It is left off deliberately: coast_jitter is the one overlay property a pass reads, so generating this mark changes the next bake everywhere, and that is a decision to take on purpose rather than to inherit from a default.",
+      "name": "wild_coast", "rgb": [255, 128, 0], "coast_jitter": 2.5,
+      "note": "Chew this shore harder than the rest of the world." },
+
+    { "_comment_inert": "Everything below is inert. No pass reads it, no height changes, and two bakes with and without it are the same terrain to the bit. What they do is travel: each one comes out as an index in the per-tile mask beside every heightmap, and as a feature in world metres in overlay.json - a centre, an area, an extent for an area; an ordered polyline for a path. That is what the engine places things from.",
+
+      "_comment_generate": "The generate block lets `terrain overlay` propose this mark from a baked world. not_classes keeps it off ground painted as ice or desert, which matters more than it sounds: height and slope cannot tell an ice cap from a meadow, and without it woodland grows across both poles. The treeline is derived from the land's own heights, because a number in metres means nothing until the world is baked.",
+      "name": "forest",  "rgb": [0, 128, 0],
+      "note": "Where trees are scattered. The mask is the volume bound.",
+      "generate": { "kind": "forest", "cover": 0.45, "wavelength_km": 6, "max_slope_deg": 22,
+                    "not_classes": ["ice", "desert"] } },
+
+    { "_comment_settlements": "Three tiers, listed largest first, which is the order the generator places them in. They share one spacing rule - the largest min_spacing_km any of them sets - so a village never lands inside a city. Sites are scored on the three things the terrain actually knows: drainage, flat ground and distance to the sea. Everything else about where a town is belongs to you, which is why these are proposals in a sheet you edit.",
+      "name": "city", "rgb": [220, 30, 30], "min_area_px": 400,
+      "note": "One settlement per painted blob. overlay.json gives its centre and radius.",
+      "generate": { "kind": "settlement", "count": 4, "min_spacing_km": 9, "not_classes": ["ice"] } },
+
+    { "name": "town", "rgb": [255, 200, 0], "min_area_px": 120,
+      "generate": { "kind": "settlement", "count": 12, "not_classes": ["ice"] } },
+
+    { "name": "village", "rgb": [150, 90, 200], "min_area_px": 24,
+      "generate": { "kind": "settlement", "count": 30, "not_classes": ["ice"] } },
+
+    { "_comment_path": "A path is a stroke whose width is not the point: it is thinned to its centreline and comes out as an ordered polyline, because the thing built from it on the other side is a spline. width_m is what the road really is on the ground and is carried rather than used. One stroke is one path - a fork reports its two longest arms as one line and drops the third - so paint each run separately and check the piece count in `terrain plan`.",
+      "_comment_generate": "Generated roads are a minimum spanning tree over the settlements along least-cost paths, not every pair, so there is exactly enough road to reach everywhere. Water is impassable, so each landmass gets its own network and a bridge stays a deliberate act.",
+      "name": "road", "rgb": [90, 60, 30], "kind": "path", "width_m": 8,
+      "generate": { "kind": "road", "max_slope_deg": 20 } },
+
+    { "name": "track", "rgb": [200, 160, 110], "kind": "path", "width_m": 3 }
+  ]
+}