Documentación de Steamworks
Steam Cloud
Resumen
Steam Cloud almacena automáticamente archivos de tu juego en los servidores de Steam para que los jugadores puedan iniciar sesión en Steam y acceder a sus partidas guardadas desde cualquier equipo.
Nivel de integración
Configuración de las rutas de archivo necesarias en el sitio web de Steamworks. Opcionalmente, se requieren algunas llamadas API desde el código del juego a Steamworks para cargar, descargar, enumerar y eliminar.

Descripción general de Steam Cloud

Steam Cloud ofrece un sistema sencillo y transparente de almacenamiento remoto para los juegos. Los archivos especificados en la configuración de Auto-Cloud o guardados en disco (creados, modificados, borrados, etc.) con la API de Steam Cloud se duplican automáticamente en los servidores de Steam tras salir del juego.

Si el usuario cambia de ordenador, los archivos se descargan automáticamente en el nuevo antes de iniciar el juego. A continuación, se puede acceder a los archivos leyéndolos a través de la API de Steam Cloud o directamente en el disco, como de costumbre. Hay que evitar configuraciones específicas del equipo, como los ajustes de video.

El cliente de Steam se ocupa de que todos los archivos estén sincronizados en todos los equipos a los que acceda el usuario.

Los usuarios pueden deshabilitar de manera global la sincronización de Steam Cloud en los ajustes de este servicio, desmarcando la opción "Activar sincronización de Steam Cloud para las aplicaciones que lo soporten".

También lo pueden hacer en cada juego, dentro de sus propiedades.

Spacewar_Cloud_Properties.png

Notas y buenas prácticas


Es importante recordar que Steam sincronizará los archivos de Steam Cloud del usuario para tu juego antes y después de cada sesión. Cualquier archivo coincidente que cambie durante la sesión se cargará al almacenamiento en la nube inmediatamente después. Si tu juego escribe archivos muy grandes, o muchos archivos pequeños, en Steam Cloud, esto puede causar un impacto notable en el ancho de banda de internet del usuario y también retrasar su capacidad de cerrar Steam o volver a iniciar el juego.

Como regla general, los archivos más pequeños funcionarán mejor. Si el estado de guardado para un usuario determinado se puede dividir en diferentes categorías (cosas que pueden cambiar con frecuencia y cosas que pueden no cambiar con frecuencia), entonces recomendamos usar archivos separados para esas categorías. De esa manera, el estado sin cambios no se volverá a cargar después de cada sesión.

Límites de tamaño de los archivos


Los límites absolutos de tamaño de los archivos de Steam Cloud pueden cambiar con el tiempo. He aquí algunos límites y umbrales actuales:

TamañoRestricción
100 MBTamaño máximo para una llamada a ISteamRemoteStorage::FileWrite or ISteamRemoteStorage::FileWriteStreamWriteChunk
256 MBPuede ocasionar una elección de punto final de almacenamiento no óptima para la ubicación del usuario, lo que afecta negativamente el rendimiento de carga/descarga.

Rutas de archivos guardados

A la hora de decidir dónde guardar los archivos guardados, asegúrate de que sea una ruta exclusiva para el usuario de Steam actual. Si es necesario, puedes utilizar ISteamUser::GetSteamID para obtener el id. de Steam exclusivo del usuario. Desde ahí, puedes utilizar GetAccountID() para acceder al id. de la cuenta y conseguir una variable exclusiva para crear la ruta de guardado.

Guardados multiplataforma


En caso de que tu juego esté disponible en varias plataformas, o tengas planes para ello en un futuro, deberías considerar esto al configurar Steam Cloud en tu juego.

Si planeas leer o escribir archivos directamente a través de la interfaz ISteamRemoteStorage, entonces puedes controlar la sincronización con otras plataformas por medio de ISteamRemoteStorage::SetSyncPlatforms. La configuración predeterminada para archivos nuevos es sincronizar con todas las plataformas.

Si deseas usar Steam Auto-Cloud, hay algunas cosas importantes que debes saber. Primero, la configuración predeterminada para nuevos archivos es sincronizar solo con lo que esté establecido en los parámetros del sistema operativo (SO) en la ruta de acceso raíz de Auto-Cloud asociada. Esto significa que, al definir raíces diferentes para cada SO, todos los archivos serán divididos por plataformas y, por lo tanto, no habrá guardados entre plataformas.

Para activar el guardado multiplataforma, deberías establecer una única ruta de acceso raíz (generalmente para Windows) y luego crear reemplazos de ruta raíz para las otras plataformas. Los archivos que se correspondan con una ruta de acceso raíz proporcionada que contenga reemplazos de ruta raíz para otras plataformas se sincronizarán con todas las plataformas establecidas en la raíz original y en los reemplazos. Consulta la documentación de Steam Auto-Cloud para obtener más información.

Configuración inicial

Para configurar Steam Cloud, debes configurar la Cuota de bytes por usuario y el Número de archivos permitidos por usuario en la página Configuración de Steam Cloud del panel de administración de la aplicación de Steamworks.

Esta cuota se impone en cada juego con la nube activada, por usuario y juego. Es recomendable fijar valores razonables para el juego en concreto.

NOTA: No olvides hacer clic en Guardar, en la parte inferior de la página, y publicar los nuevos ajustes. Hecho esto, todo el que posea el juego podrá ver el icono de la nube en el cliente de Steam.

Si tu juego ya ha sido lanzado al público, puedes marcar la casilla Habilitar solo soporte en la nube para desarrolladores. Si está activado el modo solo para desarrolladores, solo verán el icono de la nube y podrán usar Steam Cloud las cuentas de Steam que cuenten con licencia "Developer Comp" para ese título. Resulta útil para probar la integración con Steam Cloud sin interrumpir la experiencia del usuario público. No tiene ningún efecto en juegos que no se han publicado, ya que, como nadie tiene el juego aún, nadie puede ver o tener acceso al almacenamiento en la nube de ese id. de aplicación.

Puedes compartir el espacio de almacenamiento en Cloud entre dos ids. de aplicación completando el campo Id. de aplicación de Cloud compartida. Esto suele utilizarse para compartir partidas guardadas entre una demo y el juego completo. El valor 0 desactiva esta característica.

API de Steam Cloud y Steam Auto-Cloud

Steam ofrece dos métodos diferentes para utilizar Steam Cloud. Aquí señalamos las diferencias entre ambos métodos para facilitar la elección del más adecuado para cada aplicación.

Primero está la API de Steam Cloud.
Esta proporciona una serie de funciones que te permiten integrar directamente Steam Cloud en tu juego. La API de Cloud aísla los archivos de los usuarios de Steam y ofrece un mayor nivel de control sobre Steam Cloud.

La API de Steam Cloud se expone a través de la interfaz API ISteamRemoteStorage y puedes encontrar ejemplos de uso en el proyecto Steamworks API Example Application (SpaceWar).

El segundo es Steam Auto-Cloud.
Steam Auto-Cloud fue diseñado para juegos en los que no se puede integrar la API de Steam Cloud. Es una forma rápida y sencilla de empezar, pero carece de la flexibilidad que sí ofrece la API de Steam Cloud.

Si prefieres una integración más profunda con Steam Cloud (por ejemplo, permitir elegir qué archivos guardados se almacenan en la nube), entonces debes usar la API de Cloud. De lo contrario, puedes usar Steam Auto-Cloud.

Steam Auto-Cloud

Steam Auto-Cloud es una alternativa a la API de Steam Cloud que permite usar Steam Cloud para aplicaciones sin tener que escribir código o modificar el juego en absoluto. Solo es necesario especificar los grupos de archivos que se desean conservar en Cloud. Steam sincronizará automáticamente los grupos de archivos cuando la aplicación se inicie y se cierre. Evita usar configuraciones específicas de equipo, como la calidad de video.
Nota: El archivo steam_autocloud.vdf se creará en cada ubicación especificada por las rutas de la nube de Steamworks. Steam usa este archivo y tu juego puede ignorarlo.

Configuración

Después de completar Configuración inicial la sección de configuración de Steam Auto-Cloud se desbloqueará en la página Configuración de Steam Cloud.

Las rutas de acceso raíz describen grupos de archivos que se conservarán en Steam Cloud. Una ruta de acceso raíz puede ser tan específica como un único archivo o tan amplia como todos los archivos de una subcarpeta determinada. Usa una nueva ruta para cada grupo de archivos que deseas sincronizar.

Una ruta de acceso raíz se compone de cinco partes:
  1. Raíz

    Es una lista de rutas predeterminadas en las que se ubican habitualmente las partidas guardadas.
    RaízSistemas operativos soportadosRuta correspondiente
    App Install DirectoryAlt[Steam Install]\SteamApps\common\[Game Folder]\
    SteamCloudDocumentsAllRuta específica de la plataforma, por ej. en Linux: ~/.SteamCloud/[username]/[Carpeta de juego]/
    WinMyDocumentsWindows%USERPROFILE%\My Documents\
    WinAppDataLocalWindows%USERPROFILE%\AppData\Local\
    WinAppDataLocalLowWindows%USERPROFILE%\AppData\LocalLow\
    WinAppDataRoamingWindows%USERPROFILE%\AppData\Roaming\
    WinSavedGamesWindows%USERPROFILE%\Saved Games\
    MacHomemacOS~/
    MacAppSupportmacOS~/Library/Application Support/
    MacDocumentsmacOS~/Documents/
    LinuxHomeLinux~/
    LinuxXdgDataHomeLinux$XDG\_DATA\_HOME/

    Nota sobre las rutas de %USERPROFILE% de Windows: las rutas correspondientes que aparecen en la lista de arriba son las ubicaciones predeterminadas. Ahora el usuario puede configurar la instalación de Windows para que estas carpetas se encuentren en diferentes ubicaciones que no estén necesariamente en %USERPROFILE%. Steam utiliza las API de Windows necesarias para encontrar la ubicación actual de estas carpetas, independientemente de si son carpetas predeterminadas o personalizadas.

  2. Subdirectorio

    Ruta del subdirectorio a los archivos almacenados en la nube, relativa a la raíz. Se usa "." si no se utiliza ningún subdirectorio.

    Valores especiales de ruta de acceso de Auto-Cloud
    Auto-Cloud permite el uso de identificadores de usuario de Steam únicos en la ruta Subdirectorio. De esta forma, se pueden almacenar por separado las partidas guardadas de cada usuario de Steam en el ordenador. Se puede usar ISteamUser::GetSteamID en tu juego para obtener el SteamID o el AccountID del usuario actual para guardar y recuperar las partidas.
    • {64BitSteamID}: usa esta variable en la ruta de Steam para insertar el id. de Steam de 64 bits de los usuarios. Id. de Steam de 64 bits se parece a: 76561198027391269
    • {Steam3AccountID}: usa esta variable en la ruta de Steam para insertar el id. de la cuenta de Steam 3 de los usuarios. Un id. de cuenta tiene este aspecto: 67125541
    Ejemplo: SavesDir/{64BitSteamID}
  3. Patrón

    Patrón de máscara de archivo que debe coincidir. Puedes utilizar * como comodín. Si deseas todos los archivos en el directorio, simplemente usa *.

    Ejemplo: *.sav
  4. SO

    Establece el sistema operativo para el que se sincronizarán estos archivos. Solo es necesario si los archivos son específicos del sistema operativo, ¡y es mejor que no lo sean!
  5. Recursivo

    Se incluyen los subdirectorios al buscar archivos coincidentes. Sirve para designar subdirectorios cuyos nombres no están fijados, como los que tienen nombres o identificadores de usuario distintos de los de Steam. Si se va a usar un id. de Steam, lo más recomendable es utilizar los valores especiales de ruta en el campo Subdirectorio.

Reemplazos de ruta raíz

Se usa cuando la aplicación es multiplataforma y requiere un directorio distinto para cada SO. Con la funcionalidad de reemplazo de ruta raíz, se puede especificar un reemplazo para la ruta de acceso raíz especificada más arriba.

Las rutas raíz especificadas arriba pueden ser sustituidas para apuntar a una ruta distinta en otro sistema operativo (SO). Si utilizas el reemplazo de ruta raíz, debes especificar [Todos los sistemas operativos] en el cuadro desplegable de arriba para Ruta raíz del SO.

Un reemplazo de ruta raíz consta de cinco partes.
  1. Raíz original

    Corresponde a una de las raíces establecidas más arriba.
  2. SO

    Sistema operativo al que se aplica este reemplazo.
  3. Nueva raíz

    Ubicación del sistema operativo especificado que corresponderá a la de la raíz original.
  4. Añadir/Reemplazar ruta

    Opcionalmente, se puede añadir la ruta de un subdirectorio que se insertará entre la nueva raíz y el subdirectorio original.
  5. Reemplazar ruta

    Si se habilita, hace que la ruta especificada en Añadir/Reemplazar ruta sustituya por completo el subdirectorio original.

Ejemplo: Configuración de Auto-Cloud para aplicaciones Unity

El siguiente es un ejemplo de la configuración de Auto-Cloud para su uso con Unity y la propiedad Application.persistentDataPath donde el valor es diferente según el sistema operativo. La versión para Windows se configura como ruta de acceso raíz, la compañía en Unity es DefaultCompany y el proyecto se llama AutocloudSample. En macOS y Linux/SteamOS, las rutas alternativas de Application.persistentDataPath se configuran en el campo Agregar/Reemplazar ruta y Reemplazar ruta está habilitada.

Con esta configuración, los archivos de Auto-Cloud se sincronizarán entre las tres carpetas, tal como aparecen en las muestras de vista previa.

Cloud_Unity_Auto-Cloud_Example.png

Pruebas prelanzamiento

Si Auto-Cloud se va a añadir a un juego que ya se ha publicado y se ha habilitado el modo solo desarrolladores durante la Configuración inicial, es necesario seguir unos pasos adicionales para probar la funcionalidad.
  1. Inicia sesión en Steam con una cuenta que posea la aplicación que estás probando.
  2. Abre la Consola Steam navegando a steam://open/console en tu navegador.
  3. Introduce testappcloudpaths <AppId> en la consola con el id. de la aplicación que estás probando. Ex: testappcloudpaths 480
  4. Introduce set_spew_level 4 4 en la consola.
  5. Inicia la aplicación desde Steam.
  6. Comprueba la actividad en la consola. Si hay archivos presentes en las rutas de acceso de Auto-Cloud, debes ver que se están subiendo. Si no los hay, guarda algún archivo desde la aplicación y ciérrala para provocar la sincronización.
  7. En otro ordenador, repite los pasos anteriores para probar la descarga de archivos desde Steam Auto-Cloud.
  8. Asegúrate de comprobarlo en todos los sistemas operativos compatibles.
  9. Establece testappcloudpaths 0 y set_spew_level 0 0 para finalizar la prueba. Puedes reiniciar el cliente de Steam para deshacerte de la pestaña de la consola.

No olvides deshabilitar el modo solo desarrolladores y publicar los cambios cuando termines las pruebas.

Sincronización dinámica con Cloud


Steam Cloud ya es compatible con la sincronización dinámica, mediante la cual los cambios que aparecen en Cloud pueden descargarse al equipo local durante las sesiones de las aplicaciones. Por ejemplo, cuando se suspende una sesión de juego en Steam Deck. En las aplicaciones marcadas como compatibles con la sincronización dinámica con Cloud, Steam sincroniza los archivos con Steam Cloud en el momento en que se suspende la sesión. En ese momento el usuario puede ejecutar el juego en otro dispositivo y recibir las actualizaciones de la sesión en Steam Deck al iniciarlo. Al salir, los cambios se suben a Steam Cloud. Por último, cuando se reinicia Steam Deck, Steam sincroniza los cambios con el dispositivo y envía una notificación a la aplicación sobre los archivos locales que han cambiado. A continuación, la aplicación puede iterar dichos cambios y realizar las acciones oportunas. Por ejemplo, el juego podría cargar el progreso actualizado a partir del disco para que el usuario pueda seguir la partida exactamente donde la dejó en el otro dispositivo.

Echa un vistazo a la publicación para obtener más información sobre por qué existe esta característica y cómo utilizarla.

Ten en cuenta que esta característica es compatible tanto con las aplicaciones que utilizan la API ISteamRemoteStorage para administrar los archivos como con las que usan Auto-Cloud.

Para obtener más información, consulta la documentación de ISteamRemoteStorage (específicamente, ISteamRemoteStorage::RemoteStorageLocalFileChange_t, ISteamRemoteStorage::GetLocalFileChangeCount y ISteamRemoteStorage::GetLocalFileChange).

Consulta también ISteamRemoteStorage::BeginFileWriteBatch y ISteamRemoteStorage::EndFileWriteBatch. Estos contenedores deben utilizarse para proporcionarle a Steam pistas que lo ayuden a sincronizarse de forma segura con Steam Cloud en el momento en que el usuario inicie una suspensión del sistema.

Pruebas de prelanzamiento


Para probar compilaciones, puedes activar de forma local la sincronización dinámica con Steam Cloud en tu aplicación, lo cual se recomienda principalmente para los juegos ya lanzados, puesto que su activación para todos los usuarios puede dar lugar a pérdidas de datos cuando se ejecutan compilaciones que no son compatibles con los nuevos métodos y funciones callback de la API.

Para probar localmente desde un PC:

  1. Inicia sesión en Steam con una cuenta que posea la aplicación que estás probando.
  2. Introduce steam://open/console en el navegador para abrir la consola de Steam. También puedes ejecutar Steam con la línea de comandos steam -console e ir a la sección de la consola directamente.
  3. Introduce @cloud_testdynamicsyncapp <AppId> en la consola con el id. de la aplicación que estás probando. Por ejemplo: @cloud_testdynamicsyncapp 480.
  4. Inicia la aplicación desde Steam.
  5. Avanza en el juego hasta llegar al punto que desees.
  6. En la consola de Steam, introduce prepare_for_suspend. Steam suspenderá el proceso del juego y subirá a Steam Cloud los archivos que hayan cambiado.
  7. De manera optativa, puedes jugar al juego en otro dispositivo para avanzar más, y después salir del juego y dejar que los datos del cliente de Steam lleguen a Steam Cloud.
  8. En el dispositivo inicial, en la consola de Steam, introduce resume_suspended_games para sincronizar los archivos necesarios con los datos de Steam Cloud, enviar las llamadas de la API correspondientes al juego y reanudar el proceso del juego.

Para probar localmente desde Steam Deck:

  1. Conecta tu Steam Deck con un kit de desarrollador.
  2. Para usar la consola CEF, véase aquí.
  3. En la consola de JS, introduce SteamClient.Console.ExecCommand(“@cloud_testdynamicsyncapp <AppId>”) para activar las pruebas. Luego puedes introducir SteamClient.Console.ExecCommand(“@cloud_testdynamicsyncapp 0”) para desactivarlas.

Depuración

En primer lugar, asegúrate siempre de haber publicado los cambios en el sitio web de asociados de Steamworks y de haber esperado al menos 10 minutos o haber reiniciado el cliente de Steam para recibir los cambios publicados.

Si tienes problemas con Steam Cloud, debes revisar el archivo de registro ubicado en %Steam Install%\logs\cloud_log.txt.

Mira Debugging the Steamworks API para más información.