Data Access Examples

Context: HL Kit … Kit Reference 

Let's look at a few examples of combining context transitions with target references into a useful target identifier. For the first example, we assume we're writing an Eval Script in which we need to access the calculated bonus conferred by the "strength" ability score for the hero. Since an Eval Script starts out in the context of a pick, we'll just go directly to the hero and drill down to get the value we need. From the hero, we transition to the pick that contains the "strength" ability score. Once we have the pick, we then transition to the "bonus" field. And finally we access the value of that field. In the end, the complete reference might look like the following:

hero.child[strength].field[bonus].value

What if our hero has a magic sword from which we need to extract information? In this situation, we need to drill down into the child gizmo and then into a pick belonging to that gizmo. Starting from the root hero again, we first access the pick that attaches the gizmo. From there, we transition to the gizmo, after which we can transition to the pick inside the gizmo. Once we have the pick context, we can get the field and access its value. The final result would look something like the following:

hero.child[magicsword].gizmo.child[attack].field[bonus].value

Now let's assume we have a script on a pick within the above gizmo that needs to access a field on a different pick within the same gizmo. Theoretically, we could bounce all the way out to the hero and drill down, but that approach won't work reliably if we have multiple magic swords on the hero. So the best approach is to move upwards to the container and then back down again into the desired pick. The process would look something like the following:

container.child[attack].field[bonus].value

The key thing to remember when writing scripts is to always know your initial context. From there, simply identify where you want to reference and then systematically transition, one step at a time. If you take things one step at a time, you'll be able to access the information you need and your scripts will work smoothly.

IMPORTANT! Within certain script contexts, all target references are treated as read-only, regardless of whether they are normally writable. Any attempts to modify the contents of a target reference that has been forced to be read-only will fail to either compile or work at run-time. For example, if a Position script for a visual element attempts to modify the contents of a pick, it will be forbidden. Any script for which this behavior occurs will specify it within the Kit Reference documentation.