Vegetation Gem

The Vegetation Gem provides tools for procedurally populating landscapes and environments. These tools are comprised of system and editor components that use a data-driven approach to automatically select, place, and manage vegetation objects dynamically at runtime. You can use these tools to replace or compliment manually placing, editing, and saving every instance in your level.

Many features of the dynamic vegetation system rely on other Gems and components to supply data about the environment, such as surfaces, images, and gradient signals, to direct where and how vegetation appears.

Dependencies

The Surface Data Gem allows a surface, like terrain or meshes, to emit signals or tags that communicate its surface type. For example, with a Vegetation Surface Mask Filter component, you can choose which types of vegetation can be placed on a particular surface by using an inclusion and exclusion list. You can also recapture the tags as a gradient signal by using the Surface Mask Gradient component.

The Gradient Signal Gem provides components that direct data to the vegetation system, controlling the appearance of dynamic vegetation. Using gradient signals with vegetation modifiers or filters, such as Position Modifier and Distribution Filter components, produce realistic, random expressions of vegetation in the world.

Provides

Entity components:

Level components:

  • Vegetation System Settings component
  • Vegetation Debugger component

System components:

API: Vegetation Gem API Reference

Source code: /Gems/docs/user-guide/components/reference/Vegetation/

Vegetation Areas

The dynamic vegetation system builds around the concept of vegetation areas that describe what, where, how, and if vegetation will generate on surfaces. Other systems in the engine register and process Vegetation areas. They can examine and take action on points in the world, like placing or preventing a vegetation instance.

In O3DE Editor, vegetation areas are referred to as vegetation layers. You can add vegetation behaviors to vegetation layers using components that describe, select, reject, or mutate potential vegetation instances. These behaviors are called, respectively, vegetation descriptor providers, selectors, filters, and modifiers. Each behavior has an interface that extends the system with new features. The Vegetation Gem contains several versions of each type, and each type has a unique purpose and effect on the vegetation instances it generates. These components expose controls that allow rapid, rule-based, procedural population of any arbitrarily sized part of the world with decorative content. Depending on its configuration, a single vegetation layer can generate a small patch of flowers or intelligently blanket the entire world with a convincing variety and groupings of plants and objects.

Vegetation instances

Vegetation instances are the objects placed throughout the world. When you create them, you configure their information using vegetation descriptors. These include a unique ID, transform, other attributes, and a reference to the source vegetation descriptor.

In O3DE Editor, vegetation instances appear within a vegetation area. They’re procedurally generated based on the configuration of the vegetation area.

Vegetation descriptors

Vegetation descriptors are structures that specify all of the common details needed to represent a type of vegetation. It includes data for mesh and material assets, the type of vegetation instances it creates, and many advanced parameters that can be enabled to override behavior of most filters and modifiers. Create Vegetation Descriptors in the Vegetation Asset List component or through Asset Editor.

Group NameParameter NameDescriptionType
WeightWeight is used during the spawning and selection process as a multiplier that changes the likelihood of one descriptor being chosen over another.Float
AdvancedWhen enabled, displays the following advanced settings that are normally hidden.Bool
PositionSettings for controlling per-instance overrides to the Position Modifier component.
Position Override EnabledWhen enabled, the Position Modifier component can use the per-instance override values specified in the descriptor instead of the component configuration.Bool
Position Min XOverride value for the minimum position offset on the X axis.Float
Position Max XOverride value for the maximum position offset on the X axis.Float
Position Min YOverride value for the minimum position offset on the Y axis.Float
Position Max YOverride value for the maximum position offset on the Y axis.Float
Position Min ZOverride value for the minimum position offset on the Z axis.Float
Position Max ZOverride value for the maximum position offset on the Z axis.Float
RotationSettings for controlling per-instance overrides for the Rotation Modifier component.
Rotation Override EnabledWhen enabled, the Rotation Modifier component can use the per-instance override values specified in the descriptor instead of the component configuration.Bool
Rotation Min XOverride value for the minimum rotation offset on the X axis.Float
Rotation Max XOverride value for the maximum rotation offset on the X axis.Float
Rotation Min YOverride value for the minimum rotation offset on the Y axis.Float
Rotation Max YOverride value for the maximum rotation offset on the Y axis.Float
Rotation Min ZOverride value for the minimum rotation offset on the Z axis.Float
Rotation Max ZOverride value for the maximum rotation offset on the Z axis.Float
ScaleSettings for controlling per-instance overrides for the Scale Modifier component.
Scale Override EnabledWhen enabled, the Scale Modifier component can use the per-instance override values specified in the descriptor instead of the component configuration.Bool
Scale MinOverride value for the minimum scale multiplier.Float
Scale MaxOverride value for the maximum scale multiplier.Float
Altitude FilterSettings for controlling per-instance overrides for the Altitude Filter component.
Altitude Filter Override EnabledWhen enabled, the Altitude Filter component can use the per-instance override values specified in the descriptor instead of the component configuration.Bool
Altitude Filter MinOverride value for the minimum altitude accepted by the filter.Float
Altitude Filter MaxOverride value for the maximum altitude accepted by the filter.Float
Distance Between Filter (Radius)Settings for controlling per-instance overrides for the Distance Between Filter component.
Distance Between Filter Override EnabledWhen enabled, the Distance Between Filter component can use the per-instance override values specified in the descriptor instead of the component configuration.Bool
Bound ModeWhen performing distance checks between two instances, this setting determines whether the radius of the mesh asset is used, as opposed to a manually-entered radius

Radius

MeshRadius.
Radius MinUser defined radius for distance checks.Float
Surface Slope Alignment
Surface Slope Alignment Override EnabledWhen enabled, the Slope Alignment Modifier component can use the per-instance override values specified in the descriptor instead of the component configuration.Bool
Surface Slope Alignment MinOverride minimum alignment strength.Float
Surface Slope Alignment MaxOverride maximum alignment strength.Float
Slope Filter
Slope Filter Override EnabledWhen enabled, the Slope Filter component can use the per-instance override values specified in the descriptor instead of the component configuration.Bool
Slope Filter MinOverride minimum slope accepted by filter.Float
Slope Filter MaxOverride maximum slope accepted by filter.Float
Surface Mask Filter
Override ModeControls how overrides are considered by the Surface Mask Filter component

Disable - Overrides are completely ignored

Replace - Overrides replace those specified in the component

Extend - Overrides are added to those specified in the component.
Inclusion TagsA set of surface tags that dictate where vegetation can be placed.SurfaceTagVector
Exclusion TagsA set of surface tags that dictate where vegetation will not be placed.SurfaceTagVector
Surface Mask Depth FilterSettings for controlling per-instance overrides for the Surface Mask Depth Filter component.
Surface TagsA set of surface tags used for depth comparisons.SurfaceTagVector
Upper Distance Range (m)A range used for vertical distance comparisons against the closest point with matching surface tags.Float
Lower Distance Range (m)A range used for vertical distance comparisons against the closest point with matching surface tags.Float

File: /Gems/Vegetation/Code/Source/Descriptor.cpp

EBus interface

Vegetation::AreaInfoBus

Request NameDescriptionParametersReturn
GetLayerGets the layer, or macro priority value of the vegetation area. GetLayer and GetPriority are useful to identify a vegetation area when there is multiple overlap.NoneFloat
GetPriorityGets the micro priority value within a layer. GetLayer and GetPriority are useful to identify a vegetation area when there is multiple overlap.NoneFloat
GetEncompassingAabbGets the axis-aligned bounding box for the entire vegetation area.NoneAZ::Aabb
GetProductCountGets the number of instances currently spawned by this vegetation area.NoneAZ::u32
GetChangeIndexGets an incrementing number that represents the number of times the Blocker area refreshed since creation.NoneAZ::u32

File: /Gems/Vegetation/Code/Include/Vegetation/Ebuses/AreaInfoBus.h

Vegetation::AreaRequestBus

Request NameDescriptionParametersReturn
PrepareToClaimRuns any pre-claim checks or logic, independent of position.EntityIdStack& stackIdsBool
ClaimPositionsProcesses a set of points for planting vegetation or performing other operations.EntityIdStack& stackIds, ClaimContext& contextNone
UnclaimPositionHandles clean-up whenever the system releases a claimed point.const ClaimHandle handleNone

File: /Gems/Vegetation/Code/Include/Vegetation/Ebuses/AreaRequestBus.h

Vegetation::DescriptorProviderRequestBus

Vegetation descriptor providers supply Vegetation Layer Spawners and Blenders with a list of vegetation descriptors from defined sources. The Vegetation Gem comes with components that can either provide descriptors from a list that’s defined directly in the component, reference a list of descriptors from externally created assets, or combine multiple descriptor lists together.

Request NameDescriptionParametersReturn
GetDescriptorsWhen a component is ready and has fully loaded all of its assets, this method creates a list of its active descriptors.DescriptorPtrVec& descriptorsNone

File: /Gems/Vegetation/Code/Include/Vegetation/Ebuses/DescriptorProviderRequestBus.h

Vegetation::DescriptorSelectorRequestBus

A Vegetation Layer Spawner component can use vegetation descriptor selectors when a vegetation descriptor provider offers multiple options. There is one selector, Vegetation Asset Weight Selector component, which chooses based on the selection weight field of a vegetation descriptor.

Request NameDescriptionParametersReturn
SelectDescriptorsUses the input gradient signal and other parameters to reduce the set of descriptors to those eligible for selection.Noneconst DescriptorSelectorParams&
DescriptorPtrVec&

File: /Gems/Vegetation/Code/Include/Vegetation/Ebuses/DescriptorSelectorRequestBus.h

Vegetation::ModifierRequestBus

Vegetation modifiers add uniqueness or variation to every vegetation instance, by changing the position, rotation, scale, alignment, or any exposed field. This allows the same vegetation descriptors throughout a vegetation area, with each instance of the descriptor to appear differently.

Request NameDescriptionParametersReturn
ExecuteModify a single vegetation instance based on configuration.Vegetation::InstanceDataNone
GetModifierStageInternal: Determines the order in which to run Vegetation Modifier components.NoneVegetation::ModifierStage

File: /Gems/Vegetation/Code/Include/Vegetation/Ebuses/ModifierRequestBus.h

Vegetation::FilterRequestBus

Vegetation areas use vegetation filters to evaluate every vegetation instance data and decide whether any activity should occur. Vegetation Layer Spawners use filters to determine whether to create vegetation instances. They can optionally evaluate filters before or after vegetation modifiers run. Evaluating filters before modifiers performs better because it skips unnecessary processing, but it yields less accurate results when position changes occur. Evaluating filters after modifiers is accurate because it evaluates the final version of the instance data.

Request NameDescriptionParametersReturn
EvaluateEvaluate if the vegetation described in the InstanceData satisfies the requirements set by a filter.InstanceDataBool
GetFilterStageGet the filter stage (PreProcess/PostProcess) for when a filter is evaluated.NoneFilterStage
SetFilterStageSet the filter stage (PreProcess/PostProcess) for when a filter is evaluated.FilterStageNone

File: Gems/Vegetation/Code/Include/Vegetation/Ebuses/FilterRequestBus.h