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.

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.

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.

Downloads V2.0.2

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

Videos

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

Terminology

  • 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.

Concept

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.
  • 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: Items that do not change even when the save data is loaded and can be added to the Default Item Collection on start.

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.

Common Errors

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

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.

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.

Required:

  • 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.

Recommended:

  • 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.
  • 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 Name: The loadout Item Collection is loaded on start and 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.

API

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);

///
/// 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 are added, remove 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.

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.

API

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)
    {
        m_ItemSets.Clear();
        
        // 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;
    }
}

Events

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

UI

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

API

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;