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

Введение

Хотя Steam может автоматически установить многие общие распространяемые компоненты, у вашего приложения могут быть и другие требования к запуску.
Обратите внимание: cценарии установки, описанные ниже, в первую очередь относятся к 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 перед выполнением любого сценария установки, кроме того, она требуется для выполнения определённых операций, включая запись куста 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 - Optional command you want to pass to the program
  • HasRunKey - Optional registry key to check that the prereq is already installed
  • NoCleanUp - Optional flag, when set install script will not delete the keyname when your app is deleted from Steam
  • MinimumHasRunValue - Optional, sets the minimum value the install script should check for when determining to launch the program
  • Requirement_OS - Optional key to apply OS requirements see OS Specific Redists for more details
  • AsCurrentUser - Optional flag, set it to 1 if it's important for that program to run as the current user. Otherwise, the Steam client might run it as Administrator to avoid elevation prompts in Big Picture or VR environments.

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

Если в игре есть игра по сети, используйте исключение для брандмауэров в 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%. Папка \\Documents and Settings\\username\\Application Data
  • %USER_MYDOCS%. Папка user\\My Documents
  • %COMMON_MYDOCS%. Папка All Users\\Documents
  • %LOCALAPPDATA%. Папка \\Documents and Settings\\username\\Local Settings\\Application Data folder (только Vista и более новые Windows)
  • %WinDir%. Папка установки Windows
  • %STEAMPATH%. Полный путь к папке установки клиента Steam.

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

Как string, так и dword можно назначить разные данные в зависимости от того, какой язык использует пользователь Steam. Для этого создайте подраздел в string или string, где укажите язык, а внутри него укажите названия и значения. Пример:
"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" } } } } }

Сценарий установки получает язык из раздела реестра Steam, запрашивая значение Language. Если оно не найдено, по умолчанию используется english.

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

Когда пользователь удаляет или проверяет целостность файлов игры в Steam, сценарий установки вызывается для удаления всех созданных им значений реестра. Сценарий установки также удалит значение, используемое для определения, должна ли программа выполняться из Run Process[code-inline], так чтобы она выполнялась при следующем запуске вашего приложения (кроме случаев, когда задан флаг [code-inline]NoCleanUp).

Run Process on Uninstall

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

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

В. Почему сценарий установки устанавливает распространяемый компонент при каждом запуске игры?
О. Обычно это означает, что распространяемый компонент возвращает ненулевой код. Steam проверяет, равен ли код нулю. Если возвращаемый код равен нулю, он помечает распространяемый компонент как установленный и не запускает его установку заново. Если он возвращает любое другое значение, Steam попытается запустить его заново при следующем запуске.

Для исправления проверьте пути установки распространяемого компонента и параметры. Некоторые распространяемые компоненты возвращают ненулевые значения, если они уже установлены. Часто это можно исправить при помощи флагов silent или quiet.

В. Почему мой раздел реестра не записывается?
О. Обычно это происходит из-за того, что сценарий установки не подписан и вы пытаетесь записать в HKLM.
См. раздел об интеграции сценариев установки в сборку, а также убедитесь, что ключ "kvsignatures" был добавлен к сценарию установки при сборке, поскольку Steam требует подпись для записи в HKLM.

Также это может быть вызвано 64-битной виртуализацией Windows в 64-битной Windows, поскольку Steam записывает в путь реестра Wow6432Node.

В. Почему мой сценарий установки вообще не запускается?
О. Пожалуйста, проверьте, что все настройки установлены верно.

В. Как добавить распространяемые компоненты для Mac? или Почему мой Run Process не работает в сценарии установки на Mac?
О. На данный момент мы не поддерживаем распространяемые компоненты для Mac. Вам придётся поместить установщик в главный исполняемый файл.
[/code-inline][/code-inline]