ItemInfo Filters and Sorters

Export

ItemInfo filters decide which Inventory entries a grid displays, while sorters decide their visible order. Use them to keep Equipment out of a Bag grid, create Consumable and Weapon tabs, search for Health Potion by name, or order stacks by amount without changing which Items the Inventory owns.

Filtering and continuous sorting are view operations. A one-time Inventory Grid sort changes the grid’s stored index order, but none of these components transfers or deletes an Item.

Choose a built-in filter

Component Important Inspector fields and defaults Released Version 1 behavior
Inventory Search Filter Inventory Grid, Input Field, and optional Bind Sorter While Searching have no manual default references. UI Designer wires the grid and schema input field. Matches the runtime Item name using the current culture and ignores letter case. It temporarily replaces the grid’s bound filter/sorter while the input is nonempty.
Item Info Category Filter Show Item Category and Hide Item Category default to none. Show Attribute Name is empty. Show Category Icon is unassigned. Category Icon Attribute Name defaults to CategoryIcon. Shows Items inherently contained by the show category and excludes Items inherently contained by the hide category. A true boolean named by Show Attribute Name overrides both category checks.
Item Info Item Collection Filter Show Item Collections is empty. Hide Item Collections defaults to Loadout and Hide. An empty show list accepts every collection except the hidden ones. Add Bag to show only Bag, then keep any additional collections that must remain hidden.
Item Info Item Collection And Category Filter Item Collections is empty and it inherits the Category Filter fields. With an empty collection list, the category rule applies to every Item. With entries, the category rule applies only inside those collections; Items from other collections pass unchanged. It is not a strict collection-and-category intersection.
Item Info Multi Filter Sorter Grid Filters starts empty when created by UI Designer. Runs each referenced filter or sorter in list order and skips a reference to itself. Every filter must accept an Item for CanContain to return true.

Category membership uses the Item’s inherent category relationship, including the category hierarchy. There is no separate built-in Item Definition filter. Name search and name sorting use Item.name, which normally starts with the Item Definition name but can differ for a runtime Item.

Choose a built-in sorter

Component Important Inspector fields and defaults Released Version 1 order
Item Info Amount Sorter No settings. Largest ItemInfo.Amount first.
Item Info Attribute Value Sorter Attribute Name is empty. Ascending defaults on. Sorts present attribute values in ascending order by default. Values must implement IComparable; Items without the attribute follow Items that have it.
Item Info Category Name Sorter Ascending defaults off. The released comparator produces category names A-Z while the field is off and Z-A while it is on. Null Items follow valid Items.
Item Info Name Sorter Ascending defaults off. The released comparator produces runtime Item names A-Z while the field is off and Z-A while it is on. Null Items follow valid Items.

The Ascending behavior of the two name sorters is counterintuitive in released Version 1; verify the visible order rather than assuming the toggle’s label. Attribute sorting uses the expected on-for-ascending behavior.

Built-in sorters compare one key and return equality when that key matches. The underlying Array.Sort operation is not stable, so equal keys have no guaranteed secondary order. For a permanent amount-then-name or category-then-name order, use one custom comparer that includes every key and a final deterministic tie-breaker.

Add default filters in UI Designer

Create one shared chain for rules that should apply whenever the grid is not temporarily controlled by a tab, search, or bound dropdown sorter.

  1. Open Tools > Opsive > Ultimate Inventory System > UI Designer, select Inventory Grid, and edit the intended grid.
  2. Open Filters and Sorters.
  3. Under Default Filters, create the filter collection. UI Designer adds an Item Info Multi Filter Sorter and binds it to the Item Info Grid.
  4. Add Item Info Item Collection Filter first. Set Show Item Collections to Bag so equipped or hidden Items do not appear in the Bag view.
  5. Add Item Info Category Filter only when this entire view should show one category, such as Consumable.
  6. Add at most one sorter after the filters, such as Item Info Name Sorter.
  7. Select each generated component to edit its Inspector values, then return to UI Designer to confirm the Default Filters list.

Order the chain as narrowing filters followed by one final sorter. A later filter sees only the entries accepted by the earlier filters. A later sorter reorders the complete result, so stacking several built-in sorters does not create a dependable multi-key order.

At this editor checkpoint, Bag accepts Health Potion and Iron Sword, excludes Items held only by Equipment or Hide, and presents the remaining entries in the chosen visible order.

Add name search without losing the Bag rule

  1. In Filters and Sorters, create Name Search bar Filter.
  2. UI Designer creates the search field, assigns its Inventory Grid, and creates a Multi Filter Sorter for Bind Sorter While Searching.
  3. Add an Item Info Item Collection Filter to the search list and set Show Item Collections to Bag.
  4. Add any category filter that must still apply while searching.
  5. Add one optional sorter last, such as Item Info Name Sorter.

The search component first checks the current input against Item.name, then runs Bind Sorter While Searching. It redraws on every text change. When the first nonempty query starts, it stores the previously bound filter/sorter, binds itself, and temporarily turns Use Grid Index off. Clearing the input restores the previous binding and the Use Grid Index value captured when the search component awoke.

Because search replaces the active binding, repeat essential Bag or category rules inside its search chain. Otherwise a search for iron can display an Iron Sword from a collection that the normal Bag view hides.

Search does not inspect Description, Item Category, Item Definition attributes, or arbitrary display text. Create a custom search filter if the player must query those values.

Build category tabs

Use tabs when one grid should switch between complete filter chains, such as All, Consumable, and Weapon.

  1. In UI Designer’s Grid Tabs, choose Create Inventory Tabs. The released creator starts with three Tab Toggles.
  2. Rename the tabs All, Consumable, and Weapon.
  3. Select All and create Tab Filters containing the Bag collection filter and the intended sorter.
  4. Select Consumable and create Tab Filters containing the same Bag filter, an Item Info Category Filter that shows Consumable, and the sorter.
  5. Select Weapon and repeat with Weapon as Show Item Category.

Selecting a tab binds that tab’s Item Info Filter, sets the Inventory Grid’s tab ID, restores the tab’s grid index data, and redraws. A tab filter replaces the previously bound default chain; include every rule that must remain active in every tab.

Use Item Info Item Collection And Category Filter only when category filtering should affect selected collections while all other collections remain visible. For a strict Bag-and-Consumable tab, use separate collection and category filters in a Multi Filter Sorter.

Add a player-controlled sort dropdown

Under Filters and Sorters, create Drop Down Sorter, then add only the choices the player needs:

  • Item Info Name Sorter for Health Potion and Iron Sword by Item name;
  • Item Info Amount Sorter for the largest stacks first; and
  • Item Info Attribute Value Sorter for a comparable value such as the numeric Attack attribute.

The Inventory Grid Sorter Drop Down contains Inventory Grid, Dropdown, Grid Sorters, Sort Selected Tab Only, and Bind The Sorter. Both boolean choices default off. Dropdown option 0 means no sort; sorter list index 0 maps to dropdown option 1.

With Bind The Sorter off, selecting a choice performs a one-time index sort, redraws, and resets the dropdown to option 0. Option 0 performs no new sort; it does not restore the index order that existed before a one-time sort. If tabs exist and Sort Selected Tab Only is off, the binding sorts every tab’s stored indexer; turn it on to affect only the selected tab.

With Bind The Sorter on, the selected sorter becomes the grid’s continuous bound filter/sorter. This replaces the current default or tab filter instead of composing with it, and choosing option 0 unbinds to null rather than restoring the previous chain. Keep the default one-time mode when collection/category filters must remain intact, or implement an explicit composite control for continuous filter-plus-sort behavior.

Understand grid indexes and refresh cost

On each draw, Inventory Grid starts with Inventory.AllItemInfos, applies the active filter/sorter, and then applies the Inventory Grid indexer when Use Grid Index is enabled. This has several practical effects:

  • a bound sorter is easiest to reason about with Use Grid Index off;
  • a one-time dropdown sort changes the indexer and is intended to work with stored positions;
  • search temporarily disables index ordering so its filtered result can be presented directly;
  • Inventory Mirror Hotbar reads the same filtered and sorted Inventory Grid result; and
  • changing a filter does not itself move, remove, or save an Item.

Filters scan the current ItemInfo list. Each sorter copies the current list into a pooled array and calls Array.Sort. A Multi Filter Sorter repeats that work for every entry in its chain, and Inventory Search Filter redraws for every input change. Prefer a few meaningful filters and one sorter, avoid duplicate stages, and use a single custom comparer when several sort keys are required.

The pooled output array reduces repeated allocations, but custom filters can reintroduce allocations if they build temporary lists or strings on every draw.

Editor checkpoint

Before entering Play Mode, confirm that:

  • the grid’s default chain begins with the intended Item Collection rule;
  • each tab repeats shared Bag restrictions instead of relying on the replaced default chain;
  • search repeats every restriction that must remain active while text is nonempty;
  • every Multi Filter Sorter contains filters first and no more than one final sorter;
  • Attribute Name is exact and resolves to one compatible IComparable value type on the Items being compared;
  • Item Info Name Sorter and Category Name Sorter have the visually verified A-Z or Z-A setting;
  • Use Grid Index, one-time sorting, and continuous binding match the intended position model; and
  • the sort dropdown’s first option is the unsorted option, followed by one option per Grid Sorters entry.

Verify in Play Mode

  1. Open Bag with Health Potion and Iron Sword present, and put another Item in Equipment. Confirm that the Bag collection filter hides the equipped Item without changing Inventory contents.
  2. Select Consumable and Weapon tabs. Confirm that Health Potion and Iron Sword appear only under their inherent category rules and that each tab retains the Bag restriction.
  3. Search for potion using different letter casing. Confirm that Health Potion matches by runtime Item name and that hidden collections remain hidden.
  4. Clear the search. Confirm that the previous tab or default filter returns and Use Grid Index returns to the value captured when the search initialized.
  5. Choose amount sorting and confirm that larger stacks appear before smaller stacks.
  6. Choose Attack attribute sorting and confirm that Items with valid comparable Attack values are ordered before Items without that attribute.
  7. Compare the name sorter’s Ascending toggle in both positions and retain the one that produces the intended visible order in Version 1.
  8. With tabs enabled, compare Sort Selected Tab Only off and on and confirm which stored tab indexes change.
  9. Add or remove an Item and confirm that bound filters refresh while a one-time sorted index remains consistent with the configured Inventory Grid index data.
  10. If an Inventory Mirror Hotbar uses this grid, confirm that it shows the same leading filtered and sorted entries.

Troubleshooting

Symptom Check Fix
Equipment Items appear in Bag Show Item Collections and Hide Item Collections Show Bag explicitly and keep every collection that must be excluded in the hide list.
A strict Bag category tab shows Items from another collection Filter type Use separate Item Info Item Collection Filter and Item Info Category Filter entries; the combined filter intentionally passes unlisted collections.
Search reveals otherwise hidden Items Bind Sorter While Searching chain Repeat the Bag and category filters inside the search chain.
Clearing search does not return the expected view Previous binding, tab changes, and Use Grid Index Confirm search began from the intended tab/default binding and clear the field before changing filter ownership.
A tab ignores the default filter That tab’s Tab Filters Add the shared collection and category rules to every tab; tab selection replaces the default binding.
Name order appears reversed Item Info Name Sorter or Category Name Sorter Ascending In Version 1, off produces A-Z and on produces Z-A for these two sorters.
Attribute sorting appears unchanged Attribute Name, attribute presence, value type, and equal values Use the exact attribute name and one compatible IComparable type; add a custom tie-breaker when values can match.
Several sorters produce inconsistent ties Multi Filter Sorter order and comparer equality Replace them with one custom multi-key comparer. Built-in sorting is not stable.
Choosing a bound dropdown sort removes category filtering Bind The Sorter Use the default one-time mode or a custom control that binds a composite filter/sorter.
Bound sorting conflicts with manual positions Use Grid Index Turn index ordering off for a continuously ordered view, or use one-time index sorting for positional grids.
Search feels expensive in a large Inventory Number of filter stages and per-filter allocations Remove redundant stages, keep one sorter, and avoid allocating temporary collections or strings on each input change.

Developer details

Implement IFilterSorter<ItemInfo> directly, or derive a component from ItemInfoFilterSorterBase, ItemInfoFilterBase, or ItemInfoSorterBase. ItemInfoFilterBase turns a per-Item Filter decision into a pooled list operation and uses the same decision for CanContain. ItemInfoSorterBase requires a Comparer<ItemInfo>, copies into the pooled output array, and always returns true from CanContain.

Bind a filter or sorter when it should run on every draw:

var previousFilterSorter = inventoryGrid.BindGridFilterSorter(filterSorter);
inventoryGrid.Draw();

// Restore the previous view later.
inventoryGrid.BindGridFilterSorter(previousFilterSorter);
inventoryGrid.Draw();

Perform a one-time positional sort with a sorter comparer:

inventoryGrid.SortItemIndexes(itemInfoSorter.Comparer);
inventoryGrid.Draw();

For a custom filter component, implement the smallest per-Item rule and let the base class reuse the pooled output array:

public sealed class PositiveAmountItemInfoFilter : ItemInfoFilterBase
{
    public override bool Filter(ItemInfo itemInfo)
    {
        return itemInfo.Item != null && itemInfo.Amount > 0;
    }
}

For stable multi-key ordering, implement one ItemInfoSorterBase comparer that compares the primary key, then name, then a stable Item identifier. Do not rely on several sequential built-in sorters to preserve earlier ties.