Документація Steamworks
Схема інвентарю Steam

Огляд схеми ItemDef

Базова схема й типи предметів

Це базові властивості, які Steam розуміє та інтерпретує і які необхідні для правильної роботи економіки, обміну та для показу інвентарю. Багато з цих властивостей ті ж самі, що повертаються у веб-API ISteamEconomy/GetAssetClassInfo.

ItemDef має бути одним із типів нижче:

НазваОпис
itemТип предмета, що знаходиться в інвентарі гравця.
bundleКомплект визначень предметів, для кожного з яких вказана кількість. Коли видається такий предмет, то він автоматично стає набором предметів, визначених у властивості bundle.
generatorПредставляє випадковий предмет. Надання цього предмету випадковим чином вибере один тип предмету з властивості bundle і створить екземпляр цього типу. (Наприклад: уявіть, що під час відкриття скрині створюється один із предметів, які можуть бути в ній).
playtimegeneratorОсоблива форма generator, яка може надаватися викликом ISteamInventory::TriggerItemDrop у застосунку.
tag_generatorОсобливе визначення предмета, яке застосовує позначки до екземплярів предметів (див. розділ про позначки предметів для докладнішої інформації).
Див. нижче подробиці щодо визначення складних типів предметів.

Властивості ItemDef

НазваОпис
appidID вашого застосунку.
назваАнглійська назва вашого предмета. Ви можете надати локалізовані версії назви вашого предмета за прикладом нижче:
name_english: "Hat" name_french: "Chapeau"0> name_ukrainian: "Капелюх"
Для інформації про правильні назви й суфікси мов дивіться розділ про локалізацію.
descriptionАнглійський опис вашого предмета.
Ви можете надати локалізовані версії опису вашого предмета за прикладом нижче:
description_english: "This is a tall hat" description_french: "Ceci est un chapeau haut de forme"0> description_ukrainian: "Це високий капелюх"
Про правильні назви й суфікси мов читайте в розділі про локалізацію.
display_typeАнглійський опис типу предмета.
Ви можете надати локалізовані версії типу вашого предмета за прикладом нижче:
display_type_english: "Weapon" display_type_french: "Arme"0> display_type_ukrainian: "Зброя"
Про правильні назви й суфікси мов читайте в розділі про локалізацію.
itemdefidID цього визначення предмета. Для предметів не з майстерні значення повинно бути нижчим за 1 000 000.
typeВнутрішнє значення. ('item' | 'bundle' | 'generator' | 'playtimegenerator' | 'tag_generator')
bundle(дивіться про комплект і генератор нижче)
promo(дивіться про промо-формат нижче)
drop_start_timeПозначка часу UTC не дозволяє видавати промо-предмети до цього часу. Застосовується, якщо promo = manual (дивіться про промо-формат нижче).
exchange(дивіться про формат обміну нижче)
price(дивіться про формат ціни нижче)
price_categoryПопередньо встановлена ціна, де ми обробляємо для вас значення різних валют. (дивіться про формат ціни нижче)
background_colorКолір тла в інвентарі у вигляді шести шістнадцяткових цифр.
name_colorКолір назви в інвентарі у вигляді шести шістнадцяткових цифр.
icon_urlПосилання на маленьку піктограму предмета. URL-адреса повинна бути загальнодоступна, бо сервери Steam здійснюватимуть завантаження й кешування. Рекомендований розмір: 200x200.
icon_url_largeПосилання на велике зображення предмета. URL-адреса повинна бути загальнодоступна, бо сервери Steam здійснюватимуть завантаження й кешування. Рекомендований розмір: 2048x2048.
marketablefalse або true. Чи можна цей предмет продавати іншим користувачам на ринку спільноти Steam.
tradablefalse або true. Чи можна цей предмет обмінювати з іншими користувачами в системі обміну Steam.
tags(див. розділ про позначки предметів)
tag_generatorsСписок ідентифікаторів визначень предметів параметра tag_generator, котрі необхідно застосувати (див. розділ про позначки предметів)
tag_generator_nameНазва позначка токена категорії (див. розділ про позначки предметів)
tag_generator_valuesСписок значень позначок і ймовірність їхнього вибору (див. розділ про позначки предметів)
store_tagsРядок із позначками, що розділені крапкою з комою «;». Ці позначки використовуватися для категоризації або фільтрування предметів у крамниці предметів Steam вашого застосунку.
store_imagesПосилання на зображення, розділені крапкою з комою «;». Ці зображення будуть за проксі й використовуватимуться на сторінці подробиць крамниці предметів вашого застосунку.
game_onlyfalse або true. Якщо true, то предмети не показуватимуться в інвентарі користувача в Steam, включно зі сповіщеннями про нові предмети. Зазвичай застосовується до наданих предметів, які одразу використовуються.
hiddenfalse або true. Якщо true, визначення предмета не буде показано користувачам, і цей предмет не можна буде придбати. Використовуйте це для приховання предметів, що не використовуються чи перебувають у розробці.
store_hiddenfalse або true. Якщо true, то предмет буде сховано в крамниці предметів Steam для вашого застосунку. Стандартно будь-які предмети з цінами показуватимуться в крамниці.
use_drop_limitfalse або true. Якщо true, вказане в drop_limit значення використовується для обмеження кількості предметів, що надаються за допомогою ISteamInventory::TriggerItemDrop (див. розділ про випадіння предметів за зіграний час)
drop_limitЦіле число. За допомогою ISteamInventory::TriggerItemDrop обмежує кількість предметів, які можуть випасти конкретному користувачу. Якщо встановити 0, цей предмет більше не випадатиме (див. розділ про випадіння предметів за зіграний час)
drop_intervalЦіле число. Ігровий час у хвилинах, який необхідний для видачі користувачу предмета. (див. розділ про випадіння предметів за час гри)
use_drop_windowfalse або true. Якщо true, тоді вказане в drop_window значення використовується для надання предмета. (див. розділ про випадіння предметів за зіграний час)
drop_windowЦіле число. Час у хвилинах, який має пройти від попереднього випадіння, перш ніж користувачу буде наданий новий предмет (див. розділ про випадіння предметів за зіграний час)
drop_max_per_windowЦіле число. Максимальна кількість предметів, які можна видати за дозволений проміжок часу до початку періоду очікування. Стандартне значення: 1 (див. розділ про випадіння предметів за зіграний час)
granted_manuallyfalse або true. Якщо true, то предмет видаватиметься лише за умови, що викликані AddPromoItem() чи AddPromoItems(), у яких чітко вказані ідентифікатори визначень предметів. В іншому випадку надання відбудеться через виклик GrantPromoItems(). Стандартно: false.
use_bundle_pricefalse або true. Дивіться розділ про продаж комплектів предметів нижче. Стандартно: false.
auto_stackfalse або true. Якщо true, то надавання предметів буде автоматично додано до єдиного набору відповідного типу. Надавання буде видиме у зворотних викликах інвентаря як зміна кількості. Стандартно: false.

Розширена схема

Ви також можете визначити будь-які додаткові властивості, які необхідні для вашої гри.

Використання визначень складних предметів

Типи предметів bundle і generator

Правила для bundle, generator і playtimegenerator визначаються полем bundle.

У випадку bundle описується тип і властивість предметів, що входять до комплекту.

У generator чи playtimegenerator ми описуємо типи можливих предметів і відносну вірогідність генерації кожного типу. Майте на увазі, що вірогідності не обов’язково повинні давати в сумі 100, хоча дотримуватися цього правила буде доречно.

Поле bundle виражається як набір параметрів предметів, що розділені крапкою з комою «;». Кожен рецепт складається з itemdef ID, а за ним необов’язково йдуть розділювач «x» і частота надання.

Якщо частота явно не вказана, то стандартним значенням є 1.

Формат bundle

bundle_def : item_recipe , { ";" , item_recipe } item_recipe : item_def , []

Приклади bundle

  • Надаємо по одному предмету 201, 202 і 203:
    type: bundle bundle: 201;202;203
  • Надаємо один екземпляр предмета 101 і п’ять екземплярів предмета 102:
    type: bundle bundle: 101x1;102x5
  • 90% імовірності надавання предмета 501, 9% — предмета 502 і 1% — предмету 503:
    type: generator bundle: 501x90;502x9;503x1
  • 90% імовірності надавання звичайного предмета, 10% — особливого.
    itemdefid: 600 name: Common generator type: generator bundle: 601;602;603;604;605 itemdefid: 700 name: Special generator type: generator bundle: 701;702;703;704;705 itemdefid: 800 name: Master generator type: generator bundle: 600x9;700x1

Зверніть увагу, як і в останньому прикладі, визначення bundle і generator можуть бути пов’язані. Під час надання складні типи предмета розкриваються, доки не лишається простий предмет.

Формули обміну

API ExchangeItems дозволяє вам визначати рецепти створення чи зміни предметів, які можна безпечно викликати з клієнта. Сервери Steam перевірять інвентар гравця й використають надані матеріали та видадуть цільовий предмет, якщо виконано вимоги.

Цільовий предмет може бути типу bundle чи generator.

Формула надається в полі exchange цільового предмета. Формула визначається як набір з одного чи більше рецептів, розділених крапкою з комою.

Кожен рецепт — це набір необхідних предметів-матеріалів, розділених комою.

Необхідні матеріали можна надати безпосередньо через itemdefid або позначку. Якщо кількість не вказано, то стандартне значення — 1.

Під час використання ExchangeItems викликач надає перелік предметів-матеріалів, які слід обміняти на цільовий предмет. Сервер перевірить кожен рецепт і обере перший, який відповідає наданим матеріалам.

Обміни гнучкі — за допомогою цих формул можна ключем відмикати скриню, створювати стильний предмет із кількох компонентів, перероблювати та покращувати предмети.

Формат обміну

<exchange>: <recipe> { ";" <recipe> } <recipe>: <material> { "," <material> } <material>: <item_def_descriptor> / <item_tag_descriptor> <item_def_descriptor>: <itemdefid> [] <item_tag_descriptor>: <tag_name> ":" <tag_value> []
Якщо не вказано чітко, то значення необхідної кількості стає 1.

Приклад формули

// необхідно одне з: // - один item#100 й один item#101; або // - п’ять item#102; або // - три item#103 і три item#104. "exchange":"100,101;102x5;103x3,104x3" // необхідна одна ліва рукавиця й одна права рукавиця: "exchange":"handed:left,handed:right" // потрібно три дерева (tree) і щось стильне (fancy): "exchange":"type:tree*3,quality:fancy" // необхідно: // - item#201 та item#202; або // - предмет зі стилем banana і предмет із вагою heavy "exchange":"201x1,202x1;flavor:banana,mass:heavy" // перероблює п’ять звичайних (common) артефактів на один особливий (special) артефакт: { "name":"special_generator", "type":"generator", "tags":"rarity:special", "bundle":...., "exchange":"rarity:common*5", ... }

Промопредмети

Промопредмети можна видавати гравцям на основі кількох критеріїв:

  • Володіння певним AppID (включно з AppID завантажуваного вмісту).
  • Досягнення.
  • Час гри в AppID.
  • Видано вручну: клієнт повинен викликати AddPromoItem із конкретним itemdef ID.

Перевірки промопредмета виконуються Steam, тож ці предмети можна безпечно запитати з клієнта, див. ISteamInventory::AddPromoItem. Для визначення промопредмета встановіть одне чи кілька правил у властивість promo визначення предмета.

Зверніть увагу, що промопредмети також можуть бути комплектом.

Промопредмети, що надаються вручну, можуть мати інтервал видачі. Наприклад, із допомогою цього ви можете видавати кілька предметів щотижня на основі того, чи виконав гравець якесь завдання (як-от внутрішньоігрове). Для використання цієї функції вкажіть значення drop_start_time і drop_interval у визначенні предмета.

Промопредмети не видаються за тимчасове володіння безкоштовною грою (включно з іграми, отриманими на безкоштовних вихідних, через сімейну бібліотеку тощо).

Формат промопредметів

<promo>: <rule> { ";" <rule> } <rule>: app_rule / ach_rule / played_rule / manual_rule <app_rule>: "owns:" <appid> <ach_rule>: "ach:" <achievement name> <played_rule>: "played:" <appid>/<minutes played, defaults to 1> <manual>: "manual"

Приклади промопредметів

// просте визначення промопредмета: "promo":"owns:440;owns:480" // зіграв щонайменше 15 хв на appid 570: "promo":"played:570/15" // використовуваний предмет, який можна видавати раз на тиждень: "itemdefid": 404, "type": "item", "name": "Weekly Quest Item", "promo": "manual", "drop_start_time": "20170801T120000Z", "drop_interval": 10080, ...

Час початку випадіння

Якщо встановити час початку випадіння предмета, то предмет не випадатиме до цього часу. Це дозволяє використовувати код, який видає предмет зарання. Формат часової позначки — ISO 8601 у зоні UTC: YYYYMMDDTHHMMSSZ. Наприклад: 20050515T171151Z.

Випадіння предметів за зіграний час

Функція випадіння предметів за зіграний час дозволяє серверам Steam відстежувати й видавати предмети на основі часу, що гравець проводить у грі. Вашій грі потрібно лише викликати ISteamInventory::TriggerItemDrop у той момент, коли, як ви вважаєте, настала пора видавати предмет. Для виконання необхідно створити предмети типу playtimegenerator.
Надання за ігровий час керується застосунком. Немає підтримки автоматичного надання виключно на основі зіграного часу. Іншими словами, ігровий час — це умова для видачі, але викликає подію надання сам застосунок.

Частота видання предметів контролюється на рівні застосунку в розділі «Спільнота» → «Служба інвентарю» → «Надання предметів за зіграний час». Там можна зробити такі пристосування:
(1) Скільки часу в грі має пройти перед наданням?
(2) Скільки предметів надати за вказаний інтервал часу? і
(3) Скільки часу в грі має пройти до того, як видати ще один предмет?

Ті ж параметри можна вказати під час визначення предмета. Такі значення будуть мати пріоритет над тими, що встановлені для цього предмета на рівні застосунку. Це дозволяє будь-якому предмету мати власні параметри.

Кожне надання генератора відстежується окремо, якщо вказані якісь параметри надання ('drop_interval', 'use_drop_window', 'drop_window', 'drop_max_per_window'). Іншими словами, якщо itemdef НЕ має налаштувань випадіння, тоді налаштування випадіння цього предмета будуть збігатися з налаштуванням інших предметів типу playtimegenerator, у яких також не вказані ці параметри, й усі вони обмежуватимуться інтервалом випадіння застосунку. Інакше, якщо itemdef безпосередньо визначає налаштування випадіння, то надання цього предмета відстежується окремо на рівні playtimegenerator, незалежно від застосунку й інших предметів цього типу.

Приклад надання ItemDef за зіграний час

  1. Дозволяємо гравцю отримати предмет після 30 хвилин ігрового часу. Недолік такого налаштування полягає в тому, що він дозволяє гравцям
    фармити цей предмет, оскільки кожні 30 хвилин вони матимуть право на отримання. Ми наполегливо рекомендуємо додати мінімальний час, який має пройти до наступного надання:
    "drop_interval" : 30
  2. Обмежуємо наданням одного предмета на день після 30 хвилин гри. Це дає нагороду гравцям кожного дня, коли вони повертаються до вашої гри.
    "drop_interval" : 30,
    "use_drop_window" : "true",
    "drop_window" : "1440"

  3. Дозволяємо гравцю отримати три предмети на день після 90 хвилин ігрового часу. Безперервно грати необов’язково. Це налаштування винагороджує тривалу гру.
    "drop_interval" : 30,
    "use_drop_window" : "true",
    "drop_window" : "1440",
    "drop_max_per_window" : "3"
Якщо під час визначення предмета пропущено певне налаштування, то воно буде замінене вказаним у застосунку.

Обмеження випадінь

Змінна drop_limit дозволяє обмежити максимальну кількість випадінь для того чи іншого предмета типу generator.
Ви можете також обмежити кількість генерувань предмета (наприклад, лише перший раз, коли гравці пройшли гру на рівні легендарної складності).
Також можна використати для недопущення подальших випадінь застарілого предмета, якщо значення прирівняти до нуля. Ми беремо до уваги це налаштування, тільки якщо значення use_drop_limit є true.

Продаж предметів

Щоби виставити ігрові предмети на продаж, просто визначте ціни чи цінові категорії відповідних предметів.
Докладніша інформація про ввімкнення й налаштування вашої сторінки знаходиться в розділі про крамницю предметів.

Визначення цін

Ціни предметів можна визначити в одному з полів нижче, але не в обох.
НазваОпис
priceВизначає конкретну ціну для кожної валюти. Усі невизначені валюти будуть автоматично конвертовані під час придбання.
price_categoryВизначає одну ціну, котра буде переведена в кожну підтримувану валюту, що використовує таблицю конвертації валют Valve.

Поле price_category вказується у валюті VLV. VLV100 — еквівалент 0,99 долара США, що конвертується у всі підтримувані валюти за курсом конвертації Valve.

Курс конвертації VLV враховує періодичні коливання курсів валют. Ми оновлюємо ціни за необхідністю, ігноруючи дрібні коливання, щоби користувачі мали стабільні ціни й позитивний досвід.

Формат цін

Price: <version>;<pricelist> Version: "1" <pricelist> : <originalprice>(;<price>)* <originalprice>: <currency><integer>(,<currency><integer)* <price>: (<daterange>)<currency><integer>(,<currency><integer)* <currency> 3 літери як "USD" <integer> сума в конкретній валюті <daterange>: YYYYMMDDTHHMMSSZ-YYYYMMDDTHHMMSSZ
<daterange> має бути рівно 33 символи.

Список параметрів dateranges має бути відсортований за спаданням (спершу майбутні дати).

Приклади цін

  • price_category: 1;VLV100
    Цінова категорія вказана з допомогою таблиці валют Valve.
  • price: 1;USD100
    (1,00 долара США)
  • price: 1;USD100,EUR080
    (1,00 долара США або 0,80 євро)
  • price: 1;USD100,EUR080;20130607T080000Z-20130606T080000ZUSD50,EUR40
    (1,00 долара США або 0,80 євро за виключенням дат від 6/6/2013, коли ціну зменшено до 0,50 / 0,40 відповідно)
  • price: 1;USD100,EUR080;20130609T080000Z-20130606T080000ZUSD50,EUR40
    (1,00 долара США або 0,80 євро за виключенням дат від 6/6/2013 до 6/9/2013, коли ціну зменшено до 0,50 / 0,40 відповідно)

Продаж комплектів


Комплект предметів можна продавати в крамниці предметів. Предмети комплекту будуть вказані під час оформлення придбання, тож користувач побачить список наданих предметів. Політика відшкодування Steam дозволяє повертати придбання впродовж певного часу, але всі включені в комплект предмети повинні лишатися незмінними в інвентарі гравця.

Ціни на комплекти

Під час встановлення ціни на комплект слід обдумати деякі додаткові кроки. Steam використовує ціни на окремі предмети всередині комплекту для визначення ціни комплекту й рівномірного розподілу прибутку. Такий розподіл визначить обсяг виплат авторам предметів із майстерні. Один комплект може легко поєднувати вміст від різних авторів майстерні або включати вміст майстерні та ваш власний вміст.

Для встановлення ціни на комплект:
  • Вкажіть ціну на кожен предмет у комплекті.
  • Якщо якісь із предметів у комплекті не повинні продавати окремо, то вкажіть для них параметр store_hidden
    як true.
  • Встановіть для поля price чи price_category в комплекті просту ціну (як-от, VLV0).
    Ця ціна не використовуватиметься в крамниці, але вона необхідна, щоби крамниця предметів зрозуміла, що це предмет на продаж.
  • Необов’язково можна встановити purchase_bundle_discount для відсоткової знижки на комплект.

За бажанням можете вказати точну ціну комплекту в кожній валюті. Перезапис ціни на комплект ігнорує всі вказані вами значення purchase_bundle_discount. Однак ціни на окремі предмети в комплекті все ще використовуються для пропорційного розподілу прибутку, тому їх необхідно надати.

Для автоматичного перезапису ціни на комплект:
  • Вкажіть потрібну ціну в полі price чи price_category комплекту.
  • Встановіть use_bundle_price як true для предмета комплекту.

Продаж предметів-генераторів

Не намагайтеся продавати предмети типу generator безпосередньо в крамниці предметів.

Для продажу предмета з випадковим умістом (скарбниці) вам потрібно визначити його як звичайний предмет типу item. Потім створіть предмет generator, який буде приймати контейнер-скарбницю як введення для схеми обміну.

Після придбання гравець може «відімкнути» скарбницю, і в цей час ви викликаєте ISteamInventory::ExchangeItems для виконання generator. Після відмикання кошти за придбання скарбниці не повертаються.

Таблиця виставлених цін у VLV

Далі вказані поточні можливі значення, які можна вказати в полі price_category предмета.
НазваЦіна в доларах США (USD)
VLV250,25 USD
VLV500,49 USD
VLV750,75 USD
VLV1000,99 USD
VLV1501,49 USD
VLV2001,99 USD
VLV2502,49 USD
VLV3002,99 USD
VLV3503,49 USD
VLV4003,99 USD
VLV4504,49 USD
VLV5004,99 USD
VLV5505,49 USD
VLV6005,99 USD
VLV6506,49 USD
VLV7006,99 USD
VLV7507,49 USD
VLV8007,99 USD
VLV8508,49 USD
VLV9008,99 USD
VLV9509,49 USD
VLV10009,99 USD
VLV110010,99 USD
VLV120011,99 USD
VLV130012,99 USD
VLV140013,99 USD
VLV150014,99 USD
VLV160015,99 USD
VLV170016,99 USD
VLV180017,99 USD
VLV190018,99 USD
VLV200019,99 USD
VLV250024,99 USD
VLV300029,99 USD
VLV350034,99 USD
VLV400039,99 USD
VLV450044,99 USD
VLV500049,99 USD
VLV600059,99 USD
VLV700069,99 USD
VLV800079,99 USD
VLV900089,99 USD
VLV1000099,99 USD

Приклад схеми визначення предмета:

{ "appid": 480, "items": [ { "itemdefid": 10, "type": "playtimegenerator", "bundle": "100x100;101x50;102x25;103x2;110x20;111x20;120x5;121x3", "name": "Drop Generator", "name_color": "7D6D00", "background_color": "3C352E", "item_slot": "generator", "icon_url": "http://cdn.beta.steampowered.com/apps/440/icons/c_fireaxe_pyro_xmas_large.fa878752e1aa09a721a03042a234063b6c929278.png", "icon_url_large": "http://cdn.beta.steampowered.com/apps/440/icons/c_fireaxe_pyro_xmas_large.fa878752e1aa09a721a03042a234063b6c929278.png", "tradable": false, "marketable": false }, { "itemdefid": 100, "type": "item", "name": "Hat decoration", "description": "Hat decoration description", "price": "1;USD99", "name_color": "7D6D00", "background_color": "3C352E", "item_slot": "decoration", "icon_url": "http://cdn.beta.steampowered.com/apps/440/icons/c_fireaxe_pyro_xmas_large.fa878752e1aa09a721a03042a234063b6c929278.png", "icon_url_large": "http://cdn.beta.steampowered.com/apps/440/icons/c_fireaxe_pyro_xmas_large.fa878752e1aa09a721a03042a234063b6c929278.png", "tradable": true, "marketable": true }, { "itemdefid": 200, "type": "item", "price": "1;VLV100", "name_english": "Red Hat", "name_german": "Roter Hut", "description_english": "Red Hat", "description_german": "Roter Hut", "store_tags": "hat;featured", "icon_url": "http://cdn.beta.steampowered.com/apps/440/icons/c_fireaxe_pyro_xmas_large.fa878752e1aa09a721a03042a234063b6c929278.png", "icon_url_large": "http://cdn.beta.steampowered.com/apps/440/icons/c_fireaxe_pyro_xmas_large.fa878752e1aa09a721a03042a234063b6c929278.png", "tradable": true, "marketable": true } ] }