Integrity Script

Context: HL Kit … Kit Reference … Script Types 

Technical Details

Initial Context:	Container
Alternate Context:	None
Fields Finalized?	Yes
Where Used:	Entities
Procedure Use:	"container" context

The Integrity script utilizes the following special symbols:

message

(String) Entry: Contains the empty string to indicate that no errors were identified. Exit: Contains the final error message text to display. If there are no errors, specify the empty string. The text may contain encoding.

Description

The Integrity script is associated with entities. This script allows the author to verify that all the appropriate values have been specified for a gizmo before allowing the user to actually save changes to the gizmo.

The Integrity script is invoked when the user finishes editing a gizmo derived from the entity for which the script is defined. When the user tries to save his changes, the script is triggered, at which point the script verifies that an assortment of characteristics are satisfied by the gizmo. If any are not satisfied, an error message is displayed to the user and the user is not allowed to save his changes until the errors are corrected.

It is the responsibility of the script to synthesize the message shown to the user that reports the errors in the gizmo. If an error is detected in the script, a suitable error message should be appended to the "message" special symbol. If multiple errors occur, the message should contain a list of them, with each message on new line. If there are no errors, then the special symbol should be the empty string, and that tells HL that the gizmo is safe to save.

When invoked, an Integrity script starts with the gizmo as its initial context. There is generally no reason to navigate outside the context of the gizmo, but it is technically allowed. The primary focus will be on the gizmo itself and the child picks within it.

NOTE! Don't be too stringent with the Integrity script. Remember that every gaming group has its own house rules that will modify the basic game rules. As such, it's important to use validation rules to trap most errors instead of requiring the user to obey certain rules. The Integrity script should only be used to enforce details that should always be required and/or that impact your ability to write quality data files.

Example

The handling of advancement that is found within the Sample data files utilizes an Integrity script. Based on the information shown for a particular advancement, certain fields must be specified by the user. If that information is not provided, the form remains shown and no changes to the gizmo are saved.

~setup a bullet character we can put at the start of each error
var bullet as string
bullet = "{bmp bullet_red}{horz 4}"

~verify that a chooser selection is made if one is required
if (parent.tagis[Advance.MustChoose] <> 0) then
  if (firstchild["Advance.Gizmo"].tagis[Advance.Gizmo] = 0) then
    @message = @message & bullet & "A specific trait/ability must be selected via the chooser.\n"
    endif
  endif

~verify that we've been given a domain if one is required
if (parent.tagis[Advance.MustChoose] + parent.tagis[Advance.AddNew] >= 2) then
  if (firstchild["Advance.Gizmo"].tagis[User.NeedDomain] <> 0) then
    if (empty(child[advDetails].field[advUser].text) <> 0) then
      @message = @message & bullet & "The selection requires that you specify an appropriate domain.\n"
      endif
    endif
  endif