Panoramica

Gli sviluppatori devono fornire un file di azioni in-game (IGA) che definisca le azioni, i set di azioni e la struttura di base della configurazione di input del loro gioco. Questo articolo descrive la struttura generale di tale file e fornisce diversi esempi concreti tratti da vari giochi.

File di esempio

• portal2_actions.vdf per Portal 2
  
• defenders_quest_actions.vdf per Defender's Quest: Valley of the Forgotten
  
• IGA file template (non da un qualsiasi gioco in particolare, ma inteso come materiale di partenza per vari generi).

Creazione manuale di un file di azione in gioco

Inizia scaricando il file iniziale delle azioni in gioco (IGA) di cui trovi il link negli esempi in alto. Poi crea una directory "controller_config" all'interno della cartella di Steam, in genere C:/Program Files (x86)/Steam/controller_config, e sposta il file in quella directory. La cartella di Steam conterrà già una cartella con un nome molto simile, quindi assicurati di usare la cartella "controller_config" e non "controller_base". Rinomina il file come segue: "game_actions_X_vdf", dove X è l'appID di Steam del tuo gioco. Se non conosci l'appID di Steam del tuo gioco, puoi trovarlo accedendo al sito di Steam per i partner.

A questo punto, apri il file in un editor di testo. Il file è nel formato standard di Valve denominato KeyValues, ossia un semplice formato di lettura. Potrebbe essere utile scaricare anche uno dei nostri template di file di azioni in gioco o il file IGA di Portal 2 per avere dei riferimenti.

Generazione di un file IGA da un gioco esistente che utilizza le API di Steam Input

Se salvi una configurazione per qualsiasi gioco su Steam come configurazione "locale " è quindi possibile trovare un file corrispondente in:
[PercorsodiSteam]\UserData\[tuoID]\241100\remote\controller_config\[appid]\[nomesalvataggio].vdf

Nell'esempio di seguito viene visualizzata la posizione in cui le configurazioni locali di Defender's Quest vengono memorizzate su un tipico computer che utilizza Windows 10:



Nota: questi file non sono copie esatte del file IGA principale caricato dallo sviluppatore, ma puoi farti un'idea della struttura originale dai blocchi dei parametri "actions" e "localization", estratti direttamente dal file principale.

Puoi scaricare il file mostrato nello screenshot (può essere utile confrontarlo con il file IGA principale di Defender's Quest) qui: #library_controllersavedefaulttitle_0.vdf.

Formato del file IGA

Il file IGA ha il formato di un documento VDF, ossia il formato proprietario dei dati di Valve per la creazione di dati di oggetti strutturati con coppie di stringhe chiave/valore.

Struttura di base

La struttura di base del file è un oggetto wrapper denominato "Azioni nel gioco" con due oggetti inferiori definiti rispettivamente "actions" e "localization":

Set di azioni

Guardiamo più da vicino la struttura dell'oggetto "actions". In questo oggetto sono inclusi i set di azioni. La struttura di un oggetto "actions" è la seguente:

Le stringhe "ActionSetNameGoesHere" e "#TitleGoesHere" sono le uniche dell'esempio precedente che l'utente deve sostituire. Per le altre si tratta di parole chiave riservate.

Il valore con cui viene sostituito "ActionSetNameGoesHere" sarà il nome del set di azioni che utilizzi per l'API di Steam Input. Il valore sostituito a "#TitleGoesHere" sarà il token di traduzione utilizzato nella sezione "localization" più avanti nel file. Tieni presente che in questo codice è necessario il simbolo #.

Ogni set di azioni deve presentare un nome di stringa univoco. Puoi aggiungere dei set semplicemente creando più oggetti nel contesto dell'oggetto contenitore "actions". Non sono necessarie virgole o parentesi quadre. Si tratta del formato VDF, non JSON.

Ci sono tre possibili oggetti secondari per ogni oggetto del set di azioni. Si tratta di "StickPadGyro", "AnalogTrigger", e "Button". Questi sono gli unici oggetti che è possibile definire. Rappresentano i contenitori che ospiteranno le definizioni delle singole azioni. Non è necessario fornire tutte e tre le categorie, tuttavia.

Questa struttura è perfettamente valida, ad esempio:

StickPadGyro

Questo blocco di set di azioni è destinato alle azioni analogiche che presentano fino a due assi di movimento, come quelle che di solito si assegnano a joystick, trackpad o giroscopi. Va inserito in questo blocco anche ciò che si desidera controllare con un mouse o una periferica con simile funzione.

AnalogTrigger

Questo blocco di set di azioni è destinato alle azioni analogiche che presentano un solo asse di movimento e che generalmente vengono assegnate a un grilletto analogico.

Tasto

Questo blocco di set di azioni è per le azioni puramente digitali, che riportano solo uno stato attivo o disattivo. Anche se il nome di questo blocco è "button", le azioni digitali possono essere assegnate a qualunque input fisico, anche quelli inizialmente destinati a dati di output analogici (come joystick, trackpad, ecc.).

Azioni

Un file IGA è inutile senza la definizione di alcune azioni. Vediamo come aggiungerne qualcuna.

Azioni di tipo StickPadGyro

Iniziamo con l'aggiunta di alcune azioni StickPadGyro (analogiche a 2 assi). Impostiamone una per lo spostamento del personaggio, che chiameremo "Move". Aggiungiamo poi un'altra azione per controllare la telecamera, assegnandole il nome "Camera".


Come noterai, la struttura astratta per un'azione StickPadGyro è la seguente:

Gli unici valori modificabili dall'utente in questa struttura sono quelli contrassegnati come "ActionNameHere", "#ActionTitleHere" e "<analog_mode>", che corrispondono rispettivamente al nome della stringa dell'azione da utilizzare nell'API di Steam Input, la chiave di localizzazione da utilizzare nella sezione del file per la localizzazione e la modalità della fonte dell'input che gestisce il modo in cui vengono elaborati e interpretati i dati analogici.

La proprietà "input_mode" può assumere due valori per le azioni StickPadGyro:

• "joystick_move"
  
• "absolute_mouse"

Per le azioni i cui valori vengono interpretati come joystick (deviazione costante da un punto centrale) è necessario utilizzare "joystick_move", mentre per le azioni analogiche con uno scopo generale più flessibile va utilizzato "absolute_mouse". In caso di dubbio, utilizza "absolute_mouse".
Facoltativamente, puoi inviare eventi del mouse di livello inferiore insieme ai dati analogici. Il gioco non sarà in grado di distinguere questi eventi del mouse da quelli generati dal sistema operativo. Puoi eseguire questa operazione aggiungendo il valore "os_mouse" e assegnando a questo un valore di 1.

Esempio:


Azioni di tipo AnalogTrigger
Le azioni AnalogTrigger sono azioni analogiche 1-D che possono essere associate ai grilletti. Se stai usando una semplice soglia del grilletto per un'azione come sparare con un'arma o avviare la modalità "Mira in basso", ti consigliamo di usare un'azione di tipo Button al posto di un'azione AnalogTrigger, in modo che gli utenti abbiano maggiore flessibilità di riassociazione.

Le azioni AnalogTrigger hanno una zona morta configurabile nell'interfaccia utente di riassociazione e sono riscalate da 0 - 1.0f tra quei valori. I controller con pulsanti di sparo digitali come Nintendo Switch Pro invieranno 0 o 1.0, quindi ti consigliamo di controllare di non avere un codice di gameplay che dipende dalle modifiche graduali del grilletto nel tempo.

Le azioni AnalogTrigger hanno un formato semplice, con il nome dell'azione come chiave e il token di localizzazione come valore. Come in questo esempio:

Azioni di tipo Button

Anche i pulsanti di azione hanno un formato simile, che usa il nome dell'azione e il token di localizzazione:

Se lo ritieni necessario, puoi definire un evento hardware dell'input nativo di livello inferiore (come un clic nativo del mouse) che si attiva parallelamente all'azione. Può essere utile in alcuni casi limite in cui il gioco si basa, ad esempio, su un gruppo di input complesso con sette livelli di profondità che non tratta quasi mai gli eventi del mouse virtuale generati dal livello dell'applicazione allo stesso modo di quelli generati direttamente dal sistema operativo.


Questo fa sì che il gioco produca un vero e proprio evento del pulsante sinistro del mouse a livello di sistema operativo ogni volta che l'azione "fancy_click" viene attivata.

Layer di set di azioni

Oltre ai set di azioni, puoi aggiungere un layer di modifiche incrementali per attivare il set di azioni con un layer di set di azioni. Puoi usarlo per gestire le specializzazioni di una modalità generale, come un layer Cecchino sopra ai controlli per muoversi a piedi o per gestire i casi in cui un'interfaccia utente compare in gioco sopra al normale gameplay, come le schermate di voto. I layer devono essere dichiarati in una propria sezione, ad esempio:

Localizzazione

Il file IGA principale deve includere, oltre alle definizioni dei set di azioni, una sezione per la traduzione denominata "localization". I singoli oggetti secondari dell'oggetto "localizzazione" saranno costituiti dalle stringhe di qualsiasi lingua supportata da Steam. Assicurati di includere almeno un blocco che includa i titoli delle azioni in lingua inglese.


Tieni presente che i nomi delle proprietà devono corrispondere alle chiavi di traduzione specificate nelle sezioni precedenti, fatta eccezione per il simbolo "#".

Per aggiungere ulteriori lingue è sufficiente aggiungere altri blocchi con la traduzione di ciascuna voce:

Il token per ogni lingua deve corrispondere al valore del "codice lingua dell'API", ad esempio "schinese" per il cinese semplificato. L'elenco completo delle lingue supportate è disponibile qui.

Utilizzo del file IGA da parte di Steam

Il file IGA principale che crei verrà utilizzato solo durante la fase di sviluppo, ma dovrà comunque essere salvato, mantenuto e conservato nel controllo della versione e così via. Quando crei una configurazione ufficiale di input per il tuo gioco durante la fase di sviluppo, il client di Steam utilizza il tuo file IGA principale per generare un modello iniziale.