ItemDef 스키마 개요

코어 스키마 및 아이템 유형

Steam이 파악 및 해석하는 주요 속성으로 경제, 거래 및 보관함을 올바르게 표시하기 위해 필요한 부분들입니다. 많은 속성들이 ISteamEconomy/GetAssetClassInfo Web API에서 반환되는 속성들과 같습니다.

ItemDef는 다음 유형 중 하나여야 합니다.

이름	설명
item	사용자 보관함에서 찾아볼 수 있는 아이템 유형.
bundle	ItemDef 모음 및 각 유형과 연관된 수량을 나타냅니다. 이 아이템이 생성되면 bundle 속성에 구성된 일련의 아이템에 자동으로 확장됩니다.
generator	무작위 아이템을 나타냅니다. 이 아이템을 승인하면 bundle 속성에서 무작위로 아이템 유형 하나를 선택하여 해당 유형의 인스턴스를 생성합니다. (예: 상자 하나가 잠금 해제되면 다음 아이템 중 하나가 생성되는 상자)
playtimegenerator	애플리케이션이 ISteamInventory::TriggerItemDrop 호출을 통해 승인할 수 있는 특수 형태의 generator입니다.
tag_generator	아이템 인스턴스에 태그를 적용하는 특수 아이템 정의입니다(자세한 내용은 Steam 보관함 아이템 태그 참조).

복합 아이템 유형을 지정하는 방법에 대한 자세한 내용은 아래를 참조하세요.

ItemDef 속성

이름	설명
appid	애플리케이션의 ID
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	아이템의 ‘유형’에 대한 영어 설명. 다음 예시를 지침으로 활용하여 아이템 유형의 현지화 버전을 제공할 수 있습니다. display_type_english: "Weapon" display_type_french: "Arme" 접미사로 사용 가능한 언어 이름은 현지화 및 언어 문서를 참조하세요.
itemdefid	이 itemdef의 ID. 창작마당 아이템이 아닌 경우 1,000,000 미만이어야 합니다.
type	내부 값. ('item' | 'bundle' | 'generator' | 'playtimegenerator' | 'tag_generator')
bundle	(아래의 번들 혹은 생성자 아이템 참조)
promo	(아래의 프로모션 형식 참조)
drop_start_time	UTC 타임스탬프 - 이 시간이 되기 전에는 프로모션 배급을 방지하며, 프로모션을 수동으로 설정했을 때만 적용이 가능합니다(아래의 프로모션 형식 참조)
exchange	(아래의 교환 형식 참조)
price	(아래의 가격 형식 참조)
price_category	사전 설정 가격으로, 다양한 통화 값을 처리하는 곳입니다. (아래의 가격 형식 참조)
background_color	6자리 숫자로 보관함 배경에 표시할 색상을 나타냅니다.
name_color	6자리 숫자로 보관함 안의 이름을 표시할 색상을 나타냅니다.
icon_url	아이템의 작은 아이콘에 대한 URL. 이 URL은 Steam 서버가 다운로드 및 캐시하기 때문에 공개적으로 접근이 가능해야 합니다. 권장 규격은 200x200입니다.
icon_url_large	아이템의 큰 이미지에 대한 URL. 이 URL은 Steam 서버가 다운로드 및 캐시하기 때문에 공개적으로 접근이 가능해야 합니다. 권장 규격은 2048x2048입니다.
marketable	false/true. Steam 커뮤니티 장터에서 아이템을 다른 사용자에게 판매할 수 있는지 여부를 결정합니다.
tradable	false/true. Steam 거래를 통해 아이템을 다른 사용자에게 판매할 수 있는지 여부를 결정합니다.
tags	(Steam 보관함 아이템 태그 참조)
tag_generators	적용할 tag_generator 아이템 정의 ID의 목록(Steam 보관함 아이템 태그 참조)
tag_generator_name	태그 카테고리 토큰의 이름(Steam 보관함 아이템 태그 참조)
tag_generator_values	태그값 및 선택될 확률의 목록(Steam 보관함 아이템 태그 참조)
store_tags	';'으로 구분된 '태그'가 있는 문자열. 이 태그는 앱의 Steam 아이템 상점에 있는 아이템을 분류/필터하는 데 사용됩니다.
store_images	';' 문자로 구분되는 이미지 URL. 이러한 이미지는 프록시 처리되어 앱을 위한 Steam 아이템 상점의 자세한 정보 페이지에 사용됩니다.
game_only	false/true. If true, then items will not be shown in the user's Steam Backpack, including new item notifications. Common uses for this are items that you grant, that are immediately consumed.
hidden	false/true. If true, the item definition will not be shown to clients or purchasable. Use this to hide unused, or under-development, itemdefs.
store_hidden	false/true. If true, this item will be hidden in the Steam Item Store for your app. By default, any items with a price will be shown in the store.
use_drop_limit	false / true . If true, then we rely on drop_limit to limit the items grant via ISteamInventory::TriggerItemDrop. (아래의 플레이시간 아이템 드롭 참조)
drop_limit	정수. Limits for a specific user the number of times this item will be dropped via ISteamInventory::TriggerItemDrop. Setting to zero will prevent any future drops of this item. (아래의 플레이시간 아이템 드롭 참조)
drop_interval	integer . Playtime in minutes before the item can be granted to the user. (아래의 플레이시간 아이템 드롭 참조).
use_drop_window	false / true . If true, we will use the "drop_window" for this itemdef. (아래의 플레이시간 아이템 드롭 참조).
drop_window	정수. Elapsed time in minutes of a cool-down window before we will grant an item. (아래의 플레이시간 아이템 드롭 참조).
drop_max_per_window	integer . Numbers of grants within the window permitted before Cool-down applies. Default value is 1. (아래의 플레이시간 아이템 드롭 참조).
granted_manually	false/true. If true, will only be granted when AddPromoItem() or AddPromoItems() are called with the explicit item definition id. Otherwise, it may be granted via the GrantPromoItems() call. Defaults to false.
use_bundle_price	false/true. See selling bundle items below. Defaults to false.
auto_stack	false / true. If true, item grants will automatically be added to a single stack of the given type. Grants will be visible in inventory callbacks as quantity changes. Defaults to false.

확장 스키마

게임에 필요한 추가 속성들을 정의할 수 있습니다.

복합 아이템 정의 사용하기

번들 및 생성자 아이템 유형

번들, 생성자, 플레이 시간 생성자 규칙은 bundle 필드로 정의됩니다.

번들의 경우 포함된 아이템의 유형과 수량을 설명합니다.

생성자 및 플레이 시간 생성자의 경우, 생성 가능한 아이템의 유형과 각 유형의 상대적 비중을 설명합니다. 100 이하의 비중를 사용하는 것이 편리하지만 반드시 요구되지는 않습니다.

bundle 필드는 ";"으로 구분된 일련의 아이템 레시피로 표현됩니다. 각 레시피는 itemdef Id로 구성되며 선택적으로 "x" 구분자와 원하는 수량을 추가할 수 있습니다.

수량이 분명하게 제시되지 않을 경우, "1"이 기본값으로 사용됩니다.

번들 형식

번들 예시

• itemdef 201, itemdef 202, itemdef 203을 하나씩 제공:
  
  type: bundle bundle: 201;202;203
• itemdef 101 인스턴스 한 개, itemdef 102 인스턴스 다섯 개를 제공:
  
  type: bundle bundle: 101x1;102x5
• 90% 확률로 itemdef 501, 9% 확률로 itemdef 502, 1% 확률로 item 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

마지막 예시를 보면 번들 및 생성자 정의가 연결될 수 있음을 알 수 있습니다. 주어진 시간 안에, 복합 아이템 유형은 단순 itemdefs만 남을 때까지 확장을 반복합니다.

교환 수식

ExchangeItems API를 사용하면 클라이언트에서 안전하게 호출할 수 있는 아이템 제작/변환 레시피를 정의할 수 있습니다. Steam 서버는 플레이어 보관함을 확인하고 주어진 자료를 원자적으로 소모하며 요구 사항을 충족하는 경우 대상 아이템을 부여합니다.

대상 아이템이 번들 및 생성자 정의가 될 수 있습니다.

수식은 대상 아이템의 exchange 필드에서 확인할 수 있습니다. 수식은 세미콜론으로 구분된 하나 이상의 레시피 세트로 지정됩니다.

각 레시피는 쉼표로 분리된 필수 자료 아이템의 세트입니다.

필수 자료들은 itemdefid 또는 태그를 통해 명시적으로 제공할 수 있습니다. 수량이 주어지지 않은 경우, 1이 기본값으로 사용됩니다.

ExchangeItems을 사용할 때 호출자는 대상 아이템과 교환할 자료 목록을 제공합니다. 서버는 각 레시피를 확인한 후 주어진 자료 목록으로 만족되는 첫 레시피를 선택합니다.

유동적인 교환 - 키로 상자를 열고, 부품으로 멋진 아이템을 만들고, 아이템을 재활용하고 업그레이드하는 모든 작업을 이 수식을 이용해 수행할 수 있습니다.

교환 형식

명확하게 주어지지 않은 경우, 필요한 수량은 1입니다.

교환 예시

프로모션 아이템

프로모션 아이템은 다음 몇 가지 기준에 따라 플레이어에게 지급할 수 있습니다.

• appid(DLC appid 포함)의 소유권
  
• 도전 과제
  
• appid 플레이 시간
  
• 수동 지급 - 클라이언트가 지정된 아이템 def ID를 보유한 AddPromoItem을 호출해야 합니다.

프로모션 아이템은 Steam에서 확인하므로 클라이언트가 안전하게 요청할 수 있습니다. ISteamInventory::AddPromoItem 문서를 참조하시기 바랍니다. 프로모션 아이템을 정의하려면 아이템 정의의 "promo" 속성에서 아이템 지급에 관한 하나 이상의 규정을 설정하세요.

프로모션 아이템 또한 번들일 수 있습니다.

수동으로 지급하는 프로모션 아이템에는 드롭 간격을 추가할 수 있습니다. 이 방법을 사용하면 매주 몇 가지 작업(예: 게임 내 퀘스트)을 완료한 플레이어에게 아이템을 지급할 수 있습니다. 이 기능을 사용하려면 itemdef에서 drop_start_time과 drop_interval 값을 설정하세요.

프로모션 아이템은 임시로 소유하고 있는 무료 게임(무료 주말, 가족 공유 게임 등)에서는 제공되지 않습니다.

프로모션 규정 형식

프로모션 예시

드롭 시작 시간

프로모션 아이템의 드롭 시작 시간을 설정하면 아이템이 해당 시간 전에 지급되는 것을 막을 수 있습니다. 또한 코드를 배치해 시작 시간 전에 아이템을 지급할 수 있습니다. 타임스탬프는 UTC 시간대의 ISO8601 형식인 YYYYMMDDTHHMMSSZ로 명시해야 합니다. 예: 20050515T171151Z.

플레이 시간 아이템 드롭

플레이 시간 아이템 드롭 기능은 Steam 서버가 사용자의 플레이 시간에 따라 아이템 드롭을 관리하고 추적할 수 있게 해줍니다. 게임에서 지급할 시기에 ISteamInventory::TriggerItemDrop을 호출하면 됩니다. 드롭을 실행하려면 아이템의 ‘playtypegenerator’유형을 생성해야 합니다.
플레이 시간 지급은 귀하의 애플리케이션으로 제어됩니다. 사용자의 플레이 시간에만 기반하여 자동 지급하는 지원 기능은 없습니다. 즉 플레이 시간은 지급의 조건이라는 뜻이며 애플리케이션이 지급 평가를 트리거합니다.

아이템 드롭 빈도는 커뮤니티->보관함 서비스->플레이 시간 아이템 드롭 섹션의 애플리케이션 레벨에서 제어할 수 있습니다. 다음 사용자 정의가 가능한 세 가지 제어 항목이 있습니다.
(1) 아이템 드롭까지 얼마나 걸립니까?
(2) 한 창에 얼마나 많은 아이템이 드롭됩니까? 그리고
(3) 또 다른 아이템을 드롭하기까지의 쿨다운 창 시간은 얼마입니까?

Itemdef마다 동일한 제어 항목이 존재합니다. 아이템에 설정된 값은 해당 아이템에 대한 애플리케이션의 모든 설정을 재정의할 것입니다. 이로써 각 아이템은 고유의 드롭률과 창당 최대 드롭, 쿨다운 창을 갖게 됩니다.

각 플레이 시간 generator 지급은 드롭 설정이 지정되면 별도로 트래킹됩니다('drop_interval', 'use_drop_window', 'drop_window', 'drop_max_per_window'). 다시 말해 itemdef에 드롭 설정이 없으면 드롭 설정이 없는 다른 모든 플레이 시간 generator와 드롭을 공유하고 애플리케이션 드롭 간격의 제약을 받게 됩니다. itemdef가 드롭 설정을 확실하게 명시할 경우, 해당 아이템의 드롭은 generator 레벨에서 별도로 지급/트래킹되며 애플리케이션이나 다른 itemdef 플레이 시간 generator에 구애받지 않습니다.

플레이 시간 ItemDef 지급 예시

1. 플레이 시간 30분 후 사용자에게 아이템이 지급되도록 허용. 이 설정만 하게 되면 30분마다 사용자가 플레이 시간 지급을 받을 자격이 되므로
   해당 아이템의 파밍을 허용한다는 단점이 있습니다. 다음과 같은 드롭 창 설정을 추가할 것을 적극 권장합니다.
   "drop_interval" : 30
   
2. 플레이 시간 30분 후 하루에 한 개의 드롭으로 한정. 이렇게 하면 사용자가 귀하의 타이틀을 플레이하러 올 때 매일 드롭을 지급합니다.
   "drop_interval" : 30,
"use_drop_window" : "true",
"drop_window" : "1440"
   
3. 최소 90분을 플레이할 경우 사용자가 매일 세 가지 아이템을 획득하도록 허용. 이 90분은 연속 플레이하지 않아도 됩니다. 이렇게 하면 오랜 플레이 시간에 보상을 줍니다.
   "drop_interval" : 30,
"use_drop_window" : "true",
"drop_window" : "1440",
"drop_max_per_window" : "3"

특정 itemdef 설정이 누락될 경우 애플리케이션에 정의된 설정을 기본값으로 합니다.

드롭 제한

drop_limit 변수는 특정 generator에 대한 최대 플레이 시간 지급을 허용합니다.
이것으로 아이템이 생성되는 시간을 제한할 수 있습니다(예: 전설 난이도에서 처음으로 게임을 끝냈을 때만).
값을 0으로 설정할 경우, 없어진 아이템이 미래에 드롭되는 것을 방지하는 데도 사용할 수 있습니다. use_drop_limit이 "true"로 지정된 경우에만 이 설정을 인정합니다.

아이템 판매

특정 게임 아이템을 판매 가능하게 하려면 적절한 itemdefs에 가격이나 가격 카테고리를 정의하면 됩니다.
상점 페이지의 사용자 정의 및 활성화에 대한 내용은 Steam 아이템 상점 문서를 참조하시기 바랍니다.

가격 명시

다음 필드 중 하나만 사용하여 아이템 가격을 정의할 수 있습니다.

이름	설명
price	각 통화의 구체적인 가격을 정의합니다. 정의되지 않은 모든 통화는 구매가 이루어질 때 자동으로 변환됩니다.
price_category	하나의 가격을 정하면 Valve가 관리하는 가격 책정표를 통해 지원되는 모든 통화로 표시됩니다.

price_category 필드는 특수 "VLV" 통화로 명시됩니다. VLV100은 $0.99 USD와 같으며 , Valve의 환산율을 사용하여 지원되는 모든 통화로 변환됩니다.

VLV 환산율은 통화 변동률에 맞춰지도록 신중하게 관리하고 있습니다. Steam은 필요할 때마다 가격을 업데이트하며 변동률을 최소화하여 고객에게 안정된 물가와 긍정적인 사용자 경험을 제공하고 있습니다.

가격 형식

<daterange> 정확히 33자여야 합니다.

daterages의 목록은 언제나 내림차순입니다(미래 날짜부터).

가격 예시

• 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 유로, 다만 2013년 6월 6일에 $0.50 / 0.40으로 할인)
  
• price: 1;USD100,EUR080;20130609T080000Z-20130606T080000ZUSD50,EUR40
  ($1.00 미국 달러 또는 0.80 유로, 다만 2013년 6월 6일부터 2013년 6월 9일까지 $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 아이템 판매

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

ItemDef 스키마 예시: