Steamworks 文献库
创建与使用安装脚本

概览

Steam 可自动安装多种常见共用发行文件,但您的应用程序可能会有其他首次运行的要求。
备注:下文所述的安装脚本功能基本上只适用 Windows 操作系统。 支持 MacOS 的功能仅限文件权限与符号链接。 目前尚无支持 Linux 或 SteamOS 的安装脚本功能。

安装脚本文件为配置文件,使您在安装时能够运行某些操作。

完整的游戏/应用程序及 DLC 程序包都可能拥有各自的安装脚本。 如果您将安装脚本集成进生成版本,安装脚本的数量将不受限制。 对于 SteamPlay 应用,我们建议您永远将安装脚本放入各操作系统专用的 Depot 中。

示例

以下为基本示例:
"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" } } }

根目录后的第二个密钥名描述了即将发生的操作。

注意: 所有密钥名与值皆可使用转义序列,因此如果您想使用\,请改用\\

将安装脚本集成进生成版本

首先,安装脚本文件必须包含在与生成版本同时安装的 Depot 中。 请注意该文件应在应用程序或 Depot 的事先定义的 ContentRoot 中。

其次,在 Depot 生成版本脚本中使用InstallScript指令标记安装脚本。 示例请见上传至 Steam – 高级文件映射规则

在生成版本的过程中,会发生以下两件事:
  • 安装脚本上传至 Steam 并加密签署。 在执行任何安装脚本前,Steam 将验证此签名,并且在执行某些操作时也需要验证签名,包括写入 Windows 中的 HKLM 配置单元。 此举可能造成您的安装脚本的本地副本被修改。
  • 安装脚本在 Depot 清单中被标记。 您可以在生成的 manifest.txt 文件中看到 Flags 字段标记为 100
当 Steam 用户启动游戏时,Steam 将扫描所有已装载的该游戏的 Depot,搜寻任何含有安装脚本标志的文件并运行。

注册表

您可以通过注册表命令创建或修改字符串和注册表 Dword 值。 任何在“注册表”下的密钥名都将被视为您想创建或开启的注册表项的完整路径。 在该密钥下,请指明“字符串”或“Dword”密钥。 任何存储于“字符串”或“Dword”密钥下的密钥名称和值都将被设为注册表名称与值。
如想设置某一注册表项的默认值,请将密钥名设为(Default)

运行进程

您的应用程序可通过运行进程命令在用户首次启动您的游戏之前运行一些程序。
安装脚本会先查看 HasRunKey 值中的密钥名(视为注册表 Dword 值),以决定是否需要执行某程序。 如果该值不存在或为 0,安装脚本将调用 processXX 或 commandXX 值上的 CreateProcess。 如果 CreateProcess 失败,则调用 ShellExecuteEx。 如果该程序的 ExitCode 为 0,那么安装脚本将视为运行成功,在注册表中将您的密钥名写为 1。

Steam 顾客都喜欢快速安静的安装过程。 我们推荐您向所有运行进程命令添加静默或安静的参数,并只需添加您的游戏绝对需要的文件。
以下为必要的运行进程密钥/值:
  • Process 1 - 想启动程序的路径
以下为可选的运行进程密钥/值:
  • 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" }

OS 特定可再发行文件

Requirement_OS 值可用于在不同 OS 版本/SKUs 中运行不同的安装程序, 但需要名为 Requirement_OS 的新密钥组,且包含额外的键/值对。 下面列出了可用的 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" } }

OS 类型示例
此示例仅在 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 文件夹(只用于 Vista 或更新版本)。
  • %WinDir% - Windows 安装目录。
  • %STEAMPATH% - Steam 客户端安装目录的完整路径。

语言特定值

视用户运行 Steam 时使用的语言,可为字符串和 DWORD 值分配不同的数据。 在“string”或“dword”中创建用语言名字命名子项,然后在子项中分配名称和值,即可使用。 例如:
"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 标记)。

卸载时的运行进程

如果您需要在卸载您的应用时运行任何进程,请将其添加至安装脚本。 切勿卸载常见可再发行文件,如 DirectX、msvc 运行时等等,因为其他游戏有可能会用到这些可再发行文件。 这只针对游戏特定的卸载进程。
注意: 用户在 Steam 中验证应用时,可能会调用卸载时的运行进程。 切勿运行会删除所有文件的进程,因为这会导致 Steam 在验证过程中重新下载所有文件。
"InstallScript" { "Run Process On Uninstall" { "Process_name" { "Process 1" "process.exe" "Command 1" "/command" } } }

常见问题

问: 为什么每次我启动游戏时,安装脚本总是运行我的可再发行文件?
答: 这通常意味着可再发行文件返回了非零返回代码。 Steam 会检查返还代码是否为零。 如果返回代码为零,则 Steam 会将可再发行文件标记为已安装,不会再次运行。 如果返回任何其他值,Steam 会在下次启动时尝试再次运行。

要修复此问题,请检查您的可再发行文件路径和参数。 如果电脑中已经存在可再发行文件,则会返回非零值。 大部分情况下,使用可再发行文件的静默或安静标记,可解决此问题。

问: 为什么我的注册表项未被写入?
答: 这通常是因为未签署安装脚本,而您写入了 HKLM。
查看将安装脚本集成进生成版本一节,并确保 "kvsignatures" 密钥已在生成过程中添加至您的脚本中,因为 Steam 需要在完成此签名后才能写入 HKLM。

这也可能是由 64 位 Windows 上的 Windows 64 位虚拟化所导致,因此 Steam 写入了注册表中的 Wow6432Node 路径。

问: 为什么我的安装脚本似乎根本就没有运行?
答: 请仔细检查您的配置是否正确。

问: 该如何添加 Mac 可再发行文件? 或者是为什么我的 Mac 安装脚本中的运行进程不工作?
答: 我们目前不支持安装 Mac 可再发行文件。 您需要将安装程序放至主可执行文件中。
[/code-inline][/code-inline]