Documentación de Steamworks
Guía de implantación de Steam Workshop

Introducción

Steam Workshop es un sistema de almacenamiento backend y páginas web frontend que permite almacenar, organizar, ordenar, valorar y descargar contenido para tu juego o aplicación.

Esta página incluye detalles técnicos relativos a la implantación de Steam Workshop en tu título. Si necesitas información y definiciones sobre los distintos tipos de integración de Workshop que se pueden usar y cómo sacar el máximo partido a las herramientas de Steam, consulta Steam Workshop antes de iniciar el proceso de integración en tu juego.

En una configuración típica, los usuarios del juego utilizarán las herramientas que les proporciones junto con él para modificarlo o crear contenido totalmente nuevo. A continuación, enviarán este contenido a Steam Workshop utilizando un formulario integrado en tu herramienta. Luego, otros clientes podrán navegar, ordenar, calificar y suscribirse a los elementos que deseen agregar a tu juego al ir a Steam Workshop en la comunidad de Steam. Hecho esto, dichos artículos se descargarán a través de Steam. Si te has registrado para la función callback ISteamUGC::ItemInstalled_t dentro de su juego, puedes llamar a ISteamUGC::GetItemInstallInfo para obtener la ubicación instalada y leer los datos directamente desde esa carpeta. El juego reconocerá el nuevo contenido en una manera que tenga sentido para el juego y el contenido creado.

Tipos de Steam Workshop, monetización y prácticas recomendadas

Si necesitas más información y definiciones sobre los distintos tipos de integración de Workshop que se pueden usar y cómo sacar el máximo partido a las herramientas de Steam, consulta la documentación de Steam Workshop.

Gestión de la visibilidad de Steam Workshop

Steam Workshop es un sitio web hospedado en Steam que reúne contenido compartido por la comunidad y permite a los usuarios votar y opinar sobre él. De forma predeterminada, las aplicaciones no son visibles en Workshop. Esto evita que el contenido que no se pretende compartir a través del portal de Steam Workshop sea visible a menos que el Workshop esté configurado como público.
Establece el estado de visibilidad del Workshop a través de los siguientes pasos:
  1. Dirígete a la página principal de la aplicación en el sitio web de Steamworks.
  2. Haz clic en Editar configuración de Steamworks
  3. Desde la pestaña Workshop, selecciona General
  4. En el lado derecho de la página, busca la sección Estado de visibilidad.
  5. Usa los botones de opción para seleccionar el nivel de visibilidad deseado, que puede incluir solo desarrolladores, desarrolladores y probadores, clientes, desarrolladores y todos.
  6. Desde la pestaña Publicar, haz clic en Preparar para publicar.
  7. Haz clic en Publicar en Steam y completa el proceso para publicar el cambio.
Nota: Para cambiar el estado de visibilidad a "Todos", hay que realizar una serie de comprobaciones de Workshop relacionadas con la personalización del logotipo, el título y la descripción. Además, debe haber un artículo visible para el público, como mínimo.

Resumen técnico

El proceso de compartir y consumir contenido generado por el usuario es mediante la API ISteamUGC que se puede encontrar en Steamworks SDK. Los métodos que incluye conforman un modo de compartir artículos de Workshop, que luego se pueden descubrir a través de Steam Workshop o desde dentro de las propias aplicaciones.

Se debe acceder a la API de Workshop a través del puntero que se devuelve desde SteamUGC().

Ejemplo:
SteamAPICall_t hSteamAPICall = SteamUGC()->CreateItem( SteamUtils()->GetAppID(), k_EWorkshopFileTypeMicrotransaction );

Habilitar ISteamUGC para un juego o aplicación

Antes de que se puedan subir artículos de Workshops al backend de Steamworks hay que realizar dos pasos previos: configurar las cuotas de Steam Cloud y habilitar la API de ISteamUGC.

Steam Cloud se usa para almacenar las imágenes de vista previa asociadas a los artículos de Workshop. La cuota de Steam Cloud se puede configurar siguiendo estos pasos:
  1. Navega a la página Configuración de Steam Cloud en el panel de administración de la aplicación.
  2. Establece la Cuota de bytes por usuario y el Número de archivos permitidos por usuario en los valores adecuados para el almacenamiento de imagen de la vista previa.
  3. Hacer clic en "Guardar".
  4. Desde la pestaña Publicar, haz clic en Preparar para publicar.
  5. Haz clic en Publicar en Steam y completa el proceso para publicar el cambio.

Para habilitar la API ISteamUGC, sigue estos pasos:
  1. Navega a la página Configuración de Steam Workshop en el panel de administración de la aplicación.
  2. Busca la sección Opciones de configuración adicionales.
  3. Comprueba en Activar ISteamUGC para la transferencia de archivos.
  4. Hacer clic en Guardar.
  5. Desde la pestaña Publicar, haz clic en Preparar para publicar.
  6. Haz clic en Publicar en Steam y completa el proceso para publicar el cambio.
Una vez establecidos estos ajustes, se puede subir contenido a Workshop usando la API.

Crear y subir contenido

El proceso de crear y subir contenido a Workshop es sencillo y repetible, como se puede ver en el siguiente diagrama de flujo.

ISteamUGCFlow-CreateUpload-Web2.png

Crear un artículo de Workshop

  1. Todos los elementos del Workshop comienzan su existencia con una llamada a ISteamUGC::CreateItem
    • La variable nConsumerAppId debe contener el id. de la aplicación para el juego o la aplicación. No se debe pasar el id. de aplicación de la herramienta con la que se creó el artículo de Workshop si tiene un id. distinto.
    • EWorkshopFileType es un tipo de enumeración que define cómo se compartirá el archivo compartido con la comunidad. Los valores válidos son:
      • k_EWorkshopFileTypeCommunity: este tipo de archivo se usa para describir los archivos que los usuarios cargarán y estarán disponibles para descargar por cualquier miembro de la comunidad. Normalmente, se usa para compartir mods creados por los usuarios.
      • k_EWorkshopFileTypeMicrotransaction: este tipo de archivo se usa para describir los archivos que los usuarios cargan, pero que solo pretende que el juego considere agregar contenido oficial. Estos archivos no serán descargados por los usuarios a través del Workshop, pero la comunidad podrá verlos para calificarlos.
        Esta es la implementación que usa Team Fortress 2.
  2. Registra un controlador de resultados de llamadas para CreateItemResult_t
  3. Primero verifica m_eResult para asegurarte de que el artículo se haya creado correctamente.
  4. Cuando se ejecute el manejador de resultados de llamadas, lee el valor m_nPublishedFileId y almacénalo para futuras actualizaciones del elemento del Workshop (por ejemplo, en un archivo de proyecto asociado con la herramienta de creación).
  5. La variable m_bUserNeedsToAcceptWorkshopLegalAgreement debe verificarse y, si es true, se debe redirigir al usuario para que acepte el acuerdo legal. Consulta la sección Acuerdo legal del Workshop para obtener más detalles.

Subir un artículo de Workshop

  1. Una vez que se ha creado un artículo de Workshop y se ha devuelto un valor de PublishedFileId_t, el contenido del artículo de Workshop se puede rellenar y cargar en Steam Workshop.
  2. La actualización de un artículo comienza con una llamada a ISteamUGC::StartItemUpdate
  3. Utilizando UGCUpdateHandle_t que se devuelve desde ISteamUGC::StartItemUpdate, se pueden realizar llamadas para actualizar el Título, Descripción, Visibilidad, Etiquetas, Contenido del artículo e Imagen de vista previa del artículo, a través de los diversos métodos ISteamUGC::SetItem[...].
  4. Una vez que se hayan completado las llamadas de actualización, llamando a ISteamUGC::SubmitItemUpdate iniciará el proceso de carga al Steam Workshop.
    • Registra un controlador de resultados de llamadas para SubmitItemUpdateResult_t
    • Cuando se ejecute el controlador de resultados de la llamada, verifica m_eResult para confirmar que la carga se ha completado correctamente.
    • Nota: No existe ningún método para cancelar la actualización y carga del artículo una vez que se llama a la función.
  5. Si lo desea, puedes seguir el progreso de la carga utilizando ISteamUGC::GetItemUpdateProgress
    • EItemUpdateStatus: define el progreso de la carga y la actualización.
    • punBytesProcessed y punBytesTotal se pueden usar para proporcionar información para un control de interfaz de usuario, como una barra de progreso para indicar el progreso de la carga.
    • punBytesTotal puede actualizarse durante el proceso de carga en función de la etapa de actualización del artículo.
  6. Al igual que cuando se crea un artículo de Workshop, se debe confirmar que el usuario ha aceptado el acuerdo legal. Esto es necesario en los casos en que el usuario no creó inicialmente el artículo, pero está editando un artículo existente.

Notas adicionales

  • Anteriormente, los artículos de Workshop se definían como archivos individuales. Con ISteamUGC, un artículo de Workshop es la representación de una carpeta de archivos.
  • Si un artículo de Workshop requiere más metadatos para las aplicaciones que lo utilizan, puedes adjuntar metadatos al artículo con la llamada a ISteamUGC::SetItemMetadata. Estos metadatos se pueden devolver en consultas sin tener que descargar e instalar el contenido del artículo.
    Anteriormente te sugerimos que guardes estos metadatos en un archivo dentro de la carpeta de artículos del Workshop, lo que, por supuesto, aún puedes hacer.

Consumo de contenido

El consumo de contenido de Workshop entra en dos categorías: suscripción de artículos e instalación de artículos.

Suscripción de artículos

La mayoría de las suscripciones a un artículo de Workshop se realizarán a través del portal de Steam Workshop. Es una ubicación conocida, común a todos los juegos y aplicaciones. Por eso, los usuarios suelen recurrir al sitio de Workshop para buscar artículos y suscribirse a ellos.

No obstante, ISteamUGC ofrece dos métodos para suscribirse y anular la suscripción de forma programática a artículos de Workshop para permitir la gestión de suscripciones en el juego.
  • ISteamUGC::SubscribeItem: suscribirse a un artículo del Workshop. Se descargará e instalará en cuanto sea posible.
  • ISteamUGC::UnsubscribeItem: anular la suscripción de un artículo del taller. Con esto, el artículo se eliminará tras salir del juego.

Existen dos métodos adicionales para enumerar los artículos a los que está suscrito un usuario.

Recibir notificaciones de acciones de suscripción externas

Es posible recibir notificaciones del juego cuando un usuario se suscribe o anular suscripción de un archivo por cualquier mecanismo (por ejemplo, ISteamUGC, el sitio web de Steam Workshop):
  • Registra un controlador de función callback para RemoteStoragePublishedFileSubscribed_t y RemoteStoragePublishedFileUnsubscribed_t
  • Las estructuras serán publicadas con ISteamRemoteStorage::PublishedFileId_t que luego se puede usar para acceder a la información sobre el artículo del Workshop.
  • Las estructuras también contienen el id. de la aplicación (m_unAppID) asociado con el artículo del Workshop. Deberá compararse con el id. de la aplicación en ejecución, ya que se llamará al controlador para todas las suscripciones de artículos, independientemente de la aplicación que se esté ejecutando.

Instalación de artículos

Una vez que se conoce la información de suscripción de artículos, se pueden utilizar los demás métodos de consumo. Estos métodos proporcionan información al juego sobre el estado de la descarga e instalación de un artículo. Las descargas de artículos de Workshop se ejecutan por medio del cliente de Steam y se realizan automáticamente según las reglas siguientes:
  1. Cuando el cliente de Steam indica que se va a ejecutar un juego o aplicación, se descargan e instalan todos los repositorios de aplicaciones que se han actualizado.
  2. Los artículos de Workshop ya instalados se actualizan si es necesario.
  3. Se inicia el juego o la aplicación.
  4. Los artículos del Workshop de nueva suscripción que no se hayan descargado, se descargarán en ese momento y se instalarán en segundo plano.
    • Los archivos de los artículos se descargarán en el cliente en el orden en que fueron suscritos.
    • La página de descarga de Steam mostrará las descargas de artículos con un cartel especial que indicará que se están descargando.
El uso de la característica "Verificar integridad de los archivos" en el cliente de Steam también hará que se descarguen los artículos de Workshop.

Dado que el juego se iniciará antes de que se descargue e instale el contenido de nueva suscripción, los demás métodos de consumo existen como ayuda para supervisar y gestionar el progreso de instalación. Pueden usarse también para ofrecer el estado de instalación en tiempo real cuando se realizan suscripciones en el juego.

Estado de un artículo del Workshop

Progreso de descarga de un artículo del Workshop

Iniciar la descarga de un artículo del Workshop o aumentar su prioridad

  • ISteamUGC::DownloadItem
    • Establece bHighPriority a true para pausar las descargas en curso existentes y comenzar a descargar de inmediato este artículo del Workshop.
    • Si el valor de retorno es true, regístrate y espera la función callback ISteamUGC::DownloadItemResult_t antes de llamar ISteamUGC::GetItemInstallInfo o accede al artículo del Workshop del disco.
    • Si la suscripción del usuario no incluye el artículo (por ejemplo, si es un servidor de juego que usa inicio de sesión anónimo), el artículo de Workshop se descargará y se guardará provisionalmente en la caché.
    • Si el artículo del Workshop tiene un ISteamUGC::EItemState de k_EItemStateNeedsUpdate, se puede llamar a ISteamUGC::DownloadItem para iniciar la actualización. No accedas al artículo del Workshop en el disco hasta que se llame a la función callback ISteamUGC::DownloadItemResult_t.
    • Este método solo funciona con ISteamUGC creando artículos de Workshop. No funcionará con artículos del Workshop heredados ISteamRemoteStorage.
    • La estructura de función callback ISteamUGC::DownloadItemResult_t contiene el id. de la aplicación (m_unAppID) asociado con el artículo del Workshop. Deberá compararse con el id. de la aplicación en ejecución, ya que se llamará al controlador para todas las descargas de artículos, independientemente de la aplicación que se ejecute.

Recuperar información sobre la copia local del artículo de Workshop

Notificación cuando se instala o actualiza un artículo de Workshop

Consultar contenido

La interfaz ISteamUGC proporciona una manera flexible de enumerar los distintos tipos de UGC en Steam (por ejemplo, artículos de Workshop, capturas de pantalla, videos, etc.).

ISteamUGCFlows-QueryingContent-web2.png

  1. Registra un controlador de resultados de llamadas para SteamUGCQueryCompleted_t.
  2. Hay disponibles algunos métodos para crear la consulta según la necesidad: consultar los contenidos asociados a un usuario, consultar todo el contenido u obtener detalles del contenido cuyos id. te pertenecen.
  3. La consulta se personaliza llamando a los métodos de ajuste de opciones:
    • Al consultar UGC de un usuario:
    • Al consultar todo el UGC:
      • ISteamUGC::SetMatchAnyTag: establece si los artículos del Workshop se devolverán si tienen una o más etiquetas coincidentes, o si todas las etiquetas deben coincidir en una consulta pendiente de UGC.
      • ISteamUGC::SetSearchText: establece una cadena para que los artículos deban coincidir con el título o la descripción en una consulta pendiente de UGC.
      • ISteamUGC::SetRankedByTrendDays: establece si el orden de los resultados se actualizará en función del rango de los artículos durante un número de días en una consulta de UGC pendiente.
    • Al consultar cualquier tipo de UGC:
      • ISteamUGC::AddRequiredTag: agrega una etiqueta requerida a una consulta pendiente de UGC. Solo devolverá el UGC que tenga la etiqueta especificada.
      • ISteamUGC::AddExcludedTag: agrega una etiqueta excluida a una consulta pendiente de UGC. Solo devolverá el UGC que no tenga la etiqueta especificada.
      • ISteamUGC::AddRequiredKeyValueTag: agrega una etiqueta de clave-valor requerida a una consulta de UGC pendiente. Esto solo devolverá los elementos del taller que tienen una clave = [param]pKey[/param] and a value = [param]pValue[/param].
      • ISteamUGC::SetReturnOnlyIDs: establece si se deben devolver solo las id. en lugar de todos los detalles en una consulta pendiente de UGC. Es útil cuando no se necesita toda la información (por ejemplo, si solo se quiere obtener los identificadores de los artículos que un usuario tiene en su lista de favoritos).
      • ISteamUGC::SetReturnKeyValueTags: establece si se devolverán las etiquetas de valor-clave para los artículos en una consulta de UGC pendiente.
      • ISteamUGC::SetReturnLongDescription: establece si se debe devolver la descripción completa de los artículos en una consulta de UGC pendiente.
      • ISteamUGC::SetReturnMetadata: establece si se devuelven los metadatos especificados por el desarrollador para los artículos en una consulta de UGC pendiente.
      • ISteamUGC::SetReturnChildren: establece si se devuelven los id. de los elementos secundarios de los artículos en una consulta pendiente de UGC.
      • ISteamUGC::SetReturnAdditionalPreviews: establece si se deben devolver imágenes o videos adicionales adjuntos a los artículos en una consulta pendiente de UGC.
      • ISteamUGC::SetReturnTotalOnly: establece si se debe devolver solo el número total de artículos coincidentes en una consulta pendiente de UGC. Los elementos reales no se devolverán cuando se llame a ISteamUGC::SteamUGCQueryCompleted_t.
      • ISteamUGC::SetLanguage: configura el idioma para devolver el título y la descripción de los artículos en una consulta pendiente de UGC.
      • ISteamUGC::SetAllowCachedResponse: establece si los resultados se devolverán desde el caché durante el período de tiempo específico en una consulta pendiente de UGC.
  4. Envía la consulta a Steam usandoISteamUGC::SendQueryUGCRequest que invocará el ISteamUGC::SteamUGCQueryCompleted_t controlador de resultados de llamadas registrado en el paso 1.
  5. En el controlador de resultados de llamadas para ISteamUGC::SteamUGCQueryCompleted_t, llama ISteamUGC::GetQueryUGCResult para recuperar los detalles de cada artículo devuelto.

  6. También se puede llamar a estas funciones para recuperar información adicional de cada artículo (algunos de los datos no se devuelven de forma predeterminada, por lo que debes configurar la consulta adecuadamente):
  7. Llama a ISteamUGC::ReleaseQueryUGCRequest para liberar cualquier memoria asignada al consultar o recuperar los resultados.

Paginación de resultados

Se devolverán hasta 50 resultados por cada consulta. Se puede lograr más resultados mediante la creación de una consulta que incremente el parámetro unPage (que debe comenzar en 1).

Seguimiento de tiempo de juego

Para rastrear el tiempo de reproducción de los elementos del taller, simplemente llama a ISteamUGC::StartPlaytimeTracking con los identificadores de los elementos que desea rastrear. Luego, cuando los elementos se eliminan del juego, llama a ISteamUGC::StopPlaytimeTracking con los identificadores que deseas que dejen de rastrear o llama a ISteamUGC::StopPlaytimeTrackingForAllItems para detener el seguimiento del tiempo de reproducción de todos los elementos a la vez.
Cuando su aplicación se apaga, el tiempo de reproducción se detendrá automáticamente.

También podrás ordenar los elementos por varias métricas de tiempo de juego en las consultas de ISteamUGC::CreateQueryAllUGCRequest. Estos son los tipos de consultas de tiempo de juego que se pueden usar:

Eliminar contenido de artículos de Workshop

Para eliminar un artículo de Workshop, puedes llamar a ISteamUGC::DeleteItem. Ten en cuenta que esto no indica al usuario y no se puede deshacer.

Ejemplo de Steamworks: integración de Spacewar

El Ejemplo de aplicación de la API de Steamworks (Spacewar!) que viene con Steamworks SDK demuestra un subconjunto de la API ISteamUGC.
  • CSpaceWarClient::LoadWorkshopItem muestra la verificación de si un artículo del Workshop se descarga e instala en el disco, y también solicita información sobre un artículo del Workshop por ISteamRemoteStorage::PublishedFileId_t
  • CSpaceWarClient::LoadWorkshopItems muestra cómo recuperar la lista de artículos del Workshop suscritos para el usuario actual de la aplicación SpaceWar
  • CSpaceWarClient::OnWorkshopItemInstalled muestra un controlador de función callback para ISteamUGC::ItemInstalled_t

Acuerdo legal del Workshop

Los artículos del Workshop estarán ocultos de forma predeterminada hasta que el colaborador acepte el acuerdo legal de Steam Workshop. Para facilitar que el colaborador haga públicamente visible el artículo, haz lo siguiente.
  1. Incluye el texto junto al botón que envía un artículo al Workshop, algo como: "Al enviar este artículo, acepta los términos de servicio del Workshop" (incluyendo el enlace).
  2. Después de que un usuario envíe un artículo, abre una ventana del navegador en la página de Steam Workshop para ese artículo llamando a ISteamFriends::ActivateGameOverlayToWebPage con pchURL configurado a steam://url/CommunityFilePage/<PublishedFileId_t> reemplazando <PublishedFileId_t> con la identificación del artículo del Workshop.
Esto tiene la ventaja de que dirige al autor a la página de Workshop para que vea el artículo y lo siga configurando si es necesario, y facilita al usuario la lectura y aceptación del acuerdo legal de Steam Workshop.

Web de API

Además de estos métodos, hay un conjunto de interfaces de la Web de API que ofrecen una funcionalidad similar, junto con las API de filtrado basadas en la comunidad que enumeran todo el contenido compartido. Consulta la documentación de la interfaz ISteamRemoteStorage en la lista de Web de API.

Servidores de juego dedicados

Los servidores de juego también pueden descargar e instalar artículos.
  • El servidor de juego necesitará saber el PublishedFileId_t para solicitar un artículo de Workshop. Puede proporcionárselo el cliente de juego o estar establecido por el operador del servidor. Luego llama a ISteamUGC::DownloadItem para recuperar una copia temporal del artículo del Workshop.
  • Luego se puede hacer una llamada a ISteamUGC::GetItemInstallInfo para recuperar información para localizar y usar el artículo del Workshop.
  • Consulta la sección Instalación de elementos más arriba para obtener más información sobre estos métodos de API.

Integración de SteamCMD

Junto con la API ISteamUGC, se puede usar la herramienta de línea de comandos steamcmd.exe para crear y actualizar artículos de Workshop con fines de pruebas. Esto solo debe servir para fines de pruebas, ya que la herramienta pide al usuario que introduzca sus credenciales de Steam (y no queremos que los clientes tengan que hacerlo).

Para crear un nuevo artículo de Steam Workshop con steamcmd.exe, se debe crear antes un archivo VDF. El VDF es un archivo de texto sin formato que debería contener las claves siguientes.
"workshopitem" { "appid" "480" "publishedfileid" "5674" "contentfolder" "D:\\Content\\workshopitem" "previewfile" "D:\\Content\\preview.jpg" "visibility" "0" "title" "Team Fortress Green Hat" "description" "A green hat for Team Fortress" "changenote" "Version 1.2" }

Notas:
  • Las teclas se asignan a los diversos métodos ISteamUGC::SetItem[...]. Para obtener más información, consulta la documentación anterior.
  • Los valores mostrados son solo ejemplos y se deben modificar adecuadamente.
  • Para crear un nuevo elemento, se debe configurar appid y publishedfileid se debe desactivar o establecer en 0.
  • Para actualizar un artículo existente, se deben configurar appid y publishedfileid.
  • Los restantes pares clave-valor se deben incluir en el VDF si la clave va a ser actualizada.
Una vez que se ha creado el VDF, steamcmd.exe se puede ejecutar con el parámetro de archivoworkshop_build_item <build config filename>. Ejemplo:
steamcmd.exe +login myLoginName myPassword +workshop_build_item workshop_green_hat.vdf +quit
Si el comando es exitoso, el valor publishedfileid en el VDF se actualizará automáticamente para contener la id. del elemento del Workshop. De esta forma, las llamadas subsiguientes con steamcmd.exe para el mismo VDF tendrán como resultado una actualización, en lugar de la creación de un nuevo artículo.

Errores y registro

La mayoría de los métodos ISteamUGC devuelven valores booleanos. Para más información sobre errores específicos, hay multitud de referencias que consultar:

Preguntas frecuentes

P.¿Puede una aplicación independiente publicar contenido en el Workshop de mi juego?

Sí. Una aplicación independiente para herramientas de edición o publicación puede configurarse con el Workshop de la aplicación básica para que esta acepte contenido de esa aplicación de edición.

Para configurarla, ve a la sección Configuración del Workshop para la aplicación básica y desplázate al final de la página. Introduce el id. de la aplicación independiente en el campo bajo "Permisos de publicación de aplicaciones" y dale a "agregar".

Una vez publicados los ajustes de Steamworks, la aplicación de edición podrá publicar contenido para el Workshop de la aplicación básica.