As of version 2.18, items can have script code associated with them. There are several different sections of code, each accomplishing something different. In many ways, this is similar to Scripting for Feats, and offers similar capabilities. An item's script is edited from the Items Editor's Script tab.
All item script sections will have access to the following objects:
Cr: The creature which owns the item.
It: The item whose script is running. Note that unlike other item objects, changes to this item object are saved automatically. If you must acquire another item object using cr.GetItemObj, make sure to call cr.SetItemObj afterwards.
func: The object with miscellaneous useful functions (see Scripting – func Object ).
This code is shared for all other code sections of this particular item. Declare full functions using 'Sub ProcedureName()' or 'Function FunctionName()'. The function or subroutine can then be called using ProcedureName or FunctionName.
This is called when player selects the 'Use Item' menu - after all the standard effects such as spell-like abilities are applied. In the case of items with multiple uses, you could prompt the user (using func.Choose for instance).
If the item has charges, one will be subtracted as per the usual procedure – even if the user pressed cancel in one of your prompts. In this case, you should restore the charge.
A variable called 'hours' is set to the number of hours that the player rested – usually 8 for one night and 24 for a full day. You can use this to recharge items automatically.
These scripts are called once whenever a player equips or unequips an item. For instance, this could be used to give a semi-permanent modifier to the PC, and remove it when unequipping (see cr.AddModifier in Scripting – Creature Functions ). It is advisable to use the Condition Effect script section though (see below), since removing an item does not automatically run the Unequip item script.
Called when a magical weapon with an ability is created, after the normal creation process is complete. The 'cAtt' variable holds the created attack, the 'It' item is the weapon item being created, and 'AbilIt' is the weapon ability object that is being applied. 'BaseAtt' is the original attack - this is a copy of the standard item, do not modify it for changes will not be saved. The 'Cr' creature object is NOT available. By modifying cAtt you can add the second dice of damage (and its type).
By changing the script code of the item you can create more complex effects. You can use the It.AppendCode function (see Scripting – Item Properties ) to easily take the code in the weapon ability and add it to the newly created weapon's item. When you code the weapon ability, say in the Condition Effect section, try to take into account that other code may be added before or after in the final magical weapon, if it has several abilities. For this reason, it is best to add to the ItemEffect string instead of replacing it, e.g.:
ItemEffect = ItemEffect & "+2 to attacks."
Similarly to the Weapon Ability code, this section will apply special effects for magical weapons. The 'It' item is the armor item being created, 'AbilIt' is the armor ability object that is being applied, and 'BaseIt' is the base armor with no effects applied at all. 'BaseIt' is a copy of the standard item - do not modify it as changes will not be saved. The 'Cr' creature object is NOT available.
By changing the script code of the item you can create more complex effects. You can use the It.AppendCode function (see Scripting – Item Properties ) to easily take the code in the armor ability and add it to the newly created armor item. When you code the armor ability, say in the Condition Effect section, try to take into account that other code may be added before or after in the final magical armor, if it has several abilities. For this reason, it is best to add to the ItemEffect string instead of replacing it, e.g.:
ItemEffect = ItemEffect & "+2 to attacks."
To change the armor data through scripting, you will need to the members of the item object It which start with "Armor_", such as Armor_Magic. See the item object, armor section for the full listing.
So, for example, this line:
It.Armor_MaxDex = 3
will change the armor's max dex bonus to AC to +3.
For a container, this script is called when something is moved in or out of the container. The ContentsWeight variable gives you the total weight of the contents (exluding the container and ignoring fixed-weight effects).
This can be used, for example, to give a warning message when the load inside an object is too great. Note that for now, this is not called if the quantity of an item changes, or if there is a change in the contents of a container that is inside this container.
This section is much the same as a feat's special code for Condition Effect (see Scripting for Feats ).
This code is called right after all the effects from all conditions, standard magical effects from items, and feats are totaled up. You can add to or change any bonus that comes from a condition. Only change variables that are recalculated in this step. This code is executed before the bonuses are applied throughout (for example, before calculating the total AC).
Set the 'ItemEffect' string to a description of the effect to give feedback to the user in windows like the Detailed AC Bonuses. (This is used like FeatSpecial is for feats).
This is called repeatedly when calculating the owner's attack bonus. The object 'cAtt' holds the attack being modified. Note that this is called for all attacks, not just one that may correspond to this item (if this item is a weapon). This means that if the bonus applies only to that particular item, you should check if the attack name corresponds to the item name. For example:
if (cAtt.Name = It.Name) then
cAtt.DamageBonus = cAtt.DamageBonus + 1
end if
Make sure you only modify values that are re-calculated each time. For example:
cAtt. WeaponDamageBonus = cAtt. WeaponDamageBonus + 1
will cause the weapon's damage bonus to grow uncontrollably, because WeaponDamageBonus is a persistent value for the attack.