PolyTerrain getting started

Get a mesh terrain partition from zero to Play-ready as quickly as possible: enable the Gem and Registry gates, create an MPD, add a Poly Partition, iterate in Preview, then bake Compiled Sections.

Prerequisites

• PolyTerrain is enabled in the project (Project Manager or project.json). Dependencies include LmbrCentral, GradientSignal, SurfaceData, Atom RPI features, and WorldStreaming.
• AssetProcessor is running when you bake (.polypartition → .polypartitionsection / .polypartitionweights).
• For large-world anchors, prefer pairing with double-precision rendering.

Minimal loop (five steps)

1 Enable Gem + Registry
 → 2 Create MPD (.polypartitiondefinition)
 → 3 Create Poly Partition entity
 → 4 Sculpt / Paint in Preview
 → 5 Build Compiled Sections

1. Enable the Gem and Registry

Enable PolyTerrain in the project, then turn the feature on in Settings Registry (project or gem override):

{
 "O3DE": {
 "PolyTerrain": {
 "Enabled": true,
 "EditorModeEnabled": true
 }
 }
}

Restart the editor.

Without Enabled, heightfield terrain and existing levels behave as before. Without EditorModeEnabled, Outliner / Inspector workflows still work when Enabled is on, but the six-tab mode stays hidden.

Defaults live in Gems/PolyTerrain/Registry/polyterrain.setreg. Full key table: Reference.

2. Create an MPD

1. Content Browser → Create → Data Asset → Poly Partition Definition (.polypartitiondefinition). Name it e.g. MPD_LevelName.
2. Declare Priority Layers (e.g. Base → Sculpt → Boolean → WeightPaint) and Weight Channels (e.g. Grass, Rock).
3. Optionally set Material hints, Build variants, and Preview complexity caps (details in Materials and bake).

The Create Tab also offers an MPD wizard that writes a default definition (layers, channels, StaticMesh + Skirt + Collision pipeline) and binds it to a new partition.

3. Create a Poly Partition

1. Tools → Poly Terrain Mode → Create Tab.
2. Create a Poly Partition entity (or use the MPD wizard).
3. Assign the MPD on Poly Partition. Defaults can auto-generate a plane:

Section anchors are world AZ::Vector3d. Keep a single section span roughly ≤ 2 km; split larger areas. See Core concepts.

4. Sculpt, paint, and iterate

1. Modifiers Tab (or Outliner palette): add Sculpt and Weight Paint.
2. Sculpt / Paint Tabs: brush geometry and weight channels on the Preview mesh.
3. Outliner Build To truncates the preview stack while iterating (faster feedback).
4. Use Rebuild Preview when you need a full synchronous refresh.

Strokes are stored in partition space and undo through the standard editor undo stack. Modifier catalog: Modifiers. Tool details: Authoring.

5. Build Compiled Sections

1. Build Compiled Sections from the Edit Tab, Outliner, or Inspector (incremental when ContentHash is unchanged).
2. AssetProcessor produces .polypartitionsection and .polypartitionweights.
3. PolyPartitionPrefabProcessor expands runtime section entities (and can inject World Streaming membership). Order is before WS processors when WS is enabled.

Then enter PIE / game and confirm render + collision. Optional: add Poly Partition Collision and Poly Partition Surface Data on runtime section entities (often injected by the PrefabProcessor when the Transformer Pipeline includes Collision).

Sample level

Open AutomatedTesting/Levels/PolyTerrain/PolyTerrainSample for a small plane partition with Sculpt / WeightPaint already wired. The AutomatedTesting project Registry turns Enabled / EditorModeEnabled on for that suite.

Verify

If something fails, start with Debugging. Next: Authoring for the six tabs, or Materials and bake for MPD and Transformer details.