Lumberyard
User Guide (Version 1.16)

Constraint

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

The Constraint component creates a physical limitation or restriction between an entity and its target, such as a door rotating about a set of hinges, a sliding glass door moving along a track, or a bell clapper swinging within its bell housing.

A working Constraint component setup has three distinct pieces: the Constrained entity, the Constraint target, and the Constraint pivot, which is the entity with the constraint component on it. To use the previous example, the door would be the constrained entity, the wall with the hinges would be the constraint target, and then a third entity, placed between them, would be the constraint pivot. The constraint pivot defines the constraint behavior, connects the constrained entity to the constraint target, and provides the point about which the constrained entity moves.

The Constrained entity is always a movable object. For example, the rotating door, the sliding glass door, and the bell clapper are all movable objects.

The Constraint target is an anchor to which the constraint pivot is attached. The constraint target can be movable or unmovable; for example, a wall with door hinges or a sliding glass door track aren't typically movable, but a bell is.

The Constraint pivot is typically a third entity that contains only the constraint component, and is placed between the constrained entity and the constraint target. The constraint pivot defines the constraint behavior type, such as ball, hinge, slider, plane, magnet, fixed, or free. There are other ways to use the constraint pivot as well, such as the following:

  • Add the constraint pivot directly to the constrained entity, and then set the Owning entity to Self. This causes the constrained entity to move in the defined constraint behavior type about its own axis.

  • Set the constraint pivot's Target type to World space. This causes the constraint pivot to be anchored to its position in world space rather than to another object. The Constraint target field is not available when you select world space.

The following procedure provides an example for placing a constrained entity, a constraint target, and a constraint pivot.

To place a constrained entity, a constraint target, and a constraint pivot

  1. To place the constrained entity, and then add necessary mesh and physics components to it, follow these steps:

    1. Create an entity.

    2. In the Entity Inspector, click Add Component, Rendering, Mesh. For Mesh asset, click the ellipsis button to select an asset.

      This defines the shape and appearance of your object.

    3. In the Entity Inspector, click Add Component, Physics, Rigid Body Physics. Set rigid body properties as appropriate.

      This defines the entity as a movable object.

    4. Click Add Component, Physics, Primitive Collider or Mesh Collider.

      This allows other objects to collide with this object.

  2. To place the second entity, repeat the previous set of steps for a new entity. If you want this entity to be stationary (unmovable), however, set its physics behavior element as Static Physics (instead of rigid body).

  3. To place the constraint pivot, do the following:

    1. Create an entity.

    2. In the Entity Inspector, click Add Component, Physics, Constraint.

    3. For Owning entity, select Other entity.

      You will select the owning entity (constrained entity) in a later step.

      In this example procedure, you are placing the constraint pivot between the constrained entity and the constraint target. The other option, Self, is used when you place the constraint component directly on the constrained entity.

    4. For Target type, select Entity.

      The other option, World space, causes the constrained entity to move about the world space position of the constraint pivot.

    5. Next to Constrained entity, click the object picker (hand icon), and then in the viewport, click the first entity you created.

    6. Next to Constraint target, click the object picker (hand icon), and then in the viewport, click the second entity you created.

  4. Set Constraint Component Properties as appropriate.