Shapes: Cylinder, Capsule, Disk, Box, Sphere, Compound

Open 3D Engine (O3DE), the successor to Lumberyard, is now available in Developer Preview. Download O3DE or visit the AWS Game Tech blog to learn more.

Add shape components to entities that have other components that require shapes.

For example, add shape components to your entities to create volumes for the following:

• Create a trigger volume using theTrigger Area component. Entities that enter the volume trigger an action.

• Create a collision volume using the PhysX Collider component. Entities that collide with the collision volume respond to the impact, such as slowing down or bouncing back.

• Define reverb or echo effects using the Audio Environment component.

• Create an audio area using the Audio Trigger component so that a specific sound plays in that area of the level.

Note

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

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

As a best practice, when you scale a shape, adjust the shape component's properties, such as its Dimensions, Height, and Radius.

Tip

Modify the shape component's properties instead using the Scale tool, which changes the entity's Transform component.

Example

See the following examples for the different scaling:

1. In nonuniform 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 nonuniformly, 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 the third example.

Box Shape Component Properties

The Box Shape component has the following properties.

Name	Description
Visible	The component always appears in the viewport, even if the entity isn't selected.
Game View	Renders the box shape in game mode in Lumberyard Editor. To enter game mode, press Ctrl+G.
Shape Color	Specifies the color to render the shape.
Dimensions	Defines dimensions of the shape along all three axes in local space. If the Transform component applies a scale, these dimensions are multiplied by the same value.
Edit	Choose Edit, and the component is locked for editing. For more information, see Editing Components in the Viewport.

The Box Shape component also has its own Component Mode with several linear manipulators for each axis.

Capsule Shape Component Properties

The Capsule Shapecomponent has the following properties.

Name	Description
Visible	The component always appears in the viewport, even if the entity isn't selected.
Game View	Renders the shape in game mode. To enter game mode, press Ctrl + G.
Shape Color	Specifies the color to render the shape.
Height	The end-to-end height of the capsule, including the cylinder and both caps. If the Transform component applies a scale, these dimensions are multiplied by the same value.
Radius	The radius of the capsule. If the Transform component applies a scale, these dimensions are multiplied by the same value.

Compound Shape Component Properties

With the Compound Shape component, you can combine shapes to create a complex object to generate a physics collider, trigger shape, or any other application of shapes. The individual shapes might or might 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, don't set them as child entities.

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

See the following Compound Shape properties.

Name	Description
Child Shape Entities	Specifies the entities and their shapes that make up the compound shape. These entities might or might not be children of the entity with the compound shape.

Cylinder Shape Component Properties

The Cylinder Shape component has the following properties.

Name	Description
Visible	The component always appears in the viewport, even if the entity isn't selected.
Game View	Renders the shape in game mode in Lumberyard Editor. To enter game mode, press Ctrl + G.
Shape Color	Specifies the color to render the shape.
Height	The height of the cylinder. If the Transform component applies a scale, these dimensions are multiplied by the same value.
Radius	The radius of the cylinder. If the Transform component applies a scale, these dimensions are multiplied by the same value.

Disk Shape Component Properties

See the following Disk Shape properties.

Name	Description
Visible	The component always appears in the viewport, even if the entity isn't selected.
Game View	Renders the shape in game mode in Lumberyard Editor. To enter game mode, press Ctrl + G.
Shape Color	Specifies the color to render the shape.
Radius	The radius of the disk. If the Transform component applies a scale, these dimensions are multiplied by the same value.

Sphere Shape Component Properties

See the following Sphere Shape properties.

Name	Description
Visible	The component always appears in the viewport, even if the entity isn't selected.
Game View	Renders the shape in game mode in Lumberyard Editor. To enter game mode, press Ctrl + G.
Shape Color	Specifies the color to render the shape.
Radius	The radius of the sphere. If the Transform component applies a scale, these dimensions are multiplied by the same value.

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

The following table describes the ShapeComponentRequestsBus.

Name	Description	Parameter	Return	Scriptable
DistanceFromPoint	Returns the minimum distance between a specified point and the shape.	point – Vector3 point to calculate distance from.	Distance from point to shape. Type: Float	Yes
DistanceSquaredFromPoint	Returns the minimum squared distance between a specified point and the shape.	point – Vector3 point to calculate square distance from.	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 for accessing that particular shape. The buses have similar functions and only differ for the requested shape type.

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