Steamworks ドキュメンテーション
インストールスクリプトの作成と使用

概要

Steamは様々な共通再頒布可能ファイルを自動的にインストールしますが、アプリケーションに初回実行要件がある場合があります。
注意:以下で説明するインストールスクリプト機能は、主にWindowsオペレーティングシステム用です。 macOSのサポートは、ファイルのアクセス許可とシンボリックリンクに限られます。 現時点では、Linux/SteamOSのインストールスクリプト機能はありません。

インストールスクリプトファイルは、インストール時に特定のアクションを実行できるようにする設定ファイルです。

フルゲーム/アプリケーション、またはDLCパッケージがそれぞれインストールスクリプトを持つ場合があります。 インストールスクリプトをビルドに統合する場合、インストールスクリプトの数に制限はありません。 SteamPlayアプリについては、インストールスクリプトは常にOS固有のデポに格納することが推奨されます。

スクリプトの基本的な例:
"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" } } }

ルートの後ろの2つ目のキー名は、実行する処理を記述します。

注意: すべてのキー名と値にはエスケープシーケンスが使用可能です。「\」を使用する場合は「\\」と記述します。

ビルドへのインストールスクリプトの統合

まず、インストールスクリプトファイルは、ビルドと共にインストールされるデポの一部である必要があります。 そのファイルは、必ずアプリまたはデポの定義されたContentRoot内に配置してください。

次に、「InstallScript」ディレクティブを使用してデポビルドスクリプト内でインストールスクリプトを指定します。 高度なファイルマッピングルールの例を参照してください。

ビルドプロセス中に次の2つが行われます。
  • インストールスクリプトがSteamにアップロードされ、暗号化され署名されます。 この署名は、Steamにより、すべてのインストールスクリプトの実行前に認証されます。これはWindows上のHKLMハイブへの書き込みなど、特定の操作の実行に必要になります。 これにより、インストールスクリプトのローカルコピーに変更が加えられる場合があります。
  • インストールスクリプトはデポマニフェスト内でマークされます。 これは生成されたmanifest.txtファイルのFlagsフィールドの100として確認することができます。
Steamユーザーがゲームを始めると、Steamはゲーム用にマウントされた全デポで、インストールスクリプトのフラグが付いたファイルを探して実行します。

レジストリ

レジストリコマンドを使用すると、string(文字列型)とdword(数値型)のレジストリ値の作成または変更を実行できます。 「Registry」キー名の下のすべてのキーは、作成したい、または開きたいレジストリキーへのフルパスとして扱われます。 そのキーで「string」または「dword」キーを指定します。 「string」または「dword」キーに保存されたすべてのキー名および値は、取得・設定されるレジストリ名と値になります。
レジストリキーに既定値を設定する場合は、キー名に「(Default)」と入力してください。

プロセスの実行

Run Processコマンドを使用すると、ユーザーがゲームを初めて起動する前に、アプリケーションにプログラムを実行させることができます。
プログラムを実行する必要があるかどうかを判断するために、インストールスクリプトはHasRunKey値のキー名を(レジストリのDWORD値として)確認します。 値が存在しない、または0の場合、processXX/commandXX値でCreateProcessを呼び出します。 CreateProcessが失敗した場合、ShellExecuteExが呼び出されます。 プログラムのExitCodeが0の場合、インストールスクリプトは成功したと仮定し、レジストリでキー名を1として書き込みます。

Steamユーザーは高速なサイレントインストールを好みます。 すべてのRun Processコマンドにサイレントまたは非表示用のパラメーターを追加してください。追加するのはゲームに絶対に必要なものだけにしてください。
Run Processに必要なキー/値:
  • Process 1-起動したいプログラムへのパス
Run Processのオプションのキー/値:
  • Command 1-プログラムに渡すオプションのコマンド
  • HasRunKey-事前に必要なファイルがインストールされているかどうかをチェックするオプションのレジストリキー
  • NoCleanUp-オプションのフラグで、これが設定されている場合、インストールスクリプトは、アプリがSteamから削除された際にキー名を削除しません
  • MinimumHasRunValue-オプションのフラグで、プログラムを起動するかを判断する場合にインストールスクリプトがチェックすべき最小値を任意で設定
  • Requirement_OS-OS要件に適用するオプションのキー。詳細は、OS固有の再頒布可能ファイルを参照してください。
  • AsCurrentUser-オプションのフラグで、現在のユーザーとしてプログラムを実行することが重要である場合は1に設定します。 それ以外の場合、Steamクライアントは管理者として実行し、Big PictureまたはVR環境での昇格時のプロンプトを回避します。

ファイアウォールの例外

ゲームがネットワークを使用する場合には、ファイアウォールの例外を使用して、ユーザーに例外を受け入れるように強制することなく、Windowsが自動的にファイアウォールを介してゲームを許可するようにしてください。
"Firewall" { "Space War Game" "%INSTALLDIR%\\SpaceWar.exe" }

OS固有の再頒布可能ファイル

Requirement_OS値は異なるOSバージョン/SKU上で別のインストールを実行するのに利用できます。 これには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 Typeの例
この例は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のデータフォルダー
  • %USER_MYDOCS%-ユーザーの\My Documentsフォルダーを取得する
  • %COMMON_MYDOCS%-All Users\Documentsフォルダーを取得する
  • %LOCALAPPDATA%-\Documents and Settings\username\Local Settings\Applicationのデータフォルダー(Vistaおよびそれ以降のバージョン)
  • %WinDir%-Windowsインストールディレクトリ
  • %STEAMPATH%-Steamクライアントのインストールディレクトリへのフルパス

言語固有の値

ユーザーがSteamを実行している言語によって、string(文字列型)と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" } } } } }

InstallScript.dllはSteamのレジストリキーから言語を取得し、「Language」値を照会します。 値が見つからない場合には「english」が設定されます。

アプリのアンインストール

ユーザーがSteamからアプリケーションの削除または確認を行った場合、作成された全レジストリ値の削除のためにインストールスクリプトが呼び出されます。 インストールスクリプトは、プログラムがRun Processから実行されるべきかを判断するのに使用した値も削除します。そうすることで、プログラムは次回のアプリケーション起動時にも実行可能になります(NoCleanUp0>フラグが設定されている場合を除く)。

[section=runOnUninstall]アンインストール時のRun Process[/section]
アプリケーションのアンインストール時に何らかのプロセスを実行する必要がある場合は、これをインストールスクリプトに追加してください。 DirectX、msvcランタイムなどの共通再頒布可能ファイルは、他のゲームで使用される可能性があるため、アンインストールしないでください。 これは、ゲーム固有のアンインストールプロセスのみを対象としています。
注意: アンインストール時のRun ProcessはユーザーがSteamでアプリを確認する際にも呼び出されます。 全ファイルを削除するプロセスは実行しないでください。これを実行すると、確認時にSteamがすべてのデータを再ダウンロードすることになります。
"InstallScript" { "Run Process On Uninstall" { "Process_name" { "Process 1" "process.exe" "Command 1" "/command" } } }

よくある質問

Q. ゲームを起動するたびにインストールスクリプトが毎回再頒布可能ファイルをインストールしようとするのはなぜですか?
A. これは一般的に再頒布可能ファイルが0以外のリターンコードを返していることを意味します。 Steamはリターンコードが0かを確認します。 リターンコードが0であることが確認されると、再頒布可能ファイルがインストール済みとマークされ、再び実行されることはなくなります。 他の値を返す場合、 Steamは次回起動時に再び再頒布可能ファイルのインストールを試みます。

これを解決するには、再頒布可能ファイルのパスとパラメーターを確認してください。 一部の再頒布可能ファイルは、マシン上に既にファイルが存在する場合に、0以外の値を返す場合があります。 これは再頒布可能ファイルのサイレントまたは非表示フラグを使うことで大抵解決できます。

Q. レジストリキーが書き込まれないのはなぜですか?
A. 通常、これはインストールスクリプトが署名されていない状態で、HKLMに書き込みを行っていることが原因です。
ビルドの統合に関するセクションを参照し、kvsignaturesキーがビルド時にスクリプトに追加されていることを確認してください。SteamがHKLMに書き込むためには、スクリプトの署名が完了している必要があります。

また、64ビットWindows上でのWindows 64ビット仮想化が原因の可能性もあります。SteamはレジストリのWow6432Nodeパスに書き込みを行います。

Q. インストールスクリプトが全く実行されないのはなぜですか?
A. 正しい設定になっているかどうかを再度確認してください。

Q. Macの再頒布可能ファイルを追加するには? また、MacのインストールスクリプトでRun Processが実行されないのはなぜですか?
A. 弊社では現在Macの再頒布可能ファイルのイントールに関するサポートを行っておりません。 メインの実行ファイル内にインストーラーを配置する必要があります。