Обзор схемы определений предметов

Базовая схема и типы предметов

Далее приведены базовые свойства, которые Steam воспринимает и интерпретирует. Они необходимы для корректного функционирования экономики, обменов, а также для отображения инвентаря. Многие из этих свойств совпадают со свойствами, возвращаемыми веб-API-функцией ISteamEconomy/GetAssetClassInfo.

Предмет (ItemDef) должен относиться к одному из следующих типов:

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

Подробная информация о том, как определить комплексные типы предметов, приведена ниже.

Свойства предметов (ItemDef)

Название	Описание
appid	Номер вашего приложения
name	Англоязычное название предмета. Вы можете задать перевод названия предметов на другие языки, используя следующий код в качества примера: name_english: "Hat" name_french: "Chapeau" См. допустимый список суффиксов, обозначающих языки, в разделе документации о локализации.
description	Англоязычное описание предмета. Вы можете задать перевод названия предметов на другие языки, используя следующий код в качества примера: description_english: "This is a tall hat" description_french: "Ceci est un chapeau haut de forme" См. допустимый список суффиксов, обозначающих языки, в разделе документации о локализации.
display_type	The Англоязычное описание «разновидности» предмета. Вы можете задать перевод описания разновидностей предметов на другие языки, используя следующий код в качества примера: display_type_english: "Weapon" display_type_french: "Arme" См. допустимый список суффиксов, обозначающих языки, в разделе документации о локализации.
itemdefid	Номер данного предмета. Для предметов не из мастерской значение должно быть меньше 1 000 000.
type	Внутреннее значение. ('item' | 'bundle' | 'generator' | 'playtimegenerator' | 'tag_generator')
bundle	(см. типы bundle или generator ниже)
promo	(см. раздел «Промо» ниже)
drop_start_time	Метка времени UTC - предотвратить выдачу промо-предметов до этого времени. Применимо, только если promo = manual (см. раздел «Промо» ниже)
exchange	(см. раздел «Обмены» ниже)
price	(см. раздел «Формат цен» ниже)
price_category	Предустановленная нами ценовая категория, благодаря которой можно не пересчитывать цену в другие валюты. (см. раздел «Формат цен» ниже)
background_color	Цвет фона в инвентаре (три пары шестнадцатеричных цифр).
name_color	Цвет названия в инвентаре (три пары шестнадцатеричных цифр).
icon_url	Ссылка на маленькую иконку предмета. Адрес должен быть общедоступным, поскольку серверы Steam будут совершать загрузку и кэширование. Рекомендуемый размер — 200 на 200 пикселей.
icon_url_large	Ссылка на большую иконку предмета. Адрес должен быть общедоступным, поскольку серверы Steam будут совершать загрузку и кэширование. Рекомендуемый размер — 2048 на 2048 пикселей..
marketable	Принимает значение false или true. Можно ли продать предмет другим пользователям Steam на Торговой площадке.
tradable	Принимает значение false или true. Можно ли обменять предмет.
tags	(см. Метки предметов инвентаря Steam)
tag_generators	Список номеров определений предметов параметра tag_generator, которые необходимо задать (см. Метки предметов инвентаря Steam)
tag_generator_name	Название метки токена категории (см. Метки предметов инвентаря Steam)
tag_generator_values	Список значений меток и вероятность их выбора (см. Метки предметов инвентаря Steam)
store_tags	Строка с метками, разделёнными точкой с запятой. Эти метки используются для фильтрации предметов в магазине предметов приложения.
store_images	Ссылки на изображения, разделённые точкой с запятой. Эти изображения будут проксированы и использованы на странице в магазине предметов вашего приложения.
game_only	Принимает значение false или true. Если true, предмет не будет отображаться в инвентаре пользователя, и о его получении не будет уведомления. Подходит для случаев, когда выданные предметы используются сразу.
hidden	Принимает значение false или true. Если true, предмет не будет виден пользователям и его нельзя будет приобрести. Подходит для случаев, когда нужно скрыть предметы, которые пока не используются или находятся в разработке.
store_hidden	Принимает значение false или true. Если true, предмет будет скрыт в магазине предметов вашего приложения. По умолчанию все предметы, для которых заданы цены, показываются в магазине.
use_drop_limit	Принимает значение false или true. Если true, тогда заданное в drop_limit значение используется для ограничения количества предметов, выдаваемых с помощью ISteamInventory::TriggerItemDrop. См. раздел «Выдача предметов за игровое время» ниже.
drop_limit	Целое число. Ограничивает число выдач предмета с помощью ISteamInventory::TriggerItemDrop для конкретного пользователя. Если равно нулю, выдача предмета прекратится. См. раздел «Выдача предметов за игровое время» ниже.
drop_interval	Целое число. Игровое время в минутах, по истечении которого предмет может быть выдан пользователю. См. раздел «Выдача предметов за игровое время» ниже.
use_drop_window	Принимает значение false или true. Если true, тогда между выдачами предмета будет перерыв, заданный параметром drop_window. См. раздел «Выдача предметов за игровое время» ниже.
drop_window	Целое число. Время в минутах, которое должно пройти с предыдущей выдачи, прежде чем пользователю будет выдан предмет. См. раздел «Выдача предметов за игровое время» ниже.
drop_max_per_window	Целое число. Максимальное число выдач в пределах разрешённого периода, после которого начнёт действовать перерыв. По умолчанию равно 1. См. раздел «Выдача предметов за игровое время» ниже.
granted_manually	Принимает значение false или true. Если true, предмет будет выдаваться только при вызове AddPromoItem() или AddPromoItems(), где явно указан номер itemdefid. В противном случае выдача может происходить при вызове 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 значение записывается как набор параметров предметов, разделённых точкой с запятой. Каждый набор параметров содержит номер предмета itemdefid, после которого опционально может следовать разделитель «x» и количественное значение.

Если количественное значение не задано, по умолчанию используется 1.

Формат bundle

Примеры 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 вызывающая сторона предоставляет список материалов, которые обмениваются на получаемый предмет. Сервер проверит каждый сценарий и выберет первый, которому соответствуют полученные материалы.

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

Формат обмена

Если количество не задано явно, то используется значение 1.

Пример обмена

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

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

• владение определённым AppID (в том числе и AppID дополнения);
  
• достижение;
  
• игровое время в приложении AppID;
  
• выдача вручную — клиент должен вызвать AddPromoItem с конкретным itemdefid.

Проверка промопредметов выполняется Steam, поэтому эти предметы могут быть безопасно запрошены у клиента (см. ISteamInventory::AddPromoItem). Для определения промопредмета укажите одно или несколько правил его выдачи в свойстве promo.

Обратите внимание, что промопредметы могут иметь тип bundle.

Промопредметы, выдаваемые вручную, также могут иметь интервал выдачи. Таким образом, вы можете выдавать по несколько предметов каждую неделю, если игрок выполняет какую-либо задачу (к примеру, внутриигровой квест). Чтобы воспользоваться этой функцией, укажите значения drop_start_time и drop_interval в определении предмета.

Промопредметы не выдаются за временное владение бесплатной игрой (во время бесплатных выходных, с помощью функции Family Sharing и так далее).

Формат правила промоакции

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

Время начала выдачи

Если установить время начала выдачи (drop_start_time), промопредмет не будет выдан до наступления этого момента. Это позволяет использовать код, который выдаёт предмет заранее. Формат временной метки — ISO 8601 в UTC: ГГГГММДДTЧЧММССZ. К примеру, 20050515T171151Z.

Выдача предметов за игровое время

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

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

Те же параметры можно указать при определении предмета. Значения, указанные при определении предмета, будут иметь приоритет над значениями, установленными для этого предмета на уровне приложения. Это позволяет задавать для каждого предмета отдельные параметры.

Если заданы какие-либо из параметров (drop_interval, use_drop_window, drop_window, drop_max_per_window), каждая выдача предметов типа playtimegenerator будет отслеживаться отдельно. Иными словами, если при определении предмета параметры выдачи НЕ указаны, тогда он будет выдаваться по тем же правилам, что и остальные предметы типа playtimegenerator, у которых также не указаны эти параметры, и все они будут подчиняться настройкам приложения. В противном случае, если параметры выдачи заданы при определении предмета, его выдача выполняется и отслеживается отдельно на уровне playtimegenerator, независимо от приложения и других предметов этого типа.

Пример выдачи предмета за игровое время

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. Значение 100 VLV эквивалентно 0,99 доллара США и конвертируется во все поддерживаемые валюты по курсу Valve.

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

Формат цен

<daterange> — в значении должно быть ровно 33 символа.

Список параметров daterange должен быть отсортирован по убыванию (сначала будущие даты).

Примеры цен

• price_category: 1;VLV100
  Ценовая категория задана с помощью таблицы валют Valve.
  
• price: 1;USD100
  (1 доллар США)
  
• price: 1;USD100,EUR080
  (1 доллар США или 0,8 евро)
  
• price: 1;USD100,EUR080;20130607T080000Z-20130606T080000ZUSD50,EUR40
  (1 доллар США или 0,8 евро, кроме 6 июня 2013 года, когда цена снижена до 0,5 долл. США / 0,4 евро)
  
• price: 1;USD100,EUR080;20130609T080000Z-20130606T080000ZUSD50,EUR40
  (1 доллар США или 0,8 евро, но с 6 июня 2013 года по 9 июня 2013 года цена снижена до 0,5 долл. США / 0,4 евро)

Продажа наборов

Набор предметов (bundle) можно продавать в магазине предметов. Входящие в набор предметы будут показаны во время оформления покупки, так что пользователь увидит список выдаваемых предметов. Правила возврата средств в Steam позволяют возвращать покупки в течение определённого времени, но все включённые в набор предметы должны по-прежнему находиться в инвентаре игрока и оставаться неизменёнными.

Цены на наборы

При задании цены стоит помнить о нескольких дополнительных действиях. Steam учитывает цены на отдельные предметы в составе набора, чтобы определить цену набора и равномерно распределить выручку с его продажи. Это определит размер выплат авторам предметов из мастерской. В наборе может сочетаться контент от различных авторов мастерской или ваш собственный контент.

Чтобы задать цену на набор предметов:

• Укажите цену для каждого предмета в наборе.
  
• Если какие-либо из содержащихся в наборе предметов не должны продаваться по отдельности, укажите для них параметр store_hidden
  со значением true.
  
• В поле price или price_category набора укажите простое значение цены (к примеру, VLV0).
  Эта цена не будет использоваться в магазине, но она необходима для обозначения того, что это предмет для продажи.
  
• Если хотите, задайте скидку на набор в значении параметра purchase_bundle_discount.

При желании вы можете указать точную цену набора в каждой валюте. При изменении цены на набор все заданные параметры purchase_bundle_discount будут проигнорированы. Но поскольку цены на отдельные предметы в наборе по-прежнему используются для пропорционального распределения выручки, их необходимо предоставить.

Чтобы изменить автоматически предложенную цену на набор:

• Укажите желаемую цену в поле набора price или price_category.
  
• Установите значение true для use_bundle_price у предметов в наборе.

Продажа предметов типа generator

Не пытайтесь продать предметы типа generator напрямую в магазине предметов.

Чтобы продать предмет со случайным содержимым (например, ящик), его необходимо определить как предмет простого типа item. Затем создайте предмет типа generator, который будет принимать предмет «ящик» как входное значение сценария обмена.

После покупки игрок может «открыть» этот «ящик», и тогда вы вызовете ISteamInventory::ExchangeItems для генерации предмета. С этого момента «ящик» нельзя будет вернуть, поскольку он открыт.

Таблица предустановленных цен VLV

Далее представлены текущие возможные значения, которые можно указать в поле price_category предмета.

Название	Цена в долларах США
VLV25	0,25 доллара США
VLV50	0,49 доллара США
VLV75	0,75 доллара США
VLV100	0,99 доллара США
VLV150	1,49 доллара США
VLV200	1,99 доллара США
VLV250	2,49 доллара США
VLV300	2,99 доллара США
VLV350	3,49 доллара США
VLV400	3,99 доллара США
VLV450	4,49 доллара США
VLV500	4,99 доллара США
VLV550	5,49 доллара США
VLV600	5,99 доллара США
VLV650	6,49 доллара США
VLV700	6,99 доллара США
VLV750	7,49 доллара США
VLV800	7,99 доллара США
VLV850	8,49 доллара США
VLV900	8,99 доллара США
VLV950	9,49 доллара США
VLV1000	9,99 доллара США
VLV1100	10,99 доллара США
VLV1200	11,99 доллара США
VLV1300	12,99 доллара США
VLV1400	13,99 доллара США
VLV1500	14,99 доллара США
VLV1600	15,99 доллара США
VLV1700	16,99 доллара США
VLV1800	17,99 доллара США
VLV1900	18,99 доллара США
VLV2000	19,99 доллара США
VLV2500	24,99 доллара США
VLV3000	29,99 доллара США
VLV3500	34,99 доллара США
VLV4000	39,99 доллара США
VLV4500	44,99 доллара США
VLV5000	49,99 доллара США
VLV6000	59,99 доллара США
VLV7000	69,99 доллара США
VLV8000	79,99 доллара США
VLV9000	89,99 доллара США
VLV10000	99,99 доллара США

Пример схемы определения предметов: