Огляд схеми ItemDef
Базова схема й типи предметів
Це базові властивості, які Steam розуміє та інтерпретує і які необхідні для правильної роботи економіки, обміну та для показу інвентарю. Багато з цих властивостей ті ж самі, що повертаються у веб-API
ISteamEconomy/GetAssetClassInfo.
ItemDef має бути одним із типів нижче:
Назва | Опис |
item | Тип предмета, що знаходиться в інвентарі гравця. |
bundle | Комплект визначень предметів, для кожного з яких вказана кількість. Коли видається такий предмет, то він автоматично стає набором предметів, визначених у властивості bundle . |
generator | Представляє випадковий предмет. Надання цього предмету випадковим чином вибере один тип предмету з властивості bundle і створить екземпляр цього типу. (Наприклад: уявіть, що під час відкриття скрині створюється один із предметів, які можуть бути в ній). |
playtimegenerator | Особлива форма generator , яка може надаватися викликом ISteamInventory::TriggerItemDrop у застосунку. |
tag_generator | Особливе визначення предмета, яке застосовує позначки до екземплярів предметів (див. розділ про позначки предметів для докладнішої інформації). |
Див.
нижче подробиці щодо визначення складних типів предметів.
Властивості ItemDef
Назва | Опис |
appid | ID вашого застосунку. |
назва | Англійська назва вашого предмета. Ви можете надати локалізовані версії назви вашого предмета за прикладом нижче: 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: "Зброя"
Про правильні назви й суфікси мов читайте в розділі про локалізацію. |
itemdefid | ID цього визначення предмета. Для предметів не з майстерні значення повинно бути нижчим за 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. |
marketable | false або true. Чи можна цей предмет продавати іншим користувачам на ринку спільноти Steam. |
tradable | false або true. Чи можна цей предмет обмінювати з іншими користувачами в системі обміну Steam. |
tags | (див. розділ про позначки предметів) |
tag_generators | Список ідентифікаторів визначень предметів параметра tag_generator, котрі необхідно застосувати (див. розділ про позначки предметів) |
tag_generator_name | Назва позначка токена категорії (див. розділ про позначки предметів) |
tag_generator_values | Список значень позначок і ймовірність їхнього вибору (див. розділ про позначки предметів) |
store_tags | Рядок із позначками, що розділені крапкою з комою «;». Ці позначки використовуватися для категоризації або фільтрування предметів у крамниці предметів Steam вашого застосунку. |
store_images | Посилання на зображення, розділені крапкою з комою «;». Ці зображення будуть за проксі й використовуватимуться на сторінці подробиць крамниці предметів вашого застосунку. |
game_only | false або true. Якщо true, то предмети не показуватимуться в інвентарі користувача в Steam, включно зі сповіщеннями про нові предмети. Зазвичай застосовується до наданих предметів, які одразу використовуються. |
hidden | false або true. Якщо true, визначення предмета не буде показано користувачам, і цей предмет не можна буде придбати. Використовуйте це для приховання предметів, що не використовуються чи перебувають у розробці. |
store_hidden | false або true. Якщо true, то предмет буде сховано в крамниці предметів Steam для вашого застосунку. Стандартно будь-які предмети з цінами показуватимуться в крамниці. |
use_drop_limit | false або true. Якщо true, вказане в drop_limit значення використовується для обмеження кількості предметів, що надаються за допомогою ISteamInventory::TriggerItemDrop (див. розділ про випадіння предметів за зіграний час) |
drop_limit | Ціле число. За допомогою ISteamInventory::TriggerItemDrop обмежує кількість предметів, які можуть випасти конкретному користувачу. Якщо встановити 0, цей предмет більше не випадатиме (див. розділ про випадіння предметів за зіграний час) |
drop_interval | Ціле число. Ігровий час у хвилинах, який необхідний для видачі користувачу предмета. (див. розділ про випадіння предметів за час гри) |
use_drop_window | false або true. Якщо true, тоді вказане в drop_window значення використовується для надання предмета. (див. розділ про випадіння предметів за зіграний час) |
drop_window | Ціле число. Час у хвилинах, який має пройти від попереднього випадіння, перш ніж користувачу буде наданий новий предмет (див. розділ про випадіння предметів за зіграний час) |
drop_max_per_window | Ціле число. Максимальна кількість предметів, які можна видати за дозволений проміжок часу до початку періоду очікування. Стандартне значення: 1 (див. розділ про випадіння предметів за зіграний час) |
granted_manually | false або true. Якщо true, то предмет видаватиметься лише за умови, що викликані AddPromoItem() чи AddPromoItems(), у яких чітко вказані ідентифікатори визначень предметів. В іншому випадку надання відбудеться через виклик GrantPromoItems(). Стандартно: false. |
use_bundle_price | false або true. Дивіться розділ про продаж комплектів предметів нижче. Стандартно: false. |
auto_stack | false або 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 за зіграний час
- Дозволяємо гравцю отримати предмет після 30 хвилин ігрового часу. Недолік такого налаштування полягає в тому, що він дозволяє гравцям
фармити цей предмет, оскільки кожні 30 хвилин вони матимуть право на отримання. Ми наполегливо рекомендуємо додати мінімальний час, який має пройти до наступного надання:
"drop_interval" : 30
- Обмежуємо наданням одного предмета на день після 30 хвилин гри. Це дає нагороду гравцям кожного дня, коли вони повертаються до вашої гри.
"drop_interval" : 30,
"use_drop_window" : "true",
"drop_window" : "1440"
- Дозволяємо гравцю отримати три предмети на день після 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) |
VLV25 | 0,25 USD |
VLV50 | 0,49 USD |
VLV75 | 0,75 USD |
VLV100 | 0,99 USD |
VLV150 | 1,49 USD |
VLV200 | 1,99 USD |
VLV250 | 2,49 USD |
VLV300 | 2,99 USD |
VLV350 | 3,49 USD |
VLV400 | 3,99 USD |
VLV450 | 4,49 USD |
VLV500 | 4,99 USD |
VLV550 | 5,49 USD |
VLV600 | 5,99 USD |
VLV650 | 6,49 USD |
VLV700 | 6,99 USD |
VLV750 | 7,49 USD |
VLV800 | 7,99 USD |
VLV850 | 8,49 USD |
VLV900 | 8,99 USD |
VLV950 | 9,49 USD |
VLV1000 | 9,99 USD |
VLV1100 | 10,99 USD |
VLV1200 | 11,99 USD |
VLV1300 | 12,99 USD |
VLV1400 | 13,99 USD |
VLV1500 | 14,99 USD |
VLV1600 | 15,99 USD |
VLV1700 | 16,99 USD |
VLV1800 | 17,99 USD |
VLV1900 | 18,99 USD |
VLV2000 | 19,99 USD |
VLV2500 | 24,99 USD |
VLV3000 | 29,99 USD |
VLV3500 | 34,99 USD |
VLV4000 | 39,99 USD |
VLV4500 | 44,99 USD |
VLV5000 | 49,99 USD |
VLV6000 | 59,99 USD |
VLV7000 | 69,99 USD |
VLV8000 | 79,99 USD |
VLV9000 | 89,99 USD |
VLV10000 | 99,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
}
]
}