เอกสาร Steamworks
การสร้างและการใช้งานสคริปต์ติดตั้ง

ภาพรวม

แม้ว่า Steam จะสามารถติดตั้ง redistributables ทั่วไป มากมายได้โดยอัตโนมัติ แต่แอปพลิเคชันของคุณก็อาจจะมีข้อกำหนดในการใช้งานครั้งแรกอย่างอื่นอยู่
หมายเหตุ: ฟังก์ชันการทำงานของสคริปต์ติดตั้งที่ได้ระบุไว้ด้านล่างนี้มีไว้สำหรับระบบปฏิบัติการ Windows เป็นหลัก การรองรับ macOS จะถูกจำกัดไว้เแค่เพียงสิทธิ์ และ symlinks ของไฟล์เท่านั้น ในขณะนี้ยังไม่มีฟังก์ชันการทำงานของสคริปต์ติดตั้งระบบ Linux/SteamOS

ไฟล์สคริปต์ติดตั้ง คือ ไฟล์การกำหนดค่าสำหรับเรียกใช้การดำเนินการบางอย่างขณะติดตั้ง

เกมตัวเต็ม/แอปพลิเคชัน และแพ็คเกจเนื้อหาดาวน์โหลดอาจจะมีสคริปต์ติดตั้งได้ทั้งคู่ หากคุณได้ ประสานสคริปต์ติดตั้งของคุณไว้ในบิลด์ของคุณ คุณอาจจะมีสคริปต์ติดตั้งจำนวนเท่าใดก็ได้ สำหรับแอป 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 ต่อจากรูทจะอธิบายถึงประเภทการดำเนินการที่จะเกิดขึ้น

หมายเหตุ: ชื่อคีย์และค่าทั้งหมดจะสามารถใช้ Escape Sequences ได้ ดังนั้น หากคุณใช้ \ กรุณาทำเป็น \\

การประสานสคริปต์ติดตั้งไว้ในบิลด์ของคุณ

เริ่มแรก ไฟล์สคริปต์ติดตั้งจะต้องเป็นส่วนหนึ่งของดีโปที่ได้ติดตั้งไว้กับตัวบิลด์ดังกล่าว กรุณาตรวจสอบให้มั่นใจว่าไฟล์ดังกล่าวได้อยู่ใน ContentRoot ของแอปหรือดีโปที่ได้ให้นิยามไว้

จากนั้น ทำเครื่องหมายสคริปต์ติดตั้งโดยการใช้คำสั่ง InstallScript ในสคริปต์ของบิลด์ดีโป คุณสามารถดูตัวอย่างได้ที่หน้า การอัปโหลดไปยัง Steam - กฏการแมปไฟล์ขั้นสูง

ในระหว่างกระบวนการบิลด์ จะมีสองสิ่งเกิดขึ้น:
  • สคริปต์ติดตั้งจะถูกอัปโหลดไปยัง Steam และถูกลงนามเข้ารหัสไว้ Steam จะตรวจสอบความถูกต้องของลายเซ็นก่อนเริ่มดำเนินการการสคริปต์ติดตั้งนั้น ๆ และจำเป็นจะต้องดำเนินการบางอย่าง ซึ่งรวมถึงการเขียนไปยัง HKLM hive บน Windows ซึ่งอาจจะทำให้สำเนาภายในเครื่องของสคริปต์ติดตั้งของคุณถูกแก้ไขได้
  • สคริปต์ติดตั้งจะถูกทำเครื่องหมายในมานิเฟสต์ดีโป ซึ่งคุณสามารถดูได้ในไฟล์ manifest.txt ที่ถูกสร้างขึ้นเป็น a 100 ในช่องข้อความ แฟล็ก
เมื่อผู้ใช้ Steam เริ่มเปิดเกม Steam จะสแกนดีโปทั้งหมดที่เชื่อมต่ออยู่สำหรับเกมนั้น เพื่อหาไฟล์ใดก็ตามที่มีแฟล็กสคริปต์ติดตั้งแล้วเรียกใช้ไฟล์ดังกล่าว

รีจิสทรี

คำสั่งรีจิสทรีจะอนุญาตให้คุณสร้างหรือแก้ไขค่ารีจิสทรีของสตริงและ dword ได้ คีย์ใด ๆ ที่อยู่ใต้ชื่อคีย์ "รีจิสทรี" จะถูกปฏิบัติว่าเป็นเส้นทางแบบเต็มไปยังคีย์รีจิสทรีที่คุณต้องการจะสร้างหรือเปิด ภายใต้คีย์ดังกล่าว ให้ระบุคีย์ "สตริง" หรือ "dword" ชื่อคีย์และค่าใดก็ตามที่จัดเก็บไว้ในคีย์ "สตริง" หรือ "dword" จะเป็นชื่อรีจิสทรีและค่าที่ตั้งค่าไว้
ในการตั้ง ค่าเริ่มต้น ให้กับคีย์รีจิสทรี คุณควรจะใส่ชื่อคีย์เป็น (เริ่มต้น)

คำสั่ง Run Process

คำสั่ง Run Process จะอนุญาตให้แอปพลิเคชันของคุณเรียกใช้โปรแกรมได้ก่อนที่ผู้ใช้งานจะเปิดเกมของคุณขึ้นมาเป็นครั้งแรก
ในการพิจารณาว่าจำเป็นจะต้องใช้โปรแกรมในการเรียกใช้หรือไม่ สคริปต์ติดตั้งจะมองหาชื่อคีย์ (ที่เป็นค่า DWORD ในรีจิสทรี) ที่อยู่ในค่า HasRunKey หากค่าดังกล่าวไม่มีอยู่ หรือมีค่าเป็น 0 ก็จะเรียก CreateProcess ในค่า processXX/commandXX หาก CreateProcess ล้มเหลว จะมีการเรียก ShellExecuteEx หาก ExitCode ของโปรแกรมเป็น 0 สคริปต์ติดตั้งจะถือว่าประสบความสำเร็จและจะเขียนชื่อคีย์ของคุณเป็น 1 ลงในรีจิสทรี

ลูกค้าของ Steam ชอบการติดตั้งที่ทั้งรวดเร็วและไม่รบกวนการใช้งานอื่น ๆ เพิ่มพารามิเตอร์ 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.

Firewall Exceptions

หากเกมของคุณจำเป็นจะต้องใช้การเชื่อมต่อทางเครือข่ายใด ๆ ก็ตาม ให้ใช้ข้อยกเว้นของไฟร์วอลล์เพื่อมอบสิทธิ์ข้อยกเว้นของไฟร์วอลล์ใน Windows โดยอัตโนมัติโดยที่ไม่จำเป็นต้องบังคับให้ผู้ใช้ต้องยอมรับข้อยกเว้น
"Firewall" { "Space War Game" "%INSTALLDIR%\\SpaceWar.exe" }

OS Specific Redists

ค่า Requirement_OS จะพร้อมใช้งานในการเรียกใช้การติดตั้งต่าง ๆ ในเวอร์ชัน/SKU ของ OS หลาย ๆ ประเภท ซึ่งจำเป็นต้องใช้กลุ่มคีย์ใหม่ที่เรียกว่า Requirement_OS จากนั้นจะต้องใช้ค่าคีย์เพิ่มเติมที่จับคู่ไว้ภายใน ตัวเลือก OS ที่สามารถใช้งานได้ระบุไว้ด้านล่างนี้
  • Is64BitWindows - ระบุว่ากระบวนการจะทำงานบนระบบปฏิบัติการเวอร์ชัน 64 บิตเท่านั้น ค่าที่สามารถระบุได้คือ 0 หรือ 1
  • 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% - เส้นทางเต็มที่ได้ติดตั้งแอปพลิเคชันไว้ โดยไม่ใส่เครื่องหมาย backslash
  • %ROOTDRIVE%0> - ตัวอักษรระบุไดรฟ์ที่ได้ติดตั้งแอปพลิเคชันไว้ เช่น 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

ค่าเฉพาะภาษา

ทั้งค่าสตริงและ DWORD สามารถกำหนดข้อมูลที่ต่างกัน ทั้งนี้ขึ้นอยู่กับภาษาที่ผู้ใช้กำลังเรียกใช้ Steam ในการใช้งาน ให้สร้างซับคีย์ในคีย์ "สตริง" หรือ "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 ซึ่งจะคิวรี่ค่า "ภาษา" หากไม่พบค่า ก็จะใช้ "english" เป็นค่าเริ่มต้น

การถอนการติดตั้งแอป

เมื่อผู้ใช้ลบหรือยืนยันแอปของคุณจาก Steam ก็จะมีการเรียกสคริปต์ติดตั้งเพื่อลบค่ารีจิสทรีที่แอปสร้างขึ้นมา นอกจากนี้ สคริปต์ติดตั้งจะลบค่าที่ใช้พิจารณาว่าควรเรียกใช้โปรแกรมจาก Run Process[code-inline] เพื่อให้สามารถดำเนินการได้ในครั้งต่อไปที่แอปของคุณเรียกใช้ (เว้นแต่ว่าจะมีการตั้งแฟล็ก [code-inline]NoCleanUp)

คำสั่ง Run Process ในการถอนการติดตั้ง

หากคุณจำเป็นจะต้องเรียกใช้กระบวนการใดก็ตามในขณะกำลังถอนการติดตั้งแอปของคุณ ให้เพิ่มสิ่งนี้เข้าไปยังสคริปต์ติดตั้งด้วย กรุณาอย่าถอนการติดตั้ง common redists เช่น DirectX, msvc run time ฯลฯ เพราะว่าเกมอื่น ๆ จำเป็นจะต้องใช้สิ่งเหล่านี้ นี่เป็นการดำเนินการที่มีไว้สำหรับกระบวนการถอนการติดตั้งที่เจาะจงเฉพาะเกมเท่านั้น
หมายเหตุ: จะมีการเรียก Run Process ในการถอนการติดตั้ง เมื่อผู้ใช้ได้ทำการยืนยันแอปบน Steam อย่าเรียกใช้กระบวนการที่จะลบไฟล์ทั้งหมด เพราะจะทำให้ Steam ต้องดาวน์โหลดทุกอย่างซ้ำอีกรอบเวลาที่ทำการยืนยัน
"InstallScript" { "Run Process On Uninstall" { "Process_name" { "Process 1" "process.exe" "Command 1" "/command" } } }

คำถามที่พบบ่อย

ถาม: ทำไมสคริปต์ติดตั้งของฉันถึงเรียกใช้ Redistributable ของฉันในทุกครั้งที่ฉันเปิดเกมขึ้นมา?
ตอบ: โดยทั่วไปแล้วนี่หมายความว่า redist ได้คืนค่ารหัสคืนค่าที่ไม่ใช่ศูนย์กลับมา Steam จะมีการตรวจสอบว่ารหัสที่คืนมาให้นั้นมีค่าเป็นศูนย์ หากพบว่ารหัสที่คืนค่ามามีค่าเป็นศูนย์ Steam จะทำเครื่องหมาย redist ดังกล่าวว่าได้รับการติดตั้งแล้ว และจะไม่เรียกใช้ redist ดังกล่าวอีก หากคืนค่ามาเป็นค่าอื่น ๆ Steam จะพยายามทำการเรียกใช้อีกครั้งในการเปิดใช้ครั้งถัดไป

ในการแก้ไข ให้ตรวจสอบเส้นทางและพารามิเตอร์ของ redistributable ของคุณ สำหรับ redist บางตัวจะคืนค่าที่ไม่ใช่ศูนย์กลับมา หากมีอยู่บนเครื่องเรียบร้อยแล้ว ส่วนมากสามารถแก้ไขได้ด้วยการใช้แฟล็ก silent หรือ quiet ของ redist นั้น ๆ

ถาม: ทำไมถึงไม่มีการเขียนคีย์รีจิสทรีของฉัน?
ตอบ: โดยปกติแล้วเรื่องนี้จะมีสาเหตุมาจากการที่สคริปต์ติดตั้งยังไม่ได้ถูกลงนามและคุณกำลังเขียนไปยัง HKLM
กรุณาดูเพิ่มเติมที่หมวด การประสานบิลด์ และตรวจสอบให้มั่นใจว่าคีย์ "kvsignatures" ได้ถูกเพิ่มเข้าไปยังสคริปต์ของคุณแล้วในระหว่างการบิลด์ เพราะ Steam จำเป็นต้องใช้การลงนามนี้ที่เสร็จสมบูรณ์แล้วในการเขียนไปยัง HKLM

รวมทั้งอาจจะมีสาเหตุมาจาก Windows 64 bit Virtualization ของ Windows 64 บิต โดย Steam จะเขียนไปยังเส้นทาง Wow6432Node ที่อยู่ในรีจิสทรี

ถาม: ทำไมสคริปต์ติดตั้งของฉันถึงดูเหมือนจะไม่ยอมทำงานเลย?
ตอบ: กรุณาตรวจสอบอีกรอบว่าการกำหนดค่าของคุณได้รับการจัดเตรียมเหมาะสมดีแล้ว

ถาม: ฉันจะเพิ่ม redistributables ของ Mac ลงไปได้อย่างไร? หรือทำไม Run Process ถึงไม่ทำงานในสคริปต์ติดตั้งบนเครื่อง Mac ของฉัน?
ตอบ: ในขณะนี้ทางเรายังไม่ได้ให้การรองรับการติดตั้ง redistributables ของ Mac คุณจำเป็นจะต้องใส่ตัวติดตั้งเข้าไปยังตัวโปรแกรมที่สั่งใช้งานได้ตัวหลักของคุณ
[/code-inline][/code-inline]