Currency Asset Reference ​

Intermediate40-60 minutesWindowsUnturned ServerNotepad++

The currency asset is the data definition for custom in-game money systems in Unturned™. A currency asset binds a collection of items together into a unified currency, assigns each item a numeric value, defines how amounts are displayed in vendor menus and dialogue text, and enables NPCs to automatically convert between different denominations. Without a currency asset, all vendor transactions use the default experience-point currency. With a currency asset, a server can implement any monetary system the modder can conceive: a modern cash economy with bills and coins, a post-apocalyptic barter economy where ammunition serves as currency, a faction-specific scrip system, or a casino token economy.

This article is the 57 Studios™ canonical reference for the currency asset type. It covers the currency .asset file format, the entry-value pair system, the formatting string syntax, the default condition format, vendor and condition integration, and the console-based testing workflow. The Currency asset is unusual among NPC system assets in that it uses a .asset file format (JSON-based) rather than the key-value .dat format, a distinction that is the first point of confusion for modders coming from item or NPC .dat authoring.

Vendor interface showing custom currency denominations and formatted prices in Unturned

Documentation source: This article references the official Smartly Dressed Games modding documentation for field definitions and game behavior. Community-validated notes are marked where the official documentation is silent on a detail.

Who this article is for ​

This article is written for Unturned™ server operators and mod authors who have already configured at least one vendor asset and want to replace the default experience-point currency with a custom item-based currency system. If you are new to the NPC and vendor system, start with the Introduction to NPCs and Vendor Asset Reference articles before configuring custom currency. If you are comfortable with GUID management and have a collection of item assets to serve as currency denominations, this article provides the complete currency asset reference.

What you'll learn ​

  • The currency .asset file format and how it differs from the .dat format used by other NPC system assets
  • How to define currency entries: item GUID, value, and visibility settings
  • The ValueFormat and DefaultConditionFormat string syntax for custom currency display
  • How to link a currency asset to a vendor through the vendor's Currency GUID field
  • How currency conditions and rewards work in the dialogue and quest system
  • How to test currency grants using the @give console command with currency GUIDs
  • The complete Canadian currency asset as a worked reference example

Currency asset file format ​

The currency asset uses a .asset file format rather than the .dat format used by NPC, Dialogue, Quest, and Vendor assets. The .asset format is a JSON-based structure with a Type field declaring the C# class name (SDG.Unturned.ItemCurrencyAsset), a set of formatting strings, and an Entries array containing the item-value pairs that make up the currency. The file is placed in the same folder structure as other NPC system assets, but its contents are JSON rather than key-value text.

The .asset format is used because the currency asset has a more complex data structure than the flat key-value field set of a .dat file. The Entries array, a list of item GUIDs paired with integer values, requires a nested data structure that the .dat parser does not natively support. The .asset format, being JSON, supports nested objects and arrays natively.

Folder structure ​

A currency asset lives in a folder alongside other NPC system assets. The file extension .asset is the distinguishing feature, it signals to the engine that this file should be parsed as JSON rather than as key-value text.

Workshop/Content/304930/<ModID>/
└── Items/
    └── Supplies/
        └── MyCurrency.asset      ← currency asset definition

The .asset file contains the full currency definition. There is no companion English.dat for currency assets, the display formatting is defined entirely within the .asset file through the ValueFormat and DefaultConditionFormat strings.

Type declaration ​

Every currency .asset file begins with a Type field that declares the C# class the engine should instantiate to handle this asset:

Type SDG.Unturned.ItemCurrencyAsset

The Type field value must be exactly SDG.Unturned.ItemCurrencyAsset. No other type name is valid for a currency asset. The type name is case-sensitive and must match the internal C# class name exactly.

Currency asset properties ​

Formatting strings ​

The currency asset defines two formatting strings that control how currency values appear in vendor menus and condition text.

FieldTypeRequiredPurpose
ValueFormatstringYesString template for formatting a single currency value. The placeholder {0} is substituted with the numeric value at runtime.
DefaultConditionFormatstringYesDefault formatting string used when an NPC currency condition does not specify its own format. The placeholder {0} is the total value held in the player's inventory; {1} is the condition's required value.

The ValueFormat string is applied in every vendor interface display: the player's current currency balance, the cost of each buy and sell slot, and the total cost when purchasing multiple items. The format string can include literal text, currency symbols, and the standard C# numeric format specifier inside the placeholder. The vanilla Canadian currency example uses the format string "${0:N0} CAD", which renders a value of 1000 as $1,000 CAD.

The {0:N0} segment is the key formatting instruction: {0} refers to the first (and only) argument (the numeric value); :N0 is a C# standard numeric format string meaning "number with thousands separators and zero decimal places." Other format specifiers are supported: {0:N2} displays two decimal places; {0:D} displays the value as a plain integer with no formatting. The cohort recommendation for most currency systems is {0:N0}, which produces clean, readable numbers with thousands separators.

The DefaultConditionFormat string is used in dialogue and condition display text. When an NPC condition checks whether the player has a certain amount of currency, the condition display string can use a custom format specific to that condition. If no custom format is specified, the DefaultConditionFormat is used as the fallback. The vanilla format is "${0:N0}/{1:N0} CAD", which renders as, for example, $500/1,000 CAD to indicate the player has 500 out of the required 1,000 currency.

Currency entries ​

The Entries array defines the items that make up the currency and assigns each item a numeric value. Each entry is a JSON object with three fields.

FieldTypeRequiredPurpose
Item.GUIDstring (hex GUID)YesThe GUID of the item that serves as a currency denomination.
ValueintegerYesThe numeric value of this denomination in the currency system.
Is_Visible_In_Vendor_MenuboolNo (default true)If false, the item is hidden from the vendor currency list display.

The Value integer represents how much this item is worth in the currency system. A $10 bill item would have "Value": "10"; a $20 bill item would have "Value": "20". The NPC system automatically converts between denominations: if a vendor sells an item for 35 currency and the player has one $20 bill and one $10 bill (total 30), the vendor will not accept the purchase (insufficient funds). If the player also has a $5 bill (total 35), the vendor will accept the purchase and deduct the appropriate denominations.

The Is_Visible_In_Vendor_Menu flag controls whether the item appears in the currency breakdown display within the vendor interface. For currency systems with many denominations, hiding low-value coins or intermediate-value bills from the display keeps the vendor interface clean without affecting the currency's functionality. The items still function as currency regardless of their visibility setting, the flag only controls the vendor UI display.

Example: Canadian currency entries ​

The vanilla Canadian currency asset at Bundles/Items/Supplies/CanadianCurrency.asset is the definitive reference example. Its entries define a multi-denomination cash economy:

{
    "Item"
    {
        "GUID" "b6b87dfad5f342dc91bbb2de950f56ee"
    }
    "Value" "10"
}
{
    "Item"
    {
        "GUID" "3b9847bb328d445495b64be9e5ea9400"
    }
    "Value" "20"
}

Each entry is a self-contained JSON object with an Item sub-object (containing the GUID field) and a Value field. Multiple entries are placed sequentially in the Entries array. The vendor interface displays all entries (except those with Is_Visible_In_Vendor_Menu false) sorted from lowest to highest value.

Complete currency .asset example ​

The following example defines a complete custom currency .asset file: a post-apocalyptic barter currency based on ammunition, with three denominations (9mm round as the base unit, 5.56mm round worth 5, shotgun shell worth 10), custom formatting strings, and one hidden denomination.

Type SDG.Unturned.ItemCurrencyAsset
ValueFormat "{0:N0} Rounds"
DefaultConditionFormat "{0:N0}/{1:N0} Rounds"
Entries
{
    "Item"
    {
        "GUID" "a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d"
    }
    "Value" "1"
    "Is_Visible_In_Vendor_Menu" true
}
{
    "Item"
    {
        "GUID" "b2c3d4e5f64a7b8c9d0e1f2a3b4c5d6e"
    }
    "Value" "5"
    "Is_Visible_In_Vendor_Menu" true
}
{
    "Item"
    {
        "GUID" "c3d4e5f64a7b8c9d0e1f2a3b4c5d6e7f"
    }
    "Value" "10"
    "Is_Visible_In_Vendor_Menu" true
}
{
    "Item"
    {
        "GUID" "d4e5f64a7b8c9d0e1f2a3b4c5d6e7f8a"
    }
    "Value" "50"
    "Is_Visible_In_Vendor_Menu" false
}

In this example, the 50-value item (a high-value ammunition box) is hidden from the vendor currency list display. Players holding this item still receive its full 50-unit value in transactions, but the item does not clutter the currency breakdown in the vendor interface. The formatting strings produce vendor prices like "250 Rounds" and condition text like "500/1,000 Rounds."

How currency integrates with vendors ​

A vendor links to a currency asset through the vendor's Currency field. When a vendor's Currency field is set to a currency asset's GUID, every aspect of the vendor's interface switches from experience-point mode to custom-currency mode.

The flowchart shows the four-way relationship: the vendor asset references the currency asset by GUID; the vendor interface reads the currency asset's formatting strings and entry definitions to display prices and the player's balance; the player's inventory provides the actual currency items; and transactions debit or credit those items.

Currency display in vendor menus ​

When a currency asset is linked, the vendor menu's currency display area shows:

  1. The total value of all currency items the player holds, formatted with ValueFormat.
  2. The cost of each buy and sell slot, formatted with ValueFormat.
  3. A breakdown of visible currency denominations (those with Is_Visible_In_Vendor_Menu true), sorted from lowest to highest value.

The total value calculation sums the Value of every currency item in the player's inventory, including items with Is_Visible_In_Vendor_Menu false. The visible breakdown shows only the denomination items whose visibility flag is set to true. This means a player's total balance may be higher than the sum of the visible denomination items, the hidden denomination contributes its value to the total but is not listed in the breakdown.

Transaction mechanics ​

When the player sells an item to the vendor, the vendor debits currency items from the vendor's internal pool and credits them to the player's inventory, or credits the player's currency total using newly generated currency items. When the player buys an item from the vendor, currency items are debited from the player's inventory and credited to the vendor.

The engine automatically handles denomination conversion: if a player buys an item costing 35 currency and has a $50 bill (value 50) and no smaller denominations, the system will deduct the $50 bill if there is no mechanism for making change (the exact behavior depends on the game version and whether the vendor has smaller denominations in its internal pool). The cohort recommendation for currency systems with large-denomination items is to ensure that all possible transaction amounts can be composed from the available denominations, or to accept that large-denomination transactions will sometimes overpay and lose the difference.

Currency denomination design

A poorly designed currency denomination set, one where many transaction amounts cannot be exactly composed from the available denominations, causes player frustration because the system may deduct a larger-denomination item than necessary without returning change. The cohort recommendation is to design currency denominations so that every transaction amount the vendor charges is exactly composable from the available items. For a vendor that charges 25, 50, 75, and 100 currency for its items, the denomination set should include a 25-value item (or a 5-value item combined with others) to make every price exactly payable. The vanilla Canadian currency achieves this with 10 and 20 dollar denominations, accepting that amounts not divisible by 10 cannot be exactly paid, and the vanilla vendors are designed with prices that are all multiples of 10.

How currency integrates with conditions and rewards ​

The currency asset is referenced by the conditions and rewards system through two mechanisms: currency conditions check whether the player has a minimum total currency value, and currency rewards grant currency amounts to the player.

Currency conditions ​

A condition of type Currency can be used in dialogue messages, dialogue responses, quest conditions, and vendor slot conditions to require the player to have a minimum total value of a specific currency. The condition references the currency asset by GUID and specifies a required amount.

When a Currency condition is evaluated, the engine sums the Value of every currency item in the player's inventory that belongs to the specified currency (i.e., every item whose GUID matches one of the currency asset's entry GUIDs). If the total equals or exceeds the required amount, the condition is satisfied.

The display format for a currency condition uses the condition's own Format string if specified, or the currency asset's DefaultConditionFormat if no per-condition format is specified. This allows dialogue text to display currency requirements in the server's established currency format: "You need $500/1,000 CAD to access this area" rather than a bare numeric requirement.

Currency rewards ​

A quest reward of type Currency grants a specified amount of a currency to the player when a quest completes. The reward references the currency asset by GUID and specifies an amount. When the reward is processed, the engine creates or transfers currency items to the player's inventory with a total value matching the reward amount.

The system attempts to compose the reward amount from the currency's available denominations, prioritizing larger denominations to minimize the number of items granted. If the reward amount cannot be exactly composed (for example, a reward of 15 in a currency system with only 10-value and 20-value denominations), the behavior depends on the engine version, some versions round up to the nearest composable amount, while others round down or fail to grant the reward. The cohort recommendation is to design reward amounts and denomination sets so that every reward amount is exactly composable.

Testing currency with the console ​

The built-in @give command accepts currency GUIDs as an alternative to item IDs. When a currency GUID is provided with an amount suffix, the engine grants that amount of the currency to the player rather than granting a specific number of items.

@give <currencyGUID>/<amount>

For example, the following command grants $1,000 CAD to the local player:

@give 5150ca8f765d4a68bfe54912146da410/1000

The currency GUID is the GUID of the currency .asset file. The amount is the total value to grant, not the number of individual items. The engine automatically converts the granted value into the appropriate mix of denomination items.

Testing workflow

The cohort-validated workflow for testing a currency system in single-player:

  1. Author the currency .asset file and place it in the mod folder structure.
  2. Launch Unturned™ in single-player with the mod loaded.
  3. Open the console with ~.
  4. Grant yourself a test amount of currency: @give <currencyGUID>/1000.
  5. Open a vendor configured to use that currency and confirm the correct balance is displayed.
  6. Purchase an item and confirm the correct amount is deducted.
  7. Sell an item and confirm the correct amount is credited.
  8. Test edge cases: grant amounts that require denomination conversion, test buying items that cost more than the player's balance, test selling items when the player has no currency.

Currency design patterns ​

The following design patterns are recurring archetypes in successful Unturned™ currency mods. Each pattern describes a proven combination of denomination values, formatting strings, and vendor integration that achieves a specific economic feel.

The modern cash economy ​

A straightforward cash economy modeled on real-world currency denominations. Values are chosen to make common vendor prices easily composable.

  • Currency items: $1 coin, $5 bill, $10 bill, $20 bill, $50 bill, $100 bill
  • ValueFormat: "${0:N0}"
  • DefaultConditionFormat: "${0:N0}/{1:N0}"
  • Suitable for: modern-setting RP servers, city maps, civilian trader networks
  • Denomination design principle: every value from 1 upward is composable from the available denominations

The post-apocalyptic ammunition barter ​

An economy where ammunition serves as currency. Ammunition types are assigned values based on their rarity and utility, and the currency format reflects the barter nature of the economy.

  • Currency items: 9mm round (value 1), 5.56mm round (value 3), 7.62mm round (value 5), shotgun shell (value 8), .50 cal round (value 20)
  • ValueFormat: "{0:N0} Rounds"
  • DefaultConditionFormat: "{0:N0}/{1:N0} Rounds"
  • Suitable for: survival servers, post-apocalyptic settings, military-themed RP
  • Denomination design principle: lower-value rounds serve as "small change" for cheap consumables; high-value rounds are the equivalent of large bills for expensive gear

The faction scrip system ​

An economy where a single item type serves as the faction's scrip or token. Only one item is in the currency, and its value is 1, every transaction is in whole units.

  • Currency items: Faction Scrip (value 1)
  • ValueFormat: "{0:N0} Scrip"
  • DefaultConditionFormat: "{0:N0}/{1:N0} Scrip"
  • Suitable for: faction-locked vendors, quest-reward-only obtainable currency
  • Design note: a single-denomination currency is simple but produces inventory clutter for large balances. Consider a higher-value scrip stack item (value 100) as a secondary denomination to reduce inventory footprint.

Complete currency design workflow ​

The cohort-validated workflow for designing and authoring a custom currency system:

  1. Decide the economic model. What does the currency represent in the game world? Cash, ammunition, bottle caps, faction scrip, digital credits?
  2. Choose denomination items. For each denomination, author a new item asset (or select existing vanilla items) to serve as the currency token. Each item needs a GUID, a name, and a visual model if the item is visible in the player's inventory.
  3. Assign denomination values. Choose integer values for each denomination. Design the value set so that every vendor price is composable.
  4. Write the .asset file. Define the Type, ValueFormat, DefaultConditionFormat, and Entries array with each item's GUID, value, and visibility flag.
  5. Link to vendors. Set each vendor's Currency field to the currency asset's GUID.
  6. Set vendor prices. Adjust every Buying_N_Cost and Selling_N_Cost on every vendor to reflect the new currency's value scale. A vendor that charged 500 experience points for an item might charge 50 currency for the same item.
  7. Test transactions. Use @give <currencyGUID>/<amount> to grant test currency, then buy and sell items at each vendor. Confirm prices display correctly and balances update correctly.
  8. Test edge cases. Test with zero currency (should show "0"), with exact amounts (should deduct exactly the right items), with large amounts (should be formatted with thousands separators), and with hidden denominations (their value should contribute to the total without appearing in the breakdown).

Frequently asked questions ​

Why does a currency asset use .asset format instead of .dat? ​

The currency asset has a nested data structure, the Entries array of item GUIDs paired with integer values, that the flat key-value .dat parser does not support. The .asset format is JSON-based and supports nested objects and arrays natively. The .asset format is used for a small number of asset types with complex internal structure; most NPC system assets use .dat.

Can I use any item as a currency denomination? ​

Yes. Any item with a valid GUID can serve as a currency denomination. The item does not need to be a special "currency type", a can of beans, a box of ammunition, or a custom token all function identically as currency denominations. The currency asset only cares about the item's GUID and the assigned value; the item's gameplay properties (whether it can be consumed, equipped, or stacked) are independent of its role as currency.

How many denominations can a currency have? ​

There is no hard limit on the number of entries in the Entries array, but practical considerations limit the useful number. Each denomination adds a line item to the vendor currency display (if visible). More than approximately eight visible denominations makes the vendor interface cluttered. Use Is_Visible_In_Vendor_Menu false to hide intermediate denominations that exist for conversion convenience but do not need to clutter the display.

What happens if two entries have the same value? ​

The vendor interface displays both entries as separate line items. The engine does not merge them or treat them as interchangeable, each is a distinct item with its own GUID. Two entries with the same value (for example, a $10 bill from the old currency and a $10 bill from the new currency) both contribute 10 to the player's total and both appear in the vendor display. This is occasionally useful for transitional currency systems where two item types coexist during a migration period.

Can a currency entry reference a consumable item? ​

Yes. The currency system does not prevent a currency-denomination item from being consumed through its normal item behavior. If a player eats a can of beans that is also a currency denomination, the player loses that currency value. This is either a feature (in a survival economy where food itself is currency) or a bug (in a modern cash economy where a player should not be able to eat their money). The cohort recommendation for non-consumable currency systems is to use items that are not consumable by their own item-type definition.

How does the engine choose which denominations to deduct? ​

The engine attempts to deduct the exact amount from the player's inventory using the largest available denominations first (a greedy algorithm). If the player has a $50 bill and a $20 bill, and the transaction costs 35, the engine may deduct the $50 bill and leave the change handling to the game's internal logic (which varies by version). The cohort recommendation is to design denomination sets that make exact deduction possible for all vendor prices.

Can a vendor use multiple currencies? ​

No. A vendor has a single Currency field that accepts one currency GUID. A vendor cannot accept payment in multiple currencies simultaneously. To create a vendor that accepts multiple forms of payment, use multiple vendor assets (each with a different currency) accessed from different dialogue responses, or use server-side plugin logic to handle multi-currency conversion if the plugin framework supports it.

What is the difference between ValueFormat and DefaultConditionFormat? ​

ValueFormat is used for every instance of displaying a single currency amount: the player's balance, item costs in the vendor interface, reward amounts in quest text. It contains only the {0} placeholder for the numeric value. DefaultConditionFormat is used when displaying a currency requirement alongside the player's current progress: "You have X out of Y required currency." It contains both {0} (the player's current total) and {1} (the required amount) placeholders. Both format strings support the standard C# numeric format specifiers.

How do I test that my currency works without setting up a full vendor? ​

Use the @give console command with the currency GUID and amount suffix: @give <currencyGUID>/<amount>. This grants the specified amount of currency directly to the player's inventory, bypassing the vendor entirely. The console command is the fastest way to verify that the currency asset loads correctly, that denomination items appear in the player's inventory, that the total value calculation is correct, and that the formatting strings produce the expected display.

Can I change a currency asset after the server has launched? ​

Yes. Currency asset changes take effect on the next server restart (or mod reload, if the server supports hot-reloading). Changing denomination values, adding or removing entries, or modifying formatting strings will affect all players and all vendors using that currency. The cohort recommendation is to test all currency changes on a staging server before applying them to a production server, because a denomination-value change can substantially alter the economic balance, an item that was worth 50 currency yesterday and is worth 5 currency today effectively deletes 90% of the currency's value from players who were holding that item.

Can I make a currency that uses items from vanilla Unturned? ​

Yes. The Entries[].Item.GUID field can reference any loaded item GUID, including vanilla items. A currency system based on vanilla ammunition items (9mm rounds, 5.56mm rounds, shotgun shells) works without any custom item mods -- only the currency .asset file is needed, plus vendor configuration. This is the fastest path to a custom currency for servers that do not want to author custom currency-item mods.

What happens when a player has currency items but the linked Currency asset is not loaded? ​

The vendor falls back to experience-point mode, and the currency items in the player's inventory are treated as ordinary items with no currency value. The vendor displays experience-point costs, and transactions use experience points. The player's currency items are not lost -- they remain in the inventory as ordinary items. When the Currency asset is loaded again (after a server restart with the correct mod), the items regain their currency value and the vendor switches back to custom-currency mode.

Can I use a currency with fractional values (decimal amounts)? ​

The Value field on each currency entry is an integer, so individual denomination values cannot be fractional. However, the ValueFormat string can display decimal places (using {0:N2} for two decimal places), and condition and reward amounts can be specified as fractional values. The underlying calculation is still integer-based -- a value of 0.5 in a condition would represent half of the base unit. For most currency systems, integer values and {0:N0} formatting produce the cleanest player experience.

The currency system imposes no mathematical relationship between denomination values. A currency could have denominations with values 1, 3, 8, 21, 55 (a Fibonacci-like progression), and the engine would handle conversion between them using the same greedy algorithm. Non-decimal denomination sets are harder for players to reason about (mental arithmetic with base-10 numbers is more intuitive), but they create interesting economic texture for servers where disorienting the player's economic intuition is a deliberate design choice -- a wasteland barter economy where nothing trades at predictable ratios.

How do quest rewards grant currency? ​

A quest reward of type Currency references the currency asset's GUID and specifies an amount. When the quest completes and the reward is processed, the engine grants currency items to the player's inventory with a total value matching the reward amount, using the largest available denominations. The reward amount should be designed to be composable from the currency's denominations. If the amount cannot be exactly composed, the engine behavior varies by version -- some round up, some round down, and some fail silently. The cohort practice is to use reward amounts that are clean multiples of the currency's smallest denomination.

Can I create a currency where denominations have no physical representation at all -- a purely digital balance? ​

The currency system requires at least one physical item as a denomination. There is no "virtual wallet" mechanism in the vanilla currency system. Every unit of currency is represented by an item in the player's inventory. Server operators who want a purely digital currency must implement it through a plugin framework (RocketMod or OpenMod) rather than through the currency .asset system. The closest vanilla approximation is to use a single invisible, non-droppable, non-consumable token item as the sole denomination, hidden from the vendor display via Is_Visible_In_Vendor_Menu false, so that players see only a total balance and not individual currency items in the interface. This approach still consumes one inventory slot per stack of tokens, which means high-wealth players will carry multiple stacks, but it achieves the visual appearance of a digital balance in the vendor interface alone.

Can I have currency items that are not transferable between players? ​

Currency denomination items follow the same transfer rules as any other item. If the item is droppable and tradeable (the default), players can transfer currency items to each other by dropping them or trading through the standard player-to-player trade interface. If you want non-transferable currency (a "bound" currency that stays with the character), configure the denomination items as non-droppable through the item's own .dat fields or through server-side restrictions. The currency .asset file does not control item transferability -- transferability is a property of the item asset, not the currency definition. For RP servers with per-character progression, bound currency prevents high-level characters from funneling wealth to new characters and preserves the intended progression arc.

Best practices ​

  • Design denomination values so that every vendor price is exactly composable from the available denominations.
  • Use {0:N0} format specifier for whole-number currency systems; use {0:N2} for decimal currency systems.
  • Set Is_Visible_In_Vendor_Menu false for high-value denominations that exist for inventory compactness rather than display clarity.
  • Choose currency items that are not consumable through their normal item behavior, unless the consumption is an intentional economic mechanic.
  • Test the denomination conversion logic with edge cases: exact amounts, amounts that require multiple denominations, and amounts that cannot be exactly composed.
  • Maintain consistent vendor pricing relative to the currency's value scale across all vendors that share the currency.
  • Document the currency denomination breakdown in the server's player guide so players understand which items have economic value.
  • Test currency grants through quest rewards and console commands before publishing to confirm amounts are correctly converted to denomination items.
  • Use a staging server for currency changes, a denomination-value change affects every player's wealth and the entire vendor economy.
  • Name currency item assets clearly so players can identify what serves as money. "Scrap Token" is clearer than "Token" when the item is in a mixed-loot inventory.
  • Design vendor price lists to use round numbers that are cleanly divisible by the available denominations. Avoid prices like 37 in a currency system with only 10-value and 5-value denominations, the player cannot pay exactly.
  • For currency systems with consumable denominations (food, ammunition), accept that players may accidentally or intentionally consume their money and design the economy around that fact, either by making denominations abundant enough that consumption is not punitive, or by using non-consumable token items.
  • Test the complete transaction lifecycle for every vendor and every currency amount before server launch: grant currency, buy an item, sell an item back, confirm the balance is correct after each step.
  • Document the currency system in the server's player-facing guide, including a list of which items are currency and their values, so new players understand what to look for in loot.

Appendix A: Currency .asset field quick reference ​

FieldTypeRequiredExamplePurpose
TypestringYesSDG.Unturned.ItemCurrencyAssetC# class name. Must be exactly this value.
ValueFormatstringYes"${0:N0} CAD"Display format for single currency values. {0} is the numeric value.
DefaultConditionFormatstringYes"${0:N0}/{1:N0} CAD"Default display format for currency conditions. {0} is current total, {1} is required amount.
Entries[].Item.GUIDstring (hex GUID)Yes"b6b87dfad5f342dc91bbb2de950f56ee"GUID of the item that serves as a currency denomination.
Entries[].ValueintegerYes"10"Numeric value of this denomination.
Entries[].Is_Visible_In_Vendor_MenuboolNo (default true)falseWhether this denomination appears in the vendor currency breakdown display.

Additional currency design patterns ​

The dual-currency economy ​

A server design in which two distinct currencies coexist, each used by a different set of vendors. One currency might be the "civilian" currency used by general-store vendors, while another is the "military" currency used by armory vendors. The two currencies are independent, civilian currency cannot be spent at military vendors and vice versa, creating two parallel economic loops that players navigate with different strategies.

Implementation: create two separate Currency assets, each with its own GUID. Assign civilian vendors (general stores, food vendors, clothing shops) to the civilian currency and military vendors (weapon dealers, vehicle depots, attachment specialists) to the military currency. A single NPC can access both economies through different dialogue responses, each opening a different vendor with a different currency.

The event-limited currency ​

A currency that is only obtainable during limited-time events and is only spendable at event-specific vendors. The currency items are added to loot tables during the event period and removed after. The event vendors are activated during the event period and deactivated after (or their dialogue responses are gated behind time-of-day or seasonal conditions). This pattern creates urgency and event engagement without permanently altering the server's base economy.

Implementation: author the currency .asset and the event vendor assets as part of the event mod content. Use seasonal conditions (Has_Halloween_Outfit on NPCs, time-of-day conditions on dialogue responses) to gate vendor access to the event period. After the event, the currency items remain in players' inventories as collectibles but are not spendable (the event vendors are closed), which creates a natural memorabilia economy without inflating the base currency.

The crafting-ingredient currency ​

A currency where the denomination items are also crafting ingredients for other recipes. A "Gold Nugget" might be worth 100 currency at vendors and also be a required ingredient in a high-tier crafting recipe. This creates an economic tension: should the player save gold nuggets for crafting, or spend them at vendors for immediate gear?

Implementation: author the gold nugget as a standard item with its normal gameplay properties (usable in crafting recipes) and also include it as a currency entry in the currency .asset file. The item functions normally in both roles, it can be spent at vendors, held as currency, or consumed in crafting recipes. The economic tension is emergent from the dual-purpose design and requires no additional configuration beyond the item and currency definitions.

Appendix B: Currency diagnostic table ​

SymptomMost likely causeResolution
Vendor shows experience points instead of custom currencyCurrency field on vendor is not set or references a non-loaded currency GUIDConfirm the vendor's Currency field exactly matches the currency asset's GUID
Currency items do not appear in vendor breakdownIs_Visible_In_Vendor_Menu is false for those itemsSet Is_Visible_In_Vendor_Menu true for items that should display
Currency display shows raw placeholder textValueFormat or DefaultConditionFormat has incorrect placeholder syntaxConfirm the format strings use {0} and {1} with valid C# format specifiers
@give with currency GUID does not workCurrency GUID is incorrect or the .asset file is not loadedConfirm the GUID matches the currency .asset file exactly; confirm the file is in the correct folder
Vendor transaction deducts a higher denomination than expectedDenomination set cannot exactly compose the transaction amountRedesign denominations or adjust vendor prices to be composable
Currency total shows wrong valueOne or more denomination Value integers are incorrectConfirm each entry's Value field matches the intended denomination value
Currency condition never evaluates to trueCondition references wrong currency GUID or requires an unachievable amountConfirm condition's currency GUID and required amount
Currency format does not show thousands separators{0:N0} is not used; plain {0} produces unformatted numbersChange format string to include :N0 for number formatting with separators
Currency .asset file fails to loadFile is not in the expected folder path or JSON syntax is malformedConfirm file path matches expected folder structure; validate JSON syntax for correct bracket and quote pairing
Game crashes when opening vendor with custom currencyCurrency asset GUID collision with another loaded assetRegenerate the currency asset GUID and update all vendor references
Vendor shows decimal values when whole numbers are expectedValueFormat uses {0:N2} (two decimal places)Change format to {0:N0} for zero decimal places
Currency items stack incorrectlyCurrency denomination items have incompatible stack-size settingsConfirm each denomination item's stack size is appropriate for its value tier; high-value denominations should have smaller stack sizes
Player has currency items but vendor still shows experience pointsMod containing the currency .asset file is not loaded on the serverConfirm the mod is subscribed and loaded; check server log for .asset loading errors
Denomination item appears in vendor breakdown when it should be hiddenIs_Visible_In_Vendor_Menu is true or the flag is missing from the entrySet "Is_Visible_In_Vendor_Menu" false in the entry's JSON object
Multiple currency assets with overlapping item GUIDs cause confused totalsTwo currency .asset files each claim the same item GUID as a denominationEnsure each item GUID appears as a denomination in only one currency asset

Appendix C: Currency denomination design reference ​

The table below provides the cohort-validated denomination value recommendations for common currency archetypes. Each row recommends a set of values that produce well-composable amounts for the target economic scale.

ArchetypeSmallest unitRecommended denominationsRationale
Modern cash (small scale)11, 5, 10, 20, 50, 100All values from 1-100 are composable. Familiar to players from real-world currency.
Modern cash (large scale)11, 5, 10, 25, 50, 100, 500, 1000Adds 25-cent piece and high-value denominations for expensive gear.
Ammunition barter (tight)11, 3, 5, 10, 25Lower value ceiling; suited for scarce-resource survival servers.
Ammunition barter (generous)11, 5, 10, 25, 50, 100Higher ceiling; suited for military-loot servers with expensive vehicles.
Token/scrip system11, 10, 100Simple three-denomination set; clean multiples minimize conversion complexity.
Casino chip economy11, 5, 25, 100, 500Non-decimal middle denominations (25 instead of 20) create a casino feel.
Wasteland barter11, 2, 3, 5, 8, 13, 21Fibonacci-like progression; intentionally harder to reason about, suits disorienting post-apocalyptic tone.

The archetypes above are starting points, not prescriptive requirements. A server's economic scale -- the typical cost of a basic item versus an endgame item -- determines whether the denomination set's ceiling is appropriate. A server where a bandage costs 5 currency and a helicopter costs 50,000 currency needs denominations that span that range; a server where everything costs between 1 and 500 currency needs a tighter set.

Denomination stack-size considerations ​

Each currency denomination is an item in the player's inventory, and each item has a maximum stack size (the number of identical items that can occupy one inventory slot). Currency denominations with low values should have large stack sizes (e.g., a 1-value coin that stacks to 250) so that modest wealth does not consume excessive inventory space. Currency denominations with high values should have smaller stack sizes (e.g., a 1000-value bill that stacks to 10) as a natural balance lever: a player carrying 50,000 currency in high-value bills uses less inventory space than a player carrying the same amount in low-value coins.

The cohort-recommended stack-size guidelines by denomination value:

Denomination valueRecommended stack sizeRationale
1-5250Small change should not clog inventory.
10-25100Mid-value denominations; manageable inventory footprint.
50-10050Higher value; naturally rarer in the loot economy.
500+10Very high value; small stacks encourage converting wealth into items rather than hoarding currency.

These stack sizes are configured on the individual item assets that serve as currency denominations, not in the currency .asset file. The .asset file only references the items by GUID; the items' own .dat files control their stack size.

Appendix D: External references ​

Authoring checklist ​

  • [ ] Currency .asset file has Type SDG.Unturned.ItemCurrencyAsset on the first line
  • [ ] ValueFormat and DefaultConditionFormat strings are defined with valid C# format specifiers
  • [ ] Each currency entry has a valid item GUID, an integer Value, and a boolean Is_Visible_In_Vendor_Menu flag
  • [ ] All denomination values together can exactly compose every vendor price in the economy
  • [ ] At least one denomination is visible in the vendor menu (Is_Visible_In_Vendor_Menu true)
  • [ ] Denomination items are authored as item assets with appropriate names, stack sizes, and non-consumable behavior (unless consumption is intentional)
  • [ ] Currency GUID is referenced by at least one vendor's Currency field
  • [ ] Tested with @give <currencyGUID>/<amount> in single-player before server deployment

Document history ​

VersionDateAuthorNotes
1.02026-07-2657 StudiosInitial publication. Complete currency .asset format reference, entry-value pair system, formatting string syntax, vendor integration, condition and reward integration, console testing workflow, economic design patterns, denomination design reference, and diagnostic reference.

Cross-references ​

57 Studios logo with slogan

Beginner-friendly guides for Unturned modding, tools, publishing, server operations, and troubleshooting.

Learn

Getting StartedSteam SetupInstalling Unturned

Explore

ItemsSelf-HostingTroubleshootingHome

Built for Unturned creators, server staff, and 57 Studios™ contributors.

Copyright © 57 Studios™. All rights reserved. 57 Studios™, its branding, guides, and associated original content are protected by applicable copyright and trademark law.