UnrealPrototyping/Docs/World-Dressing.md

Dressing the world: substances, sky, light and things that grow

A plan, not a specification. It covers what has to happen for L_World to read as deserts, coasts, tropics and craters rather than as one grass-and-rock material stretched over 2549 km², and for there to be a sky and trees worth looking at.

World-Pipeline.md is how the ground gets made and imported; this is what it wears afterwards. Everything here is off the ladder (D-47) and blocks no step in Steps.md.

---

What we already have, which is more than it looks

The single most important fact: the biomes are already painted. Map5.legend.json is not a set of erodibility numbers that happen to have names — it is a per-pixel classification of the planet.

Class	RGB	Is
ocean / deep	91,175,185 / 66,165,180	sea, two depths
ice	250,250,250	ice cap
lowland	150,200,105	plains
highland	71,175,100	hill and mountain country
desert	226,215,145	arid
crater	124,116,111	impact ground

That map exists at planet resolution in three forms already registered to the world by the same normalised u,v as everything else: Plan/map_class.png, Bake_NNN/map_class.png, and Orogen Gens/orogen-painted-class-7945.png. There is also orogen-climate-7945.png, Orogen's own climate bands, which is where tropical comes from — it is the one biome you asked for that is not a painted class.

The overlay legend already carries forest (generation enabled), plus city/town/village and road/track. terrain overlay and the studio's Generate marks button already place them.

And what we do not have:

Substances	Three. Base_Layer (rock), Layer_02 (meadow grass), Layer_03 (high rock) — all from Elite_RockyMeadows, collected into Content/Terrain/ (D-69a). No sand, no beach, no jungle floor, no ice, no crater regolith.
Trees	None, in any pack. HouseForge has one mushroom and a cover-plant material; Medieval_Weapons and RPGEnvironmentVFX have no ground cover at all.
Grass	None. M_Ground_Landscape has no LandscapeGrassOutput node, so nothing grows anywhere.
Sky	Elite_RockyMeadows' skybox mesh, sun with cloud shadows, sky light, exponential fog — scaled for world size in rocky_meadows.py. Serviceable; not authored.
Biome weightmaps	Not carried. region_manifest.LAYER_SUFFIXES is a fixed dict of three, and Region.json's layers block derives them from slope and altitude alone.

---

Five decisions that gate the work

All five are now taken (D-74); the reasoning is kept because it is why the phases are shaped as they are. The two that were a genuine fork went: dress Route A now rather than wiring Route C first, and Fab/Quixel Megascans for the substances and the trees.

1. Where the substances come from. [DECIDED] Fab/Quixel Megascans. Free for Unreal use and has every surface on the list — sand, shingle, jungle litter, regolith, ice — plus trees for Phase 5. Each goes into RawContent/Terrain/ground.json exactly as the Rocky Meadows set did, so collect_terrain_assets.py keeps owning Content/Terrain/ and no pack is ever modified. This is the one thing the plan needs from a person: the assets have to be added to the project from Fab before Phase 2 can start. Phase 1 does not wait on them.

2. The layer budget. [DECIDED] eight layers. This is the real constraint and it is not obvious. Unreal packs four paint layers per weightmap texture, per component. We have three, so one texture each across 9800 components. A fourth is free; the fifth doubles it. The shader cost is linear too — every layer is a full material function sampled and blended whether or not it contributes.

So the honest budget is six to eight layers, and that is the whole design:

Layer	Rule	Substance
Base_Layer	slope	Layered_Rock_Cliff (D-76)
Layer_03	altitude	the pack's high rock
Layer_02	remainder	the pack's meadow grass
Beach	near sea level, low slope	Thai_Beach_Sand
Sand	class desert	Bright_Desert_Sand
Ice	class ice	Snow
Regolith	class crater	Desert_Western_Ground_Gravel_Coarse_04

Seven, with one spare in the budget. A Jungle layer reading Köppen Af+Am+Aw was specified and then dropped (D-76): the nearest substance to hand is a mossy rocky ground, which is temperate and damp where a tropical forest floor is leaf litter, and the wrong green over the whole equator is more misleading than no biome at all. The equator wears the remainder layer instead — generic, but not wrong. Everything needed to bring it back is still in place; it is one manifest entry and one substance.

3. Route A or Route C first. [DECIDED] Route A, now. Today's ground came from Orogen with no erosion pass, so there is no wear, flow or deposit map to read — which is why the paint rules are slope and altitude alone. terrain tiles already produces those maps at 2 m. Dressing Route A means sand where the class says desert; dressing Route C means sand where sediment actually accumulated, and beaches where the coast pass actually laid them.

Route C is better ground and is the point of the generator, but it is a whole world rebuild in front of the dressing rather than after it, with nothing to look at until it finishes. Route A gives a visible result in Phase 1 and nothing authored for it is wasted: when Route C lands it changes the inputs to the layer rules, not the material, the sky, the grass or the trees. The two costs accepted are that beaches are approximated from altitude and slope rather than taken from where the coast pass put them, and that no rule can read sediment or wear.

4. Whether trees need collision. [DECIDED] no, for now. LandscapeGrassOutput is the only thing that scales to 2549 km² without authoring actors — GPU-instanced, distance-culled, driven straight off the layer weights we are about to add, and it costs nothing to author once the material has the node. But grass-output instances have no collision. Trees you can walk into mean PCG or foliage actors, which is a different and much larger job at this scale. Recommendation for a prototype: grass output for everything including trees, and revisit when a step needs to collide with one.

5. One sky or many. [DECIDED] one. It is one planet, so it is one sun, one sky light and one skybox. "Desert lighting" and "tropical lighting" as distinct looks means per-region post-process volumes, which at 98 landscapes is a lot of actors to place and keep in step. Recommendation: one authored sky, and let the ground carry the biome.

---

The plan

Each phase says what exists afterwards and what proves it. They are ordered so that nothing waits on anything later.

Phase 1 · Carry the biome into the tiles — done

The class map and the climate map become per-vertex layer weights, sampled at the same global coordinates as the height, so they are seam-exact for the same reason it is.

• Region.json's layers block gained biomes (the two sources and the blend width) and paint, an ordered list of layers each with a rule: slope, altitude, beach, class, climate or remainder.
• region_manifest.py models the list; LAYER_SUFFIXES survives as what a manifest with no paint block means.
• mapart biomes classifies the two sources and writes one blurred greyscale mask per biome.
• generate_region_tiles.py samples the masks and composes every enabled layer, --all-layers to preview the ones nothing can import yet.

Three things it turned up.

The class source is the painting, not Orogen's class render. The render is the legend's colours double-encoded to sRGB, which puts exported desert nearer to legend ice than to legend desert — nearest colour matching against it is simply wrong. The painting is made of the legend's own colours and nothing else: measured, worst nearest-colour distance 0.0 over all 29 M pixels. One is data; the other is a picture of data.

Tropical is Köppen, not latitude. Tools/Orogen/js/koppen.js has a real classification with exact colours, and the climate export decodes against it cleanly once the same sRGB encode is applied — every observed colour within 1.4/255, and only 0.423 % of pixels not close to any class, which is the anti-aliased ring at class boundaries and nothing else. Jungle is Af+Am+Aw, 8.11 % of the planet.

The registration is measured, not assumed. The painting is 7738 × 3761 and the heightmap 8192 × 4096; the two candidate mappings were tested against each other on land/sea agreement and identity won, 98.09 % against 96.14 %, in every latitude band including the polar ones where a vertical scale error shows first.

Proved by: seams 0 differing vertices across all nine files on a shared column; weights 255..256 and never under, so no ground is unpainted; and the default three-layer path still produces the built world — height, rock and high rock bit-identical, meadow differing in 6 of 6 507 601 vertices by 1, which is the deliberate rounding change and nothing else.

Left for Phase 2: rocky_meadows.LAYER_INFOS still knows only three layers and now refuses loudly rather than dropping one silently, which is the hook the substances plug into. Underwater ground gets the remainder layer, because no rule claims the sea floor; the sea plane covers it, so it costs nothing but it does inflate the meadow's share in any per-tile number. And the beach rule wants tuning against real coastline once there is a sand substance to see — it lands at 0.1–0.2 % of a coastal tile today.

Phase 2 · The project's own landscape material — all but the layer infos

Built by Scripts/Authoring/build_ground_material.py, which extends the pack's material rather than replacing it: a new layer is a copy of an existing layer function with its six parameters renamed, so it inherits the camera-distance colour blend D-69a found load-bearing at this scale. Verified: the LandscapeLayerBlend carries seven wired layers, the new functions' parameters are uniquely prefixed so they do not collide in the instance, and twenty texture parameters point the layers at the Fab substances.

The layer infos are done too. LayerName is read-only from Python and there is no LayerInfo factory in the bindings - duplicate-and-rename produces an asset that silently keeps the name it was copied from - so it goes through ULandscapeAuthoringLibrary::CreateLayerInfo, in the editor module for the same reason CreateLandscapeFromHeightmap is. Verified per layer: layer info, LayerName, parameter prefix, substance, and weightmap_entries resolving 7 of 7.

The notes below were the plan and are kept because they are still what the phase is for.

M_Ground_Landscape is already our copy (D-69a), so extending it modifies nothing of the pack's.

• Add the five new layers and their material functions, one per substance, following the three that exist.
• Keep the existing distance-blend structure — it is the reason the world does not read as tiling mush from the air, and MI_Ground_RockyMeadows's far-colour corrections are load-bearing at this scale.
• New layer infos in Content/Terrain/Layers/, and the LayerName on each must match what the material blends.

Proves it: fly the world; deserts are sand, the ice cap is ice, the crater floor is not grass.

Phase 3 · Sky and light

Authored rather than inherited. One pass, and it is mostly numbers.

• A sky worth having: Sky Atmosphere plus Volumetric Clouds, or keep the pack's skybox mesh if the atmosphere costs too much at this scale — decide by looking, not in advance.
• Exposure that works both standing on the ground and looking down from 25 km, which is the case that has already bitten twice (the white sea material read as an ice sheet; the fog at demo density was opaque).
• Fog density stays scaled by world size — scale_fog already does this and the reason is in rocky_meadows.py.
• Sun angle and colour chosen once and written down, because "the sun is wrong" has already cost one commit (positional unreal.Rotator is (roll, pitch, yaw)).

Proves it: a screenshot from the ground and one from 25 km, both legible, no blown highlights on the sea.

Phase 4 · Ground cover

• Add a LandscapeGrassOutput to the landscape material, fed by the layer weights from Phase 1.
• One ULandscapeGrassType per layer that should have cover: grass on lowland, scrub on desert, none on rock, ice or sea.
• Density and cull distance tuned at this scale, not the demo's.

Proves it: ground cover appears where the layer says and stops where it does not, and the frame time at ground level is still sane.

Phase 5 · Trees

• Tree meshes from the chosen source (decision 1), as grass types placed by the same output.
• Density driven by the layer weight and, where it exists, by the overlay's forest mark.
• Treeline: the overlay generator already takes its treeline from a quantile of the land's own heights, because metres mean nothing until a world is baked (D-68). Use the same rule here.

Proves it: forests are where the overlay says, thin out with altitude, and are absent from desert, ice and open water.

---

What this does not cover

• The overlay carry into Unreal is still unbuilt. Region.json reserves an overlay block and region_manifest.py has marks_path; nothing writes one and nothing reads one. Phase 5 can work off layer weights alone without it — that is the cheaper path and the one to take first. Reading actual forest blobs means building the carry.
• Water. The sea is M_Sea_Proto, a placeholder grey, deliberately. Real water is its own job and the engine's single-layer water read as a lake shader stretched over a planet.
• Rivers. The bake knows where they are (map_flow.png); nothing in Unreal does.
• HLODs. Needed for any of this to be visible from the air at all, and they have to be rebuilt after the material changes. See the sculpting note in Terrain.md §5.1 before hand-editing anything.