Script Macros

[Context: HL Kit … Basic Concepts and Terminology … Scripting Language … Language Basics]

The scripting language syntax is designed to support accessing a complex assortment of game elements. This can result in some rather lengthy terms to specify exactly the information you want to access. Many of these terms will be used extensively within the data files for a given game system. To simplify scripts, the Kit allows you to define an assortment of script macros that serve as a shorthand notation for quickly accessing common elements.

For example, in the data files for the d20 System, there are numerous effects that apply bonuses to skills (e.g. feats). The syntax for accessing the bonus value for a given feat looks something similar to the code shown below (for more details, please refer to the Kit Reference).

hero.childfound[kTumble].field[Bonus].value

If you had to type this in everywhere, there would be lots of opportunity for errors and it would be tedious to type each time. So the d20 System data files define a "skillbonus" macro that can be used in place of the above syntax. Using the "skillbonus" macro, the resulting syntax is simplified to the following:

#skillbonus[kTumble]

By using a script macro, the code becomes simpler to write, plus it becomes clearer regarding what it's doing. The above macro is clearly accessing the skill bonus value for the skill with unique id "kTumble". This is much clearer than the lengthy text to which the macro corresponds.

The syntax for using a script macro is that it always starts with a '#' character, followed by the name of the macro. Parameters for the macro are placed within square brackets and separated by commas (if there are more than one). When HL compiles the data files, it knows to replace the macro with the corresponding long syntax, as specified for the game system, allowing the compiler to generate the proper behavior.

The data file structure will vary greatly from one game system to the next, as will the commonly accessed information for each game system. As such, the specific set of macros defined for each game system will vary based on what's most appropriate that game system. To simplify getting started with your own data files, the starter data files provided with the Kit include a number of useful script macros that you can both put to use and refer to as examples when adding your own new macros.