Debugging Mechanisms
[Context: HL Kit … Basic Concepts and Terminology]
Overview
The development of a fully functional set of data files for a game system involves a great many steps and there are bound to be a few problems along the way. As a result, we consider the task of fixing these problems to be a basic component of the development process. In order to facilitate the resolution of problems, HL includes a variety of built-in mechanisms that can be leveraged when issues arise. Since errors in software are traditionally called "bugs", we refer to these mechanisms as "debugging" aids.
Topics
The topics below outline a number of incredibly useful tools and techniques for quickly figuring out what is going wrong within your data files. Familiarize yourself with these debugging mechanisms now, since you will find yourself putting them to use at various points in the development process.
Info Windows
[Context: HL Kit … Basic Concepts and Terminology]
Whatever the game system, HL will be tracking a great deal of information. Portfolios contain multiple heroes and heroes can have child gizmos. Heroes and gizmos contain a large number of picks, and those picks will contain a healthy number of fields. Everything has a wide assortment tags. And don't forget the task list that tracks all of the different operations that are performed on all of these objects. Even if the game system is relatively simple, there will be lots of information, and the volume increases dramatically as the game system complexity goes up.
At any point in time during development, you'll be working on some subset of this information. After you make some changes to the data files, you'll be expecting everything to work. However, if it doesn't work, you'll want to understand why. This is usually achieved by looking at the appropriate subset of information within HL that you are manipulating to see what is happening, which can typically narrow down where the error is lurking.
To help out in these situations, HL provides a bunch of different ways to view the information that is being tracked internally. This is accomplished through "info windows". Each info window is a floating window that is separate from the main HL window and contains specific information about some facet of the current portfolio. Every time that a change is made to portfolio, the contents of each info window are updated, so you can see the direct effects of changes in real-time.
Info windows can be created at any time by going to the "Debug" menu, selecting the "Floating Info Windows" menu, and then choosing the appropriate option from the sub-menu that is presented. Once created, the info window persists until you close it. You can move the info window around and resize it as you deem appropriate.
Each type of info window contains different information that may prove useful in different situations. The table below offers a quick summary of the information provided by each info window.
Hero Tags Displays a list of all the tags assigned to the active hero. This list includes tags from three different sources. First, any tags dictated by the user's selection of sources and/or rule sets are included. Second, tags that are dynamically assigned to the actor by scripts are included. Lastly, tags that are automatically assigned to minions are included (only if the hero is a minion). Hero Fields Displays a list of all the fields assigned to the active hero. Heroes don't technically possess fields, but every hero automatically contains a single "actor" pick that does possess fields. Since the "actor" pick is considered synonymous with the actor in a variety of situations (e.g. the Tactical Console and Dashboard), the fields within the "actor" pick are considered to be "actor fields" (or hero fields). Task List (Active Hero) The complete set of all tasks for the active hero are listed. The task list includes all actions that are scheduled to occur during the evaluation cycle, such as Eval Scripts, Eval Rules, Bounding scripts, Condition tests, and a host of other operations. Anything that is scheduled to be performed at a specific phase and priority has a corresponding task that will appear in this list. Task List (Full) This option shows the complete task list for all heroes within the context of the current lead. When minions are used and those minions have timing inter-dependencies with their master, the interplay of all the tasks for all the actors can be critical. In those situations, the full list can be used to help diagnose timing errors between different actors. Selection List Displays a list of all of the picks that have been added to the active hero. There are a variety of mechanisms within the Kit that control whether picks are added to an actor, such as bootstraps, condition tests, and live tests. This info window can help you to diagnose whether things are behaving as you intend. Selection Tags When you select this option, a list of all of the picks for the active hero is presented. You can select as many picks as you want, after which separate info windows will be created for each pick you specified. The info windows will contain a complete list of all the tags that are assigned to the pick at the conclusion of evaluation. If a tag is deleted at some point during evaluation, it will not appear in this list. Selection Fields When you select this option, a list of all of the picks for the active hero is presented. You can select as many picks as you want, after which separate info windows will be created for each pick you specified. The info windows will contain a complete list of all the fields and their values for the pick at the conclusion of evaluation. Debug Output This option opens up a window into which debugging output is written during evaluation. This topic is discussed in detail in the following topics.
Debug Output Via Scripts
In most traditional programming languages, there is the age-old technique of inserting a "print" statement at various points in the code to display the state information. This technique is used to verify that everything is behaving correctly and to diagnose errors that surface. The Kit provides two related mechanisms that offer a similar solution.
The first mechanism is the "notify" statement within the scripting language. This statement allows you to synthesize a string and then display it to the user. The string can be anything, such as the contents of fields, the results of an arithmetic expression, or even just a simple error message. So you can display whatever information you need to convey.
The notify mechanism displays an alert message to the user, requiring the user to dismiss the message before continuing. It works very similarly to the way run-time errors are handled. Consequently, the notify mechanism is ideal for reporting unexpected and/or error conditions that are encountered during evaluation. It is also useful for inserting a quick verification of a few values during testing of new functionality.
The second mechanism is the "debug" statement within the scripting language. Like the notify mechanism, this statement allows you to synthesize a string for output, but the resulting text is not displayed directly to the user. Instead, the text is sent to the Debug Output window, which can be shown via the "Floating Info Windows" sub-menu of the "Debug" menu.
When the Debug Output window is visible, the use of a sequence of "debug" statements will send a progressive series of messages to the window. You can use this technique to monitor the flow of execution through all of your scripts and watch both the values of fields and the presence of tags at various points during the evaluation cycle. Every time the evaluation cycle is triggered, all of the debug messages are output again, so you can easily watch the effects of changing selections and values within the character through each new evaluation cycle.
This particular technique is probably the single most valuable method for quickly diagnosing where things are going wrong within your scripts. Once you know where things are going wrong, it's usually pretty easy to figure out why the error is occurring and put in the proper correction.
Script Timing Issues
when to recognize a timing issue - everything looks good via info windows but the expected behavior still isn't being performed properly list of tasks debug output of script timing
Defining Timing Dependencies
naming tasks establishing before and after dependencies the timing report
