Lumberyard
User Guide (Version 1.20)

Shapes: Cylinder, Capsule, Box, Sphere, Compound

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

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.


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

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.


                    Nonuniform 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 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 properties in Lumberyard Editor.

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.


                Box Shape component in the viewport.

Capsule Shape Component Properties


                The Capsule Shape component properties in
                    Lumberyard Editor.

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


                The Compound Shape component properties in
                    Lumberyard Editor.

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

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.

Sphere Shape Component Properties


                See the sphere shape component properties in Lumberyard Editor.

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