Ko-FiPatreon

UPDATE: As of v1.3, VSUFramework functions and config files must include a modID. This will allow mods doing different things to not interfere with each other in the framework. You will need to rebuild the VSU database after updating.

This mod provides a framework to support transitions between related clothing items. Configuration files can define rules to link groups of items together, which allows mods using this framework to support easier customization. Users can create their own rules to link items from existing mods without using Creation Kit.

While one use case is for potentially lewd mods, there is plenty of capability for innocent purposes. For example, a mod could be made to transition armor or clothing to a damaged state after an amount of damage is taken (or item condition falls below a threshold, if combined with a durability framework). Additional configuration files would be able to add outfits to that system without requiring modification to the mod itself, letting end users add support for their own custom items without needing Creation Kit or xEdit.

After installing or removing a plugin that uses this framework, use the Mod Configuration Menu to rebuild the database, under "VSU Framework". The database should build automatically when VSU Framework is first installed (when the MCM menu is added), but it will need to be rebuilt if another mod using the framework is later installed or removed.

Requirements:
- PapyrusUtil: Hard requirement. This is necessary for the primary functionality of this framework.
- SkyUI: Hard requirement.

- Keyword Item Distributor (KID): While not required, this can be used to distribute the keywords for items in the different states. These keywords can be used for dialogue conditions, with the WornHasKeyword condition. If the mod using this framework does not require dialogue conditions, then this would not be necessary. Please include Keyword Item Distributor as a requirement for your mod if you need to use it, because users downloading this mod may not all need it.

Usage for users:
The database will need to be rebuilt whenever changes are made. This can be done in the Mod Configuration menu, under the "VSU Framework" mod page. Mod authors using this framework should include the necessary configuration files, but additional outfits can be customized fairly easily by adding new rules.

Usage for mod authors:
After a mod in this framework is loaded, the user will need to rebuild their database in the MCM. I do not recommend calling the RebuildDatabase function yourself, since a user may install multiple mods at once, and I can't guarantee that multiple calls to RebuildDatabase at the same time will work properly. Please instruct users to rebuild the database in the VSU Framework MCM after installing your mod.

Item grouping rules are defined in config files:
Place config files in the data/vsu/ folder, creating it if it doesn't exist. Config files must have file type .ini, and the file name should end with _VSU.ini e.g. data/vsu/plugin_VSU.ini

Each line in the configuration file defines a rule for a group of items. Line format is as follows:
ModID|State1FormID~Plugin|State2FormID~Plugin|State3FormID~Plugin|IsMaleRule|IsFemaleRule

Example rules:
VSU|0x875~Clothing.esp|0x877~Clothing.esp|0x879~Clothing.esp|1|0
VSU|0x875~Clothing.esp|0x881~Clothing.esp|0x883~Clothing.esp|0|1
VSU|0x885~Clothing.esp|0x887~Clothing.esp|0x889~Clothing.esp|1|1
VSU|0x801~Clothing.esp|0x803~Clothing.esp|NONE|0|1
VSU|0x801~Clothing.esp|NONE|0x805~Clothing.esp|1|0

A rule can also be written with only 2 states, if a third state is not desired, as demonstrated in the example rule. Simply write NONE in the undesired state's position. When changing clothing states, boolean parameters can be used to decide if items without a state, or items without a linked item for the new state should be unequipped.

The plugin file provides 3 keywords that can be associated with armor items using Keyword Item Distributor:
VSU_State1: 0x801~VSUFramework.esp
VSU_State2: 0x802~VSUFramework.esp
VSU_State3: 0x803~VSUFramework.esp

These states can be used to identify clothing states in dialogue conditions, with the WornHasKeyword condition. In order to use these keywords in your mod, you will need to add this mod's plugin as a master. To add an esp as a master in Creation Kit, it needs to be flagged as an esm. This can be done with xEdit/SSEEdit.

Here is an example of KID rules to distribute the keywords:
Keyword = VSU_State1|Armor|0x875~Clothing.esp
Keyword = VSU_State2|Armor|0x877~Clothing.esp
Keyword = VSU_State3|Armor|0x879~Clothing.esp


The VSUFramework script provides several global functions:
These functions can be used to get or set the clothing state for actors. Please see VSUFramework.psc for usage parameters and additional comments. Functions to change clothing state take boolean parameters to decide if they should remove items after they are replaced, if unrecognized items should be removed, or if items with a state but no item of the new state should be unequipped. This should provide ample functionality to handle various conditions for mods using this framework.

ModID parameter: This is a string parameter that you must include in your function calls to VSUFramework. This allows mods to share functionality, but also allows mods with different functionality to operate independently. For example, you might be using VSU Degradation for damaged versions of clothes, but you also want to make a mod that lets you pull up or down your hood. VSU Degradation uses the modID "DEG". You can write your scripts and VSU rules to use a different modID, so that the two mods can coexist without interfering with each other.

ActorChangeClothingState: Set the clothing state for items worn in all slots.
ActorForceChangeClothingState: Same as above but with an extra parameter to set equipitem's abPreventRemoval.
ActorChangeSlotClothingState: Set the clothing state for items worn in a specific slot.
ActorForceChangeSlotClothingState: Same as above but with an extra parameter to set equipitem's abPreventRemoval.
GetActorClothingState: Gets the highest clothing state from items worn in all slots.
GetActorSlotClothingState: Get the clothing state for items worn in a specific slot.
GetActorSlotHasClothingState: Returns true if the item in an actor's slot supports changing to a new state.

ActorChangeClothingState and ActorChangeSlotClothingState take some boolean parameters to determine some additional behaviour. Check the comments in VSUFramework.psc for more details:
- unequipUnknownItems: items without a known state will be unequipped. This means that items that are not registered with VSU will be unequipped.
- unequipUnreplacedItems: items without a corresponding item in the new state will be unequipped. This means that if an item is recognized, but no item is found for that slot in the new state, it will be unequipped.
- removeOldItems: items changed out of will be removed from inventory when they are replaced. This means that when an item is replaced, the old state's item will be removed from inventory. This can be used to prevent clutter, and for immersion. If this is true, it will also transfer enchantments, smithing improvements, and display names to the new item (as long as it shares the same slot). Display names will only transfer if the item is enchanted.
ActorForceChangeClothingState and ActorForceChangeSlotClothingState take all the above, and an extra boolean parameter:
- forceWornItem: Sets equipitem's abPreventRemoval to this value. Can be used to prevent NPCs from unequipping this item when their inventory is changed.
- equipDelay: When removeOldItems is true, there will be a delay before and after equipping items. This makes the transferring of enchantments and condition during combat much more reliable.

The MCM page script, VSUFrameworkMCM.psc , contains commented out sections to add MCM buttons to change the player's VSU state. This was used for debugging. It is very easy to set up yourself, but I will leave the comments in case anyone wants to see how that can be done.

Limitations
- Using PapyrusUtil's StorageUtil, each item has pointers to the other items in its group, so that they can be found when switching states. This means that an item cannot be a part of more than one rule group or state (i.e. the same base item cannot branch off to two different groups. If an item is part of multiple rules in configuration files, then the linked items will be overwritten by the last loaded rule). Different branches for male or female items are allowed, however, as long as the shared item(s) is (are) the same state in both the male and female rules (e.g. You might want to use a vanilla outfit as State 1 for a rule, but then switch to different items for male and female in the other states, if they come from different mods). Different branches are allowed for items in different modID groups. For example, if you use VSU Degradation, the rules use the modID "DEG", and contain damaged versions of vanilla armors and clothing. If you wish to create rules that can operate independently of the degradation system, you can create rules that use a different modID, and use that modID for your function calls. This way, you can have rules for different purposes that do not interfere with each other.
- If a clothing item is removed, the actor will lose the clothing state for that associated item. This can be an issue if you intend for the states of an item to be 1: Fully on, 2: Partially on, 3: Removed. There is a workaround for this, though. You can create a clothing item that simply consists of an empty mesh, then that item can be used for the third state. This should give the appearance of removing an item or replacing it, within this framework.
- Alternatively, you may wish for an item to be unchanged for certain states, for example 1: fully on, 2: fully on, 3: removed. The most comprehensive way to achieve this would be to create a duplicate item and use the duplicate for the second state.
- If you cannot create an .esp plugin to do this, there will be limitations to other approaches, but there is possible functionality: The ActorChangeClothingState and ActorChangeSlotClothingState functions take boolean parameters unequipUnknownItems, unequipUnreplacedItems, and removeOldItems. These can be used to create the desired logic. For example, when setting slot 52 (pelvis, or slot mask 0x00400000 I believe) to state 2, do not unequip unreplaced items. This will leave the state 1 item equipped when the other clothing occupies state 2. Do not list the same item twice in the rule. An item can only be referenced once, in one rule.
- Clothing items in different states could be worn at the same time if they occupy different Slots. The recommended practice is to take the highest worn state as the actor's current state.
- Enchantments and smithing improvements may transfer weirdly if there are duplicates of the base item in inventory. When an item is removed after replacement (removeOldItems is true), the enchantments and improvements are transferred to the newly equipped item. However, when the item is removed I can't be 100% sure it is the same item that was worn. It is possible that if an actor has 2 of a base item, and one is enchanted, then if the unenchanted one is changed an unenchanted replacement will be equipped, but then the enchanted one could be removed from inventory. As far as I can tell right now, there is no clear way to make sure it is the same item that was just equipped that is removed, so if there's a duplicate of the same base form it will just remove one of them. I might work on figuring this out more, but it is a relatively niche problem, and it shouldn't be an issue if you (or the NPC) are wearing the enchanted version.
- Similarly, if different states in an item group occupy different slots, there could be issues if removeOldItems is true. This is because removeOldItems also tells the script to transfer enchantments and improvements to the new item in the same slot. It is not recommended to make item groups with items that occupy different slots. It should still work (mostly), but for the best user experience, items should occupy the same slots.
- Custom names for items are transferred if the item is enchanted. This means if the item is enchanted, but the new state item has a different name, it will keep the enchanted item's name. For example, suppose an armor degradation mod has Leather Armor degrade to Ragged Leather Armor for the base item. If the player had an enchanted Leather Armor, then the display name will still be the same when it is replaced with an enchanted version of Ragged Leather Armor. This is intended behaviour, to support custom named items.
- Removing items from an NPC's inventory seems to reset their worn items. If this is running on NPCs for aesthetic purposes, set removeOldItems to false to prevent this from happening. This will mean that the NPC retains copies of the outfits they changed out of, but their worn items will not reset. They will not get more than one copy of each item in this way.

Sample Mod:
(sample mod has not yet been updated for v1.3, to include a modID. For updated examples, check the mods that require this mod: Wenches With a View, or VSU Degradation)
A sample mod making use of this framework is included as an optional file. This sample mod simply creates a rule using existing vanilla items (1: Leather Armor, 2: Forsworn Armor, 3: Roughspun Tunic), and whenever the player is hit (without blocking) increases the player's VSU state by 1 (to a maximum of 3). Additional rules can easily be created to support more item groups. The sample mod includes a Keyword Item Distributor file for the VSU keywords, however the mod itself does not use them. That is purely for demonstration purposes.

The sample mod shows how this framework could be used alongside a durability mod to have armor that visually reflects its condition.