Panoramica sullo schema dell'elemento ItemDef

Schema di base e tipi di oggetti

Si tratta delle proprietà fondamentali comprese e interpretate da Steam, necessarie per il corretto funzionamento dell'economia, degli scambi e della visualizzazione dell'inventario. Molte di queste proprietà sono le stesse che vengono restituite dall'API web ISteamEconomy/GetAssetClassInfo.

Un ItemDef deve essere uno dei tipi seguenti:

Nome	Descrizione
item	Un tipo di oggetto che può essere trovato nell'inventario di un giocatore.
bundle	Rappresenta una raccolta di elementi ItemDef, con la loro quantità associata a ciascun tipo. Quando questo oggetto viene assegnato, si espande automaticamente nell'insieme di oggetti configurati nella proprietà bundle.
generator	Rappresenta un oggetto casuale. Quando viene assegnato un oggetto di questo tipo, viene selezionato un tipo di oggetto casuale dalla proprietà bundle e creata un'istanza di tale tipo. Ad esempio, immagina che sia come una cassa quando viene aperta e uno dei possibili oggetti viene creato.
playtimegenerator	Si tratta di una forma speciale di generator che può essere concessa effettuando la chiamata a ISteamInventory::TriggerItemDrop dall'applicazione.
tag_generator	Speciale definizione dell'oggetto che applica etichette alle istanze dell'oggetto (per maggiori dettagli, consulta la sezione Etichette degli oggetti dell'inventario di Steam).

Per i dettagli sulla definizione dei tipi di oggetti complessi, dai un'occhiata qui.

Proprietà dell'elemento ItemDef

Nome	Descrizione
appid	L'ID dell'applicazione.
name	Il nome in lingua inglese dell'oggetto. Puoi fornire versioni tradotte del nome dell'oggetto utilizzando l'esempio seguente come guida: name_english: "Hat" name_italian: "Cappello" Per i suffissi validi da usare per i nomi delle lingue, consulta la documentazione Localizzazione e lingue.
description	La descrizione in inglese dell'oggetto. Puoi fornire versioni tradotte della descrizione dell'oggetto utilizzando l'esempio seguente come guida: description_english: "This is a tall hat" description_italian: "Questo è un cappello a cilindro" Per i suffissi validi da usare per i nomi delle lingue, consulta la documentazione Localizzazione e lingue.
display_type	La descrizione in inglese del "tipo" di oggetto. Puoi fornire versioni tradotte del tipo di oggetto utilizzando l'esempio seguente come guida: display_type_english: "Weapon" display_type_italian: "Arma" Per i suffissi validi da usare per i nomi delle lingue, consulta la documentazione Localizzazione e lingue.
itemdefid	L'ID dell'elemento ItemDef. Questo valore deve essere inferiore a 1.000.000 per gli oggetti che non fanno parte del Worskhop.
type	Un valore interno ('item' | 'bundle' | 'generator' | 'playtimegenerator' | 'tag_generator').
bundle	Consulta la sezione Oggetti di tipo pacchetto o generatore di seguito.
promo	Consulta la sezione Formato della proprietà promo di seguito.
drop_start_time	Timestamp in formato UTC che impedisce l'assegnazione di oggetti promozionali prima dell'orario indicato. Applicabile solo quando la promozione viene impostata in modo manuale (consulta la sezione Formato della proprietà promo di seguito).
exchange	Consulta la sezione Formato di scambio di seguito.
price	Consulta la sezione Formato dei prezzi di seguito.
price_category	Un prezzo preimpostato, in cui gestiamo i vari valori di valuta al posto tuo. Consulta la sezione Formato dei prezzi di seguito.
background_color	Il colore da visualizzare sullo sfondo dell'inventario espresso come numero esadecimale a 6 cifre.
name_color	Il colore in cui visualizzare il nome nell'inventario espresso come numero esadecimale a 6 cifre.
icon_url	L'URL dell'icona piccola dell'oggetto. L'URL deve essere pubblicamente accessibile in quanto i server di Steam lo scaricheranno e lo memorizzeranno nella cache. La dimensione consigliata è di 200 pixel x 200 pixel.
icon_url_large	L'URL dell'immagine grande dell'oggetto. L'URL deve essere pubblicamente accessibile in quanto i server di Steam lo scaricheranno e lo memorizzeranno nella cache. La dimensione consigliata è di 2048 pixel x 2048 pixel.
marketable	Può essere "false" o "true". Indica se l'oggetto può essere venduto agli altri utenti nel Mercato della Comunità di Steam.
tradable	Può essere "false" o "true". Indica se l'oggetto può essere scambiato con altri utenti attraverso il sistema di scambio di Steam.
tags	Consulta Etichette degli oggetti dell'inventario di Steam.
tag_generators	Elenco degli ID di definizione dell'oggetto tag_generator da applicare (consulta Etichette degli oggetti dell'inventario di Steam).
tag_generator_name	Nome del token della categoria dell'etichetta (consulta Etichette degli oggetti dell'inventario di Steam).
tag_generator_values	Elenco dei valori dell'etichetta e relativa possibilità di essere selezionati (consulta Etichette degli oggetti dell'inventario di Steam).
store_tags	Stringa con le "etichette" delimitate dal carattere ";". Queste etichette verranno utilizzate per suddividere gli oggetti in categorie o applicare filtri nel Negozio di oggetti della tua applicazione.
store_images	URL di immagini delimitate dal carattere ";". Queste immagini verranno trasmesse e utilizzate nella pagina dei dettagli del Negozio di articoli Steam per la tua app.
game_only	Può essere "false" o "true". Se "true", allora gli oggetti non verranno mostrati nello zaino dell'utente di Steam, incluse le notifiche dei nuovi oggetti. Gli usi comuni per questa funzione sono oggetti assegnati e consumati immediatamente.
hidden	Può essere "false" o "true". Se "true", la definizione dell'oggetto non verrà visualizzata dai client e l'oggetto non sarà acquistabile. Utilizza questa proprietà per nascondere le definizioni dell'oggetto inutilizzate o in fase di sviluppo.
store_hidden	Può essere "false" o "true". Se "true", l'oggetto sarà nascosto dal Negozio di oggetti di Steam dell'applicazione. Per impostazione predefinita, tutti gli oggetti con un prezzo verranno visualizzati nel Negozio.
use_drop_limit	Può essere "false" o "true". Se "true", faremo affidamento su drop_limit per limitare l'assegnazione degli oggetti da ISteamInventory::TriggerItemDrop. Consulta la sezione Assegnazione di oggetti in base al tempo di gioco di seguito.
drop_limit	Un valore intero. Limita il numero di volte in cui l'oggetto potrà essere assegnato da ISteamInventory::TriggerItemDrop. L'impostazione di questo valore su zero eviterà che l'oggetto venga assegnato in futuro. Consulta la sezione Assegnazione di oggetti in base al tempo di gioco di seguito.
drop_interval	Un valore intero. Il tempo di gioco in minuti prima che l'oggetto possa essere assegnato all'utente. Consulta la sezione Assegnazione di oggetti in base al tempo di gioco di seguito.
use_drop_window	Può essere "false" o "true". Se "true", useremo "drop_window" per questo elemento ItemDef. Consulta la sezione Assegnazione di oggetti in base al tempo di gioco di seguito.
drop_window	Un valore intero. Intervallo di tempo in minuti prima che un oggetto venga assegnato. Consulta la sezione Assegnazione di oggetti in base al tempo di gioco di seguito.
drop_max_per_window	Un valore intero. Numero di assegnazioni concesse nel dato intervallo di tempo. Il valore predefinito è 1. Consulta la sezione Assegnazione di oggetti in base al tempo di gioco di seguito.
granted_manually	Può essere "false" o "true". Se "true", l'oggetto sarà assegnato solo quando AddPromoItem() o AddPromoItems() vengono chiamate con l'ID esplicito della definizione dell'oggetto. In caso contrario, l'oggetto può essere assegnato tramite la chiamata GrantPromoItems(). Valore predefinito: false.
use_bundle_price	false/true. Consulta la sezione Vendita di oggetti di tipo pacchetto di seguito. Valore predefinito: false.
auto_stack	Può essere "false" o "true". Se "true", le assegnazioni degli oggetti saranno aggiunte automaticamente a uno stack singolo del tipo determinato. Le assegnazioni saranno visibili nei callback dell'inventario come modifiche delle quantità. Valore predefinito: false.

Schema esteso

Puoi definire anche eventuali proprietà aggiuntive di cui hai bisogno specificatamente per il tuo gioco.

Uso di definizioni complesse degli oggetti

Oggetti di tipo pacchetto o generatore

Le regole per gli oggetti di tipo pacchetto, generatore o generatore in base al tempo di gioco vengono definite attraverso il campo bundle.

Per i pacchetti descriviamo il tipo e la quantità di oggetti contenuti al loro interno.

Per gli oggetti di tipo "generator" o "playtimegenerator", descriviamo i possibili tipi di oggetto da generare e il relativo peso di ciascun tipo. Tieni presente che non è necessario che la somma dei pesi sia 100, ma è più pratico.

Il campo bundle viene espresso come una serie di ricette dell'oggetto separate da ";". Ogni ricetta è costituita da un ID dell'elemento ItemDef, seguito facoltativamente da una "x", che svolge la funzione di separatore, e dalla quantità desiderata.

Se la quantità non viene indicata esplicitamente, per impostazione predefinita viene utilizzato il valore "1".

Formato del pacchetto

Esempi di pacchetti

• Assegna un itemdef 201, un itemdef 202 e un itemdef 203:
  
  type: bundle bundle: 201;202;203
• Assegna un'istanza di itemdef 101 e cinque istanze di istemdef 102:
  
  type: bundle bundle: 101x1;102x5
• Casuale: 90% di possibilità di ottenere itemdef 501, 9% di possibilità di ottenere itemdef 502, 1% di possibilità di ottenere l'oggetto 503:
  
  type: generator bundle: 501x90;502x9;503x1
• 90% di possibilità di ottenere un oggetto comune; 10% di possibilità di ottenere un oggetto speciale.
  
  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

Nota: come nell'ultimo esempio, le definizioni del pacchetto e del generatore possono essere concatenate. Al momento dell'assegnazione, tutti i tipi di oggetti complessi vengono espansi più volte fino a quando non rimane un semplice elemento ItemDef.

Formule di scambio

L'API ExchangeItems consente di definire ricette per la creazione/trasformazione degli oggetti che possono essere chiamate in modo sicuro dal client. I server di Steam controlleranno l'inventario del giocatore, consumeranno in maniera atomica i materiali forniti e assegneranno l'oggetto finale se i requisiti vengono soddisfatti.

L'oggetto finale può essere un tipo pacchetto o generatore.

La formula è fornita nel campo exchange dell'oggetto finale. La formula viene specificata come una serie di una o più ricette separate da punti e virgola.

Ogni ricetta è una serie di oggetti materiale obbligatori, separati da virgole.

I materiali richiesti possono essere assegnati in modo esplicito da itemdefid o in base all'etichetta. Se non viene indicata una quantità, viene presunta una quantità di 1.

Quando si usa ExchangeItems, il caller fornisce un elenco di oggetti materiale da scambiare per l'oggetto finale. Il server controllerà ogni ricetta e quindi sceglierà la prima soddisfatta dai materiali assegnati.

Gli scambi sono flessibili: queste formule consentono di utilizzare una chiave per aprire un forziere, di creare un oggetto fantasioso costruito con parti di ricambio diverse, nonché di riciclare e di aggiornare gli oggetti.

Formato di scambio

Se non è indicata esplicitamente, la quantità richiesta è 1.

Esempio di scambio

Oggetti promozionali

Gli oggetti promozionali possono essere assegnati ai giocatori in base a diversi criteri:

• Proprietà di un appID (incluso l'appID di un DLC)
  
• Un achievement
  
• Tempo di gioco registrato con un appID
  
• Assegnato manualmente: il client deve effettuare la chiamata a AddPromoItem con l'ID specifico della definizione dell'oggetto.

I controlli degli oggetti promozionali vengono eseguiti da Steam, pertanto gli oggetti possono essere richiesti in modo sicuro dal client. Consulta la sezione ISteamInventory::AddPromoItem. Per definire un oggetto promozionale, imposta una o più regole per l'assegnazione dell'oggetto nella proprietà "promo" della definizione dell'oggetto.

Tieni presente che anche un pacchetto può costituire un oggetto promozionale.

Gli oggetti promozionali che vengono assegnati manualmente possono presentare determinati intervalli di assegnazione. Ad esempio, utilizzando il parametro promo potresti assegnare alcuni oggetti ogni settimana a fronte del completamento di un compito da parte del giocatore, ad esempio una missione nel gioco. Per utilizzare questa funzione, imposta i valori drop_start_time e drop_interval nell'elemento ItemDef.

Gli oggetti promozionali non vengono assegnati per la proprietà temporanea di un titolo gratuito (inclusi i titoli dei weekend gratis, quelli a cui l'accesso è stato effettuato tramite la condivisione familiare, ecc.).

Formato della regola della proprietà promo

Esempi di promozioni

Orario di inizio dell'assegnazione

Impostando l'orario di inizio dell'assegnazione dell'oggetto promozionale, si eviterà di assegnarlo in un orario precedente a quello indicato. In questo modo è possibile implementare il codice per l'assegnazione dell'oggetto anticipatamente rispetto all'orario di inizio. Il timestamp deve essere specificato nel formato ISO 8601 nel fuso orario UTC: YYYYMMDDTHHMMSSZ. Ad esempio: 20050515T171151Z.

Assegnazione di oggetti in base al tempo di gioco

Questa funzione consente ai server di Steam di tenere traccia della distribuzione degli oggetti e di gestirla in base al tempo di gioco dell'utente. Quando desideri assegnare un oggetto nel gioco, è sufficiente effettuare la chiamata alla funzione ISteamInventory::TriggerItemDrop. Per effettuare l'assegnazione, dovrai creare oggetti del tipo "playtimegenerator".
L'assegnazione in base al tempo di gioco è controllata dalla tua applicazione. Le assegnazioni automatiche basate interamente sul tempo di gioco degli utenti non sono supportate. In altre parole, il tempo di gioco costituisce una condizione per l'assegnazione, ma questa viene tuttavia valutata e attivata dall'applicazione.

Il tasso di assegnazione degli oggetti può essere controllato a livello di applicazione attraverso la sezione raggiungibile da Comunità->Servizio dell'inventario->Distribuzione di oggetti in base al tempo di gioco. Puoi personalizzare il processo con tre controlli:
(1) Quanto tempo deve essere trascorso per distribuire un oggetto?
(2) Quanti oggetti vengono distribuiti in un intervallo?
(3) Qual è la durata di attesa della finestra prima di poter assegnare un altro oggetto?

Lo stesso controllo esiste per l'elemento ItemDef. I valori impostati sull'oggetto sovrascriveranno qualsiasi impostazione dell'applicazione per l'oggetto specifico. Ciò consente a ogni oggetto di disporre del proprio tasso di distribuzione, di un numero massimo per finestra e di un tempo di attesa.

Nel caso siano state applicate impostazioni alla distribuzione ("drop_interval", "use_drop_window", "drop_window", "drop_max_per_window"), ciascuna assegnazione del generatore in base al tempo di gioco verrà registrata separatamente. In altre parole, se per l'elemento ItemDef NON vengono specificate impostazioni per la distribuzione, questa avverrà normalmente come per tutti i generatori basati sul tempo di gioco che non presentano impostazioni. La distribuzione verrà limitata dall'intervallo di distribuzione dell'applicazione. In caso contrario, se per l'elemento ItemDef vengono specificate delle impostazioni per la distribuzione, gli oggetti vengono assegnati e monitorati separatamente a livello di generatore, indipendentemente dall'applicazione o da altri generatori basati sul tempo di gioco dell'elemento ItemDef.

Esempio di assegnazione dell'ItemDef in base al tempo di gioco

1. Consente all'utente di ricevere un oggetto dopo 30 minuti di tempo di gioco. Lo svantaggio di impostare solo questa proprietà è che consente all'utente di accumulare il tipo di oggetto, in quanto gli verrà assegnato ogni 30 minuti di gioco.
   Consigliamo vivamente di aggiungere un'impostazione della finestra per la distribuzione:
   "drop_interval" : 30
   
2. Limita l'assegnazione a un singolo oggetto al giorno dopo 30 minuti di gioco. Questa impostazione ti consente di premiare i giocatori ogni giorno quando fanno ritorno al tuo gioco.
   "drop_interval" : 30,
"use_drop_window" : "true",
"drop_window" : "1440"
   
3. Consente all'utente di ottenere tre oggetti al giorno giocando per almeno 90 minuti. Non è necessario che i minuti siano consecutivi. Questa proprietà consente di ricompensare i tempi di gioco più lunghi.
   "drop_interval" : 30,
"use_drop_window" : "true",
"drop_window" : "1440",
"drop_max_per_window" : "3"

Se un'impostazione specifica dell'elemento ItemDef è mancante, per impostazione predefinita verrà impostata su quanto definito nell'applicazione.

Limiti di assegnazione

La variabile drop_limit consente di definire un numero massimo di assegnazioni in base al tempo di gioco per un generatore specifico.
Puoi utilizzare la variabile per limitare la generazione di un oggetto (ad esempio, assegnandolo solo la prima volta che l'utente completa il gioco in modalità difficoltà leggendaria).
In alternativa, impostando il valore su zero può essere utilizzata per prevenire eventuali distribuzioni future di un oggetto obsoleto. L'impostazione verrà riconosciuta solo se use_drop_limit è impostato su "true".

Vendita di oggetti

Per abilitare la vendita di alcuni oggetti del gioco, definisci semplicemente il prezzo o le categorie di prezzo nell'elemento ItemDef appropriato.
Per maggiori informazioni sull'abilitazione e la personalizzazione della tua pagina del Negozio, consulta la documentazione di Steam Negozio di oggetti.

Definizione dei prezzi

I prezzi degli oggetti possono essere definiti in uno qualunque dei seguenti campi, ma non in entrambi.

Nome	Descrizione
price	Definisce un prezzo specifico per ciascuna valuta. Le valute non definite verranno convertite automaticamente al momento dell'acquisto.
price_category	Definisce un prezzo che sarà presentato in tutte le valute supportate utilizzando la tabella dei prezzi curata da Valve.

Il campo price_category viene specificato nella valuta speciale "VLV". VLV100 è equivalente a 0,99 USD e viene convertito in tutte le valute supportate usando i tassi di conversione di Valve.

I tassi di conversione VLV sono accuratamente gestiti per adattarsi alle fluttuazioni delle valute nel tempo. Aggiorniamo i prezzi secondo necessità, consentendo piccole fluttuazioni per fornire ai clienti un prezzo stabile e un'esperienza utente positiva.

Formato dei prezzi

<daterange> deve essere esattamente di 33 caratteri.

L'elenco degli intervalli di data "dateranges" deve essere in ordine decrescente (ossia prima le date future).

Esempi di prezzi

• price_category: 1;VLV100
  Categoria di prezzo preimpostata dalla tabella dei prezzi curata da Valve.
  
• price: 1;USD100
  (1,00 dollaro americano)
  
• price: 1;USD100,EUR080
  (1,00 dollaro americano o 0,80 €)
  
• prezzo: 1;USD100,EUR080;20130607T080000Z-20130606T080000ZUSD50,EUR40
  (1 dollaro americano o 0,80 euro, tranne a partire dal 6/6/2013, quando il prezzo è stato ridotto a 0,50 $/0,40 €)
  
• price: 1;USD100,EUR080;20130609T080000Z-20130606T080000ZUSD50,EUR40
  (1,00 dollaro americano o 0,80 euro, fatta eccezione per il periodo compreso tra il 6/6/2013 e il 9/6/2013, quando il prezzo è stato ridotto a 0,50 $ o 0,40 €)

Vendita di pacchetti

Gli oggetti inclusi in un pacchetto possono essere venduti nel Negozio di oggetti. Il pacchetto verrà espanso durante il processo di acquisto, pertanto l'utente potrà vedere l'elenco degli oggetti inclusi. La politica di rimborso di Steam consente di rimborsare l'acquisto entro un certo limite di tempo, ma tutti gli oggetti contenuti devono essere ancora presenti nell'inventario del giocatore e non devono esservi state apportate modifiche.

Prezzi dei pacchetti

Per la definizione del prezzo di un pacchetto ci sono alcuni aspetti ulteriori da considerare. Steam utilizza i prezzi dei singoli oggetti all'interno del pacchetto per determinarne il prezzo e suddividere i ricavi in modo proporzionale. Questa suddivisione determinerà il valore degli esborsi per i collaboratori del Workshop. Un pacchetto può prevedere contenuti di vario tipo offerti da collaboratori diversi del Workshop o includere contenuti del Workshop assieme a quelli offerti dallo sviluppatore.

Per stabilire il prezzo di un oggetto incluso in un pacchetto:

• Definisci i prezzi per ogni oggetto all'interno del pacchetto.
  
• Se alcuni degli oggetti contenuti non devono essere vendibili singolarmente, imposta il campo store_hidden
  su "true" per tali oggetti.
  
• Imposta il campo price o price_category del pacchetto su un prezzo semplice (come VLV0).
  Questo prezzo non verrà utilizzato nel Negozio, ma è necessario per segnalare al Negozio di oggetti che si tratta di un oggetto vendibile.
  
• Facoltativamente, imposta il campo purchase_bundle_discount su una percentuale di sconto da applicare al pacchetto.

Se preferisci, puoi definire il prezzo specifico del pacchetto per ogni valuta. La sovrascrizione del prezzo del pacchetto ignorerà qualsiasi sconto specificato nel campo purchase_bundle_discount. Tuttavia, i prezzi dei singoli oggetti sono ancora utilizzati per suddividere in modo proporzionato i ricavi del pacchetto, pertanto è necessario fornirli.

Per sovrascrivere il prezzo automatico del pacchetto:

• Specifica il prezzo desiderato nel campo price o price_category del pacchetto.
  
• Imposta use_bundle_price su true per il pacchetto.

Vendita di oggetti di tipo "generator"

Non tentare di vendere oggetti di tipo generator direttamente nel Negozio di oggetti.

Per vendere un oggetto con una componente casuale (ad esempio un forziere), è necessario definire l'oggetto nel forziere come item di tipo semplice, quindi creare un oggetto di tipo generatore che consenta al forziere di ricevere una ricetta di scambio.

Dopo l'acquisto, il giocatore può scegliere di "aprire" il forziere, ed è a questo punto che potrai effettuare la chiamata a ISteamInventory::ExchangeItems per eseguire il generatore. L'acquisto del forziere non sarà più rimborsabile una volta aperto.

Tabella dei prezzi VLV preimpostati

Di seguito sono presentate le possibili valute attualmente a tua disposizione per specificare il parametro price_category dell'oggetto.

Nome	Prezzo in 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

Esempio di schema dell'elemento ItemDef: