Документация Steamworks
Создание и использование скриптов установки

Введение

Хотя Steam может автоматически установить многие общие распространяемые компоненты, у вашего приложения могут быть и другие требования к запуску.
Обратите внимание: скрипты установки, описанные ниже, в первую очередь относятся к Windows. Поддержка MacOS ограничена файлами разрешений и символическими ссылками. Скрипты установки для Linux/SteamOS пока не реализованы.

Файл скрипта установки — это файл настроек, который позволяет выполнить те или иные действия для установки.

Как полные игры/приложения, так и комплекты с доп. контентом могут иметь свои скрипты установки. Если вы интегрируете скрипты установки в сборку, их может быть любое количество. Для приложений SteamPlay рекомендуется, чтобы скрипты установки располагались в хранилищах, предназначенных для той или иной операционной системы.

Пример

Самый простой скрипт может выглядеть так:
"InstallScript" { "Registry" { "HKEY_LOCAL_MACHINE\\SOFTWARE\\Foo\\Bar" { "string" { "Install_Path" "%INSTALLDIR%" "Exe_Path" "%INSTALLDIR%\\foobar.exe" } "dword" { "PatchVersion" "12" } } } "Run Process" { "DirectX" { "HasRunKey" "HKEY_LOCAL_MACHINE\\Software\\Valve\\Steam\\Apps\\480" "Process 1" "%INSTALLDIR%\\DirectX\\DXSETUP.exe" "Command 1" "/silent" "NoCleanUp" "1" } } }

Второй ключ после корневого описывает, какая будет выполняться команда.

Внимание: все ключи и значения могут использовать экранирование последовательности символов, так что если вы используете \, пусть это будет \\.

Интеграция скриптов установки в сборку

Во-первых, файл скрипта установки должен быть частью хранилища, которое устанавливается со сборкой. Убедитесь, что файл располагается в папке ContentRoot, определенной для приложения или хранилища.

Во-вторых, пометьте скрипт установки с помощью директивы InstallScript в скрипте сборки хранилища. Пример можно увидеть в документации о загрузке в Steam.

Во время процесса сборки происходят два процесса:
  • Скрипт установки отправляется в Steam и подписывается криптографически. Steam подтверждает эту подпись перед выполнением любого скрипта установки, кроме того, она требуется для выполнения определённых операций, включая запись в куст HKLM на Windows. Это может вызвать изменения в вашей локальной копии скрипта установки.
  • Скрипт установки помечается в манифесте хранилища. Это можно увидеть в созданном файле manifest.txt как значение 100 в поле Flags.
Когда пользователь Steam запускает игру, Steam сканирует все её подключённые хранилища и запускает все файлы, помеченные как скрипты установки.

Registry

Команда Registry позволяет создавать и изменять значения реестра в форматах string и dword. Любое название раздела реестра в секции Registry будет восприниматься как полный путь к разделу реестра, который вы хотите создать или открыть. Под этим путём добавьте раздел либо в string, либо в dword. Любые пары ключ-значение, хранящиеся в string или dword, будут заданными разделами и значениями реестра.
Для того, чтобы задать значение по умолчанию, следует определить название раздела как (Default).

Run Process

Команда Run Process позволяет приложению запускать программы до того, как пользователь впервые запустит вашу игру.
Чтобы определить, какая программа должна быть запущена, скрипт установки ищет название раздела (как значение dword) в значении HasRunKey. Если это значение отсутствует или равно нулю, вызывается CreateProcess со значениями, указанными в processXX и commandXX. Если CreateProcess не запускается, вызывается ShellExecuteEx. Если ExitCode программы равен нулю, тогда скрипт установки считает, что она была успешна и записывает ваше название раздела в реестр как 1.

Пользователи Steam предпочитают быструю (quick) и тихую (silent) установку. Добавьте параметры silent или quiet всем командам Run Process, и добавляйте только то, что вам абсолютно необходимо.
Run Process требуют следующие пары ключ-значение:
  • Process 1. Путь к программе, которую вы хотите запустить
Необязательные пары ключ-значение для Run Process таковы:
  • Command 1. Необязательная команда, которую вы хотите передать программе.
  • HasRunKey. Необязательный ключ для проверки, установлена ли необходимая программа.
  • NoCleanUp. Необязательная пометка, которая используется для того, чтобы скрипт установки не удалял название раздела при удалении вашего приложения из Steam.
  • MinimumHasRunValue. Необязательное минимальное значение, при достижении которого скрипт установки запустит программу.
  • Requirement_OS. Необязательные значения, с помощью которых можно добавить требования к конкретным ОС. Подробнее об этом читайте в разделе «Требования к ОС».
  • AsCurrentUser. Необязательная пометка. Задайте значение 1, если для программы важен запуск от имени текущего пользователя. В противном случае клиент Steam может запустить её как администратор, чтобы избежать запросов повышения прав в режиме Big Picture или приложениях виртуальной реальности.

Исключения для брандмауэров

Если в игре есть игра по сети, используйте исключение для брандмауэров в Windows, чтобы пользователю не пришлось давать разрешение вручную.
"Firewall" { "Space War Game" "%INSTALLDIR%\\SpaceWar.exe" }

Требования к ОС

Значение Requirement_OS позволяет запускать разные версии установки на разных версиях операционных систем. Оно потребует наличия группы Requirement_OS, внутри которой будут располагаться дополнительные пары ключ-значение. Доступные версии ОС перечислены ниже.
  • Is64BitWindows. Уточняет, что процесс может быть запущен только на 64-битной версии операционной системы. Значения: 1 или 0.
  • OSType Уточняет, что процесс может быть запущен только на определённой версии операционной системы. Уточняет, что процесс может быть запущен только на определённой версии операционной системы. Значения:
    • Windows 3.11
    • Windows 95
    • Windows 98
    • Windows ME
    • Windows NT
    • Windows 2000
    • Windows XP
    • Windows 2003
    • Windows Vista
    • Windows 7
    • Windows 2008
    • Windows 2012
    • Windows 2012 R2
    • Windows 8
    • Windows 8.1
    • Windows 10

Пример 64-битной версии
Данный код запустит соответствующую установку в случае 32 и 64 битных систем.
"Net32" { "Process 1" "%INSTALLDIR%\\redist\\Controller\\32bitInstaller.exe" "NoCleanUp" "1" "Requirement_OS" { "Is64BitWindows" "0" } } "Net64" { "Process 1" "%INSTALLDIR%\\redist\\Controller\\64bitInstaller.exe" "NoCleanUp" "1" "Requirement_OS" { "Is64BitWindows" "1" } }

Пример типа ОС
Данный код будет применён только к Windows XP

"Controller" { "Process 1" "%INSTALLDIR%\\redist\\WinXPInstaller.exe" "NoCleanUp" "1" "Requirement_OS" { "OSType" "Windows XP" } }

Переменные среды

Скрипт установки поддерживает переменные среды. Кроме стандартных переменных среды Windows вы можете использовать несколько дополнительных, относящихся к скрипту установки. А именно:
  • %INSTALLDIR%. Полный путь установки приложения без обратных косых черт.
  • %ROOTDRIVE%. Буква, обозначающая диск установки приложения, к примеру C.
  • %APPDATA%. Папка \Users\username\AppData\.
  • %USER_MYDOCS%. Папка user\My Documents.
  • %COMMON_MYDOCS%. Папка All Users\Documents.
  • %LOCALAPPDATA%. Папка \Documents and Settings\username\Local Settings\Application Data (только Vista и более новые версии Windows).
  • %WinDir%. Папка установки Windows.
  • %STEAMPATH%. Полный путь к папке установки клиента Steam.

Обратите внимание, что указанные выше стандартные пути могут отличаться в зависимости от того, какая версия Windows установлена у пользователя.

Значения для конкретных языков

Значения параметров string и dword могут содержать разные данные в зависимости от того, на каком языке запущен Steam у пользователя. To use, create a subkey in the "string" or "dword" key with the name of the language, then assign the names and values in there. For example:
"InstallScript" { "Registry" { "HKEY_LOCAL_MACHINE\\SOFTWARE\\MonkeyDime Studios\\Killer Banana Peel" { "dword" { "english" { "Language" "1" } "french" { "Language" "2" } "german" { "Language" "3" } "italian" { "Language" "4" } "spanish" { "Language" "5" } } } } }

The install script gets the language from Steam's registry key, querying the value "Language". If that value isn't found then "english" is the default.

Удаление приложения

Когда пользователь удаляет приложение или проверяет целостность файлов установки в Steam, вызывается скрипт установки, чтобы удалить значения созданных реестров. The install script will also remove the value used to determine if a program should execute from Run Process, so that it can execute the next time your app runs (unless the NoCleanUp flag is set).

Run Process on Uninstall

Если во время удаления приложения требуется запустить какой-либо процесс, добавьте информацию об этом в скрипт установки. Не удаляйте общие распространяемые компоненты, например DirectX, msvc run time и т. д. Скорее всего, их используют и другие игры. Это относится только к процессу удаления игры.
ВНИМАНИЕ: Когда пользователь проверяет целостность файлов приложения в Steam, также вызывается Run Process On Uninstall. Поэтому не запускайте процесс, удаляющий все файлы, чтобы их не понадобилось повторно загружать при такой проверке.
"InstallScript" { "Run Process On Uninstall" { "Process_name" { "Process 1" "process.exe" "Command 1" "/command" } } }

Частые вопросы

В. Почему скрипт установки устанавливает распространяемый компонент при каждом запуске игры?
О. This typically means that the redist is returning a non-zero return code. Steam checks that the return code is zero. If it sees that the return code is zero, it marks the redist as installed and doesn't run it again. If it returns any other value, Steam will attempt to run it again on next launch.

To fix this examine your redistributable paths and parameters. Some redists will return non-zero values if they already exist on the machine. This can often be fixed by using the redist's silent or quiet flag.

В. Почему мой раздел реестра не записывается?
О. Typically this is because the install script isn't signed and you're writing to HKLM.
See the section on build integration, and ensure that a "kvsignatures" key was added to your script during the build, as Steam requires this signing to be completed to write to HKLM.

This can also be caused by the Windows 64 bit virtualization on 64 bit Windows, Steam writes to the Wow6432Node path in the registry.

В. Почему мой скрипт установки вообще не запускается?
О. Please double check that your configuration is properly prepared.

В. Как добавить распространяемые компоненты для macOS? Почему Run Process не работает в скрипте установки для macOS?
О. We don't currently have support for installing Mac redistributables. You will need to put the installer into your main executable.