SKIN_SupportEquipSkin(object, int)

Forces a creature to equip a skin item in its creature armor inventory slot.

void SKIN_SupportEquipSkin(
    object oSkin,
    int nCount = 0
);

Parameters

oSkin

The skin item to be equipped.

nCount

The count subtracted from the maximum number of attempts made (29) to ensure the skin is equipped. Must always be in the 0-28 range. Default value is 0 meaning 29 maximum attempts will be made.

Description

Forces a creature to equip a skin item in its creature armor inventory slot. If the creature is busy the equip command is reissued until either too many attempts have been made or the creature successfully equips the skin.

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.

Used to ensure a creature will equip a skin item (force it). If the creature is unable to equip the skin within 2/10ths of a second, the command is reissued. By default the command will reissue 29 times before giving up.

The creature affected will be OBJECT_SELF. Therefore if this function is to be used from a script not attached to an event on the creature who is supposed to be equipping the skin, the AssignCommand function must be used in conjunction with it to force the correct creature to perform the action. Calling it without using AssignCommand from any script not attached to, or called from, a creature object event will have no effect.

The function assumes that the creature already possesses the item specified in oSkin before the function is called. If this is not the case, the equip command will always fail and so it will always be reissued the maximum number of times.

The value specified in nCount can be used to control how many times the equip command will reissue. It must be in the range 0-28. The value entered is subtracted from 29 to get the maximum attempts tried. So if you use 9, the command will reissue a maximum of 29-9 or 20 times. If you decide to make use of this internal function, best practice would be to leave the nCount variable at its default value of 0 every time you call it.

If called for a creature that is currently resting, or if the creature starts a rest cycle before he is able to equip the skin but prior to his reaching the maximum retry count, the function pauses until the rest cycle is complete before resuming the reissuing of equip actions.

If the creature is already wearing a skin item and a different item is specified in oSkin, the item specified in oSkin will be destroyed and no equip actions will be issued. If the parameter oSkin refers to the skin currently equipped in the creature's armor slot, the function does nothing. If the creature is unable to equip the skin within the maximum number of retries, the item specified in oSkin will not be destroyed.

Known Bugs

Although not technically a bug per se, the function does not check to see if the item specified in oSkin is actually a skin type item or even if it is a valid item at all. Yet the creature will be commanded to equip that item into the creature armor slot anyway. Since the equip action will fail in this case every time, the action to equip the item will always be reissued the maximum number of times. This does not cause a bug, but it does waste time trying to make the creature do something he is incapable of.

Requirements

#include "x3_inc_skin"

Version

1.69

Example


// This example OnEnter script ensures all entering creatures
// (PC or NPC) will be given a new skin if they do not already
// have one. It would work if called from an area OnEnter, trigger
// OnEnter, or encounter OnEnter. It must not be used in the
// module's OnClientEnter script or in the x3_mod_pre_enter
// OnClientEnter hook script in a NWN v1.69 environment or it will
// interfere with the Bioware v1.69 horse system.


// OnEnter script - ensure everybody has a skin equipped.
#include "x3_inc_skin"


void main()
{
    // First find the creature who is entering.
    object oCreature = GetEnteringObject();

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

    // Next, create a new skin item in the creature's inventory.
    object oSkin = CreateItemOnObject("x3_it_pchide", oCreature);

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

    // Force the creature to equip the skin.
    AssignCommand(oCreature, SKIN_SupportEquipSkin(oSkin));
}

functions:	ActionEquipItem \| ActionUnequipItem \| GetItemInSlot \| SKIN_SupportGetSkin
categories:	Action on Object \| Inventory Functions