AWS Documentation » Amazon Lumberyard » User Guide » Working with Component Entities » Component Reference » Shapes: Cylinder, Capsule, Box, Sphere, Compound

Shapes: Cylinder, Capsule, Box, Sphere, Compound

Component entity system is in preview release and is subject to change.

You can use shape components with other components that use shapes. For example, you can use a Sphere component to create a space around a component to create a trigger area.

You can use shape components to define the following:

• Trigger volumes – Use shapes as volumes with the Trigger Area component to specify triggering bounds.

• Collision volumes – Use shapes as volumes with the Mesh Collider component to specify collider bounds.

• Audio area ambiances – Use shapes as volumes with the Audio Environment component in which a reverb is applied.

• Audio areas – Use shapes as volumes with the Audio Trigger component in which a sound plays.

Note

You can add only one shape component to an entity. If you need more than one shape on a single entity, create child entities and add shape components to them.

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.

The Shape component includes the following shapes and properties:

Scaling Shapes

When you scale a shape, the recommended best practice is to adjust the shape component's properties, such as its Dimensions, Height, and Radius, as shown in the following image.

We recommend that you modify the shape component's properties instead of the Scale tool, which changes the entity's Transform component.

Example

See the following examples for the different scaling.

1. In non-uniform scaling, adjusting an entity's transform scale leads to different values for X, Y, and Z.

2. In uniform scaling, X, Y, and Z have the same value.

3. In uniform normalized scaling, all of the scale values are 1.

If an entity has been scaled non-uniformly, then rendering and intersection tests use the largest component of the scale vector. Although this can work, the best practice is to keep a uniform and, ideally, normalized (1, 1, 1) transform scale, as shown in example 3.

Box Shape Component Properties

See the following Box Shape properties.

Name	Description	Valid Values
Visible	The Box Shape component always appears in the viewport, even if the entity is not selected.	Type: Boolean Default value: True
Game View	If selected, the box shape renders in game mode in Lumberyard Editor. To enter game mode, press Ctrl+G.	Type: Boolean Default value: False
Dimensions	Define dimensions of the shape along all three axes in local space. If the Transform component applies a scale then these dimensions are multiplied by the same value.	N/A Default value: X: 1.0 m Y: 1.0 m Z: 1.0 m

Capsule Shape Component Properties

See the following Capsule Shape properties.

Name	Description	Valid Values
Visible	The Capsule Shape component always appears in the viewport, even if the entity is not selected.	Type: Boolean Default value: True
Game View	If selected, the capsule shape renders in game mode in Lumberyard Editor. To enter game mode, press Ctrl+G.	Type: Boolean Default value: False
Height	End-to-end height of the capsule, including the cylinder and both caps. If the Transform component applies a scale then these dimensions are multiplied by the same value.	: 2*Radius to ∞ Type: Float Default value: 1 m
Radius	Radius of the capsule. If the Transform component applies a scale then these dimensions are multiplied by the same value.	Range: 0 to ∞ Type: Float Default value: 0.25 m

Compound Shape Component Properties

With the Compound Shape component, you can combine shapes to create a complex object that you can use to generate a physics collider, trigger shape, or any other application of shapes. The individual shapes may or may not be children of the entity with the Compound Shape component.

Note

• To move the shapes together with the compound shape, set them as child entities.

• To move the shapes independent of the entity with the compound shape, do not set them as child entities.

• For EBus (event bus) requests, compound shapes service the full shape component bus. However, note that each individual shape that you add increases the cost of requests such as IsPointInside.

See the following Compound Shape properties.

Name	Description	Valid Values
Child Shape Entities	Specifies the entities and their shapes that are used to construct the compound shape. These entities may or may not be children of the entity with the compound shape.	N/A

Cylinder Shape Component Properties

See the following Cylinder Shape properties.

Name	Description	Valid Values
Visible	The Cylinder Shape component always appears in the viewport, even if the entity is not selected.	Type: Boolean Default value: True
Game View	If selected, the cylinder shape renders in game mode in Lumberyard Editor. To enter game mode, press Ctrl+G.	Type: Boolean Default value: False
Height	Height of the cylinder. If the Transform component applies a scale then these dimensions are multiplied by the same value.	0 to ∞ Type: Float
Radius	Radius of the cylinder. If the Transform component applies a scale then these dimensions are multiplied by the same value.	0 to ∞ Type: Float

Sphere Shape Component Properties

See the following Sphere Shape properties.

Name	Description	Valid Values
Visible	The Sphere Shape component always appears in the viewport, even if the entity is not selected.	Type: Boolean Default value: True
Game View	If selected, the sphere shape renders in game mode in Lumberyard Editor. To enter game mode, press Ctrl+G.	Type: Boolean Default value: False
Radius	Radius of the sphere. If the Transform component applies a scale then these dimensions are multiplied by the same value.	Type: Float 0 to ∞ Default value: 0.5 m

Request 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 specified shape.

Use the following request functions with the event bus interface to communicate with other components in your game.

For more information, see Working with the Event Bus (EBus) System.

ShapeComponentRequestsBus

See the following ShapeComponentRequestsBus:

Name	Description	Parameter	Return	Scriptable
DistanceFromPoint	Returns the minimum distance between a specified point and the shape.	point – Vector3 point from which to calculate distance.	Distance from point to shape. Type: Float	Yes
DistanceSquaredFromPoint	Returns the minimum squared distance between a specified point and the shape.	point – Vector3 point from which to calculate square distance.	Square distance from point to shape. Type: Float	Yes
GetEncompassingAabb	Returns an AABB that encompasses the entire shape.	None	AZ::Aabb that encompasses the shape.	No
GetShapeType	Returns the specified shape type for the component.	None	AZ::Crc32(shape_name) For example: AZ::Crc32("Box") | AZ::Crc32("Sphere") | AZ::Crc32("Capsule") | AZ::Crc32("Cylinder")	Yes
IsPointInside	Checks whether a specified point is inside or outside a shape.	point – Vector3 point to check.	Indicates whether the point is inside or outside the shape. Type: Boolean	Yes

ComponentRequestsBus

Each shape component has its own specific event bus that you can use to access that particular shape. The buses have similar functions and only differ for the shape type requested.

BoxShapeComponentRequestsBus

Request Name	Description	Parameter	Return	Scriptable
GetBoxConfiguration	Returns the configuration of the BoxShape.	None	BoxShapeConfiguration object that contains the configuration for the box shape.	Yes

CapsuleShapeComponentRequestsBus

Request Name	Description	Parameter	Return	Scriptable
GetCapsuleConfiguration	Returns the configuration of the CapsuleShape.	None	CapsuleShapeConfiguration object that contains the configuration for the capsule shape.	Yes

CompoundShapeComponentRequestsBus

Request Name	Description	Parameter	Return	Scriptable
GetCompoundShapeConfiguration	Returns the configuration of the CompoundShape.	None	CompoundShapeConfiguration object that contains the configuration for the compound shape.	Yes

CylinderShapeComponentRequestsBus

Request Name	Description	Parameter	Return	Scriptable
GetCylinderConfiguration	Returns the configuration of the CylinderShape.	None	CylinderShapeConfiguration object that contains configuration for the cylinder shape.	Yes

SphereShapeComponentRequestsBus

Name	Description	Parameter	Return	Scriptable
GetSphereConfiguration	Returns the configuration of the SphereShape.	None	SphereShapeConfiguration object that contains the configuration for the sphere shape.	Yes

ShapeComponentNotificationsBus

All shapes share a single notification bus named ShapeComponentNotificationsBus.

Notification Name	Description	Parameter	Return	Scriptable
OnShapeChanged	Notifies listeners that the shape component has been updated.	ShapeChangeReasons – Indicates whether the shape was updated from a transform change or a shape parameter change.	Void	Yes