Version:

# Terrain Physics Heightfield Collider Component

The Terrain Physics Heightfield Collider component provides terrain data to the physics system in the form of a heightfield and material assignments. You can configure the dimensions of the collider by modifying the Axis Aligned Box Shape component on the same entity.

Terrain Gem

## Dependencies

The PhysX Heightfield Collider is only a dependency when using this component with PhysX. When implementing an alternate physics system, the Terrain Physics Heightfield Collider requires a companion Heightfield Collider component for that physics system instead.

## Properties

PropertyDescriptionValuesDefault
Default Surface Physics MaterialSelects a physics material to be used by unmapped surfaces by default.Material: Physics Material(default)
Surface to Material MappingsAn array of surface tags and physics materials to map together.
Surface TagSelects a surface tag to map to a phsyics material.Surface: Surface Tag(unassigned)
Material AssetSelects a physics material to apply to the surface.Material: Physics Material(default)

## Usage

The physics system receives collision information about the terrain through the Terrain Physics Heightfield Collider component. This component takes the region within the associated Axis Aligned Box Shape component and creates a heightfield collider in the physics system. The heightfield collider has physics material assignments that varies per vertex based on the underlying terrain surface weights and the surface type to physics material mappings on this component.

Because the terrain system uses the abstracted physics APIs in O3DE, the Terrain Physics Heightfield Collider component requires a companion Heightfield Collider component to interact with to convert terrain data into physics data for whichever physics system has been implemented. For example, when using this component with NVIDIA PhysX, the PhysX Heightfield Collider component is required on the same entity as the Terrain Physics Heightfield Collider to create a terrain heightfield in PhysX.

The Terrain Physics Heightfield Collider can exist on the same entity as a Terrain Layer Spawner component if it’s convenient, but this is not a requirement. The collider is not directly tied to a spawner. This component can be used with any region whether it overlaps multiple spawners, a single spawner, or no spawners at all. The primary advantage to keeping the collider on a separate entity from the spawner is that the physics colliders can be dynamically spawned and despawned at different times and sizes than the terrain. This enables having a large fully viewable terrain in the world and only a small subregion around the player that exists in the physics world for better control over performance and memory usage.

You can assign which terrain surface types map to specific physics materials by selecting a surface type in the surface pull down menu, then selecting a physics material type in the material pull down. Multiple terrain surface types can map to the same physics material. Any terrain surface types that aren’t mapped to a specific physics material will automatically be mapped to the Default Surface Physics Material.

## HeightfieldProviderRequestsBus

The HeightfieldProviderRequestsBus is an internal system bus that is only intended for communication between the physics system and the heightfield component. You should only typically need to use this EBus if you are implementing a new Heightfield Collider component for an alternate physics system. Use the following request functions with the HeightfieldProviderRequestsBus EBus interface to communicate with a Terrain Physics Heightfield Collider component.

Request NameDescriptionParameterReturnScriptable
GetHeightfieldGridSpacingReturns the resolution of the heightfield.NoneResolution: Vector2No
GetHeightfieldGridSizeReturns the size of the heightfield in the form of a row and column count.NoneRow Count: Integer; Column Count: IntegerNo
GetMaterialListReturns an array of surfaces used by this component.NoneArray of Physics Materials Indexes: INo
GetHeightsReturns the heightfield as an array of float values.NoneArray of Heights: FloatNo
GetHeightsAndMaterialsReturns an array of the heights in the heightfield, together with the physics material index for each point.NoneArray of Heights: Float, Physics Material Indexes: IntegerNo
UpdateHeightsReturns a subsection of the heightfield array within specific bounds.Bounds: AabbArray of Heights: FloatNo

The HeightfieldProviderNotificationBus is an internal system bus that is only intended for communication between the physics system and the heightfield component. You should only typically need to use this EBus if you are implementing a new Heightfield Collider component for an alternate physics system. Register for the following notification functions with the HeightfieldProviderNotificationBus EBus interface to receieve communications from a Terrain Physics Heightfield Collider component.
OnHeightfieldDataChangedNotifies when any terrain data that affects a heightfield has changed.Dirty Region: Aabb, Change Mask: Bitfield that contains Settings for settings changes, HeightData for height changes, SurfaceData for surface data changes, and SurfaceMapping for surface type to material mapping changes.NoneNo