Identification Hooks

Hook – “CanIdentify”

Search Order

1. The character

Context

1. Character

2. Item

Parameters

• Hook Parameter 4 contains the key of the item in the character's inventory.

• Hook Parameter 5 is empty but can be used to pass information to the “Identify” hook. See discussion.

When the player views a character's possessions ( ITEMS ), the menu item “ID ITEM” ( identify the item ) will be automatically displayed under certain circumstances. For example, a SHOP event can be configured to allow the character to “ID ITEM”. When this menu item is automatically displayed, no hook scripts will be executed. The item will be marked as identified if the player selects this option.

If the “ID ITEM” option is not automatically displayed, then this hook will be called each time the player highlights an unidentified item in the character's inventory. If the hook returns a value starting with 'Y' then the menu option “ID ITEM” will be displayed and hook parameter[5] will be saved to pass onto the “Identify” hook if the player selects “ID ITEM”.

Hook – “Identify”

This hook is called when a character 'Identifies' an item as a result of the 'CanIdentify' hook's returning a “Y”. It will not be called when “ID ITEM” is displayed automatically. It will only be called when the hook “CanIdentify” returns a “Y” for a particular item.

Search Order

1. The Character

Context

1. Character

2. Item

Parameters

• Hook Parameter 4 contains the key of the item in the character's inventory.

• Hook Parameter 5 is the value that the 'CanIdentify' hook set before returning “Y”.

Return Value

If the hook returns a value starting with 'Y' then the item will be marked as 'identified'. The hook might enforce some sort of probability of success, for example.

The $IsIdentified(actor, key, num)

• 'actor' is the character who possesses an item

• 'key' is the item number in the character's inventory.

• 'num' tells how the item's 'identified' status should be changed

1. num > 0: set the identified flag for 'what' items of the same type.

2. num < 0: clear the identified flag for '-what' items of the same type.

3. num = 0: change nothing. Return non-zero if the item is already identified.

When 'num' is non-zero, we attempt to change that many items. The first item changed is the item with the specified key and it counts as one item changed even if it is already set to the proper value and is therefore unchanged. Then we attempt to change identical items sequentially starting at key = 1 and, if they are not set to the proper value, we set set them to the proper value. Only those that are actually changed count against the specified number 'num'. So this function can change 'num' minus one items in addition to the item whose key is specified.

If 'num' is non-zero, the return value is the number of items actually changed (not the number of items examined). If 'num' is zero, the return value is the status of the one item whose key is specified.

A Bit of Discussion

These hooks (and the function “$IsIdentified (item, key, what)” were provided to allow a character to identify items by casting a spell. Here is an example of how it might work:

• An “Identify Liquids” spell is cast upon Pluto the Plutarch.

• The spell results in Pluto receiving a Special Ability named “Liquid Expert”.

• Pluto receives treasure, including a bottle of Jack Daniels whiskey but it is not yet identified and is listed simply as “Bottle of Brown Liquid”. The “Bottle of Brown Liquid” has a special ability named “is_Liquid”.

• The player examines Pluto's items and highlights the “Bottle of Brown Liquid”.

• The Special Ability 'Liquid Expert”, which the spell attached to Pluto, has a script named “CanIdentify”. We run the script.

• The script examines the “Bottle of Brown Liquid”, sees that it has the Special Ability named “is_Liquid”, and returns the value “Yes”.

• The Menu option “ID ITEM” appears and the player selects it.

• The Special Ability 'Liquid Expert”, which the spell attached to Pluto, has a script named “CanIdentify”. We run the script.

• The script deletes the Special Ability “Liquid Expert” from Pluto ( so that he gets only one identify opportunity per spell....you could set the Special Ability's parameter to some number when the spell is cast and decrement it here) and returns “Yes”.

• Suddenly the “Bottle of Brown Liquid” becomes “80 Proof Tennessee Nectar”.