Shadowing & Displacement

Basics

Shadowing and Displacement are intended for use on picks present on gizmos. If a pick is shadowed or displaced, it effectively exists in two containers at once (the gizmo container, and usually the hero container).

This means that the pick can be found by iterators (for example, a foreach loop, a call to firstchild, or a table shown in the UI) in both containers. This is often used to add a pick on a gizmo, then have that pick also appear on the hero in some way (for example, in a list of weapons or special abilities).

Shadowing and Displacement are set up using the shadow and displace elements on a component.

Note that both displaced and shadowed picks may only be deleted through the original container they were added through. They may not be deleted by the user from a table in any other container.

What's the Difference?

Normal (non-shadowed or -displaced) picks have only one container - the container that they were added through, which is known as their "owner" container. Shadowed and displaced picks have another, named the "shadow" container.

• If a pick is shadowed, its owner container remains the same. The shadow container is the secondary container (the hero or parent of the gizmo).

• If a pick is displaced, its owner container is the container the pick is displaced into (the hero or parent of the gizmo). The shadow container is the original container.

This has important implications. The "container" transition always goes to the owner container. For example, this script:

perform container.assign[Group.Tag]

On a normal or shadowed pick, the tag "Group.Tag" is assigned to the container the pick was added to. However, on a displaced pick, the tag is assigned to the container the pick was displaced into.

Also, bootstrapped picks are always added to the owner container. This means that if a displaced pick bootstraps other picks, those picks will be added to the container the pick was displaced into.

Script Access

Several related script transitions and target references are available for shadowed and displaced picks.

shadow	Transitions to the shadow container for a pick.
shadowed	Returns 0 if the pick is not shadowed, non-zero otherwise.
displaced	Returns 0 if the pick is not displaced, non-zero otherwise.

Limitations

The following limitations apply to shadowed and displaced picks:

• Choose One Only: It is not legal to have a pick that is shadowed under some circumstances, and displaced under others. Only one of the components in a component set may specify a "shadow" or "displace" element. Trying to do otherwise will cause a compilation error.

• Uniqueness: Even if a shadowed or displaced pick is unique, it will not be merged with other picks in the shadow container; merging two unique picks with different containers is not possible. (Uniqueness is observed normally in the "owner" container.)

• User-ordering: When a pick is shadowed or displaced, it maintains a SEPARATE user-sorted order within each container to avoid conflicts. The "echo" behavior of the user-sorted order into a field value is only performed for the order within the "owner" container.

• Duplication & Moving: Displaced picks can't be duplicated or stacked, or moved between gizmos and the hero (since movement and stacking effectively duplicates the original pick to move or split it). Note: This only applies to displaced picks. Shadowed picks can be duplicated, moved and stacked as normal.

• Maxlimit: Displaced picks can't use "maxlimit". This is because limits within a foreign container cannot be properly detected and policed by Hero Lab's engine. Note: This only applies to displaced picks. Shadowed picks can be duplicated, moved and stacked as normal.