The character controller is seamlessly integrated with the Ultimate Inventory System allowing you to use the Ultimate Inventory System inventory rather than the inventory included with the character controller. The integration includes many additional scripts and functionality which are responsible for the communication between the two assets. The main ones are the Character Inventory Bridge and the Inventory Item Set Manager. This integration can be downloaded from one of the pages listed below.

Current Version 2.0.7, compatible with the Character Controller version 2.4.4-2.4.6 and the Inventory System version 1.2.4-1.2.7. Always use the latest version of each asset for the best compatibility.

A great way to get familiar with the integration is by playing around in the integration demo scene which can be found in the
Assets\Opsive\UltimateCharacterController\Integrations\UltimateInventorySystem\Demo folder.

Integration Download

Ultimate Character Controller
First Person Controller
Third Person Controller
UFPS: Ultimate First Person Shooter
UTPS: Ultimate Third Person Shooter
UFPM: Ultimate First Person Melee
UFPM: Ultimate Third Person Melee


The videos are a great starting point. Once you go through them to get a good idea of how the system works it is recommended to read through the documentation to learn more.
The Integration Videos come in two parts: Part 1 Setting up the Character & Item and Part 2 Setting up the UI

You may want to go through some of the other video tutorials specific to the Character and Inventory systems too.
Some of the videos you may interested in are

  1. Character: First/Third Person Character Creation
  2. Character: First/Third Person Item Creation
  3. Character: Runtime Item Pickup
  4. Character: XXXX Weapon/Item Setup (Keep in mind that you should create Item Prefabs, so do not follow things to the letter)
  5. Character: State System
  6. Inventory: Basic Concepts
  7. Inventory: Getting Started With The Ultimate Inventory System
  8. Inventory: Creating a Database and Attributes
  9. Inventory: Inventory Component and Item Collections
  10. Inventory: UI Designer Overview
  11. Inventory Item View Slot Containers
  12. Inventory: Customizing UI
  13. Inventory: Item Actions

Videos just show the tip of the iceberg. It is highly recommended to read the documentation to get all the information required to use the systems to their full potential

Getting Started

It is highly recommended to fully read through the documentation below once, before following the steps below, as it gives more context.

It is important that the Ultimate Inventory System and the Character controller are updated to the latest version. Check the version of our assets in the bottom left of our editor windows. Do NOT trust the package manager version, the Unity Package Manager doesn’t always import the most recent update after you download the asset. Ensure you are getting the latest by removing the package cache from the Asset Store download folder.

You may check the required versions for both packages in the Integration window (inside the inventory system editor).

Do not forget that the Character Controller package must be installed after it has been imported. Learn more about the Character Controller installer here


  • Inventory Item: An item defined in the scope of the Inventory system. It is a simple object that is used to store attribute values.
  • Character Item: An item defined in the scope of the Character Controller. It is a component on a GameObject which define how the object should be animation, used, etc…
  • Equippable: an Item that can be equipped using the character controller.
  • Equippable Collections: one or multiple Item Collections that store items that the character can switch between using the character controller.
  • Item Set: a set of items the the character holds at any one time. They are managed by the Item Set Manager.
  • Item Set Rule: An object that will define what item Set will be created depending on the items equipped.
  • Item Slot Set: An object that can be used on an Item Slot Collection to define what items can be “soft equipped” on the character.
  • Soft Equipped: When an item is equipped on the character but is not active (for example when a character has his weapon holstered on their belt or back)
  • Active Equipped: An Item that the character physically holds and can be used.
  • Item Set Slot: The slot within an Item Set managed by the Item Set Manager. Also known as “SlotID” in the character system scope.
  • Equippable Slot: The slot within an Item Slot Collection which uses an Item Slot Set and that was set as an Equippable Item Collection.


The integration is used to communicate between the character and the inventory system. Therefore it is important to understand the parts of both system that overlap where the integration is mostly used.

Any item which the character can hold and use with the character controller will need to be “Equippable” and follow the integration requirements. This includes items such as Weapons, Body, Tools, etc. Any of the other items should not be “Equippable”. This includes Ammo, Materials, Armor, etc.

In some cases the items can be in a grey area. For example Armor or Magic, should they be “Equippable” character Items or not?
In most cases armor is not a usable Item and therefore does not need to be a character item. Instead it can be equipped using the Equipper solution from the Inventory system. If that is the case make sure that the armor does not inherit the “Equippable” category which should only be used by inventory items with character items. For Magic it really depends on the use case, but either way could make sense. It mostly depends which workflow you prefer building on: Inventory Item Actions or Character Item Actions.

Most of the UI related to items should be controlled by the Inventory System, although the Character UI can be used to display the equipped items and the ammo amount. The items are organized in Item Collection within the Inventory System Inventory. On a high level these are the required Item Collections.

  • Default: the main item collection can be considered as the characters bag, it contains all the items the character owns expect the equipped items.
  • Ammo (multiple): The ammo Item Collections are any collection that may contain an ammo item which can be used to fill an item on reload.
  • Equippable (multiple): The Equippable Item Collections holds the inventory items which are on the character and can be equipped at any time by switching Item Set. Multiple Equippable Item Collections can be used. A good example for it is having a an ItemSlotCollection for a primary and secondary weapon, while having another Item Collection for the Body item that is always equipped and cannot be removed.
  • Loadout (multiple/optional): Items that do not change even when the save data is loaded and can be added to other Item Collections, using an Item Collection of type “Character Loadout Item Collection”, or to the Default Item Collection otherwise.

Whenever an item is added to or removed from one of the Equippable Item Collections the Item Sets in the Inventory Item Set Manager are recomputed using the Item Set Rules to match set of  items in the Equippable Item Collections. This allows great flexibility and scalability with Item Sets. No need to define all possible item combinations or even add ItemSets on Item Pickups anymore (although it is still allowed if required).

When an inventory item is removed from the Equippable Item Collection it can only be reused by that same character. Any property values (example DamageAmount) on the character item that you wish to save or carry over to another character Item must be bound to an attribute on the inventory item. This can be done using the Item Binding component or with custom components, like the ShootableWeaponAmmoBinding used to bind ammo definition, clip size and remaining amount.

Setup scene

  1. Install both packages and the integration from above.
  2. Using the Inventory Manager, create a new Inventory database that follows the requirements defined below (or simply duplicate the EmptyCharacterInventoryDatabase).
  3. Create a new scene, use the Inventory and Character Manager to setup the scene with the required manager components.

Setup character

  1. Create an Opsive Character using the Character Manager (skip this step if you already have a character set up).
  2. Open the Integrations Manager from Tools -> Opsive -> Ultimate Inventory System -> Integrations Manager. Select the Integration Inspectors tab.
  3. Drag your character into the Character field under Character Setup. The character must be in the scene and must first be setup with the Character Manager. Select Setup Character.
  4. The step above automatically creates and assigns an Item Set Rule Object and an Item Slot Set. These can be found in the folder where the Inventory Database was saved. Refer to the documentation below to learn more about those and customize them to your liking.
  5. Ensure the Character Inventory Bridge component references the Equippable and Ammo Item categories. Ensure it also references the correct Item Collections and a Inventory Item Pickup Prefab. Learn more about the item collections and pickups below.
  6. The character is now setup, you may start creating Items.

Setup Item

  1. Using the Inventory Manager Editor, create a new Item Definition for the item that you’d like to add. Ensure that it inherits from the Equippable Item Category and from either the Single Item or Multi (or equivalent) Item category.
  2. Using the Character Manager Editor, create your Item prefab using the Runtime Item Pickup steps. Item Types from the Ultimate Character Controller do not need to be created as you should instead use the Item Definitions.
  3. Using the Integration Manager Editor, select the Item prefab(s) you created and bind them to your Item Definition. This ensures that the Item Definition references the prefab(s) within an attribute and vice versa. It also adds some components to the character item prefab.
    Some extra options are available for character items with the Shootable Weapon component, allowing to bind ammo data between the inventory and character item at runtime.

  4. Ensure the character Item prefab is now setup correctly, if you are using Item Set Rules to create the Item Set ensure the “Unique Item Set” field on the Item prefab is toggled off.
  5. Make good use of Object Identifiers to find references to objects (transforms, colliders, etc…) on the character once the item is spawned at runtime.
  6. On the Character Item Prefab use the Item Binding or custom components (like the Shootable Weapon Ammo Binding) to bind your Inventory Item Attribute values to properties on your item. Example “DamageAmount”.

Converting Existing Ultimate Character Controller Items

If you have an existing project using the character controller and wish to convert the items on your character to work with the Ultimate Inventory System you must follow the steps below. Character Items which are already prefabs set to work with the Runtime pickup can go straight to the steps defined in the Setup Item section above.

  1. Create a new character Item prefab using the steps from the runtime pickup section. The bottom Object Identifier section is especially useful for specifying the locations of GameObjects that exist on the character.
  2. Copy the Item and ItemAction components (Shootable Weapon, Melee Weapon, Throwable Item, Magic Item) from your existing item to the new item prefab that was just created.
  3. Delete the item from your character using the Item Manager.

Once you have the character item prefab use the steps defined in the Setup Item section above.

Setup Item Set Rules

Setting up your item set rules is important to decide how Item Sets will be created at runtime. Item Sets are the combination of items that can be equipped by the character, Example Sword+Shield: Sword in the right hand (slot 0) and Shield in the left hand (slot 1).

  1. Go to the Inventory Item Set Manager inspector
  2. Set the “Slot Count” to the number of Slots the character can equip simultaneously. This number must match the number of “Item Slot” component inside the characters Rig. The “Item Slot” component has an ID which must be unique, it’s location within the rig will define where the item will be spawned when equipped. By default Item Slot ID 0 is used for the right hand and ID 1 is used for the left hand. You may have more slots if you wish. In the demo scene we use a thrid slot, Slot ID 2 for magic items which can be cast simultaneously to having an item equipped in both hands.
  3. Define your Item Set Rule Categories. These are groups of Item Set Rules that will create Item Sets at runtime. Only one Item Set within an Item Set Category can be active at a time. Having multiple Item Set Categories allows you to combine multiple active item sets toghether. For example having an Equippable Item Set Rule Category for your weapons (sword, shield, Bow, etc…) and having another Item Set Rule Category for Magic Items can allow you to equip any combination of Item Sets within the Equippable Category with any Item Set within the Magic Item Set Rule Category. So Instead of creating all the possible combination of Sword+NaN+NaN, Sword+NaN+Magic, Sword+Shield+NaN, Sword+Shield+Magic, NaN+Bow+Nan, NaN+Bow+Magic etc.. You may simply have Sword+NaN+NaN, Sword+Shield+NaN, NaN+Bow+NaN in one category and NaN+NaN+Magic in the other one. Depending on the amount of ItemSet Rules you will require, this can save you a great amount of repetitive setup.
  4. Create Your Item Set Rules in a was that is restrictive enough. Think of your Item Set Rules as the types of items that can be equipped toghether and or act differently. For example Melee Weapon, or Melee Weapon + Shield, or Bow. Even though Melee Weapon and Bow are just one Item, they act very differently, therefore they should have their own ItemSet with a specific State name. The Item Set Rule State name is  very important to change the state of the player depending on the equipped Item Set. For example the Bow uses the state system extensively, here is a forum post on how to setup a bow using the integration. To learn more about the State System and preset go here.
  5. Learn more about the Inventory Item Set Manager and Item Set Rules below and check the integration demo scene to see an example of how to setup your Item Set Rules.
Create Bow Item Steps
  1. Follow the generic “Setup Item” steps above
  2. Make sure to follow the video tutorial on how to setup a Bow Item
  3. Don’t forget to use an ObjectIdentifier component to define the position where the character will hold the arrow (check the demo scene for further assistance.)
  4. Add an Item Set Rule that uses the Bow in slot 1 (slot 1 is the left hand by default). Make sure there aren’t other ItemSet Rules which could be adding the Bow in the wrong slot
  5. In the Bow Item Set Rule set the “State” name to “Bow”. The state name is used in a lot of places to change the character when the character holds the Bow.
  6. In the character Item Abilities find the “Use(Slot 0)” and “Use(Slot 1)” Ability, and assign a new state for “Bow” -> “BowUseSlot<0/1>” accordingly. This ensures that pressing the attack button (left click) uses the left hand item (Bow) and not the right hand item.
  7. Refer to the Bow Item prefab within the integration Folder for further assisance.
Create Body Item Steps

The body item is often used as the default item that is equipped when not other items are equipped. Step 1-4 are to create the item, step 5-7 are to make it the default item.

  1. Follow the generic “Setup Item” steps above. Make sure to that the body prefab item has the “First/Third Person Perspective Item” & “First/Third Person Melee Weapon Properties”
  2. Set the Animator Audio states within the Melee Weapon. And make sure your Animation Events are setup correctly or instead you may choose to not wait for animation events
  3. Of course the Body Item is added at runtime, therefore to reference the colliders on the character you must use ObjectIdentifiers. In the “First/Third Person Melee Weapon Properties” you may define a list of colliders. Clicking on an element in that list will allow you to define the Collider Object ID. When the Item spawns the system will search for Object Identifier components with those IDs on the character to fetch references to the colliders.
  4. Create an Item Set Rule for your Body Item and make sure it has state name “Body”.
  5. The Item Set Rule should have “Default” and “Enabled” set to True and “Can Switch To” set to False if you wish to make it your default item when nothing is equipped.
  6. To allways have the Body Item equipped create a new Item Collection called “Equippable” and renamed your weapon equipment item collection to “Equippable Slots”. “Equippable Slots” will be of type ItemSlotCollection and have purpose set to Equipment or None (aka Other). “Equippable” would normally have type ItemCollection and purpose set to None.
  7. Assign “Equippable” and “Equippable Slots” as Equippable ItemCollections within the Character Inventory Bridge component under the “Equippable Item Collection Names” field. Doing so will allow the bridge to monitor both item collections and equip item accordingly.
  8. Refer to the Body Item prefab within the integration Folder for further assisance.

Common Errors

Here are some common errors that users have reported and how to fix them.

Error when updating the Ultimate Inventory System

This error happens when updating the integration, if  both the character controller and the inventory system were removed before they are re-imported. If the Ultimate Inventory System is re-imported before the Character Controller then this error will appear.

Simply install the Character Controller using the installer to fix the error.

Equip Unequip Ability has a Category with ID 3636…. that cannot be found

This errors happens if you setup a new character with built-in abilities preconfigured from the Character Controller Demo.

The easiest way to fix it is to go through each Equip/Unequip Ability, within the Character Locomotion script under Item Abilities, and re-selecting the item set category to force the category ID to be serialized.

Null Reference Exception within Item Action Awake

This error can happen when an the main item prefab with all the Ultimate Character Controller scripts (Item, First/Third Person Perspective, Melee/Shootable Weapon, etc…) is spawned outside the player. This can often happen if the Item prefab was mistakenly set as the “DropPrefab” instead of a simple model without any scripts.

Item Action in this case is refering to the Ultimate Character Controller Item Action (Melee Weapon, Shootable Weapon, etc…) and not to the Ultimate Inventory System Item Action which is used in the UI in most cases.

Duplicate ID ‘1’ found

This warning happens if Character Setup is used to create multiple characters. The Character setup will create a Character with an Inventory Identifier, since it is extremely useful for the main player character. The Inventory Identifier must have a unique ID set in the inspector.

There are two options to fix this warning:

  1. On the Inventory Identifier change the ID and make sure it is Unique
  2. Remove the Inventory Identifier component

For enemy character prefab the Inventory component must be removed, otherwise the warning will appear each time a new enemy is spawned.

Inventory Database

The integration includes two databases: IntegrationDemoInventorySystem and EmptyCharacterInventoryDatabase. The IntegrationDemoInventorySystem database is used within the Ultimate Character Controller demo scene. To get started within a fresh database you can use the EmptyCharacterInventoryDatabase which contains the minimum for the Ultimate Character Controller integration. This database can be duplicated from the Ultimate Inventory System’s Setup Manager:

It is also possible to create your own database from scratch or edit an existing Database to be compatible with the Integration.


  • A parent category for all your Character Items, usually called “Equippable”:
    • Equippable: The Equippable category specifies the items that can be equipped, such as an assault rifle or a sword. While this high level category is required, the Ultimate Inventory System allows you to nest categories so you can have any category structure beneath this.
  • A parent category for all your Ammo (also known as Consumable for the Character controllers), usually called “Ammo”:
    • Ammo: The Ammo category specifies the objects that can be “consumed” by items, such as assault rifle bullets or mana.
  • All “Equippable” Item Definition must have an Attribute of type “GameObject” or “GameObject[]”, usually called “Prefab” and “Prefabs” respectively. It is recommended to create a “Single Item” and “Multi Item” or “Single Equippable” and “Multi Equippable” category which have those attributes respectively. Then any child category, can use use either one.
    • Multi Item: the Multi Item category is an optional category which specifies that the same item can be equipped in multiple item set slots. Examples include dual pistols or the grenade which can be equipped in the left or right hand. Any item which satisfies this requirement must inherit the Multi Item category. Items which can be dual wielded but are not of the same item type, such as a sword and shield, do not need to be parented to the Multi Item category.
    • Prefab: A GameObject which is used by items which are in the Single Item category. This attribute specifies the prefab that should be spawned. This prefab should be a runtime pickup prefab.
    • Prefabs: A GameObject[] which is used by items which are in the Multi Item category. This attribute specifies the set of prefabs that should be spawned. The array order does not matter, the item set slots used are defined on the prefabs.


  • It is recommended to use a category example “Shootable” that has a “AmmoData” Item Attribute which can be used to bind the character “ShootableWeapon” consumable item amount and clip size to data stored on the Inventory Item itself. A “ShootableWeaponAmmoBinding” component is required to bind the attribute to the “ShootableWeapon” properties.
    • AmmoData: A AmmoData which is used store the Ammo ItemDefinition, the clip size and the remaining clip amount. It must be set as a Item Attribute to be updated at runtime as the weapon is used.
    • If the AmmoData type does not show up in the type drop down within the Attribute Editor, that means it is not part of your Unit Options. Learn more about Attributes and Unit Options here 
  • Add categories with Item or ItemDefinition attributes which can be used to bind with character Item Action component properties. Some good examples are “DamageAmount”, “ImpactForceFrames”, “ImpactForce”, etc…
  • Add categories specific to equipment slots in an ItemSlotSet (example “Primary”, “Secondary”, “HeadGear”, etc…)
  • Add categories for the item sets. These are categories used to define what items can be combined together on the character. (example “One Hand Blade”, “Shield”, “Two Hand Gun”, “Multi Wield Gun”, etc…)
  • Use the category multiple parents to your advantage. Simply mix and match the categories you need. (example “Multi Wield Gun” could inherit from “Equippable”, “Primary”, “Secondary”, “Shootable”, “Multi Item”, “Gun”, etc…)
  • ItemDefinitions can inherit from other ItemDefinitions take advantage of that feature to create a lot of items which are slightly similar.
  • Read more about Attributes and the Database in the Inventory System documentation.

Character Inventory Bridge

The character Inventory Bridge derives from the Character Controller Inventory Base script, it communicates with the Inventory System Inventory to make a smooth integration between both tools.

  • Equippable Category: The Equippable category specifies the items that can be equipped, such as an assault rifle or a sword. While this high level category is required, the Ultimate Inventory System allows you to nest categories so you can have any category structure beneath this.
  • Ammo Category: The Ammo category specifies the objects that can be “consumed” by items, such as assault rifle bullets or mana.
  • Single Item Prefab Attribute Name: The attribute name of the GameObject attribute which specifies the prefab that should be spawned. This prefab should be a runtime pickup prefab.
  • Multi Item Prefabs Attribute Name: The attribute name of the GameObjects attribute which specifies the prefabs that should be spawned for mutli items. Those prefab should be a runtime pickup prefab.
  • Default Item Collection Name: The main item collection with all non-equippable the items.
  • Ammo Item Collection Names: A list of item collections containing ammo, these will usually include the main item collection but may also include other collections.
  • Equippable Item Collection Names: A list of equippable item collections which are used to store all items which can be equipped or are equipped by the Character Controller.
  • Loadout Item Collection Names: The loadout Item Collections are loaded on start. If the loadout Item Collection are of type “Character Loadout Item Collection” they will be loaded by the collection otherwise the item will be added to the main item collection.
  • Drop Using Character Item When Possible: If true the when dropping a Character Item, the drop prefab will be used from the Character Item instance Drop Prefab. If not, the generic “Inventory Item Pickup Prefab” will be used.
  • Inventory Item Pickup Prefab: The prefab used to drop all items, except Character Items if the “Drop Using Character Item When Possible” field above is toggle on, when the Drop function is called on the Character Inventory Bridge script.
  • Item Drop Position Offset: The offset from the character position to spawn the item drop.


The Character Inventory Bridge has a lot of useful functions used to get the items you want, equip them, etc…

// Get the Inventory system Inventory from anywhere using the manager.
var inventory = InventorySystemManager.GetInventoryIdentifier(1).Inventory;
// Get the character Inventory Bridge from the Inventory.
var characterInventoryBridge = inventory.gameObject.GetCachedComponent<CharacterInventoryBridge>();
// Get all the equippable item collection, returns a Item Collection Group.
var equippableItemCollections = characterInventoryBridge.EquippableItemCollections;

/// Equip Items

//Items must be added to the Inventory before they can be added.
// This adds the item to the main item collection.
var addedItem = inventory.AddItem("Assault Rifle", 1);
// Before an item can be equipped it must be part of one of the Equippable Item Collection.
var equippableCollectionIndex = 0;
var slotIndex = -1; //The itemcollection slot index.
characterInventoryBridge.MoveItemToEquippable(addedItem, equippableCollectionIndex, slotIndex);

// Once the item ins in equippable it can be equipped.
characterInventoryBridge.Equip(addedItem, true);
// And unequipped
characterInventoryBridge.Equip(addedItem, false);

// Note that the item is still in equippable at this point and it can be sent back to default item collection with
characterInventoryBridge.MoveItemToDefault(addedItem, equippableCollectionIndex, slotIndex);

// It is actually more efficient to use the MoveEquip if you plan to move to equippable and equip directly after.
// Moving the item to one of the Equippable item collection and Equipping it can be done in one line of code.
characterInventoryBridge.MoveEquip(addedItem, true);
// It can be unequipped too.
characterInventoryBridge.MoveEquip(addedItem, false);

/// Get Items
// Get a character Item from an inventory Item.
var slotID = -1; // The Item Set slot.
var characterItem = characterInventoryBridge.GetCharacterItem(addedItem.Item, slotID);
// For multi inventory item can have multiple character items
var characterItems = characterInventoryBridge.GetCharacterItems(addedItem.Item);
// you can get the inventory item from a character item.
var inventoryItem = characterInventoryBridge.GetInventoryItem(characterItem);

/// Get Equipped Items

// Get the "Active" equipped item by checking the UCC slotID:
var activeEquippedItemInSlot0 = characterInventoryBridge.GetActiveInventoryItem(0);
//In this case the SlotID is the UCC slotID, not the ItemSlotCollection slot index, they are not always the same.

//Get the soft&active equipped items by looping over the items in the equippable item collections:
var allEquippedItems = characterInventoryBridge.EquippableItemCollections.GetAllItemStacks();
for (int i = 0; i < allEquippedItems.Count; i++) {
    var item = allEquippedItems[i].Item;
    var isActive = characterInventoryBridge.IsItemActive(item);

    //Do stuff with the soft or active equipped item.

/// Drop Items
var inventoryDrop = characterInventoryBridge.DropItem(addedItem, true, true);

Inventory Item Set Manager

The Inventory Item Set Manager takes care of creating the Item Sets for the equippable items using the Item Set Rule Object.

When an item is added to, or removed from, the Equippable Item Collections, the Character Inventory Bridge component will notify the Inventory Item Set Manager to update the Item Sets. The system will go through all the Item Set Rules and check if any of them return a new Item Set for the current set of equippable Items. Once the Item Sets are created they function as they do in the Character Controller system.

Some events are fired before and after the Item Sets are updated. This event specifies what Item Sets will be added, removed or kept. This data can be used to modify some of the Item Sets even more when individual Item Set Rules are not enough. Although custom Item Set Rules are probably the way to go in most advanced and complex use cases.

When creating your Item Set Rules it is important to restrict them to specific categories and make use of the State System and presets.


Equippable Collection has: 1 Sword, 1Shield, 1 Bow

Having a single Item Set Rule with Equippable in slot 0 (Equippable(0)) won’t work well since the Item Set Rule will try to create 3 ItemSets with the items in the right hand.
Instead the you should use at least 3 Item Set Rules: Sword(0), Sword(0)+Shield(1), Bow(1).

It is recommended to have a look at the integration demo scene to see how the Item Set Rules are setup there.

Item Set Rules

Item Set Rules are used to create Item Sets given a list of equippable items. By default there are three types of Item Set Rules:

  • Item Set Rule With Item Categories: An Item Set is created if each slot with an Item Category inherently contains an equippable item.
  • Item Set Rule With ItemDefinitions: An Item Set is created if each slot with an Item Definition inherently contains an equippable item.
  • Item Set Rule Object Container: An Item Set Rule which points to an “Item Set Rule Object” scriptable object. The Item Set Rule Object class can be inherited to create custom Rules for more advanced use cases, example a Item Set Rule which returns multiple Item Sets with different state names.

The Item Set Rule type can be chosen when adding an Item Set Rule to the Item Set Rules Object.


A custom Item Set Rule cab be created by inheriting the Item Set Rule Object class:

[CreateAssetMenu(fileName = "MyItemSetRule", menuName = "MyItemSetRule")]
public class MyItemSetRule : ItemSetRuleObject
    private int m_SlotCount = 0;
    List<ItemSet> m_ItemSets = new List<ItemSet>();
    public override ListSlice<ItemSet> GetItemSetsFor(ListSlice<Item> items)
        // Create your item sets and add them to the item sets list.
        // Refer to the Item Set Rule class to learn how to do this correctly.
        return m_ItemSets;
    public override void SetSlotCount(int slotCount)
        m_SlotCount = slotCount;
    public override bool DoesItemMatchRule(Item item)
        // return true only if the item set rule has a slot where this item could go in.
        return false;

Equipping Skinned Mesh Clothes

The Character Controller Inventory does not support character skinned mesh items. Clothes and armor must be equipped through the Ultimate Inventory System. The easiest way to do so is by using the Equipper script.
Since armor and weapons will be equipped through different systems the clothes cannot be equipped with an “Equippable” ItemCollection, these are meant to be used purely for the Character Controller weapons. Therefore another ItemCollection must be used for clothes and armor.

  1. Create a new ItemSlotCollection for your armor and name it accordingly (i.e “Armor Equipped”), set its purpose to “None” such that it won’t be confused with the “Equippable” collections.
  2. Create an ItemSlotSet for your armor slots and assign it to your new ItemSlotCollection.
  3. Add an Equipper script to your character, assign the ItemSlotSet and define which slots are skinned mesh.
  4. Create an additional Equipment UI (aka ItemSlotCollectionView) separate from the weapons equipment UI. Make sure that each are set up correctly and point to the correct ItemSlotCollections. This is done by setting the Item Collection name/purpose on the ItemSlotCollectionView inspector under the Item Collection ID field.
  5. You will have two equip item actions, one for your armor items and one for your weapon items. Use the MoveToItemCollection Item Action for equipping the armor in the UI and make sure the correct ItemCollection name are specified (i.e Main and “Armore Equipped”), The CharacterEquipItemAction should only be used for equipping “Equippable” Character Controller weapons.
  6.  Create items with skinned mesh prefabs following the Equipper guidelines for skinned mesh equipments.
  7. Make sure to only use the “EquipmentPrefab” attribute and not the “UsableItemPrefab” attribute since usable Item Prefabs are not required in the integration.

Since your armor and weapon items will be separated in two or more item collections you may wish to create an Item Collection Group to keep track of all your equipment in code.

The Equipper script is fairly simple, you may extend it or replace it with your own custom script to make it more advanced.


All the events used in the integration can be found in the “Integration Event Names” script. Most will be interested in the following Inventory system or character controller events, to know when an item moves between item collections or when it is equipped and active on the character.

EventHandler.RegisterEvent<ItemInfo, ItemStack>(m_InventoryBridge.Inventory, EventNames.c_Inventory_OnAdd_ItemInfo_ItemStack, OnAddItemToInventory);
EventHandler.RegisterEvent<ItemInfo>(m_InventoryBridge.Inventory, EventNames.c_Inventory_OnRemove_ItemInfo, OnRemoveItemFromInventory);
EventHandler.RegisterEvent<Items.Item, int>(m_CharacterGameobject, "OnAbilityUnequipItemComplete", OnUnequipItemComplete);
EventHandler.RegisterEvent<Items.Item, int>(m_CharacterGameobject, "OnInventoryEquipItem", OnEquipItemComplete);
EventHandler.RegisterEvent<Items.Item, int>(m_CharacterGameobject, "OnAbilityWillEquipItem", OnWillEquipItem);

Other useful events for the Character Controller can be found here. The Inventory system event names can be found in the “Event Names” script.

Inventory Item Pickups

Item Pickups/Drops can be either use the integration component “Inventory Item Pickups” or any of the Inventory system pickups. The main difference is that the Inventory Item Pickup works using the Character pickup ability, while the inventory system pickups work with the Inventory Interactable system. It is your choice to either use one, the other, both or neither.

As mentioned in the Character Inventory Bridge section, a generic Inventory Pickup prefab is defined on that character and is used for all items. Except for Character Items which optionally can be dropped using the pickup prefab defined on the Character Item instance itself.

The generic Inventory Pickup prefab can show different models when the “Inventory Item Visualizer” is used. This component watches the first item in an inventory and spawns a prefab set as an attribute on the item. Therefore the same pickup prefab may be used to drop a log or a brick and they will look differently if the drop prefab attribute is found on the inventory item.

You may easily create Item Pickups from the Integration Editor


The UI functions separately between the character and inventory systems. Each can be setup indepedently using the Manager Editor provided by their respective tool.

The Inventory system UI is more advanced and has many features. For example the Item Action is usually used to equip items. But the Integration equipping is more advanced than what is used in the Inventory system demo. So we created a few very useful Inventory Item Actions which can be used with the integration. It is recommended you create your own Item Actions too for more control.

Custom Inventory Item Actions

  • Character Drop: Drop Items using the character.
  • Character Quantity Drop: Drop a chosen amount of Items using the character.
  • Character Equip Unequip: Equip or Unequip an item.
  • Character Modify Attribute: Use an item attribute to modify a character attribute. This can be used to increase/decrease Health, Armor, or any other character attribute value.
  • Character Use: Equip Use and Unequip an item. This is used in the demo to cast a fire ball for example when using the Magic item “Fireball”.

Most users will wish to disable the character input while panels are opened.

By default the Character Controller hides the cursor. But while Inventory Panels are open you may wish to show that cursor. Use the Display Panel Manager Handler, instead of the Unity Input to handle the cursor


Since Item, Inventory and Item Collection class names are used in both the Character and Inventory system for different things, it is important to use the right ones when creating custom code. Here are some using statements that can help to prevent confusion:

using Item = Opsive.UltimateInventorySystem.Core.Item;
using ItemCollection = Opsive.UltimateInventorySystem.Core.InventoryCollections.ItemCollection;
using Inventory = Opsive.UltimateInventorySystem.Core.InventoryCollections.Inventory;
using CharacterItem = Opsive.UltimateCharacterController.Items.Item;

Upgrading from V1.X to V2.X

Before upgrading make sure to remove the old integration package before importing the new version. If not many warnings/errors will pop up.

All the items will be able to carry over to the new version.

To update a character to the new integration make sure to update the scripts on the character, and refer to the character setup to learn more.
Note: If a script is missing on the character it might be the Inventory Item Set Manager.

  • Ultimate Inventory System Bridge has been renamed Character Inventory Bridge
  • Inventory System Item Set Manager has been renamed Inventory Item Set Manager

Some of the Item Attributes which were previously required are no longer.
Feel free to remove the following attributes from your Item Categories, as they are no longer used:

  • IsEquipped
  • ExposedItemSet
  • CanEquipFromMenu
  • ExclusiveEquip

The Item Sets will need to be recreated using the new Item Set Rule system, you may learn more about them below.

Remove the Item Sets from your Inventory Item Pickups if you are using the Item Set Rule for that item.

The “Unique Item Set” field on the character Item Prefab should be disabled if you are using the Item Set Rules for that item (otherwise two Item Sets will be created for the same item.)

The bridge system works differently from before. Here are some of the main differences:

  • The Bridge works by listening to the Inventory Item Collection add/remove events, not the other way around. Meaning that the items can be directly added into a specific Item Collection without breaking the state of the bridge.
  • Equippable Items are no longer added to the Character Inventory automatically. This used to be a problem with scalability since all the items in the inventory would spawn and be disabled on the character.
  • The Item Set Rule changes completely how Item Sets are created, and allows for way more flexibility & scalibility.
  • Unequipped items are now removed from the Item Collection first while the unequip Item animation is playing. Therefore there is no longer a required “waiting time” for moving item collection when equipping/removing items. This was a big issue when working with other Inventory system features.
  • Multi Items are now all spawned when an item is added to Equippable, the Item Sets (created from the Item Set Rule) will decide which one is active.
  • The Is Equipped attribute is no longer used, to check if an item is “soft equipped” (in the equipppable item collection) or “active equipped” (in the active Item Set) use the Character Inventory Bridge component.
  • All the events have been changed, refer to the Event Section below to learn more
  • The Shop and Crafter component should no longer use “external remove” since the items can now be removed normally.