Skip to content

Eval Scripts

Jump to bottom
Sklore edited this page Sep 8, 2016 · 2 revisions

#What Are Eval Scripts?

Eval scripts are how one pick makes changes to itself or another facet of the hero. Most of the logic that controls how the game system works is carried out by eval scripts, either specific to an individual pick, or running behind the scenes for all picks of that type (these behind-the-scenes scripts are called "component scripts" and are invisible and unmodifiable by users). Eval scripts only run for picks, never for things, so you'll never see their effects until you add the thing containing the script to your hero.

#What Can Eval Scripts Do?

Eval scripts can change tags and fields on themselves, or another pick, in response to changing conditions of the hero. They can define variables (numbers and text), perform simple math and rounding, manipulate text in certain limited ways, and make certain changes to other content on the hero.

#What Can't Eval Scripts Do?

General, eval scripts can't affect things which haven't been added to the hero (with the exception of the name and description fields on things - see the section on Macros for an example of how to change those). Eval scripts cannot add new picks to the hero (although they can alter conditions such that a bootstrap condition is satisfied, and a previously bootstrapped pick is then added to the hero).

#Important Eval Script Concept: Timing

Every time something is changed on the hero, every pick on that hero runs all its scripts, and the Timing for each script controls the order those scripts happen in. It's very important that you choose the right timing for your eval scripts. Too early, and information you need may not have been set yet. Too late, and any changes you make may happen after the relevant field or tag has been read by the next step in whatever process it is involved in.

For example, if you were to add some value to the Proficiency Bonus in an eval script "too late", that bonus would not get passed down to the save picks which are proficient.

Timing is divided into several Phases in each game system, which happen in order. Within each phase, priority controls the relative order of eval scripts, with a higher priority occuring later in the process. For the 5th Edition SRD, the Phases (in order) are:

  • Testing Global Tags (GlobalTest) - This phase is too early for anything you may need to do with an eval script, and can generally be ignored. Certain special things run scripts very early, and have to use tests in this phase to determine if they should execute those scripts or not.
  • First - Think carefully about setting an eval script here. Very little has been set about the character at this point, so the most common reason to be doing things here is to satisfy a bootstrap condition (see the section on tag expressions for details on bootstrap conditions).
  • Pre-Levels (PreLevel) - If you need to intervene in some of the processes which will happen in Levels, put your eval script here. Classes add some portion of their level towards gaining spell slots (as discussed in Tutorial 6), so setting or changing the tags related to that should happen in Pre-Levels.
  • Levels (Level) - Ignore this phase for the most part. Most of what you will need to do will rely on what is set in the Levels phase, or will need to manipulate those processes before they execute. The Proficiency bonus is calculated by component scripts during this phase.
  • Post-Levels (PostLevel) - Anything which relies on the character's level being known should go in this phase. This is probably a safe "default" phase for most things that don't rely on knowing ability score modifiers (which have not yet been calculated). Many class special abilities which calculate a value based on the character's level do so in Post-Levels eval scripts.
  • Pre-Attributes (PreAttr) - Rarely used, most things which can go in this phase will work just as well in Post-Levels. You might add something here if it depends on an earlier script of yours in PostLevel but need to alter something about how ability score modifiers are calculated.
  • Attributes - As with Levels, you can ignore this phase and for the same reasons. The character's final ability score modifiers are calculated by component scripts during this phase.
  • Post-Attributes (PostAttr) - Anything which relies on a character's ability score values or modifiers goes in this phase. The component scripts which set the bonus for saving throws happen in this phase.
  • Final - This is the phase when many things from various places get pulled together and combined to make their final value. The final bonus to damage rolls for a weapon is computed during this phase.
  • Render - This phase is for defining the presentation of picks (chiefly designing the name and summary they display when viewed in various parts of Hero Lab) and the application of situational modifiers.

#Important Eval Script Concept: Context

Every script starts somewhere, and if you give a command without specifying otherwise, the command is carried out in that default Context for the script (usually affecting the pick the script is running on). If that's not what you want, you must tell the script to "transition" to another context before executing the command.

This idea of “where the script is” when it carries out an action is called the script’s “context”. Where the script starts is called the “default context” and it varies based on the type of scripts (for evals the default is the pick running the script). The process of moving the script away from the default context to somewhere else is called “transitioning”, and each transition is represented in the code as a dot / period / full stop character.

For example, in an eval script, if we wanted to access the value of the “abilActive” field on the current pick, we can do this:

field[abilActive].value

Only one transition was necessary, from the field to its value.

To access the proficiency bonus, we must first establish a context of the hero, and then transition to the ProfBonus child pick on that hero, then to the “tProfBonus” field on that pick, and finally to the value of that field, like so:

hero.childfound[ProfBonus].field[tProfBonus].value

For more information on contexts, check out our Authoring Kit Wiki.

Clone this wiki locally