Lumberyard
User Guide (Version 1.15)

Constraint Component Properties

The primary Constraint component property is the Constraint type. This property defines how the constrained entity moves in relation to the constraint target.

Constraint Type

When setting constraint properties, select one of the following Constraint types.

Hinge

The constrained entity rotates around the selected Axis as if attached by a hinge. This constraint type provides one degree of freedom (X, Y, or Z) between the constrained entity and the constraint target.

An example of a hinge is a door, which rotates around the Z axis.

Ball

The constrained entity rotates around the z-axis as if attached at the constraint pivot by a ball socket or ball joint. This constraint type provides two degrees of freedom between the constraint owner and the constraint target.

An example of a ball constraint is a bell's clapper (the swinging part inside the bell housing).

This constraint type always moves about the z-axis. If you want to use this constraint type, but need it to move in a different direction (for example, attaching at the bottom and moving at the top), you must change the orientation of the z-axis. To do this, rotate the constraint pivot.

Slider

The constrained entity slides along one axis. If rotation is also enabled, then the constrained entity acts like a movable hinge around the selected axis.

An example of a slider constraint is a sliding door.

Plane

The constrained entity moves along one plane (xy, yz, or xz). Select the x-axis to move along the yz-plane, the y-axis to move along the xz plane, and the z-axis to move along the xy-plane.

An example of a plane constraint is a hockey puck sliding along a smooth surface.

Magnet

The constrained entity and the constraint target move toward each other.

Fixed

The Fixed constraint type must be applied to two rigid body (movable) entities. This constraint type constrains the two entities with no rotation relative to one another (although they can rotate together). The distance and orientation between the constrained entity and the constraint target are preserved.

An example of a fixed constraint is the two sides of a dumbell—with an invisible and intangible bar fixing the two sides together.

Free

The constrained entity can move around its target anywhere in space and any distance from its target, but the orientation of the owner and its target are locked to each other. For example, if the constrained entity and the constraint target were both statues, they could be moved any distance apart and in any direction, but if one is knocked over, the other mirrors that orientation, wherever it is.

Constraint Properties

The following properties are common to all of the constraint types, except where noted.

Constraint type

Select from hinge, ball, slider, plane, magnet, fixed, or free.

Default value: Hinge

Owning entity

Select either Self or Other entity.

In the typical setup, select Other entity, then select the Constrained entity. If you select Self, the constrained entity moves about its own axis.

Default value: Self

Target type

Select either Entity or World space.

Select Entity if the constraint target is a rigid body (movable object), and you want the constraint pivot anchored to it. Select World space if the constrained entity is to move about the constraint pivot's position in world space.

Default value: Entity

Constrained entity

Click the picker (hand icon) and, in the viewport, select the entity that is to be the constraint owner. This field is not available if you set Owning entity to Self.

Constraint target

Click the picker (hand icon) and, in the viewport, select the entity that is to be the constraint target. This field is not available if you set Target type to World space.

Axis

Visible when Constraint type is set to hinge, slider, or plane.

For the hinge constraint, the constraint owner rotates about the defined axis. For example, a typical door rotates on the z-axis. A typical pet door would rotate about the x- or y-axis.

For the slider constraint, the axis specifies the direction that the constraint owner slides. For example, choose the z-axis if you want an up-and-down slider (such as an elevator).

For the plane constraint, the axis you choose is perpendicular to the plane upon which the constraint owner moves. For example, choose x to move along the yz-plane, y to move along the xz-plane, and z to move along the xy-plane.

Default value: z

Enable on activate

If selected, the constraint is enabled upon activation of the level.

Part ids

If selected, you can specify the following:

  • Owner part id – Part ID on the constrained entity, such as a weapon, that is to be constrained.

  • Target part id – Part ID on the constraint target, such as a character's hand, that is to be the constraint target.

Force limits

If selected, you can specify the Max pull force in Newtons (N) and the Max bend torque in Newtons per meter (NM). If the constraint is set to Breakable, and a force exceeding those values is exerted upon the constraint, then the constraint is removed (broken). If the Breakable setting is not selected, Force limits control how much force the constraint applies to keep the constrained entities together.

Rotation limits

Visible when constraint is set to hinge, ball, or slider.

When selected and set to hinge constraint, the Min setting defines the limit of the clockwise rotation. Use a negative value to set a limit clockwise. For example, -90 degrees would be at the 3 o'clock marker. -180 degrees would be at 6 o'clock. The Max setting defines the rotation counterclockwise. Use a positive value. For example, 90 degrees would be at the 9 o'clock marker. 180 degrees would be at the 6 o'clock marker. You can reverse these settings by selecting the negative axis (for example, Negative Y).

When selected and set to ball constraint, you can set the Half angle. Visualize the rotation area as a cone; the half angle represents the distance between the middle of the cone and the edge. When you set the half angle, a blue cone appears in the viewport to represent the rotation area.

When selected and set to slider constraint, use a positive number for the Max setting to define how far in the positive direction the object can move from its starting point. Use a negative number for the Min setting to define how far the object can move from its starting point in the opposite direction. A blue arrow appears in the viewport when a constraint entity is selected.

Damping

If selected, you can specify the damping of a constraint movement.

Use this setting to prevent perpetual motion, or for constraints that don't properly come to rest. Start with small values, such as 0.2 to 0.3. Values above 0.5 may make objects seem unnatural and overly dampened.

Enable collision

If selected, enables collision between constrained entities.

Breakable

If selected, the constraint is removed (broken) if force limits are exceeded.

EBus Notification Bus Interface

Use the following notification functions with the constraint component notification bus EBus interface to communicate with other components of your game.

For more information about using the event bus (EBus) interface, see Working with the Event Bus (EBus) System.

OnConstraintEntitiesChanged

Notifies that one or both of the constrained entities has changed.

Parameters

AZ::EntityId oldOwner – The prior owner of the constraint.

AZ::EntityId oldTarget – The prior target of the constraint.

AZ::EntityId newOwner – The new owner of the constraint.

AZ::EntityId newTarget – The new target of the constraint. If the constraint target is world space, this can be Invalid EntityId.

Return

None

Scriptable

Yes

OnConstraintEnabled

Notifies that the constraint has been enabled.

Parameters

None

Return

None

Scriptable

Yes

OnConstraintDisabled

Notifies that the constraint has been disabled.

Parameters

None

Return

None

Scriptable

Yes