Lumberyard
User Guide (Version 1.16)

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.


                Scale a Box Shape by adjusting its Dimensions values. Scale a Cylinder Shape by adjusting its
                        Height and Radius values.

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.


                    Non-uniform scaling (1) where X, Y, and Z have different values. Uniform scaling (2) where X, Y, and Z values are the same (in this case,
                            4). Uniform normalized scaling (3) where X, Y, and Z values
                        are all 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 box shape component properties in Lumberyard Editor.

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 capsule shape component properties in Lumberyard Editor.

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


                See the compound shape component properties in Lumberyard Editor.

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 cylinder shape component properties in Lumberyard Editor.

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 sphere shape component properties in Lumberyard Editor.

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