SetSkinFloat(object, string, float)

Stores a persistent floating point variable on a creature's skin item.

void SetSkinFloat(
    object oCreature,
    string sVariableName,
    float fValue
);

Parameters

oCreature

The creature object whose skin will have the variable stored on it.

sVariableName

The variable name used to identify the variable placed on the skin.

fValue

The value assigned to the variable.

Description

Stores a floating point variable on a creature's skin item set to a specified value. These variables are persistent when applied to a PC and travel with the character when exported.

Remarks

The variable name specified in sVariableName will be stripped of all underscore characters. Thus, a variable name specified as "My_Custom_Variable" will actually be stored under the name "MyCustomVariable".

If the object specified by oCreature is an NPC, the variable is stored on the creature itself rather than its skin. If used on an NPC who possesses an item with the TAG "x3_it_pchide", that item will be destroyed.

If used on a PC, the variable is stored on the skin item equipped in the PC's creature armor slot.

If used on a PC who has no item equipped in the creature armor slot, the PC is searched for an item with the TAG "x3_it_pchide". If one is found, the variable is stored on that item and the PC is forced to try and equip it into its creature armor slot. Should the item found be one that is not equippable in the creature armor slot, the equip action will fail but the variable will still be stored on the item found.

If used on a PC who has no item equipped in the creature armor slot and also does not possess an item with the TAG "x3_it_pchide", a new skin item is created from the standard blueprint "x3_it_pchide" and added to the PC's inventory. The variable is stored on the new skin, and the PC is forced to equip the new skin in the creature armor slot.

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

Although not technically a bug per se, a PC that has no skin equipped who is carrying an item with the TAG "x3_it_pchide" will be commanded to equip that item into the creature armor slot even when the item is not a skin. This does not cause a bug, but it does waste time trying to make the PC do something he is incapable of.

Should this function be used on a PC who has no skin equipped and is carrying more than one item with the TAG "x3_it_pchide", there's no telling which of the items will get the variable stored on it.

Due to the fact that the variable name is stripped of all underscores, it is not possible to use this function (or GetSkinFloat either) to treat two skin variables whose names differ only by underscores as independent separate variables. In other words, if you use a skin variable called "My_Custom_Variable" you cannot have a different skin variable called "MyCustomVariable" since this function (and GetSkinFloat as well) will treat them both as the same variable. The easiest way to avoid any potential problems related to this issue is to simply not put any underscores into your skin variable names.

Requirements

#include "x3_inc_skin"

Version

1.69

Example

// In this example players are given a "Rod of the Wise" item that uses the tag-based
// item scripting system to customize its Unique Power (Self-Only) behavior. They can
// use it once per day to gain a temporary +1 wisdom bonus. The duration of the bonus
// increases as the player levels up, and the bonus cannot be dispelled.
// This is accomplished by modifying the module's OnPlayerLevelUp script to store a
// persistent floating point duration value onto the player's skin every time he
// levels. The rod's tag-based item script is employed to apply the temporary wisdom
// bonus for a duration that matches the current duration value found on the player's
// skin at the time the rod is activated.

// OnPlayerLevelUp script
#include "x3_inc_skin"

void main()
{
    // Find the player who is leveling up.
    object oPC = GetPCLevellingUp();

    // If the leveling PC could not be determined, return.
    if(!GetIsPC(oPC))
    {   return;   }

    // Determine his level.
    int iPCLevel = GetHitDice(oPC);

    // Save the wisdom bonus duration for the Rod of the Wise item in a floating point
    // skin variable based on the player's level
    if((iPCLevel >= 1) && (iPCLevel <= 8))
    {   SetSkinFloat(oPC, "Rod of the Wise Duration", 67.5);   }

    else if((iPCLevel >= 9) && (iPCLevel <= 18))
    {   SetSkinFloat(oPC, "Rod of the Wise Duration", 115.0);   }

    else if((iPCLevel >= 19) && (iPCLevel <= 29))
    {   SetSkinFloat(oPC, "Rod of the Wise Duration", 175.5);  }

    else if((iPCLevel >= 30) && (iPCLevel <= 37))
    {   SetSkinFloat(oPC, "Rod of the Wise Duration", 230.0);  }

    else
    {   SetSkinFloat(oPC, "Rod of the Wise Duration", 325.5);   }

    // Perform the default OnPlayerLevelUp behavior.
    ExecuteScript("nw_o0_levelup", OBJECT_SELF);
}

// Rod of the Wise tag-based item script
#include "x2_inc_switches"
#include "x3_inc_skin"

void main()
{
    // Tell the game engine that the tag-based event has not yet been handled.
    SetExecutedScriptReturnValue(X2_EXECUTE_SCRIPT_CONTINUE);

    // If the script is not running due to an activation event, return.
    if(GetUserDefinedItemEventNumber() != X2_ITEM_EVENT_ACTIVATE)
    {   return;   }

    // Find the player who is activating the item.
    object oPC = GetItemActivator();

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

    // Retrieve his wisdom bonus duration from the player's skin variable.
    float fWisDuration = GetSkinFloat(oPC, "Rod of the Wise Duration");

    // If the duration found on the player's skin is greater than 0.0 seconds,
    // apply the wisdom bonus.
    if(fWisDuration > 0.0)
    {
        // Create a +1 wisdom bonus effect.
        effect eWisBonus = EffectAbilityIncrease(ABILITY_WISDOM, 1);

        // Turn the effect into one that cannot be dispelled.
        eWisBonus = ExtraordinaryEffect(eWisBonus);

        // Apply the effect to the PC for the duration found on the player's skin.
        ApplyEffectToObject(DURATION_TYPE_TEMPORARY, eWisBonus, oPC, fWisDuration);
    }

    // Tell the game engine that the activate event has been handled.
    SetExecutedScriptReturnValue(X2_EXECUTE_SCRIPT_END);
}

See Also