Version:

Shape Components

Shape components generate helper geometries that can be used to define shapes for area lights and shape gradients, as well as volumes and areas for AI, audio, fog, spawners, vegetation, and PhysX.

Available Shapes

Shape ComponentShape typeUsed for
Axis Aligned Box ShapeAxis-aligned box geometryTerrain, Volume, Triggers
Box ShapeBox geometryVolumes, Triggers
Capsule ShapeCapsule (cylinder with half-sphere at ends) geometryVolumes, Triggers
Compound ShapeAggregate geometry defined by other Shape componentsVolumes, Triggers
Cylinder ShapeCylinder geometryVolumes, Triggers
Disk ShapeDisk geometryAreas, Triggers
Polygon Prism ShapeN-sided prism geometryVolumes, Triggers
Quad ShapeQuad-plane geometryAreas, Triggers
Sphere ShapeSphere geometryVolumes, Triggers
SplineLines and curvesPaths
Tube ShapeTube geometryVolumes, Triggers
Note:
The White Box component does not share the same functionality as other Shape components. The sections that follow do not apply to the White Box component. For more information, refer to the White Box documentation.

Using Shape components

An entity can have only one Shape component.

Important:
Always use the Shape’s component properties to scale the shape, such as the Dimensions, Height, and Radius properties. Do not use the entity’s Transform component to scale a Shape component.

An entity containing a Shape component should have a uniform and normalized scale; that is, the Scale property of the Transform component should be X: 1.0, Y: 1.0, Z: 1.0. If a shape component is scaled non-uniformly, rendering and intersection tests use the largest vector of the Transform component’s Scale property, yielding undesirable results.

By default, shapes are always visible in the Open 3D Engine (O3DE) Editor. You can hide shapes on non-selected entities by disabling the Visible property in the shape component.

To display a Shape component for debugging purposes while in game mode, enable the Game View property.

Each Shape component provides a generic ShapeService that exposes functionality common to all shapes. Each shape also provides a more specific service, such as BoxShapeService or SphereShapeService.

Shape component EBus interface

All Shape components provide access to two separate request buses. The first bus is the ShapeComponentRequestsBus that returns general information about the Shape component. The second bus is the ShapeNameComponentRequestsBus that returns property configurations for the specific shape. Information on the ShapeNameComponentRequestsBus can be found on the reference pages for each Shape component.

All shapes share a single notification bus named ShapeComponentNotificationsBus.

You can use the following functions with the event bus interface to communicate with other components in your game.

ShapeComponentRequestsBus

Request NameDescriptionParameterReturnScriptable
DistanceFromPointReturns the minimum distance between a specified point and the shape.Point: Vector3 point to calculate distance from.Float - Distance from point to shape.Yes
DistanceSquaredFromPointReturns the minimum squared distance between a specified point and the shape.Point: Vector3 point to calculate squared distance from.Float: Squared distance from point to shape.Yes
GetEncompassingAabbReturns an AABB (Axis Aligned Bounding Box) that encompasses the entire shape.NoneAZ::Aabb that encompasses the shape.Yes
GetShapeTypeReturns the specified Shape Type for the component.NoneAZ::Crc32(<shape_type_name>): for example, AZ::Crc32("Sphere")Yes
IsPointInsideChecks if a specified point is inside the shape.Point: Vector3 point to check.Boolean: Returns True if the specified point is inside the shape. Returns False if the point is not inside the shape.Yes

ShapeComponentNotificationsBus

Notification NameDescriptionParameterReturnScriptable
OnShapeChangedNotifies listeners that the shape has been updated.ShapeChangeReasons: Indicates whether the shape was updated by a transform change or a shape property change.VoidYes