Change Script

Context: HL Kit … Kit Reference … Script Types 

Technical Details

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

The Change script utilizes the following special symbols:

-None-

There are no special symbols for the Change script.

Description

The Change script is utilized within chooser and menu portals. The purpose of the script is to enact special handling whenever the contents of the portal are changed.

It is rare that you'll need to use this mechanism, because the impact of a selection will usually be handled via Eval scripts during the next evaluation cycle. The key exception to this is when the user is customizing a gizmo within the form for that gizmo. If the influence of the selection is required before the gizmo changes are finally saved, a Change script is needed to apply the necessary effects.

As an example, consider the World of Darkness data files. When a character spends XP during advancement, the XP cost for each advancement varies based on a numerous conditions. The Change script is utilized to properly calculate the XP cost for the selected advancement, which can then be displayed to the user before the advancement is officially added.

When invoked, the Change script starts out with a container as its initial context. This container is the one that the portal is associated with. For example, a chooser portal will reside within a layout, which is within a panel or form. The container associated with the panel or form is the initial context.

The "altpick" context may also be accessed from this script. This transitions to the pick that the selection was changed on (i.e. the pick "behind" the template) for menus, or to the newly selected pick for choosers. This is intended for use on the iPad, where changing the currently equipped weapon in a menu needs to deselect all other equipped weapons.

Note that altpick transitions to the pick behind the current template for menus, NOT the pick that was selected by the menu, as you can get the latter from the former. "altthing" is not supported in these contexts, only "altpick".

Example

The Change script below shows how the calculation of XP cost is performed for the World of Darkness game system. This example is edited down to show the core behaviors, as the real script handles additional factors.

~get the cost of each dot for the ability
var eachdot as number
eachdot = firstchild["Advance.Gizmo"].field[idotcost].value

~determine the tagexpr with which to identify the pick we're interested in
var tagexpr as string
tagexpr = "component.CanAdvance & Advance." & firstchild["Advance.Gizmo"].idstring

~if there is a half-price discount for the ability, incorporate that
if (hero.tagsearch["HalfPrice." & firstchild["Advance.Gizmo"].idstring] > 0) then
  eachdot = eachdot / 2
  eachdot = round(eachdot,0,1)
  endif

~if there is a double-cost penalty for the ability, incorporate that
if (hero.tagsearch["DoubleCost." & firstchild["Advance.Gizmo"].idstring] > 0) then
  eachdot *= 2
  endif

~get the previous dot level
current = hero.firstchild[tagexpr].field[iprevlevel].value

~get the current dot level
nextlevel = hero.firstchild[tagexpr].field[ilevel].value

~determine the XP cost to improve to the next dot level
var xp as number
var dotcount as number
var dotcost as number
dotcount = nextlevel
call dotcost
xp = dotcost
dotcount = current
call dotcost
xp -= dotcost
xp = xp * eachdot

~save out the calculated XP cost
child[advDetails].field[ixpcalc].value = xp
child[advDetails].field[inewdots].value = nextlevel