EvalRule Script

Context: HL Kit … Kit Reference … Script Types 

Technical Details

Initial Context:	Pick
Alternate Context:	None
Fields Finalized?	No
Where Used:	Components, Things
Procedure Use:	"evalrule" type, "pick" context

The EvalRule script utilizes the following special symbols:

valid	(Number) Entry: Assumed the rule is not satisfied with a value of zero. Exit: Indicates whether the rule is satisfied (non-zero) or not satisfied (zero).
message	(String) Entry: Contains the default message text if the rule is not satisfied. Exit: Contains the final message text to display if the rule is not satisfied. The text may contain encoding.
summary	(String) Entry: Contains the default summary text if the rule is not satisfied. Exit: Contains the final summary text to display if the rule is not satisfied. If not specified, but the "message" symbol is modified, the summary automatically uses the message text.

Description

The EvalRule script is very similar to an Eval script, with the primary distinction being that the EvalRule script verifies a rule is observed instead of applying changes. This script is scheduled during the evaluation cycle, so it allows you to check the state of an actor at intermediate points, in addition to at the end of evaluation. Intermediate checks make it possible to verify values before they are further modified by other aspects of the character.

An EvalRule script shares all the same behaviors of an Eval script, plus it adds the rule to be validated. The rule can be anything you want. However, the rule is always either satisfied or not satisfied. This is determined by the "valid" special symbol. The symbol starts out as zero, indicating that the rule is not satisfied. At any point during the script, you can set the symbol to non-zero, thereby indicating that the rule is satisfied. You can also change the symbol value throughout the script if you want. The only value that matters is the final value when the script ends, where a non-zero value indicates the rule is satisfied.

If the validation test is not satisfied, the message and summary for the rule are displayed within the validation report and validation summary for the actor, respectively. Since the message and summary are typically static requirements (e.g. an attribute must be a value of X or more), you will rarely need to modify them. However, there will be cases where you want to tailor the message and/or summary to provide more detailed information based on dynamic information. When these situations arise, simply set the "message" and/or "summary" special values to the desired contents and they will be used.

Since an EvalRule script is equivalent to an Eval script, it is possible to apply changes throughout the structural hierarchy via the script. However, it is generally a bad idea to do that, since the purpose of an EvalRule script is to validate a rule - not effect change. We therefore recommend that you avoid applying changes within EvalRule scripts.

Like an Eval script, every EvalRule script is associated with a particular thing. If an EvalRule script is defined for a component, then it is inherited by the things which derive from that component. When a thing is added to a container, it becomes a pick, and new instances of every EvalRule script for that thing are created and managed by HL. You associate all of the validation rules with each pick via the EvalRule scripts defined for the underlying thing.

When invoked, an Eval script starts with its associated pick as its initial context. You are free to navigate through the hierarchy and test the state of anything that impacts the rule. However, a given EvalRule script should typically either pertain to the associated pick or pertain to the actor as a whole.

Example

An EvalRule script can be used to test virtually anything. Within the Sample data files, a rule is used to ensure that pieces of gear are not both equipped and held within a container (e.g. a sword being equipped and stored in a backpack). The rule below will verify this condition.

~if not both equipped and held within a container, we're valid
if (field[grIsEquip].value + isgearheld < 2) then
  @valid = 1
  done
  endif

~mark the tab as invalid
linkvalid = 0