Dokumentacja Steamworks
Tworzenie i używanie skryptów instalacyjnych

Wprowadzenie

Mimo że Steam może automatycznie zainstalować wiele pospolitych pakietów redystrybucyjnych, twoja aplikacja może mieć inne wymagania dotyczące pierwszego uruchomienia.
UWAGA: działanie opisanych poniżej skryptów instalacyjnych dotyczą głównie systemów Windows. Obsługa systemu macOS jest ograniczona do uprawnień plików i dowiązań symbolicznych. Obecnie nie istnieje działanie skryptu instalacyjnego dla systemów Linux/SteamOS.

Plik skryptu instalacyjnego to plik ustawień, który umożliwia wykonanie określonych działań po instalacji.

Zarówno pełne gry i aplikacje, jak i pakiety DLC mogą mieć skrypty instalacyjne. Jeśli zintegrujesz swoje skrypty instalacyjne w swojej kompilacji, możesz mieć dowolną liczbę skryptów. W przypadku aplikacji SteamPlay zawsze zalecane jest przechowywanie skryptów instalacyjnych w magazynach zawartości zaprojektowanych dla określonego systemu operacyjnego.

Przykład

Podstawowy skrypt instalacyjny może wyglądać tak:
"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" } } }

Druga nazwa klucza po katalogu root opisuje, jakie działanie zostanie wykonane.

Uwaga: wszystkie nazwy kluczy i wartości mogą korzystać z sekwencji specjalnych, więc jeśli używasz \, zmień to na \\.

Integracja skryptów instalacyjnych w twojej kompilacji

Po pierwsze, plik skryptu instalacyjnego musi być częścią magazynu zawartości instalowanego wraz z kompilacją. Sprawdź, czy plik znajduje się w folderze ContentRoot określonym dla aplikacji lub magazynu.

Po drugie, oznacz skrypt instalacyjny w skrypcie kompilacji magazynu, używając dyrektywy InstallScript. Przykład można zobaczyć na stronie dokumentacji o przesyłaniu na Steam w dziale o zaawansowanych zasadach mapowania plików.

Podczas tego procesu mają miejsce 2 rzeczy:
  • Skrypt instalacyjny jest przesyłany do Steam i podpisywany kryptograficznie. Podpis jest potwierdzany przez Steam przed wykonaniem jakiegokolwiek skryptu instalacyjnego i musi on wykonać pewne operacje, włączając w to zapis do ula HKLM na systemie Windows. Może to spowodować zmiany w lokalnej kopii skryptu instalacyjnego.
  • Skrypt instalacyjny jest oznaczony w manifeście magazynu zawartości. Możesz zobaczyć to w generowanym pliku manifest.txt jako 100 w polu Flags.
Gdy użytkownik Steam uruchomi grę, Steam przeskanuje wszystkie zamontowane magazyny tej gry w poszukiwaniu jakichkolwiek plików z flagą skryptu instalacyjnego, po czym je uruchomi.

Polecenie Registry

Polecenie Registry umożliwia tworzenie i modyfikowanie wartości rejestru „string” i „dword”. Każdy klucz pod nazwą klucza „Registry” będzie interpretowany jako pełna ścieżka do klucza rejestru, który chcesz utworzyć lub otworzyć. Pod tym kluczem określ klucz „string” lub „dword”. Wszelkie nazwy kluczy i wartości przechowywane w „stringu” lub „dwordzie” zostaną ustawione jako nazwa rejestru i wartości.
Aby ustawić domyślną wartość dla klucza rejestru, należy wprowadzić nazwę klucza jako (Default).

Polecenie Run Process

Polecenie Run Process umożliwia twojej aplikacji uruchamianie programów przed pierwszym uruchomieniem gry przez użytkownika.
Aby ustalić, czy program musi zostać uruchomiony, skrypt instalacyjny szuka nazwy klucza (jako wartości rejestru DWORD) w wartości HasRunKey. Jeśli brakuje tej wartości lub jest równa 0, to zostanie wywołany CreateProcess na wartościach processXX/commandXX. Jeśli CreateProcess nie powiedzie się, zostanie wywołane ShellExecuteEx. Jeśli kod programu ExitCode wynosi zero, skrypt instalacyjny przyjmie, że jego działanie powiodło się i zapisze twoją nazwę klucza w rejestrze jako 1.

Klienci Steam uwielbiają szybką i cichą instalację. Dodaj parametry „silent” albo „quiet” do wszystkich poleceń Run Process i dodaj tylko to, czego absolutnie potrzebujesz.
Wymagane pary klucz-wartość dla Run Process to:
  • Process 1 – ścieżka do programu, który chcesz uruchomić.
Opcjonalne pary klucz-wartość dla Run Process to:
  • Command 1 – opcjonalna komenda, którą chcesz dodać do programu.
  • HasRunKey – opcjonalny klucz rejestru sprawdzający, czy wymagany plik został już wcześniej zainstalowany.
  • NoCleanUp – opcjonalna flaga, po ustawieniu której skrypt instalacyjny nie usunie nazwy klucza, kiedy twoja aplikacja zostanie usunięta ze Steam.
  • MinimumHasRunValue – opcjonalne, ustawia minimalną wartość, jaką skrypt instalacyjny powinien sprawdzić podczas określania, czy program ma zostać uruchomiony.
  • Requirement_OS – opcjonalny klucz do zastosowania wymagań specyficznych dla danego systemu. Aby dowiedzieć się więcej, sprawdź dział o pakietach redystrybucyjnych specyficznych dla danego systemu.
  • AsCurrentUser – opcjonalna flaga; ustaw ją na 1, jeśli jest ważne dla danego programu, by został uruchomiony jako obecny użytkownik. W przeciwnym wypadku klient Steam może uruchomić go jako administrator, by uniknąć próśb o uruchomienie jako użytkownik z większymi uprawnieniami podczas korzystania w środowiskach Big Picture oraz VR.

Wyjątki w zaporze sieciowej

Jeśli gra korzysta z kodu sieciowego w dowolny sposób, użyj wyjątku zapory, aby automatycznie przyznać wyjątek dla niej w systemie Windows bez zmuszania użytkownika do jego zaakceptowania.
"Firewall" { "Space War Game" "%INSTALLDIR%\\SpaceWar.exe" }

Pakiety redystrybucyjne specyficzne dla danego systemu operacyjnego

Wartość Requirement_OS umożliwia uruchamianie różnych wersji instalacji w różnych wersjach systemów operacyjnych i SKU. Wymaga ona obecności nowej grupy klucza o nazwie Requirement_OS, w której będą znajdować się dodatkowe pary kluczy-wartości. Dostępne opcje systemów operacyjnych są wymienione poniżej.
  • Is64BitWindows – określa, że proces będzie się uruchamiał tylko w 64-bitowej wersji systemu operacyjnego. Wartości wynoszą 1 lub 0.
  • OSType – określa, że proces będzie się uruchamiał tylko na danej wersji systemu operacyjnego. Wartości wynoszą:
    • 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

Przykład wersji 64-bitowej
W tym przykładzie zostanie uruchomiona odpowiednia instalacja dla systemów 32- i 64-bitowych.
"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" } }

Przykład typu systemu operacyjnego
W tym przykładzie uruchomiona zostanie instalacja tylko dla Windows XP.

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

Zmienne środowiskowe

Zmienne środowiskowe są wspierane w skrypcie instalacyjnym. Wszystkie standardowe zmienne środowiskowe dostępne na systemie Windows mogą zostać użyte wraz z kilkoma innymi określonymi dla skryptu instalacyjnego. Ich lista to:
  • %INSTALLDIR% – pełna ścieżka instalacji aplikacji bez ukośników wstecznych.
  • %ROOTDRIVE% – litera dysku, na którym aplikacja jest zainstalowana, np. C.
  • %APPDATA% – folder \Użytkownicy\nazwa użytkownika\AppData\
  • %USER_MYDOCS% – uzyskaj folder \Użytkownicy\nazwa użytkownika\Dokumenty
  • %COMMON_MYDOCS% – uzyskaj folder \Użytkownicy\Wszyscy użytkownicy\Dokumenty
  • %LOCALAPPDATA% – folder \Użytkownicy\nazwa użytkownika\AppData\Local (na systemach Vista i nowszych).
  • %WinDir% – katalog instalacyjny Windows.
  • %STEAMPATH% – pełna ścieżka do katalogu instalacyjnego Steam.

Wartości określone dla języka

Zarówno wartościom „string”, jak i „DWORD” można przypisać różne dane w zależności od języka, którego używa użytkownik Steam. Aby to zrobić, utwórz podklucz w kluczu „string” lub „dword” z nazwą języka, a następnie przydziel w nim nazwy i wartości, np.:
"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" } } } } }

Skrypt instalacyjny pobiera język z klucza rejestru Steam, pytając o wartość „Language”. Jeżeli takowa nie zostanie znaleziona, to domyślnie zostanie użyta „english”.

Odinstalowywanie aplikacji

Kiedy użytkownik usuwa lub weryfikuje twoją aplikację ze Steam, skrypty instalacyjne zostaną wywołane, by usunąć wszelkie wartości rejestru, jakie ona utworzyła. Skrypt instalacyjny usunie także wartość używaną do określenia, czy program powinien być wykonywany z poleceniem Run Process[code-inline]. W ten sposób uruchomi się on wraz z kolejnym uruchomieniem aplikacji, chyba że została ustawiona flaga [code-inline]NoCleanUp.

Polecenie Run Process on Uninstall

Jeżeli musisz uruchomić jakikolwiek proces w momencie odinstalowania aplikacji, dodaj to do skryptu instalacyjnego. Nie odinstalowuj pospolitych pakietów redystrybucyjnych takich jak DirectX, msvc run time itd., ponieważ prawdopodobnie są one używane przez inne gry. Zamierzone użycie tej metody to tylko procesy odinstalowujące konkretną grę.
UWAGA: polecenie Run Process On Uninstall zostanie także wywołane, gdy użytkownik zweryfikuję aplikację z poziomu Steam. Nie używaj procesu, który usunie wszystkie pliki, ponieważ zmusi to Steam do ponownego pobrania wszystkiego podczas weryfikacji.
"InstallScript" { "Run Process On Uninstall" { "Process_name" { "Process 1" "process.exe" "Command 1" "/command" } } }

Najczęściej zadawane pytania

P: Dlaczego mój skrypt instalacyjny uruchamia pakiet redystrybucyjny za każdym razem, gdy włączam grę?
O: Zazwyczaj oznacza to, że pakiet redystrybucyjny zwraca niezerowy kod zwrotny. Steam sprawdza, czy kod zwrotny jest równy zeru. Jeśli wynosi on zero, oznacza on pakiet redystrybucyjny jako zainstalowany i nie uruchamia go ponownie. Jeśli zwróci jakąkolwiek inną wartość, Steam spróbuje uruchomić go ponownie przy następnym uruchomieniu.

Aby to naprawić, sprawdź ścieżki i parametry pakietów redystrybucyjnych. Niektóre pakiety redystrybucyjne zwracają wartości niezerowe, jeśli są już zainstalowane na danym komputerze. Często można to naprawić za pomocą flag pakietu „silent” lub „quiet”.

P: Dlaczego mój klucz rejestru nie jest zapisywany?
O: Zazwyczaj dzieje się tak, ponieważ skrypt instalacyjny nie jest podpisany, a ty próbujesz zapisać do HKLM.
Sprawdź dział dotyczący integracji w kompilacji i upewnij się, że klucz "kvsignatures" został dodany do twojego skryptu podczas kompilowania, ponieważ Steam wymaga ukończonego podpisu, by zapisywać do HKLM.

Problem ten może też być powodowany przez wirtualizację 64-bitowego systemu Windowsa na 64-bitowym systemie Windows. Steam używa do zapisu w rejestrze ścieżki Wow6432Node.

P: Dlaczego mój skrypt instalacyjny w ogóle nie chce się uruchomić?
O: Sprawdź jeszcze raz, czy konfiguracja jest poprawna.

P: Jak mogę dodać pakiety redystrybucyjne dla macOS? Dlaczego polecenie Run Process nie działa w moim skrypcie instalacyjnym macOS?
O: Obecnie nie wspieramy instalacji pakietów redystrybucyjnych macOS. Musisz umieścić instalator w swoim głównym pliku wykonywalnym.
[/code-inline][/code-inline]