Change Script: Difference between revisions

From HLKitWiki
Jump to navigationJump to search
Newer edit →
New page: {{context|Kit Reference|Script Types}} ==Technical Details== :{| class="scripttable" |class="leftnormal"|Initial Context: |Container |- |Alternate Context: |None |-...
 
No edit summary
Line 24: Line 24:


==Description==
==Description==


-Choosers and menus can define a "change" script
-Choosers and menus can define a "change" script
Line 33: Line 32:
     -Script starts with container context associated with the portal
     -Script starts with container context associated with the portal


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.


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.
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.
 
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.


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.
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 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.
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.


==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
 
~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


~update the new "max" values for both picks based on the new stack quantity
~get the previous dot level
field[trkMax].value = field[stackQty].value
current = hero.firstchild[tagexpr].field[iprevlevel].value
altpick.field[trkMax].value -= altpick.field[stackQty].value


~the user value for the first pick is the quantity of ammo still unused,
~get the current dot level
~subject to the maximum size for the pick
nextlevel = hero.firstchild[tagexpr].field[ilevel].value
field[trkUser].value = minimum(user,field[trkMax].value)


~subtract the quantity allocated to the first pick from what's now left
~determine the XP cost to improve to the next dot level
user -= field[trkUser].value
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


~if we have any unused ammo left to assign to the other pick, assign it
~save out the calculated XP cost
if (user <= 0) then
child[advDetails].field[ixpcalc].value = xp
  altpick.field[trkUser].value = 0
child[advDetails].field[inewdots].value = nextlevel
else
  altpick.field[trkUser].value = user
  endif
</pre>
</pre>

Revision as of 21:58, 14 December 2008

Context: HL Kit &#133; Kit Reference &#133; Script Types 

Technical Details

Initial Context: Container
Alternate Context: None
Fields Finalized? Yes

The Change script utilizes the following special symbols:

-None- There are no special symbols for the Change script.

Description

-Choosers and menus can define a "change" script 

   -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

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.

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
Retrieved from "https://hlkitwiki.wolflair.com//index.php?title=Change_Script&oldid=1671"