TransactSetup Script

Context: HL Kit … Kit Reference … Script Types 

Technical Details

Initial Context:	Pick or Thing
Alternate Context:	None
Fields Finalized?	Yes
Where Used:	Components
Procedure Use:	"xactsetup" type, "transact" context, "pick" context

The TransactSetup script utilizes the following special symbols:

isbuy	(Number) Entry: Indicates whether the transaction is buy (non-zero) or sell (zero). Exit: Ignored.
ispick	(Number) Entry: Indicates whether the context is a pick (non-zero) or a thing (zero). Exit: Ignored.
isprimary	(Number) Entry: Indicates whether this is the primary transaction taking place (non-zero) or not (zero). Exit: Ignored.
special	(Number) Entry: Value specified with the definition of the portal to allow different behaviors based on usage. Exit: Ignored.
notransact	(Number) Entry: 0 Exit: If set to non-zero in the setup script for a "sell" transaction, no sell transaction happens - instead, the regular "Delete?" form is shown instead. This is intended for Shadowrun and similar games, where you always want to refund 100% of an item's cost during character creation, or while building an item - in those cases, you don't sell something, you're actually "un-buying" it so the money was never deducted in the first place. This is totally ignored in the xactsetup script for a "buy" transaction.

Description

The TransactSetup script is invoked at the beginning of a transaction, whether it be a buy or sell operation. When invoked, the initial context is either the thing being purchased or the pick being sold. The script can also access the separate "transaction" context to manipulate the transaction pick. In fact, the role of the TransactSetup script is to appropriately configure the transaction pick so that everything is properly presented and handled for the user.

The engine will automatically setup the transaction pick with a few pieces of information. It's up to you to setup the remaining details for how you want the transaction to be handled. The automatic behaviors of the engine differs for buying and selling operations, so both are outlined separately below.

Setup logic for a "buy" transaction:

1. The "xactName" field is set to the name of the thing being purchased
2. The "xactLimit" field is set to no limit
3. The "xactQty" field is set to the lot size for the thing being purchased
4. The TransactSetup script is invoked

Setup logic for a "sell" transaction:

1. The "xactName" field is set to the name of the thing being purchased
2. The "xactLimit" field is set to the total quantity possessed for the pick
3. The "xactQty" field is set to the total quantity possessed
4. The TransactSetup script is invoked

Within the TransactSetup script, the "xactEach" field must always be set to the proper unit cost for the item being purchased or sold. Other fields may be setup as you deem appropriate to the transaction requirements.

Please see the separate documentation for further details on using transactions.

Example

The TransactSetup script below shows the behavior of the Sample data files for handling gear transactions. The "each" cost is setup to the cost of the gear, the actual amount paid is set to zero so that default handling is used, and the gear is identified as a holder if appropriate.

~start by assuming our unit cost is the cost of one item
var cost as number
cost = field[grCost].value

~setup the unit cost for the item
hero.transact.field[xactEach].value = cost

~zero out the cash amount to be paid (implying use of the standard cost)
hero.transact.field[xactCash].value = 0

~if the item is gear, setup whether the item holds other gear
if (isgear <> 0) then
  hero.transact.field[xactHolder].value = gearcount
  endif