Script Timing Issues

[Context: HL Kit … Basic Concepts and Terminology … Debugging Mechanisms]

Overview

We'll start this section off by answering the obvious question. What's a timing issue?

The evaluation cycle controls the order in which everything is processed for each character, and it's up to the author to make sure that every task is assigned an appropriate phase and priority. A timing issue is the result of scheduling a task in the wrong sequence, which causes the evaluation cycle to yield the wrong final results.

It doesn't matter how experienced you are as an author, script timing issues will crop up if the game system has even a modicum of complexity. The trick is in being able to recognize when you are dealing with a timing issue. In general, timing issues are identified via a process of elimination, wherein the possibility of all other types of errors is systematically ruled out.

This section provides assorted tips on how to recognize and resolve timing issues.

Using the Task List

The most fundamental tool for solving timing issues is the task list, which is accessible via the "Debug" menu and the "Floating Info Windows" sub-menu. The task list, as its name suggests, presents a single list of all of the different tasks that are scheduled during the evaluation cycle. This list is often rather lengthy, since every pick and every field has its own distinct set of tasks.

The list is sorted in the order that the tasks will be evaluation by the HL engine. For each task, you'll see its phase, priority, and a brief description. This description should help in identifying exactly what the task is doing and what it is operating upon.

If you think you have a timing issue, the thing to do is check the task list. Make sure that each of the tasks you're working with is occurring in the proper sequence. If you're integrating new functionality that relies upon other tasks to setup state appropriately, be sure to check that your new tasks are occurring after the existing tasks have been invoked. Similarly, if your new tasks apply modifications that other tasks will rely upon, make sure to verify that sequencing as well.

Remember that there are two separate task lists. In general, you will want to utilize the task list for the active hero. This task list is perfect for verifying timing relationships between tasks within a single actor, which is normally what you'll be trying to do. The full list contains all the tasks for all actors, interspersed amongst each other. The only time you'll want to use this task list is when you have masters and minions that have inter-dependencies between each other, such as familiars in the d20 System, which have traits derived from their master and also confer bonuses back onto their master.

Script Timing Output

debug output of script timing

Debug Output Tracing

debug output of each step in evaluation to monitor the timing and flow

Diagnosing a Timing Issue

The first diagnostic step is always to review each of the tasks involved in the behavior you're implementing. For each task, you need to double-check the associated tag expressions and/or script code. Then check the appropriate info windows to see whether all of your assumptions are being satisfied. Do fields contain the values they should? Are all the proper tags assigned where they should?

You may also find it useful to insert a few "debug" or "notify" statements into pertinent scripts to verify that values and tags are

appropriate info windows.

There are two primary types of timing issues that can arise, and each has slightly different symptoms. For both, however, the first diagnostic step is to review the appropriate info windows.

contents of info windows is wrong, but the scripts are performing the correct actions

everything looks good via info windows but the expected behavior still isn't being performed properly