Difference between revisions of "Change Script"

From HLKitWiki
Jump to: navigation, search
(New page: {{context|Kit Reference|Script Types}} ==Technical Details== :{| class="scripttable" |class="leftnormal"|Initial Context: |Container |- |Alternate Context: |None |-...)
 
 
(4 intermediate revisions by one other user not shown)
Line 12: Line 12:
 
|Fields Finalized?
 
|Fields Finalized?
 
|Yes
 
|Yes
 +
|-
 +
|Where Used:
 +
|[[Portal Element (Data)|Portals]]
 +
|-
 +
|Procedure Use:
 +
|"container" context
 
|-
 
|-
 
|}
 
|}
Line 25: Line 31:
 
==Description==
 
==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.
  
-Choosers and menus can define a "change" script
+
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.
    -Script is invoked any time the contents of a chooser or menu are changed
+
    -Behaves similarly to a trigger action portal
+
    -Defined via a "change" element where the PCDATA contains the actual script
+
    -Script is invoked via UI by calling C_Portal_Select::Change_Trigger
+
    -Script starts with container context associated with the portal
+
  
 +
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.
  
The Split script handles the splitting of one piece of gear into two separate picks via stacking behavior. It is invoked whenever the user performs a split operation of stackable gear. The goal of the script is to allow authors to properly reconcile whatever fields are necessary for an accurate splitting of one pick into two distinct picks.
+
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 Split script is defined for a component. As such, it is inherited into every thing that derived from that component. Each script is intended to properly split the fields within that component and nothing else. This ensures that a thing derived from multiple components, each with their own Split script, will perform appropriate split behavior without incident.
+
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.
  
When invoked, the Split script starts out with a pick as its initial context. However, there are two picks involved in the split operation. When a split takes place, there is the initial pick that is being split (e.g. decreasing its quantity) and the new pick that is ultimately created through the split process. The initial context is the existing pick that is being split. The second pick is made available via an alternate pick context, which can be accessed via the "altpick" context. This makes it possible to split  one pick into two, regardless of what fields or behaviors are involved.
+
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".
 
+
When splitting picks, the engine will automatically update the "stackQty" field of both picks with the appropriate values. Therefore, if a pick with a quantity of 20 is split, with a new quantity of 7 specified, the engine will setup the pick being split with a "stackQty" field of 13 and the new pick with a "stackQty" of 7. You can then use these field values to accurately adjust everything else for each pick.
+
  
 
==Example==
 
==Example==
  
The sample Split script below splits one pick into two and properly adjusts all user-tracking details to accurately reflect the impact of the change.
+
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.
  
 
<pre>
 
<pre>
~save the quantity of ammo that still remains unused
+
~get the cost of each dot for the ability
var user as number
+
var eachdot as number
user = field[trkUser].value
+
eachdot = firstchild["Advance.Gizmo"].field[idotcost].value
  
~update the new "max" values for both picks based on the new stack quantity
+
~determine the tagexpr with which to identify the pick we're interested in
field[trkMax].value = field[stackQty].value
+
var tagexpr as string
altpick.field[trkMax].value -= altpick.field[stackQty].value
+
tagexpr = "component.CanAdvance & Advance." & firstchild["Advance.Gizmo"].idstring
  
~the user value for the first pick is the quantity of ammo still unused,
+
~if there is a half-price discount for the ability, incorporate that
~subject to the maximum size for the pick
+
if (hero.tagsearch["HalfPrice." & firstchild["Advance.Gizmo"].idstring] > 0) then
field[trkUser].value = minimum(user,field[trkMax].value)
+
  eachdot = eachdot / 2
 +
  eachdot = round(eachdot,0,1)
 +
  endif
  
~subtract the quantity allocated to the first pick from what's now left
+
~if there is a double-cost penalty for the ability, incorporate that
user -= field[trkUser].value
+
if (hero.tagsearch["DoubleCost." & firstchild["Advance.Gizmo"].idstring] > 0) then
 
+
   eachdot *= 2
~if we have any unused ammo left to assign to the other pick, assign it
+
if (user <= 0) then
+
  altpick.field[trkUser].value = 0
+
else
+
   altpick.field[trkUser].value = user
+
 
   endif
 
   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
 
</pre>
 
</pre>

Latest revision as of 22:51, 19 December 2013

Context: HL KitKit 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