Descripción general
Los desarrolladores deben proporcionar un archivo de acciones en el juego llamadas In-Game Actions (IGA) que defina las acciones, los sets de acciones y la estructura básica de configuración de entrada de sus juegos. Este artículo describe la estructura general de este archivo y muestra varios ejemplos concretos de distintos juegos.
Archivos de ejemplo
Creación manual de un archivo de acciones en el juego
Comienza descargando el archivo inicial de las acciones en el juego (IGA) mencionado en los ejemplos anteriores. A continucación, crea un directorio de "controller_config" dentro de la carpeta de Steam, por lo general en C:/Program Files (x86)/Steam/controller_config, y coloca el archivo en el directorio. Asegúrate de colocarlo en la carpeta "controller_config", y no en la carpeta "controller_base", porque habrá carpetas con nombres muy similares en la carpeta Steam. Cambia el nombre del archivo a lo siguiente: "game_actions_X.vdf", donde la "X" es el id. de aplicación (AppID) de tu juego en Steam. Si no conoces el id. de aplicación de Steam de tu juego, puedes encontrarlo iniciando sesión en tu sitio de asociado de Steam.
A continuación abre el archivo en tu editor de texto preferido. El archivo es un formato estándar de Valve llamado KeyValues, que es sencillo y fácil de leer. También podrías encontrar útil descargar una de nuestras plantillas para archivos de acciones en el juego o las IGA de Portal 2 como referencia.
Generación de un archivo IGA de un juego ya existente que utiliza la API de Steam Input
Si guardas una configuración para cualquier juego de Steam como configuración "local", se puede encontrar el archivo correspondiente en:
[SteamDirectory]\UserData\[youruserid]\241100\remote\controller_config\[appid]\[savename].vdfEste es un ejemplo de dónde se guardan mis configuraciones locales de
Defender's Quest en un típico equipo Windows 10:
Toma nota de que estos archivos no son réplicas exactas del archivo IGA principal cargado por el desarrollador, aunque es posible hacerse una idea de la estructura original observando los bloques de "acciones" y "localización", que se obtienen directamente del archivo principal.
Aquí tienes un enlace de descarga para el
#library_controllersavedefaulttitle_0.vdf archivo mostrado en la captura de pantalla anterior. Puede que te resulte útil compararlo con el IGA principal de
Defender's Quest.
Formato IGA
El archivo IGA toma la forma de un documento VDF, que es el formato de datos propio de Valve para la creación de datos de objetos estructurados con pares de cadenas clave-valor.
Esqueleto
La estructura básica del archivo es un objeto contenedor de nombre "In Game Actions" y dos subobjetos llamados "actions" y "localization", respectivamente:
"In Game Actions"
{
"actions"
{
}
"localization"
{
}
}
Sets de acciones
Veamos de cerca el objeto "actions". Este objeto contendrá tus sets de acciones. La estructura de un objeto "actions" tiene este aspecto:
"actions"
{
"ActionSetNameGoesHere"
{
"title" "#TitleGoesHere"
"StickPadGyro"
{
}
"AnalogTrigger"
{
}
"Button"
{
}
}
}
Las cadenas
"ActionSetNameGoesHere" y
"#TitleGoesHere" son las únicas cadenas en el ejemplo anterior que el usuario debe reemplazar, el resto son palabras clave reservadas.
El valor con el que reemplazas
"ActionSetNameGoesHere" es el nombre del set de acciones que utilizas en la API de Steam Input. Y el valor con el que reemplazas
"#TitleGoesHere" será el token de localización que uses en la sección de
"localization" más adelante en el archivo. Ten en cuenta que el signo # es necesario aquí.
Cada set de acciones debe tener un nombre de cadena único y se agregan más simplemente creando más objetos dentro del ámbito del objeto contenedor "actions". No son necesarios comas o corchetes; esto es VDF, no JSON.
Hay tres posibles subobjetos por cada objeto de set de acciones. Estos son
"StickPadGyro",
"AnalogTrigger" y
"Button". Estos son los únicos objetos que puedes definir y son los contenedores que alojarán tus definiciones de acciones individuales. Sin embargo, no es necesario proporcionar las tres categorías.
Esta estructura, por ejemplo, es perfectamente válida:
"actions"
{
"ActionSetName1"
{
"title" "#Title1"
"AnalogTrigger"
{
}
"Button"
{
}
}
"ActionSetName2"
{
"title" "#Title2"
"StickPadGyro"
{
}
}
"ActionSetName3"
{
"title" "#Title3"
"Button"
{
}
}
}
StickPadGyroEste bloque de sets de acciones es para acciones analógicas que tendrán hasta dos ejes de movimiento, el tipo de cosa que puedes querer enlazar a un joy
stick, un track
pad, o un
giroscopio. Aquí también debería ir cualquier cosa que se quiera controlar con un mouse o similares.
AnalogTriggerEste bloque de set de acciones es para acciones analógicas con un solo eje de movimiento, la clase de elemento que se vincula a un gatillo analógico.
ButtonEste bloque de set de acciones es para acciones puramente digitales, que solo comunican un estado de encendido o apagado. Aunque el nombre del bloque sea "button", las acciones digitales pueden asignarse a casi cualquier entrada física, incluidas las originalmente diseñadas para producir datos analógicos (como joysticks, trackpads, etc.).
Acciones
Un archivo IGA no hará nada hasta que hayamos definido algunas acciones, ¡así que añadamos algunas!
Acciones StickPadGyroComencemos añadiendo algunas acciones
StickPadGyro (analógicas de 2 ejes). ¿Qué tal una que mueva al personaje? La llamaremos "Move". Y otra para controlar la cámara, que llamaremos "Camera"
"actions"
{
"FPSControls"
{
"title" "#Set_FPSControls"
"StickPadGyro"
{
"Move"
{
"title" "#Action_Move"
"input_mode" "joystick_move"
}
"Camera"
{
"title" "#Action_Camera"
"input_mode" "absolute_mouse"
}
}
}
}
Como puedes ver, la estructura abstracta para una acción
StickPadGyro es:
"ActionNameHere"
{
"title" "#ActionTitleHere"
"input_mode" "<analog_mode>"
}
Los únicos valores editables por el usuario en esta estructura son aquellos marcados "ActionNameHere", "#ActionTitleHere" y <analog_mode>. Corresponden, respectivamente, al nombre de cadena de la acción para usar en la API de Steam Input, la clave de localización para usar en la sección de localización de este archivo y el modo de fuente de entrada que rige cómo se procesan e interpretan los datos analógicos.
La propiedad
input_mode tiene dos posibles valores para las acciones
StickPadGyro:
"joystick_move"
"absolute_mouse"
Debes usar
joystick_move para una acción cuyos valores se interpretan como un joystick (desviación constante desde un punto central) y debes usar
absolute_mouse para una acción analógica de propósito general más flexible. Cuando tengas dudas utiliza
absolute_mouse.
"joystick_move" vs. "absolute_mouse"
Toda insistencia es poca en nuestra recomendación de que, cuando se cree una entrada de cámara para un juego en primera o tercera personas o para cualquier cosa que dependa del movimiento de un cursor, deberá usarse siempre el tipo "absolute_mouse" y reaccionar a los deltas como si se tratase de un mouse.
La API se encargará, automáticamente, de hacer lo correcto para las entradas basadas en joystick, de modo que todavía se obtendrá una entrada de joystick modulable si la cámara se aplica a un joystick analógico (del estilo de PS4 o Xbox) con zonas muertas, curvas de respuesta, etc. que puedes especificar en tu configuración predeterminada. Esta misma entrada funcionará para joysticks, trackpads o giroscopios de control de movimiento (Steam Controller o PS4), además de ser compatible en el futuro con el mouse.
No deberá usarse el método de entrada basado en "joystick_move" para la cámara, ya que no es posible asignar la dirección opuesta para obtener datos 1:1 útiles para pad, giroscopios, mouse o controladores de movimiento.
Esto también se aplica a las entradas basadas en cursor: "absolute_mouse", cumplirá correctamente para entradas basadas en joysticks, de modo que no será necesario preocuparse de crear cursores propios basados en joysticks si fuesen necesarios.También puedes enviar eventos de mouse de bajo nivel junto con tus datos analógicos. El juego no podrá distinguir estos eventos de mouse de los generados por tu sistema operativo. Esto lo haces añadiendo el valor
"os_mouse" y le asignas un valor de 1.
Un ejemplo:
"StickPadGyro"
{
"Mouse"
{
"title" "#Action_Mouse"
"input_mode" "absolute_mouse"
"os_mouse" "1"
}
}
Acciones de AnalogTriggerLas acciones de AnalogTrigger son acciones analógicas de un solo eje que pueden vincularse a gatillos. Si estás usando un umbral simple del gatillo para algo como disparar un arma o para iniciar el modo de "mirillas de apuntar", te conviene usar una acción de botón en lugar de una acción AnalogTrigger, de modo que los usuarios tengan más flexibilidad para las reasignaciones.
Las acciones AnalogTrigger tienen una zona muerta configurable en la interfaz de usuario de las reasignaciones e incluyen una escala de 0 - 1.0 (punto flotante) o de 0 - 1,0 (coma flotante) entre esos valores. Los controles con botones de gatillo digitales, como el de Nintendo Switch Pro, enviarán bien 0 o 1.0 por lo que deberías comprobar que no tienes código de juego que dependa de cambios graduales del gatillo a lo largo del tiempo.
Las acciones de AnalogTrigger tienen un formato sencillo, con el nombre de la acción como clave y el token de localización como valor. Así:
"AnalogTrigger"
{
"AccelerationAxis" "#Action_Accelerate"
"BreakingAxis" "#Action_Brake"
}
Acciones de "Button"Las acciones de "button" también tienen un formato similar, y utilizan el nombre de la acción y el token de localización:
"Button"
{
"digital_action_1_name_here" "#DigitalAction1TitleHere"
"digital_action_2_name_here" "#DigitalAction2TitleHere"
}
Si es necesario, se puede definir un evento hardware de entrada nativo de bajo nivel (como un clic de mouse nativo) que se active junto con la acción. Es útil en algunos casos raros en los que el juego depende de, por ejemplo, una delicada acumulación de entrada de siete capas de profundidad que nunca trata los eventos de mouse simulados de la capa de la aplicación exactamente igual que los generados directamente por el sistema operativo.
"Button"
{
"simple_click" "#simple_click"
"fancy_click" "#fancy_click, mouse_button LEFT"
}
Esto provoca que el juego emita un auténtico evento de botón izquierdo del mouse del sistema operativo cada vez que se activa la acción "fancy_click".
¡Advertencia!
Nunca debe usarse este truco como una muleta para forzar asignaciones de entrada fijas específicas para las acciones. Esto echaría por tierra el propósito del paradigma "acciones, no entradas" y de entregar al usuario del control total sobre su configuración. Si se acaba utilizando esta función para algo más que arreglar casos raros concretos, probablemente se esté sobreutilizando.Capas del set de acciones
Además de los sets de acciones, también puedes superponer cambios incrementales en el set de acciones activo con una capa de set de acciones. Puedes usarlo para manejar las especializaciones de un modo general, como tener una capa de francotirador encima de tus controles para caminar, o puedes manejar casos donde tienes una interfaz de usuario dentro del juego, la cual emerge sobre el juego normal como lo hacen las pantallas de votación. Las capas se declaran en su propia sección, por ejemplo:
"action_layers"
{
"IngameModalLayer"
{
"title" "#Layer_IngameModal"
"legacy_set" "0"
"set_layer" "1"
"parent_set_name" "InGame"
"AnalogTrigger"
{
}
"Button"
{
"Modal_Accept" "#Action_Modal_Accept"
"Modal_Decline" "#Action_Modal_Decline"
}
}
}
Localización
El archivo maestro IGA debería incluir una sección de localización junto con las definiciones del set de acciones. Los objetos secundarios individuales del objeto de localización serán cualquiera de las cadenas de idioma que Steam admite. Hay que asegurarse de incluir al menos un bloque que contenga los títulos de acción en inglés.
"localization"
{
"english"
{
"move" "Move"
"camera" "Camera"
}
}
Recuerda que el nombre de las propiedades debe corresponderse con las claves de traducción que especificaste en las secciones anteriores, pero sin el carácter "#".
Para agregar idiomas adicionales, solo hay que agregar más bloques de idioma con texto localizado para cada entrada:
"localization"
{
"english"
{
"move" "Move"
"camera" "Camera"
}
"spanish"
{
"move" "Mover"
"camera" "Cámara"
}
"norwegian"
{
"move" "Bevege"
"camera" "Kamera"
}
}
El token para cada idioma deberá coincidir con el valor de "código de idioma API" , ex: "schinese" para chino simplificado. La lista completa de idiomas compatibles se puede encontrar
aquí.
¿Cómo utiliza Steam el archivo IGA?
El archivo maestro IGA que se crea se utilizará únicamente durante el desarrollo (aunque debe guardarse, mantenerse, y almacenarse en el control de versión, etcétera). Cuando
creas una configuración de entrada oficial para tu juego durante el desarrollo, el cliente de Steam usa tu archivo IGA maestro para generar una plantilla de inicio.
