The Inventory system's v1.72 update

AC's inventory system has been overhauled as part of its v1.72.0 update. This page serves as both an overview of how it works from an API level, but also as a guide to developers looking to port custom scripts to the new system.

Inventory item data - as entered into the Inventory Manager - is stored in the InvItem class. Prior to v1.72.0, copies of this class were made at runtime whenever the player handled an item - whether it be in their own inventory, used in crafting, or placed in a Container. This meant that - when dealing with this class in scripts - there was ambiguity about where the InvItem was actually from. Such InvItem classes were stored in Lists, and modified through external functions.

The new inventory system makes two fundamental changes to this:

1. When an inventory is handled at runtime, the original InvItem class is left alone. Instead, an InvInstance class is created, which references the InvItem. This new class has additional properties to record things like the amount of the item it represents, the selection mode (Use vs Give), and so on. Though the original InvItem class can still be accessed, this means that there is no longer ambiguity about where it's coming from.
2. Whenever a list of items are recorded - whether it be for the player's inventory, crafting, or a Container - they are now placed in a dedicated InvCollection class. The InvCollection class has internal functions to handle the addition and removal of items, as well as transfer of items from one collection to another. This removes the need for multiple sets of modification functions depending on what items are being accessed.

As with previous versions, the currently-selected item can be gotten with:

AC.KickStarter.runtimeInventory.SelectedItem;

However, this no longer represents the runtime instance of the item. To get that, we can use:

AC.KickStarter.runtimeInventory.SelectedInstance;

It is important to note that - since item instances can be invalidated, e.g. having a "Count" of zero - it is important to check for its validity before accessing it. This can be done with:

InvInstance myInvInstance;
if (InvInstance.IsValid (myInvInstance))
{
	// OK to access myInvInstance
}

To get the associated InvItem of an InvInstance class:

myInvInstance.InvItem;

InvInstance is also the new home for inventory interaction functions:

myInvInstance.Select ();
myInvInstance.Use ();
myInvInstance.Use (int iconID);
myInvInstance.Examine ();
myInvInstance.Combine (InvInstance otherInvInstance);

To get Player's collection of inventory items:

KickStarter.runtimeInventory.PlayerInvCollection;

or:

KickStarter.player.Inventory;

To get a Container's collection:

myContainer.InvCollection;

With the InvCollection class, we can access individual instances by referencing its index, for example:

InvInstance myInvInstance = KickStarter.player.Inventory.GetInstanceAtIndex (indexValue);

The InvCollection class has many functions and properties to access and modify its contents. For more, see its entry in the Scripting Guide.

The custom events fired when selecting and modifying inventory items are still intact from previous releases, but again: InvItem parameters now refer to the original item in the Inventory Manager. If we want to access the runtime InvInstance that's being affected, we can use the following alternatives:

OnInventoryAdd_Alt (InvCollection invCollection, InvInstance invInstance, int amount)
OnInventoryRemove_Alt (InvCollection invCollection, InvInstance invInstance, int amount)
OnInventoryCombine_Alt (InvInstance invInstanceA, InvInstance invInstanceB)
OnInventoryInteract_Alt (InvInstance invInstanceA, int iconID)
OnInventorySelect_Alt (InvCollection invCollection, InvInstance invInstance)
OnInventoryDeselect_Alt (InvCollection invCollection, InvInstance invInstance)