Items Config Format

Overview

Items are the core building blocks of the inventory system. Each item has a unique identifier and a type that determines its behavior when obtained by a player.

To learn how the game interacts with the inventory service, see the .

Adding Items Config

To use items, you need to:

  1. Add item descriptions to the items config.

  2. Deploy configs to services.

The config supports up to 10,000 items.

Item Description Format

{
  "name_english": "Sword",
  "itemdefid": 1,
  "type": "item"
}

Fields

name_english string required

English name of the item. Used as fallback if a localized name is not available. Length: 1–64 characters.

itemdefid positive int required

Unique identifier of the item within the game. Used in recipes, generators, and bundles.

type string required

Type of the item. Determines its behavior when obtained.

Possible values:

  • item – A regular item that appears in the user’s inventory.

  • bundle – When obtained, immediately unfolds into a set of items defined in the bundle field.

  • generator – When obtained, issues one item randomly selected from the list in the bundle field.

  • delayedexchange – A special bundle with a non-zero lifetime.

    A delayedexchange item has the following characteristics:

    • Exists as a separate instance in the user’s inventory alongside regular items.

    • Must have the bundle and exchange fields filled in.

    • Cannot be marketable.

    • Must have a non-empty lifetime field. Upon expiration, it unfolds as a bundle.

    • During its lifespan, can be transformed back into the set of items it was created from.

Localization

name_{language} string optional

Localized name of the item. Length: 1–64 characters. If not set for a specific language, name_english is used. See Available Languages.

description_{language} string optional

Localized description of the item. Maximum 1024 characters. See Available Languages.

Available Localization Languages

arabic, brazilian, bulgarian, czech, danish, dutch, english, finnish, french, german, greek, hungarian, italian, japanese, koreana, norwegian, polish, portuguese, romanian, russian, schinese, spanish, swedish, tchinese, thai, turkish, ukrainian

Inventory Behavior

deprecated bool optional

If true, the item is hidden from the client and market, cannot be used in or obtained from crafting or bundle opening, and is excluded from dependency calculations when loading configs. Defaults to false.

hidden bool optional

If true, the item description is not sent to the client. Use this to hide unused or unfinished items. Defaults to false.

item_quality positive int optional

Quality level of the item.

lifetime string optional

Duration of the item’s lifespan after acquisition. Specified as a number followed by a unit suffix: s (seconds), m (minutes), h (hours), d (days), w (weeks). Maximum 16 characters. Example: 7d.

lifetime_modifier string optional

Optional Squirrel expression returning a multiplier for lifetime. The script receives a table s with keys in the format count_NNN, each containing the quantity of the corresponding item in the player’s profile. Maximum 512 characters.

expireAt string optional

Timestamp. After this date, the item is removed from the player’s inventory.

premium string optional

Duration of premium account time granted when the item is obtained. Uses the same format as lifetime: a number with a unit suffix (s, m, h, d, w).

bundle_hidden bool optional

If true, the list of items in the bundle is not sent to the client. Defaults to false.

meta JSON object optional

Arbitrary JSON data attached to the item. Use this to pass custom game-specific information to the client. Maximum 32768 characters.

Crafting

bundle array optional

Defines the items issued when this item is obtained. Used for bundle, generator, and delayedexchange types. See Bundle Format.

exchange string optional

Crafting recipes that produce this item. Maximum 4096 characters. See Exchange Format.

required_items string optional

Requirements for adding this item via the AddItem command. Maximum 512 characters. See Required Items Format.

Store

store_hidden bool optional

If true, the item is not displayed in the in-game store (GetItemPrices / ClnPurchaseItem API). Defaults to false.

store_tags object optional

Key-value tags for the store. Keys and values may contain letters, numbers, underscores, and hyphens. Keys must be unique.

"store_tags": { "category": "weapon", "rarity": "rare" }
price array optional

Price for selling the item through the store, per currency. Maximum 16 price elements. See Price Format.

limitOnPurchase non-negative int optional

Maximum number of this item a player can purchase through the store. Does not apply to items obtained through other means.

Purchases

granted_by_purch string (GUID) optional

GUID of the purchase on the purch server (real-money purchase) that triggers the issuance of this item. Multiple items can share the same GUID – all of them will be issued. Consider setting a reasonable tradable_delay_sec to prevent fraudulent resale of purchased items.

Market

Note

The market is not currently supported on GAP.

marketable bool optional

If true, the item can be sold on the market. Defaults to false.

market_hash_name string optional

String identifier used by the market. Maximum 128 characters. Allowed characters: letters, numbers, underscores, hyphens, and spaces.

If not set and marketable is true, copied from name_english. Once assigned, resists changes to avoid breaking market listings. If a change is necessary, transfer the item to a new config and update market_hash_name simultaneously. Multiple items can share the same market_hash_name, in which case they appear in the same market listing.

market_fee float optional

Commission fraction taken from the transaction on the exchange. Must be non-negative. Split between the exchange and beneficiaries.

tradable_delay_sec non-negative int optional

Time in seconds during which the item and any derivatives obtained through crafting cannot be sold by the player. The effective restriction is always rounded up to the nearest hour.

Example: an item purchased at 11:50 with a 15-minute delay cannot be sold until 13:00.

tags object optional

Key-value tags for the market. Keys and values may contain letters, numbers, underscores, and hyphens. Keys must be unique.

"tags": { "type": "decal", "quality": "common" }

Visuals

background_color string optional

Background color of the item icon in the inventory and on the market. 6-character hex format without #: RRGGBB. Example: ff0000.

name_color string optional

Name color of the item icon in the inventory and on the market. 6-character hex format without #: RRGGBB. Example: ffffff.

icon_url string (URL) optional

Image used in the inventory and on the market.

icon_url_large string (URL) optional

Higher-resolution image, typically at least 800×600 pixels. Intended for web use and large-image dialogs. If set to an empty string, icon_url is used as a fallback.

Exchange Format

This section describes the format of the exchange field.

Crafting recipes are listed separated by semicolons: recipe;recipe. Each recipe consists of one or more ingredients separated by commas: ingredient,ingredient.

An ingredient can be a single itemdefid, or a choice between multiple items [itemdefid1, itemdefid2]. To require multiple instances, append x and a quantity. When multiple choices are specified, items can be spent in any combination.

Recipes support the following optional flags:

  • premium – Requires an active premium account to craft.

  • unfiltered – Issues items from crafting even if the required_items condition is not met.

  • auxiliary – Marks the recipe as auxiliary, it will not be used to generate drop descriptions for its ingredients.

  • require=<requirement> – Restricts this recipe to trusted server use only via ExchangeItemsTrusted API.

  • req_items=<itemdefid+...> – Additional items required to use this recipe. Items are checked but not consumed. Separator: +.

  • req_unlocks=<unlock+...> – Unlocks required for this recipe. Supported comparisons: <, <=, ==, !=, >=, >. Separator: +. If no comparison is specified, >= 1 is assumed.

Example:

"[40110,40111]x3,40207,premium,unfiltered;100101,10001,require=SomeRequirement;40973,auxiliary;200132,req_items=40291x3+40295,req_unlocks=killer>=3+loser"

This defines four recipes:

  • [40110 or 40111] x3 + 40207, with premium required, unfiltered

  • 100101 + 10001, trusted server only with requirement SomeRequirement

  • 40973, auxiliary recipe

  • 200132, requires items 40291 x3 and 40295, and unlocks killer >= 3 and loser >= 1

Bundle Format

Bundles and Delayed Exchanges

For bundle and delayedexchange types, the bundle field lists items to issue with their quantities.

Format: itemdefid[xN];itemdefid[xN];...

Example: 40110x3;40207;40973 issues three instances of item 40110 and one each of 40207 and 40973.

Generators

For the generator type, the bundle field lists items with relative weights. Probability is calculated as weight / total_weight.

Example: 40110x3;40207;40973x16 — total weight is 20:

Item

Weight

Probability

40110

3

15%

40207

1

5%

40973

16

80%

Weights can be specified directly as percentages. In that case, ensure they sum to 100%.

Item Postfixes

Each item in a bundle can have an optional postfix controlling its issuance behavior.

Postfix

Name

Description

S

Shuffle

Issues the item using shuffling, guaranteeing issuance within a bounded number of attempts.

Recommended for items with drop probability up to 10%.

D

Disposable

Issues the item a limited number of times.

Format: itemdefidxWeightDLimit.

If no limit is specified, the item is issued once.

L

Looped

After issuing the item a set number of times, starts issuing it again from the beginning.

U

Unique

Issues the item only if the player does not already own it. Compatible with S.

SU

Shuffle + Unique

Combines shuffle and unique behavior.

Order matters: S must come before U.

Postfixes S, D, and L are mutually exclusive for a single item. Within a bundle, different items can use different postfixes.

The U postfix accepts optional additional items to check: itemdefidU[111,112]. If the player owns any of the listed items, the item will not be issued.

Warning

It is possible to construct a generator that can never issue anything – for example, by combining D and U postfixes without fallback items.

Examples:

40110x3;40207x96;40973
40110x3;4020x20;40973x2S
40110x3;4020x20D3;4021x10D;40973x2S;4022x20L2;4023x20L
1123U;2347U111;4021U[111,112];1212x3
1123x1SU;1212x3

Shuffle Calculation

Shuffle guarantees issuance within ceil(N × IntervalsPercent / 100) generations, where:

  • N = average attempts between drops with uniform distribution = ceil(total_weight / item_weight)

  • IntervalsPercent = multiplier from config based on drop probability: {'10': 160, '100': 400, '20': 200} (key = probability %, value = multiplier)

Example: item with weight 2 in a bundle of total weight 25 (8% drop). Since 8% < 10%, IntervalsPercent = 160. N = ceil(25/2) = 13. Maximum generations before guaranteed issuance: ceil(13 × 160 / 100) = 21.

Required Items Format

Defines requirements for issuing this item via the AddItem command, dropping it from bundles obtained through crafting, or crafting it directly. Does not apply to market or store purchases.

The format resembles a bundle, with additional logical operators:

Operator

Description

;

AND

,

OR

!

NOT

( )

Grouping

OR has higher precedence than AND: 1;2,3 is equivalent to 1;(2,3). Spaces are allowed anywhere except within an itemdefid.

Examples:

40110x3;40207x2;40973
(!5;6x2;3),(7x3;((3;!(5,4)),(5;4;!3)))

Price Format

The price field is an array of price elements. Each element defines either a base price or a time-limited price.

"price": [
  { "USD": 100, "EUR": 80 },
  { "start": "2013-06-06T08:00:00Z", "end": "2013-06-09T08:00:00Z", "USD": 50, "EUR": 40 }
]

Each price element can contain:

Field

Type

Description

start

string (ISO 8601 UTC)

Start of the discounted period.

end

string (ISO 8601 UTC)

End of the discounted period.

<CURRENCY>

non-negative int

Price in the given currency. Currency code must match the configured currencies.

Value is in the smallest unit (e.g. cents for USD): 100 = $1.00.

The first element without start/end defines the base price. Subsequent elements with start/end define time-limited prices.

Examples:

[{"USD": 100}] – $1.00.

[{"USD": 100, "EUR": 80}, {"start": "2013-06-06T08:00:00Z", "end": "2013-06-09T08:00:00Z", "USD": 50, "EUR": 40}] – $1.00 or €0.80, reduced to $0.50 or €0.40 from 2013-06-06 to 2013-06-09.