SKIN_SupportGetSkin(object)

Retrieves a creature's skin item or creates a new one and forces an equip if the creature does not already have one.

object SKIN_SupportGetSkin(
    object oCreature
);

Parameters

oCreature

The creature whose skin item is to be retrieved.

Description

Retrieves a creature's skin item or creates a new one and forces an equip if the creature does not already have one.

Remarks

It is important to realize that this function was designed as an internal function intended for use exclusively by the other functions in the x3_inc_skin library and from various other places in the Bioware default v1.69 horse system scripts. It is therefore a special purpose function not a general purpose one so its use should be avoided.

Returns the skin item used by the creature specified in the oCreature parameter. If oCreature refers to an NPC, the NPC object itself is returned rather than its skin item.

When called on a PC, the function first looks for a local object variable on the PC under the name "oX3_Skin". If found, the function returns that object. If the local object variable does not refer to a valid item, the function looks for a valid item in the PC's creature armor slot. If one is found, the "oX3_Skin" variable is set to point to it and that skin item is returned.

Should no valid skin item be found either in the local variable or in the PC's creature armor slot, it searches through the PC's inventory for an item with the TAG "x3_it_pchide". If found there, the PC is forced to equip the skin found via a call to the SKIN_SupportEquipSkin function, the local object variable "oX3_Skin" is set on the PC to point to it, the skin's droppable flag is set to FALSE, and the function returns the skin found.

If the PC is not carrying or wearing a valid skin item, a new one is created for him from the standard Bioware "x3_it_pchide" blueprint. The local object variable "oX3_Skin" is then set on the PC to point to the newly created skin, the PC is forced to equip the new skin via a call to the SKIN_SupportEquipSkin function, and its droppable flag is set to FALSE.

Note that this function will always return a valid skin item since it creates a new one when it cannot find one. The only reason it will ever return an invalid object is if the PC has no skin and the new one could not be created, which should be impossible since the "x3_it_pchide" blueprint is a standard Bioware blueprint.

The local object variable "oX3_Skin" is initialized and maintained by the default Bioware scripts automatically and should not be changed externally in a custom script.

Because of the special treatment of items whose TAG is set to "x3_it_pchide", it is important to not create items with that TAG that are not skin items. It is also important to ensure creatures will never possess more than one item with the TAG "x3_it_pchide".

Known Bugs

The function does not check to see if any existing skin item found either in the local object variable or by searching the PC's inventory is actually a skin type item. Should the item found be valid but not a skin type item, the function will still treat is as such. It will store it in the local object variable on the PC and will command the PC to equip that item into its creature armor slot anyway. Since the equip action will fail in this case every time, this can cause bugs and will also waste time trying to make the PC do something he is incapable of.

As long as all skin handling is left up to the Bioware default scripts to maintain and no custom blueprints are created that use the RESREF "x3_it_pchide", then this should not be an issue. But if the builder writes custom skin item processing into his scripts he must ensure that the item is a skin type item, and he should always use the SKIN_SupportEquipSkin function instead of ActionEquipItem to equip it. The safest way to use a skin for PCs in a NWN v1.69 environment is to use this function to get, and if necessary create and equip the skin, then perform any custom scripting on the object returned.

Requirements

#include "x3_inc_skin"

Version

1.69

Example


// This example ActionTaken script is used to give players a permanent persistent
// Alertness bonus feat by adding it to his skin during a conversation. Should the   
// PC not already have a skin, a new one will be created, the bonus feat will be
// added to it, and the player will be forced to equip the new skin.


// ActionTaken script - give a permanent persistent Alertness bonus feat to players.
#include "x2_inc_itemprop" 
#include "x3_inc_skin"


void main()
{
    // First find the player who is talking.
    object oPC = GetPCSpeaker();

    // If the PC could not be determined, do nothing.
    if(!GetIsObjectValid(oPC))
    {   return;   }

    // Next, retrieve the PC's skin item creating a new one if necessary and
    // ensuring he will be forced to equip the skin if it isn't already equipped.
    object oSkin = SKIN_SupportGetSkin(oPC);

    // If the skin item could not be found or created for some reason, return
    // without doing anything further. This should never happen anyway.
    if(!GetIsObjectValid(oSkin))
    {   return;   }

    // Create the bonus Alertness feat itemproperty and add it to the skin item.
    itemproperty ipAlertnessBonus = ItemPropertyBonusFeat(IP_CONST_FEAT_ALERTNESS);
    IPSafeAddItemProperty(oSkin, ipAlertnessBonus);
}

functions:	ActionEquipItem \| ActionUnequipItem \| GetItemInSlot \| SKIN_SupportEquipSkin
categories:	Inventory Functions