Shadowing & Displacement: Difference between revisions

From HLKitWiki
Jump to navigationJump to search
 
(4 intermediate revisions by the same user not shown)
Line 1: Line 1:
== Basics ==
== 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).
Shadowing and displacement are intended for use on picks that can be present on gizmos. If a pick is shadowed or displaced, it effectively exists in '''two containers at once''': the gizmo container, and another container (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).
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).
Line 7: Line 7:


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.
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.
If a pick on the hero is shadowed or displaced, there is no effect.


== What's the Difference? ==
== 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'''.
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''' (how sinister!).


* 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 '''shadowed''', its owner container remains the same. The shadow container is the other 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.
* If a pick is '''displaced''', its owner container becomes '''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:
This has important implications. The "container" transition always goes to the '''owner container'''. Consider this script:


<pre>perform container.assign[Group.Tag]</pre>
<pre>perform container.assign[Group.Tag]</pre>


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.
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, because that's its owner container.


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.
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.
Line 33: Line 35:
|-
|-
|shadowed
|shadowed
|Returns 0 if the pick is not shadowed, non-zero otherwise.
|Returns non-zero if the pick is shadowed, 0 otherwise.
|-
|-
|displaced
|displaced
|Returns 0 if the pick is not displaced, non-zero otherwise.
|Returns non-zero if the pick is displaced, 0 otherwise.
|-
|-
|}
|}
Line 44: Line 46:
The following limitations apply to shadowed and displaced picks:
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.
* '''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. (If necessary, you can carve out the "shadow" element into a separate component, and include that component in the appropriate component sets instead of defining it in multiple components.)


* '''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.)
* '''Uniqueness:''' Even if a shadowed or displaced pick is unique, it will not be merged with other picks in the shadow container, even other shadowed or displaced picks. 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.
* '''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.
* '''Duplication & Moving:''' Displaced picks can't be duplicated, split, 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.
* '''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.

Latest revision as of 23:11, 1 March 2011

Basics

Shadowing and displacement are intended for use on picks that can be present on gizmos. If a pick is shadowed or displaced, it effectively exists in two containers at once: the gizmo container, and another container (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.

If a pick on the hero is shadowed or displaced, there is no effect.

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 (how sinister!).

  • If a pick is shadowed, its owner container remains the same. The shadow container is the other container (the hero or parent of the gizmo).
  • If a pick is displaced, its owner container becomes 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. Consider 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, because that's its owner container.

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 non-zero if the pick is shadowed, 0 otherwise.
displaced Returns non-zero if the pick is displaced, 0 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. (If necessary, you can carve out the "shadow" element into a separate component, and include that component in the appropriate component sets instead of defining it in multiple components.)
  • Uniqueness: Even if a shadowed or displaced pick is unique, it will not be merged with other picks in the shadow container, even other shadowed or displaced picks. 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, split, 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.