PolyTerrain core concepts

These concepts recur in every PolyTerrain workflow. Getting them right avoids the most common authoring mistakes (wrong layer names, baking stale Preview-only edits, dual physics owners).

Poly Partition and sections

Concept	Role
Poly Partition	Root entity with Poly Partition. Owns the MPD reference, Base Sections, and build actions.
Base Section	One mesh tile: auto plane, converted mesh, heightfield sample, or explicit mesh. Each has a world-space anchor (`AZ::Vector3d`) and anchor-local float vertices.
Modifier	Component on the partition or another entity; targets a partition via `m_targetPartition` (empty = host entity).
Preview Section	In-memory mesh after evaluating Base + modifiers. Editor only.
Compiled Section	Baked `.polypartitionsection` (+ weights) after the Transformer Pipeline. Runtime / streaming.

One partition can own many sections. Prefer splitting large footprints rather than one huge section.

MPD (Poly Partition Definition)

Asset type .polypartitiondefinition. Four logical sections:

MPD section	Declares
Material	Atom material hint, weight channels, channel texel size, physical material map
Modifiers	Priority Layer names and default sub-priority step
Build	Platform / variant list + Transformer Pipeline (or embedded stages)
Preview	Preview complexity caps and optional preview pipeline

Layers named on modifiers must match MPD layer names or the evaluator treats them as orphan and skips them.

Preview vs Compiled

	Preview	Compiled
Use	Editor feedback	Runtime render / physics / streaming
Storage	Memory only	Baked assets + spawnables
Mesh	Editable density (Refine / Coarsen)	StaticMesh LOD chain from Transformer Pipeline
Weights	Vertex buffers	Baked weight textures
Authority for ship	No	Yes (`ContentHash` + AP)

Rule: what you see in Preview is the same evaluator as bake. GPU Preview (optional) is an acceleration path only; bake and ContentHash always use the CPU evaluator.

Modifier stack order

Evaluation sorts by:

MPD Priority Layer index (declaration order),
then m_subPriority ascending within the layer.

Disabled modifiers (m_enabled = false) are skipped but remain serialized. Build To cuts the stack at a layer (and optionally a sub-priority) for Preview only.

Recommended bottom → top patterns:

Goal	Stack
Hills	Texture → Noise → Sculpt → WeightPaint
Caves	Sculpt → Boolean Subtract → WeightPaint
Roads	Spline → Remesh → WeightPaint

Boolean clears weight channels after topology replace—keep WeightPaint above Boolean. Details: Modifiers.

ContentHash and incremental bake

ContentHash folds Base geometry, modifier param hashes, MPD materials / channels, and Transformer settings that affect output. When the exported .polypartition bytes match disk, Build can skip rewriting and AssetProcessor is not woken for that source.

Force a full rebuild only when AP products look stale or you changed builder-facing code / assets outside the hash path.

Coordinates and large worlds

Data	Type
Section anchor	`AZ::Vector3d` (world)
Vertices / strokes	Float in partition space (partition entity local), shifted by section anchor at eval
Query APIs	`*D` buses with `AZ::Vector3d`

Brush stamps are recorded in partition space so one stroke can span multiple sections correctly. Prefer section span ≤ ~2 km; pair with double-precision rendering and World Streaming for open worlds.

What PolyTerrain is not

Not a replacement for heightfield Gems/Terrain on open plains.
Not a TerrainDataRequestBus provider—use PolyPartitionDataRequestBus::GetUnifiedSurfacePointD (mesh first, heightfield fallback) or query compiled meshes / SurfaceData at runtime.
Section entities are not networked actors; optional multiplayer sync copies weight stamps, not section entities. See Optional features and Integrations.