Currency

Use Currency to give an Inventory owner a balance, price Items, and complete transactions such as buying an Iron Sword for Gold. Begin with one root Currency and add denominations only when the player needs to exchange or display them.

The standard example uses Gold, an Iron Sword with a BuyPrice of 50 Gold, and a player who begins with 100 Gold.

Understand the Currency model

Part	What it represents	Gold example
Currency	A database object that defines a name, Icon, limits, and conversion relationships. It does not store a balance.	Gold
Currency Amount	One Currency paired with an amount.	50 Gold
Currency Amounts	A list of Currency Amount values, commonly used by Item attributes and prices.	Iron Sword BuyPrice = 50 Gold
Currency Collection	A balance that can add, remove, compare, and normalize related Currencies.	The player’s 100 Gold
Currency Owner	The component that holds a Currency Collection at runtime.	The player wallet
Shop	Reads an Item price, checks the buyer or seller, and changes both Currency and Inventory contents.	Buy one Iron Sword for 50 Gold

Keep these responsibilities separate. Gold defines the value, BuyPrice defines what the Iron Sword costs, and the player’s Currency Owner records what the player owns.

Set up the Gold workflow

Create Gold

1. Open Tools > Opsive > Ultimate Inventory System > Main Manager.
2. In Setup, confirm that the intended Inventory System Database is selected.
3. Open Currencies, create Gold, and assign its Icon.
4. For a one-Currency project, leave Base Currency, Overflow Currency, and Fraction Currency empty.
5. Keep Max Amount large enough for the intended economy. Set a smaller value only when the Currency Collection should enforce that boundary.
6. Review Exchange Rates and confirm that Gold is the root of its own family.

The Currency editor explains every field and the relationship view.

Define the Iron Sword price

1. In the Main Manager, open Item Categories and select the category that supplies Iron Sword’s Item Definition attributes.
2. Add BuyPrice as a CurrencyAmounts Item Definition attribute if the category does not already provide it.
3. Open Item Definitions, select Iron Sword, and set BuyPrice to 50 Gold.
4. Add a separate SellPrice only when selling should use different stored data. A Shop can deliberately use the same attribute name in both directions.

The attribute name is a contract. The Item and the Shop’s Buy Attribute Name must use the same spelling and capitalization, and the value must be CurrencyAmounts for the standard Shop.

Give the player a balance

1. Add a Currency Owner to the same player GameObject as the Inventory and Inventory Identifier.
2. Confirm that the component uses the same Inventory System Database as Gold and Iron Sword.
3. In the Currency Owner Inspector, add Gold and set the starting amount to 100.
4. Keep the player’s destination Item Collection, such as Bag, ready to accept Iron Sword.

The Currency Owner’s Currency Collection normalizes additions and removals according to Gold’s Currency settings and notifies the connected UI when its value changes.

Connect the Shop and UI

1. On the Shop component, set Buy Attribute Name to BuyPrice and leave Buy Modifier at 0 for the stored 50-Gold price.
2. Confirm that the Shop Inventory contains Iron Sword and that the player’s destination collection resolves to Bag.
3. Create the Shop Menu and its Total Price view from the UI Designer Shop tab.
4. Create a separate Currency Owner Monitor from the UI Designer Currency tab to show the player’s Gold balance.
5. Map Gold to a valid Currency View in both the price and balance displays.

The Total Price view and Currency Owner Monitor show different data: the first shows the selected transaction total, while the second shows the player’s current balance.

Choose one Currency or a family

Use one root Currency when every price, reward, and balance is expressed in Gold. This avoids conversion rules and makes a displayed price directly comparable with the player’s balance.

Use a Currency family only when several denominations represent the same underlying value. The visible Version 1 fields work together as follows:

Field	Rule
Base Currency	The less valuable parent Currency. The root has no Base Currency.
Base Exchange Rate	The amount of Base Currency equal to one unit of the selected Currency. The value must be at least 1.
Max Amount	The greatest amount of that denomination retained by a Currency Collection before overflow handling.
Overflow Currency	A more valuable Currency in the same family that receives excess value.
Fraction Currency	A less valuable Currency in the same family that receives a fractional remainder.

For example, Silver can use Bronze as its Base Currency with a Base Exchange Rate of 100, meaning 1 Silver equals 100 Bronze. Gold can then use Silver as its Base Currency. Currencies can convert only when they share the same root.

Base relationships establish exchange rates, but Overflow Currency and Fraction Currency decide how a Currency Collection stores out-of-range or fractional results. Without a valid next denomination, excess value cannot be retained above Max Amount and fractional value below the smallest configured denomination can lose precision.

How a Shop transaction runs

For a standard purchase:

1. The Shop finds the Item’s value using Buy Attribute Name.
2. It multiplies the stored CurrencyAmounts value by the selected Item quantity and by 1 + Buy Modifier. A Buy Modifier of 0 leaves the value unchanged.
3. It checks that the Item is buyable, the destination Item Collection can accept it, all buy conditions pass, and the Currency Owner has the calculated amount.
4. It removes that Currency and adds the Item to the player’s selected destination collection.
5. Successful purchase events let the UI refresh and let Shop Add Remove Binding remove finite stock when Remove On Buy is enabled.

Selling reverses the data flow: the Shop checks the Item and sell conditions, removes the Item from the seller, reads Sell Attribute Name, applies 1 + Sell Modifier, and adds the resulting Currency to the seller’s Currency Owner. Validate the sell attribute before enabling the transaction.

Currency Collections keep each result in a valid discrete state. Fractional price modifiers can therefore be converted through Fraction Currency or lose precision when no smaller denomination exists.

Editor checkpoint

Before entering Play Mode, confirm that:

• Gold exists once in the intended Inventory System Database and is the root of its Currency family;
• Iron Sword exposes BuyPrice as a CurrencyAmounts Item Definition attribute containing 50 Gold;
• the player Currency Owner contains 100 Gold and shares the player Inventory’s GameObject and database;
• the Shop’s Buy Attribute Name is exactly BuyPrice and Buy Modifier is 0;
• the Shop Inventory contains Iron Sword and the player’s Bag can accept it;
• the Shop total-price view maps Gold; and
• the separate Currency Owner Monitor resolves the player’s Currency Owner and maps Gold.

Verify in Play Mode

1. Enter Play Mode and confirm that the balance view shows 100 Gold.
2. Open the Shop, select one Iron Sword, and confirm that Total Price shows 50 Gold.
3. Buy it and confirm that Iron Sword appears in Bag while the balance becomes 50 Gold.
4. Try to buy another quantity whose total exceeds the remaining balance. Confirm that the transaction is rejected and neither the Bag nor the Gold balance changes.
5. If selling is configured, sell an eligible Item and confirm that the Item amount decreases and Gold increases by the displayed sell total.
6. If a multi-Currency family is configured, test values immediately below and above each Max Amount and confirm that overflow, fractions, and the UI use the intended denominations.

Troubleshooting

• Gold is absent from an editor field: Check that the Main Manager, scene components, and Item data use the same Inventory System Database.
• Iron Sword has no price: Check that its category supplies BuyPrice as a CurrencyAmounts Item Definition attribute and that Iron Sword has a Gold value.
• The Shop reports a missing price or shows zero: Check BuyPrice spelling and type against Buy Attribute Name, then confirm that the selected Item exposes the attribute.
• Buy remains unavailable with enough Gold: Check the player’s Currency Owner, the calculated quantity total, buy conditions, and whether Bag can accept Iron Sword.
• The wrong amount is removed: Check the stored BuyPrice, selected quantity, and Buy Modifier. Remember that the multiplier is 1 + Buy Modifier.
• The balance changes but the UI does not: Check that the Currency Owner Monitor resolves the intended Currency Owner and that its Multi Currency View maps Gold.
• Related Currencies do not convert: Check that both trace to the same root and that each Base Currency and Base Exchange Rate points from the more valuable denomination to the less valuable one.
• Overflow stops at Max Amount: Check that Overflow Currency is a more valuable member of the same family and that an exchange rate exists between them.
• A fractional result is rounded away: Add a valid lower-value Fraction Currency or keep prices and modifiers in the smallest supported whole unit.
• Shop stock never decreases: Add Shop Add Remove Binding and enable Remove On Buy; the default Shop treats its Inventory entry as an unlimited source.

Continue with shops

• Shop is the direct child guide for buying, selling, price attributes, stock behavior, callbacks, and the public transaction methods.

Related pages

• Currency editor
• Common price attributes
• Define attributes
• Shop UI Designer
• Currency UI Designer
• Shop Menu
• Multi Currency View and Currency Owner Monitor

Developer reference

Work with a Currency Owner

InventorySystemManager.GetCurrency resolves a Currency by database name. CurrencyAmount accepts either constructor order and supports (int, Currency) and (Currency, int) tuple conversion. The Currency Owner exposes its Currency Collection through CurrencyAmount.

var gold = InventorySystemManager.GetCurrency("Gold");
CurrencyAmount ironSwordPrice = (50, gold);

var balance = currencyOwner.CurrencyAmount;
var canAfford = balance.HasCurrency(gold, ironSwordPrice.Amount);

var added = currencyOwner.AddCurrency(gold, 25);
var removed = currencyOwner.RemoveCurrency(gold, 10);

var exactGoldAmount = balance.GetAmountOf(gold);
var familyValueInRootUnits = balance.GetFullAmountAsRootCurrency(gold);

GetAmountOf returns only the selected denomination. GetFullAmountAsRootCurrency combines every stored Currency from the same family and expresses the total in root units. HasCurrency uses the family value, so a compatible set of denominations can satisfy one related-Currency amount.

Use Currency.TryGetExchangeRateTo(otherCurrency, out rate) to test conversion. It returns false when the Currencies do not share a root.

Use the Version 1 Shop methods

The released Version 1 Shop methods accept an Inventory, an ICurrencyOwner, and an ItemInfo. The ItemInfo carries the Item, amount, and source collection:

var bought = shop.BuyItem(buyerInventory, currencyOwner, itemInfo);
var sold = shop.SellItem(sellerInventory, currencyOwner, itemInfo);

Both methods return false when validation fails. In the built-in synchronous purchase path, the Shop checks the destination and funds before removing Currency and adding the Item. When Add Item With Callback is enabled, Currency is removed before the external add callback reports success; provide project-level rollback if that callback can fail. Selling removes the Item before it calculates and adds the sell value, so a custom sell path must also handle rollback when later work can fail.