The "Live" State

Context: HL Kit … Advanced Authoring Concepts 

Overview

A variety of objects possess a "live" state. The "live" state controls whether an object behaves as if it exists (live), or as if it does not exist (non-live). This makes it possible to automatically include objects within your data files and then dynamically have them appear or disappear, based the contents of the current portfolio.

The "live" state applies equally to both visual elements and structural elements. A simple example of using the "live" state with visual elements is the various tab panels associated with each different class. All of those tabs are always defined and present, but each appears only when levels of the corresponding class have been added to the character. This is controlled via the "live" state.

For structural elements, the "live" state is primarily used to govern picks. A classic example in the Savage Worlds data files is arcane skills. Arcane skills are only possessed by a character when he has selected the corresponding arcane background. As such, the "live" state is used to control whether the arcane skills are made available.

Tag Expressions Control the State

The "live" state of elements is always controlled via a tag expression. The object upon which the tags are tested will vary between different types of elements, but a tag expression is always employed.

The results of the tag expression dictate the "live" state of the object. If the tag expression returns "true", then the object is considered "live". If the tag expression returns "false", the object is considered "non-live".

The tag expression is evaluated at different points in time, which depend on the nature of the element. Whenever the tag expression is re-evaluated, the behavior of the object can transition if the results of the tag expression change. This means that, whenever the tag expression is re-evaluated, the object can immediately transition from "live" to "non-live", or vice versa. The implications of transitioning the live state are different for visual and structural elements, as outlined in the sections that follow.

Visual Elements

The "live" state of visual elements is always controlled via a Live Tag Expression. This tag expression is always applied against the structural element whose contents are being displayed through the visual element. This is typically an actor, although it can also be a gizmo if the showing a form that edits the contents of the gizmo.

The "live" state is verified when the display is updated, which always occurs after each new evaluation cycle. If the container fails the tag expression test, then the visual element is completely hidden. In addition, any Position script for the visual element is ignored, since there should be nothing to show or position within the visual element.

Structural Elements

The "live" state of structural elements is generally governed by a Container Tag Expression, although other mechanisms also exist. These tag expressions are always tested against the tags on the container of the object, hence the name. The object sets forth the requirements that must be met by any prospective container that wants to hold the object.

The "live" state is tested in two separate situations for structural elements. First of all, when a thing is a candidate for display as a selectable item by the user, the "live" state is checked. If the thing fails the test and ends up being non-live, the thing is completely omitted from the list of items shown to the user. If the this is live, it is shown normally.

Once a thing is added to a container as a pick, the "live" state is again tested as part of every evaluation cycle. When a pick becomes "non-live", it goes dormant. All behaviors associated with the pick are turned off. For example, any scripts that are associated with the pick are simply ignored by the HL engine. The pick is treated as if it were never added in the first place.

However, if a pick becomes "non-live", it cannot simply be automatically omitted from the character. If the user added the pick, then the pick becomes dormant, but some additional behaviors are automatically implemented. First of all, any user-added pick that goes non-live remains visible to the user everywhere. The pick also becomes invalid, which allows for it to be color-highlighted to the user as an error that needs correction. Lastly, a validation error is reported to flag the error to the user.

A structural element that goes non-live has implications upon all elements that are chained to it. This includes all bootstrapped picks, any child gizmo, and any minion that is attached via the pick. Whenever a structural element goes non-live, anything it chains to also goes non-live. Consequently, any chained elements go dormant and simply disappear. The only exception to this is a unique pick that is added via multiple roots (e.g. bootstrapped by two or more picks), in which case the chained pick only goes dormant when all of its roots go non-live.