PolyTerrain optional features

These features are opt-in on top of /O3DE/PolyTerrain/Enabled. If a gate is off, related buses typically no-op (return false / do nothing) so content stays safe by default.

Registry gates

Feature	Key (under `/O3DE/PolyTerrain/`)	Default
Runtime VT	`VtEnabled`	false
GPU sculpt preview	`GpuPreviewEnabled`	false
Runtime PCG graph execute	`PcgRuntimeExecutionEnabled`	false
Runtime weight rewrite	`RuntimeWeightRewriteEnabled`	false
Dominant-channel re-cook after rewrite	`CollisionDominantReweightEnabled`	false
Convex hull material follow	`CollisionConvexReweightEnabled`	false

Always restart or ensure system components re-read Registry after changing gates.

Virtual texture (VT)

Set VtEnabled = true.
Create a .vt asset (atlas size, tiles per side, optional page table, trail stamp budget, Normal / Roughness / weight planes).
Place Poly Partition VT Volume + Box Shape covering the partition.
Sample in materials via Material Canvas Sample Vt Base Color / Normal / Roughness / Weight, or the shared VtSampling.azsli helpers.
Optional: VT Trail Emitter on moving entities, or call PolyPartitionVtRequestBus::SubmitTrailStamp.

Notes:

Multiple volumes (up to 4) pack into a shared atlas.
Trail stamps can write color and optional Normal / Roughness / weight planes depending on .vt flags.
Without a covering volume or with VtEnabled false, sampling falls back / stamps no-op.

PCG graphs

Editor graph pane: Poly Terrain PCG Graph Editor (Outliner partition row → Open PCG Graph Editor). Assets: .polypcggraph (level-agnostic; target partition injected at run).

Node	Role
Query	Point cloud from surface (Build To layer is non-inclusive of the write layer)
OffsetAlongNormal / NoiseDisplace	Transform points
SlopeFilter / WeightFilter	Filter
Write	→ PCG Write modifier
SpawnPatch / SpawnMeshProjection	→ Patch / Mesh Projection instances

Run Graph (Ctrl+R) validates, can auto-add missing empty-name output modifiers, and executes in one undo batch.

Python / C++: PolyPartitionPcgRequestBus — QuerySurface, WritePositions, SpawnPatchInstances, SpawnMeshProjectionInstances, ExecuteGraph / ExecuteGraphAsset.

Example script: Gems/PolyTerrain/Editor/Scripts/polypartition_batch_apply_modifier.py.

With PcgRuntimeExecutionEnabled, Write / Spawn also land on runtime modifier components in PIE / game (session state; use Save/LoadRuntimePcgStateToFile for snapshots). Components must already exist on the prefab—runtime does not auto-create them.

Also see the large-world PCG preview page.

Runtime weight rewrite and multiplayer

Set RuntimeWeightRewriteEnabled = true.
Call PolyPartitionWeightRewriteRequestBus::SubmitWeightStamp (disk in section-local space: channel, center, radius, hardness, target weight, blend mode).
Both ends recompose from the same stamp log (deterministic). SurfaceData and VT weight planes follow effective weights.

Optional physics follow-up:

Key	Cost	Use
(always with rewrite)	Low	Per-chunk blended materials update in place
`CollisionConvexReweightEnabled`	Low	Per-hull `SetMaterial`
`CollisionDominantReweightEnabled`	High	Re-cook triangle mesh when dominant winner flips

Multiplayer: PolyTerrain.Multiplayer submodule (optional build) replicates stamps, not section entities. Clients apply the same log; late join uses baseline packets. Overlay Save/Load / delta APIs exist for project-owned persistence (Gem does not bind SaveData).

GPU Preview

GpuPreviewEnabled accelerates dirty brush Preview for eligible Sculpt stacks (including masked / Smooth / Erosion and CPU-prefix + GPU-sculpt-segment mixes). Explicit RebuildPreview, PCG QuerySurface, and AP bake stay on CPU—ContentHash authority never moves to GPU. Float differences on the GPU path are preview-only.

ImGui / diagnostics can show last eval path (CPU vs GPU) when Debug overlay is on.