CanAdvance Script

Context: HL Kit … Kit Reference … Script Types 

Technical Details

Initial Context:	Hero
Alternate Context:	None
Fields Finalized?	Yes
Where Used:	Definition File
Procedure Use:	None

The CanAdvance script utilizes the following special symbols:

message

(String) Entry: The empty string to indicate the character can transition to advancement mode. Exit: If non-empty, indicates the character cannot transition to advancement mode, with the contents being shown to the user as the explanation of what must still be completed for the character. The text may contain encoding.

Description

The CanAdvance script is only utilized when the formalized advancement mechanism is enabled for the game system. This script allows the author to verify that the minimum configuration has been completed for a character before allowing the user to switch from creation mode to advancement mode.

The CanAdvance script is invoked when the user attempts to switch to advancement mode via the menu. When the user tries to make the change, the script is triggered, at which point the script verifies that the necessary creation steps have been completed for the character. If any are not satisfied, an error message is displayed to the user and the user is not allowed to transition until the creation process is completed.

It is the responsibility of the script to synthesize the message shown to the user that reports the creation steps that have not been satisfactorily completed. If a problem 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 a new line. If there are no errors, then the special symbol should be the empty string, and that tells HL that the character is ready to transition to advancement mode.

When invoked, a CanAdvance script starts with the actor as its initial context. You are free to check any aspect of the character when verifying that the transition to advancement mode is allowed.

NOTE! Don't be too picky with the CanAdvance 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 all rules. The CanAdvance 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 CanAdvance script below shows the behavior of the Sample data files for handling the advancement test. The script sets up a bullet character to put at the start of each error and then performs the tests. If any test fails, a suitable error message is appended to the message.

var bullet as string
bullet = "{bmp bullet_red}{horz 4}"

~perform tests to assure starting resources have been assigned
if (#resleft[resCP] <> 0) then
  @message = @message & bullet & "Character points must be assigned for the character.\n"
  endif
if (#resleft[resAbility] <> 0) then
  @message = @message & bullet & "Ability slots must be assigned for the character.\n"
  endif