เอกสาร Steamworks
คู่มือการใช้งานเวิร์กชอป Steam

บทนำ

เวิร์กชอป Steam เป็นระบบสำหรับเก็บข้อมูลแบ็กเอนด์ และเป็นหน้าเว็บแบบฟรอนต์เอนด์ที่ช่วยอำนวยความสะดวกในการเก็บข้อมูล จัดระเบียบ เรียงลำดับ ให้คะแนน และดาวน์โหลดเนื้อหาสำหรับเกมหรือแอปพลิเคชัน

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

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

ประเภทของเวิร์กชอป Steam, การสร้างรายได้ และแนวทางปฏิบัติที่ดีที่สุด

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

การจัดการสถานะการมองเห็นของเวิร์กชอป Steam

เวิร์กชอป Steam เป็นเว็บไซต์ที่โฮสต์ผ่าน Steam ซึ่งทำหน้าที่นำเสนอเนื้อหาที่แชร์ และเปิดโอกาสให้ผู้ใช้ได้โหวตและแสดงความคิดเห็นเกี่ยวกับเนื้อหาที่เผยแพร่ให้เห็นผ่านชุมชน โดยค่าเริ่มต้นแล้ว แอปพลิเคชันต่าง ๆ ในเวิร์กชอปจะไม่เผยแพร่ต่อสาธารณะ เพื่อปกปิดเนื้อหาที่ไม่ต้องการให้แชร์ผ่านพอร์ทัลเวิร์กชอป Steam เอาไว้ จนกว่าจะเลือกเผยแพร่เองโดยตั้งค่าเวิร์กชอปให้เป็นแบบสาธารณะ
คุณสามารถตั้งค่าสถานะการมองเห็นของเวิร์กชอปได้โดยทำตามขั้นตอนดังต่อไปนี้:
  1. ไปที่หน้าหน้ารองรับของแอปพลิเคชันในเว็บไซต์ Steamworks
  2. คลิก แก้ไขการตั้งค่า Steamworks
  3. จากแท็บ เวิร์กชอป ให้เลือก ทั่วไป
  4. จากด้านขวาของหน้า ให้ไปที่หัวข้อ สถานะการมองเห็น
  5. ใช้ปุ่มตัวเลือกเพื่อเลือกระดับการเปิดเผยที่ต้องการ ได้แก่ Developers Only (เฉพาะผู้พัฒนา), Developers & Testers (ผู้พัฒนาและผู้เข้าร่วมการทดสอบ), Customers & Developers (ลูกค้าและผู้พัฒนา) และ Everyone (ทุกคน)
  6. จากแท็บ เผยแพร่ ให้คลิก เตรียมเผยแพร่
  7. คลิก เผยแพร่ไปที่ Steam แล้วทำตามกระบวนการที่กำหนดเพื่อเผยแพร่การเปลี่ยนแปลง
หมายเหตุ: หากต้องการเปลี่ยนสถานะการมองเห็นเป็น Everyone (ทุกคน) จะต้องทำตามขั้นตอนในรายการตรวจสอบของเวิร์กชอป ซึ่งได้แก่ การระบุแบรนด์, ชื่อของเนื้อหา, คำอธิบาย และจะต้องมีเนื้อหาอย่างน้อย 1 รายการที่เปิดเผยต่อสาธารณะ

ภาพรวมเชิงเทคนิค

ฟังก์ชันในการแชร์และใช้เนื้อหาที่ผู้ใช้สร้างขึ้นจะอยู่ใน ISteamUGC API ซึ่งอยู่ที่ Steamworks SDK เมธอดที่เตรียมให้นั้นสามารถนำไปใช้เพื่อแชร์เนื้อหาไอเท็มเวิร์กชอป ซึ่งผู้เล่นจะได้ค้นพบไอเท็มเหล่านี้ผ่านประสบการณ์การใช้เวิร์กชอป Steam หรือการใช้แอป

จะต้องเข้าถึง Workshop API ผ่านพอยน์เตอร์ที่ได้คืนค่ามาจาก SteamUGC()

ตัวอย่าง:
SteamAPICall_t hSteamAPICall = SteamUGC()->CreateItem( SteamUtils()->GetAppID(), k_EWorkshopFileTypeMicrotransaction );

การเปิดใช้งาน ISteamUGC สำหรับเกมหรือแอปพลิเคชัน

ก่อนจะสามารถอัปโหลดไอเท็มเวิร์กชอปไปยังแบ็กเอนด์ของ Steamworks คุณจะต้องตั้งค่า 2 ประการ ได้แก่โควต้าของ Steam Cloud และเปิดใช้ ISteamUGC API

คุณสมบัติ Steam Cloud ใช้สำหรับบันทึกรูปภาพตัวอย่างที่เกี่ยวข้องกับไอเท็มเวิร์กชอป สามารถกำหนดค่าโควต้าของ Steam Cloud ได้โดยทำตามขั้นตอนต่อไปนี้:
  1. ไปยังหน้า การตั้งค่าคลาวด์บน Steam ในแผงควบคุมผู้ดูแลแอปของ Steamworks
  2. ตั้งค่า โควต้าจำนวนไบต์ต่อผู้ใช้หนึ่งราย และ จำนวนไฟล์ที่อนุญาตต่อผู้ใช้หนึ่งราย ให้เป็นค่าที่เหมาะกับการเก็บภาพตัวอย่าง
  3. Click Save
  4. จากแท็บ เผยแพร่ ให้คลิก เตรียมเผยแพร่
  5. คลิก เผยแพร่ไปที่ Steam แล้วทำตามกระบวนการที่กำหนดเพื่อเผยแพร่การเปลี่ยนแปลง

สามารถเปิดใช้ ISteamUGC API ได้โดยทำตามขั้นตอนต่อไปนี้:
  1. ไปที่หน้า การกำหนดค่าเวิร์กชอป Steam บนแผงควบคุมผู้ดูแลแอป
  2. Find the Additional Configuration Options section.
  3. Check Enable ISteamUGC for file transfer.
  4. Click Save.
  5. From the Publish tab, click Prepare for Publishing.
  6. คลิก เผยแพร่ไปที่ Steam แล้วทำตามกระบวนการที่กำหนดเพื่อเผยแพร่การเปลี่ยนแปลง
เมื่อตั้งค่าเหล่านี้เรียบร้อยแล้ว ก็จะสามารถอัปโหลดเนื้อหาเวิร์กชอปผ่าน API ได้

การสร้างและอัปโหลดเนื้อหา

กระบวนการสร้างและอัปโหลดเนื้อหาเวิร์กชอปนั้นง่ายและทำซ้ำได้ ดังแสดงในแผนผังลำดับการทำงานด้านล่าง

ISteamUGCFlow-CreateUpload-Web2.png

การสร้างไอเท็มเวิร์กชอป

  1. ไอเท็มเวิร์กชอปทุกชิ้นจะเริ่มมีตัวตนขึ้นจากการเรียก ISteamUGC::CreateItem
    • ตัวแปร nConsumerAppId ควรบรรจุไอดีแอปของเกมหรือแอปพลิเคชัน ห้ามส่งค่า App ID ของเครื่องมือสร้างไอเท็มเวิร์กชอป หากเป็น App ID ที่แยกต่างหาก
    • EWorkshopFileType เป็นประเภทของอีนิวเมอเรชันที่นิยามวิธีแบ่งปันไฟล์กับชุมชน ค่าที่สามารถใช้งานได้ประกอบด้วย:
      • k_EWorkshopFileTypeCommunity - ประเภทของไฟล์นี้ใช้ในการนิยามไฟล์ที่ผู้ใช้จะอัปโหลดและเปิดให้ทุกคนในชุมชนดาวน์โหลด โดยทั่วไปแล้วใช้สำหรับแชร์ม็อดที่ผู้ใช้สร้างเอง
      • k_EWorkshopFileTypeMicrotransaction - ประเภทของไฟล์นี้ใช้ในการนิยามไฟล์ที่ผู้ใช้อัปโหลด โดยมีจุดมุ่งหมายเพื่อส่งให้เกมพิจารณาคัดเลือกให้เป็นเนื้อหาอย่างเป็นทางการ ผู้ใช้จะไม่สามารถดาวน์โหลดไฟล์เหล่านี้ผ่านเวิร์กชอปได้ แต่จะสามารถเรียกดูและให้คะแนนได้โดยชุมชน
        ซึ่งเป็นการใช้งานในเกม Team Fortress 2
  2. ลงทะเบียนตัวจัดการผลลัพธ์การเรียก CreateItemResult_t
  3. ขั้นแรก ให้ตรวจสอบ m_eResult เพื่อยืนยันว่าสร้างไอเท็มสำเร็จแล้ว
  4. เมื่อเรียกใช้ตัวจัดการผลลัพธ์การเรียก ให้อ่านค่า m_nPublishedFileId แล้วบันทึกไว้เพื่อการอัปเดตไอเท็มเวิร์กชอปในอนาคต (เช่น ในไฟล์โปรเจ็กต์ที่เกี่ยวข้องกับเครื่องมือสร้างเนื้อหา)
  5. ควรจะตรวจสอบตัวแปร m_bUserNeedsToAcceptWorkshopLegalAgreement และถ้าหากมีค่าเป็น true ผู้ใช้ควรจะถูกนำไปยังหน้าสำหรับยอมรับข้อตกลงทางกฎหมาย อ่านหัวข้อ ข้อตกลงทางกฎหมายของเวิร์กชอป เพื่อรับรายละเอียดเพิ่มเติม

การอัปโหลดไอเท็มเวิร์กชอป

  1. เมื่อสร้างไอเท็มเวิร์กชอปและคืนค่า PublishedFileId_t แล้ว จะสามารถบรรจุและอัปโหลดเนื้อหาไอเท็มเวิร์กชอปไปยังเวิร์กชอป Steam ได้
  2. การอัปเดตไอเท็มจะเริ่มต้นด้วยการเรียกไปยัง ISteamUGC::StartItemUpdate
  3. เมื่อใช้ UGCUpdateHandle_t ที่คืนค่ามาจากการเรียก ISteamUGC::StartItemUpdate คุณก็จะสามารถเรียกเมธอดต่าง ๆ ของ ISteamUGC::SetItem[...] เพื่ออัปเดตชื่อ คำอธิบาย สถานะการมองเห็น แท็ก เนื้อหาไอเท็ม และรูปภาพตัวอย่างไอเท็ม
    • ISteamUGC::SetItemTitle - ตั้งชื่อใหม่ให้กับไอเท็ม
    • ISteamUGC::SetItemDescription - ตั้งค่าคำอธิบายใหม่ให้กับไอเท็ม
    • ISteamUGC::SetItemUpdateLanguage - เลือกภาษาของชื่อและคำอธิบายที่จะตั้งค่าในการอัปเดตไอเท็มนี้
    • ISteamUGC::SetItemMetadata - ตั้งค่าเมทาดาตาแบบไม่เจาะจงสำหรับไอเท็ม สามารถคืนค่าเมทาดาตาจากการคิวรี่ได้โดยไม่ต้องดาวน์โหลดและติดตั้งเนื้อหาจริง ๆ
    • ISteamUGC::SetItemVisibility - ตั้งค่าสถานะการมองเห็นไอเท็ม
    • ISteamUGC::SetItemTags - ตั้งค่าแท็กแบบไม่เจาะจงที่กำหนดโดยผู้พัฒนาให้กับไอเท็ม
    • ISteamUGC::AddItemKeyValueTag - เพิ่มคู่แท็กคีย์-ค่าให้กับไอเท็ม คีย์สามารถแมปกับค่าได้หลายค่า (ความสัมพันธ์ 1 รายการต่อหลายรายการ)
    • ISteamUGC::RemoveItemKeyValueTags - ลบแท็กคีย์-ค่าที่มีอยู่ออกจากไอเท็ม
    • ISteamUGC::SetItemContent - ตั้งค่าโฟลเดอร์ที่จะจัดเก็บในฐานะเนื้อหาของไอเท็ม
    • ISteamUGC::SetItemPreview - ตั้งค่ารูปภาพพรีวิวหลักสำหรับไอเท็ม
  4. เมื่อเรียกการอัปเดตเสร็จเรียบร้อยแล้ว การเรียก ISteamUGC::SubmitItemUpdate จะเริ่มกระบวนการอัปโหลดไปยังเวิร์กชอป Steam
    • ลงทะเบียนตัวจัดการผลลัพธ์การเรียก SubmitItemUpdateResult_t
    • เมื่อเรียกใช้ตัวจัดการผลลัพธ์การเรียก ให้ตรวจสอบ m_eResult เพื่อยืนยันว่าการอัปโหลดเสร็จเรียบร้อย
    • หมายเหตุ: ขณะนี้ยังไม่มีเมธอดสำหรับยกเลิกการอัปเดตและการอัปโหลดไอเท็ม หากเรียกใช้งานไปแล้ว
  5. สามารถติดตามความคืบหน้าในการอัปโหลดได้ด้วย ถ้าต้องการ ISteamUGC::GetItemUpdateProgress
    • EItemUpdateStatus ใช้สำหรับนิยามความคืบหน้าในการอัปโหลดและอัปเดต
    • punBytesProcessed และ punBytesTotal เพื่อเตรียมอินพุตสำหรับส่วนควบคุมของอินเตอร์เฟสผู้ใช้ เช่น แถบสำหรับแจ้งความคืบหน้าในการอัปโหลด
    • punBytesTotal อาจอัปเดตในระหว่งกระบวนการอัปโหลด ทั้งนี้ขึ้นอยู่กับสถานะการอัปเดตไอเท็ม
  6. ยืนยันว่าผู้ใช้ยอมรับข้อตกลงทางกฎหมายแล้ว โดยใช้วิธีเดียวกับในหัวข้อ \การสร้างไอเท็มเวิร์กชอป\ ข้อตกลงนี้เป็นสิ่งที่จำเป็น ในกรณีที่ผู้ใช้ไม่ได้เป็นผู้สร้างไอเท็มแต่แรก แต่นำไอเท็มที่มีอยู่มาดัดแปลงแก้ไข

หมายเหตุเพิ่มเติม

  • ในสมัยก่อน ไอเท็มเวิร์กชอปนั้นอยู่ในรูปแบบไฟล์เพียงไฟล์เดียว แต่เมื่อมี ISteamUGC นิยามของไอเท็มเวิร์กชอปได้เปลี่ยนมาเป็นโฟลเดอร์ที่บรรจุไฟล์ต่างๆ แทน
  • หากไอเท็มเวิร์กชอปต้องการเมทาดาตาเพิ่มเติม เพื่อให้แอปพลิเคชันที่ใช้ไอเท็มนำข้อมูลไปใช้ คุณสามารถแนบเมทาดาตาไปกับไอเท็มได้โดยเรียก ISteamUGC::SetItemMetadata สามารถคืนค่าเมทาดาตานี้จากการคิวรี่ได้โดยไม่ต้องดาวน์โหลดและติดตั้งเนื้อหาของไอเท็ม
    หากเป็นสมัยก่อน เราจะแนะนำให้คุณบันทึกเมทาดาตานี้กับไฟล์ที่อยู่ในโฟลเดอร์เก็บไอเท็มเวิร์กชอป ซึ่งแน่นอนว่าขณะนี้ก็ยังทำได้อยู่

การใช้เนื้อหา

การใช้เนื้อหาในเวิร์กชอปนั้นแบ่งออกเป็น 2 หมวดหมู่ ได้แก่ การสมัครสมาชิกกับไอเท็ม และการติดตั้งไอเท็ม

การสมัครสมาชิกกับไอเท็ม

การสมัครสมาชิกไอเท็มเวิร์กชอปส่วนใหญ่จะเกิดขึ้นผ่านพอร์ทัลเวิร์กชอป Steam ซึ่งเป็นสถานที่รวบรวมเกมและแอปพลิเคชันทั้งหมด ซึ่งช่วยให้ผู้ใช้สามารถค้นพบและสมัครสมาชิกไอเท็มเป็นประจำได้บนเว็บไซต์เวิร์กชอป

อย่างไรก็ดี ISteamUGC ได้เตรียมเมธอด 2 เมธอดสำหรับดำเนินการสมัครสมาชิกและยกเลิกการสมัครสมาชิกไอเท็มเวิร์กชอปผ่านโปรแกรม เพื่อรองรับการจัดการการสมัครสมาชิกไอเท็มภายในเกม
  • ISteamUGC::SubscribeItem - สมัครสมาชิกไอเท็มเวิร์กชอป ไอเท็มดังกล่าวจะได้รับการดาวน์โหลดและติดตั้งทันที
  • ISteamUGC::UnsubscribeItem - เลิกสมัครสมาชิกไอเท็มเวิร์กชอป ซึ่งจะทำให้ไอเท็มถูกลบออกหลังจากออกจากเกม

มีเมธอดเพิ่มเติม 2 เมธอดสำหรับไล่ลำดับรายการไอเท็มที่ผู้ใช้สมัครสมาชิกด้วยอีนิวเมอเรต
  • ISteamUGC::GetNumSubscribedItems - รับจำนวนไอเท็มทั้งหมดที่ผู้ใช้ปัจจุบันสมัครสมาชิกอยู่ สำหรับเกมหรือแอปพลิเคชัน
  • ISteamUGC::GetSubscribedItems - รับรายการไอเท็มทั้งหมดที่ผู้ใช้ปัจจุบันสมัครสมาชิกอยู่ สำหรับเกมปัจจุบัน

การรับการแจ้งเตือนเกี่ยวกับการสมัครสมาชิกภายนอก

สามารถรับการแจ้งเตือนในเกมได้ เมื่อผู้ใช้สมัครสมาชิกหรือยกเลิกการสมัครสมาชิกจากไฟล์ ไม่ว่าจะใช้กลไกแบบใดก็ตาม (เช่น ISteamUGC, เว็บไซต์เวิร์กชอป Steam):
  • ลงทะเบียนตัวจัดการคอลแบ็กสำหรับ RemoteStoragePublishedFileSubscribed_t และ RemoteStoragePublishedFileUnsubscribed_t
  • สตรัคจะได้รับข้อมูล ISteamRemoteStorage::PublishedFileId_t ซึ่งสามารถใช้เข้าถึงข้อมูลเกี่ยวกับไอเท็มเวิร์กชอปได้
  • สตรัคยังบรรจุไอดีของแอปพลิเคชัน (m_unAppID) ที่เชื่อมโยงกับไอเท็มเวิร์กชอปอีกด้วย ควรนำไปเปรียบเทียบกับไอดีแอปพลิเคชันที่กำลังทำงานอยู่ เนื่องจะมีการเรียกตัวจัดการสำหรับการสมัครสมาชิกไอเท็มทั้งหมด โดยไม่คำนึงถึงแอปพลิเคชันที่กำลังทำงานอยู่

การติดตั้งไอเท็ม

เมื่อทราบข้อมูลการสมัครสมาชิกไอเท็ม ก็จะสามารถใช้เมธอดการใช้ที่เหลืออยู่ได้ เมธอดเหล่านี้จะมอบข้อมูลเกี่ยวกับสถานะการดาวน์โหลดและติดตั้งไอเท็มกลับไปให้เกม การดาวน์โหลดไอเท็มเวิร์กชอปจะดำเนินการผ่านไคลเอนต์ Steam และจะเกิดขึ้นโดยอัตโนมัติ โดยเป็นไปตามกฎต่อไปนี้:
  1. เมื่อไคลเอนต์ Steam แจ้งเกมหรือแอปพลิเคชันที่จะเรียกใช้ ดีโปต์แอปทั้งหมดที่ได้รับการอัปเดตจะถูกดาวน์โหลดและติดตั้ง
  2. ไอเท็มเวิร์กชอปที่ติดตั้งไว้ทั้งหมดจะได้รับการอัปเดตถ้าจำเป็น
  3. จากนั้นเกมหรือแอปพลิเคชันจะเปิดทำงาน
  4. ไอเท็มเวิร์กชอปที่เพิ่งสมัครสมาชิกใหม่และยังไม่ได้ดาวน์โหลด จะได้รับการดาวน์โหลดและติดตั้งอยู่เบื้องหลัง
    • ไฟล์ที่สมัครสมาชิกแล้วจะถูกดาวน์โหลดมายังไคลเอนต์ตามลำดับของการสมัครสมาชิก
    • หน้าดาวน์โหลด Steam จะแสดงการดาวน์โหลดไอเท็ม Workshop พร้อมแบนเนอร์จำเพาะเพื่อระบุว่ากำลังดาวน์โหลดไอเท็มเวิร์กชอปอยู่
หมายเหตุ: การใช้คุณสมบัติ "ยืนยันความสมบูรณ์ของไฟล์เกม" ในไคลเอนต์ Steam จะทำให้การดาวน์โหลดไอเท็มเวิร์กชอปเริ่มต้นขึ้น

แต่เนื่องจากเกมจะเริ่มทำงานก่อนการดาวน์โหลดและติดตั้งเนื้อหาใหม่ที่เพิ่งสมัครสมาชิกใหม่ เมธอดการใช้ที่เหลือจึงมีหน้าที่สำหรับช่วยติดตามและจัดการความคืบหน้าในการติดตั้ง และยังสามารถใช้เมื่อสมัครสมาชิกไอเท็มในเกม เพื่อมอบสถานะการติดตั้งแบบเรียลไทม์

สถานะของไอเท็มเวิร์กชอป

  • ISteamUGC::GetItemState - รับสถานะปัจจุบันของไอเท็มเวิร์กชอปในไคลเอนต์นี้

ความคืบหน้าในการดาวน์โหลดไอเท็มเวิร์กชอป

  • ISteamUGC::GetItemDownloadInfo - รับข้อมูลเกี่ยวกับการดาวน์โหลดไอเท็มเวิร์กชอปที่รอดำเนินการอยู่ซึ่งตั้งค่า k_EItemStateNeedsUpdate เอาไว้

เริ่มต้นหรือเพิ่มระดับความสำคัญของการดาวน์โหลดไอเท็มเวิร์กชอป

  • ISteamUGC::DownloadItem
    • ตั้งค่าbHighPriority เป็น true เพื่อหยุดการดาวน์โหลดต่าง ๆ ที่ดำเนินการอยู่ แล้วเริ่มการดาวน์โหลดไอเท็มเวิร์กชอปนี้ทันที
    • ถ้าค่าที่คืนมาเป็น true ให้ลงทะเบียนและรอคอลแบ็ก ISteamUGC::DownloadItemResult_t ก่อนเรียก ISteamUGC::GetItemInstallInfo หรือเข้าถึงไอเท็มเวิร์กชอปในดิสก์
    • ถ้าผู้ใช้ไม่ได้สมัครสมาชิกไอเท็ม (เช่น เซิร์ฟเวอร์เกมที่ใช้การเข้าสู่ระบบแบบไม่ระบุชื่อ) จะมีการดาวน์โหลดไอเท็มเวิร์กชอปและแคชไว้ชั่วคราว
    • ถ้าไอเท็มเวิร์กชอปมี ISteamUGC::EItemState ของ k_EItemStateNeedsUpdate, ISteamUGC::DownloadItem ก็จะสามารถเรียก เพื่อเริ่มการอัปเดตได้ อย่าเข้าถึงไอเท็มเวิร์กชอปในดิสก์จนกว่าจะมีการเรียกคอลแบ็ก ISteamUGC::DownloadItemResult_t
    • เมธอดนี้ใช้งานได้เฉพาะกับไอเท็มเวิร์กชอปที่สร้างขึ้นด้วย ISteamUGC เท่านั้น จะไม่สามารถใช้กับไอเท็มเวิร์กชอปรุ่นเก่าจาก ISteamRemoteStorage ได้
    • ISteamUGC::DownloadItemResult_t สตรัคของคอลแบ็กยังบรรจุไอดีของแอปพลิเคชัน (m_unAppID) ที่เชื่อมโยงกับไอเท็มเวิร์กชอปอีกด้วย ควรนำไปเปรียบเทียบกับไอดีแอปพลิเคชันที่กำลังทำงานอยู่ เนื่องจะมีการเรียกตัวจัดการสำหรับการดาวน์โหลดไอเท็มทั้งหมด โดยไม่คำนึงถึงแอปพลิเคชันที่กำลังทำงานอยู่

การเรียกข้อมูลเกี่ยวกับสำเนาภายในเครื่องของไอเท็มเวิร์กชอป

  • ISteamUGC::GetItemInstallInfo - รับข้อมูลเกี่ยวกับเนื้อหาที่ติดตั้งอยู่บนดิสก์ในขณะนั้น สำหรับไอเท็มเวิร์กชอปที่ตั้งค่า k_EItemStateInstalled เอาไว้

การแจ้งเตือนเมื่อมีการติดตั้งหรืออัปเดตไอเท็มเวิร์กชอป

การคิวรี่เนื้อหา

อินเตอร์เฟส ISteamUGC เป็นวิธีที่ยืดหยุ่นในการอีนิวเมอเรต UGC ประเภทต่างๆ ใน Steam (เช่น ไอเท็มเวิร์กชอป, ภาพหน้าจอ, วิดีโอ และอื่นๆ)

ISteamUGCFlows-QueryingContent-web2.png

  1. ลงทะเบียนตัวจัดการผลลัพธ์การเรียก SteamUGCQueryCompleted_t
  2. ระบบมีเมธอดอยู่จำนวนหนึ่งที่สามารถใช้สร้างคิวรี่ได้ ทั้งนี้ขึ้นกับสถานการณ์ที่ต้องการ ได้แก่ คิวรี่เนื้อหาที่เชื่อมโยงกับผู้ใช้, คิวรี่เนื้อหาทั้งหมด หรือรับรายละเอียดเนื้อหาทั้งหมดที่คุณมี ID
    • ISteamUGC::CreateQueryUserUGCRequest - คิวรี่ UGC ที่เชื่อมโยงกับผู้ใช้ คุณสามารถใช้ฟังก์ชันนี้เพื่อทำสิ่งต่างๆ เช่น แจกแจงรายการ UGC ที่ผู้ใช้สมัครสมาชิก
    • ISteamUGC::CreateQueryAllUGCRequest - คิวรี่เพื่อค้นหา UGC ทั้งหมดที่ตรงกัน คุณสามารถใช้ฟังก์ชันนี้เพื่อแสดงรายการ UGC ทั้งหมดที่มีให้สำหรับแอปของคุณ
    • ISteamUGC::CreateQueryUGCDetailsRequest - คิวรี่หารายละเอียดของไอเท็มเวิร์กชอปที่ระบุ
  3. กำหนดค่าของคิวรี่ตามความเหมาะสมโดยเรียกเมธอดสำหรับตั้งค่าตัวเลือก:
    • เมื่อคิวรี่หา UGC ของผู้ใช้
      • ISteamUGC::SetCloudFileNameFilter - ตั้งค่าคิวรี่ UGC ที่รอดำเนินการ ว่าให้คืนไอเท็มซึ่งมีชื่อไฟล์ที่กำหนดเท่านั้น
    • เมื่อคิวรี่หา UGC ทั้งหมด
      • ISteamUGC::SetMatchAnyTag - ตั้งค่าคิวรี่ UGC ที่รอดำเนินการ ว่าจะคืนค่าไอเท็มเวิร์กชอปถ้ามีแท็กที่ตรงกันอย่างน้อยหนึ่งแท็ก หรือจะคืนค่าเมื่อแท็กทั้งหมดต้องตรงกัน
      • ISteamUGC::SetSearchText - ตั้งค่าสตริงซึ่งใช้จับคู่กับชื่อหรือคำอธิบายของไอเท็ม ให้กับคิวรี่ UGC ที่รอดำเนินการ
      • ISteamUGC::SetRankedByTrendDays - ตั้งค่าคิวรี่ UGC ที่รอดำเนินการ ว่าจะอัปเดตลำดับของผลลัพธ์โดยพิจารณาจากอันดับของไอเท็มตามจำนวนวันที่กำหนดหรือไม่
    • เมื่อคิวรี่หา UGC ทั้งสองประเภท
      • ISteamUGC::AddRequiredTag - เพิ่มแท็กที่จำเป็นให้กับการคิวรี่ UGC ที่รอดำเนินการอยู่ ซึ่งจะทำให้คืนค่า UGC ที่มีแท็กที่ระบุเท่านั้น
      • ISteamUGC::AddExcludedTag - กำหนดแท็กที่ยกเว้นให้กับการคิวรี่ UGC ที่รอดำเนินการอยู่ ซึ่งจะทำให้คืนค่าแต่ UGC ที่ไม่มีแท็กที่ระบุ
      • ISteamUGC::AddRequiredKeyValueTag - เพิ่มแท็กคีย์-ค่าที่จำเป็นให้กับการคิวรี่ UGC ที่รอดำเนินการอยู่ ฟังก์ชันนี้จะคืนค่าเฉพาะไอเท็มเวิร์กชอปที่มีคีย์ = [param]pKey[/param] และค่า = [param]pValue[/param]
      • ISteamUGC::SetReturnOnlyIDs - ตั้งค่าคิวรี่ UGC ที่รอดำเนินการ ว่าจะคืนค่าเฉพาะ ID แทนที่จะคืนรายละเอียดทั้งหมดใช่หรือไม่ มีประโยชน์เมื่อคุณไม่ได้ต้องการข้อมูลทั้งหมด (เช่น แค่อยากรับไอดีของไอเท็มที่ผู้ใช้มีในรายการโปรด)
      • ISteamUGC::SetReturnKeyValueTags - ตั้งค่าคิวรี่ UGC ที่รอดำเนินการ ว่าจะคืนแท็กคีย์-ค่าของไอเท็มหรือไม่
      • ISteamUGC::SetReturnLongDescription - ตั้งค่าคิวรี่ UGC ที่รอดำเนินการ ว่าจะให้คืนคำอธิบายแบบเต็มของไอเท็มหรือไม่
      • ISteamUGC::SetReturnMetadata - ตั้งค่าคิวรี่ UGC ที่รอดำเนินการว่าจะให้คืนค่าเมทาดาตาของไอเท็มที่กำหนดโดยผู้พัฒนาหรือไม่
      • ISteamUGC::SetReturnChildren - ตั้งค่าคิวรี่ UGC ที่รอดำเนินการ ว่าจะคืนค่า ID ของไอเท็มย่อยหรือไม่
      • ISteamUGC::SetReturnAdditionalPreviews - ตั้งค่าคิวรี่ UGC ที่รอดำเนินการ ว่าจะคืนค่ารูปภาพ/วิดีโอเพิ่มเติมที่แนบมากับไอเท็มหรือไม่
      • ISteamUGC::SetReturnTotalOnly - ตั้งค่าคิวรี่ UGC ที่รอดำเนินการ ว่าจะคืนเฉพาะค่าจำนวนทั้งหมดของไอเท็มที่ตรงกันใช่หรือไม่ -- จะไม่มีการคืนค่าไอเท็มจริงๆ เมื่อเรียก ISteamUGC::SteamUGCQueryCompleted_t
      • ISteamUGC::SetLanguage - ตั้งค่าภาษาที่ใช้สำหรับคืนค่าชื่อและคำอธิบายของไอเท็มในคิวรี่ UGC ที่รอดำเนินการ
      • ISteamUGC::SetAllowCachedResponse - ตั้งค่าคิวรี่ UGC ที่รอดำเนินการ ว่าจะคืนผลลัพธ์จากแคชภายในระยะเวลาที่กำหนดหรือไม่
  4. ส่งคิวรี่ถึง Steam ด้วย ISteamUGC::SendQueryUGCRequest ซึ่งจะเรียกตัวจัดการผลลัพธ์การเรียก ISteamUGC::SteamUGCQueryCompleted_t ที่ลงทะเบียนไว้ในขั้นตอนที่ 1
  5. ในตัวจัดการผลลัพธ์การเรียก ISteamUGC::SteamUGCQueryCompleted_t ให้เรียก ISteamUGC::GetQueryUGCResult เพื่อรับรายละเอียดของไอเท็มแต่ละชิ้นที่คืนค่ากลับมา

  6. นอกจากนี้ยังสามารถเรียกฟังก์ชันเหล่านี้เพื่อรับข้อมูลเพิ่มเติมของไอเท็มแต่ละชิ้นได้ (ข้อมูลนี้บางรายการจะไม่คืนกลับมาโดยค่าเริ่มต้น ดังนั้นคุณจะต้องกำหนดค่าคิวรี่ตามความเหมาะสม):
    • ISteamUGC::GetQueryUGCPreviewURL - รับ URL เพื่อดูภาพตัวอย่างของไอเท็มเวิร์กชอปแต่ละรายการ หลังจากได้รับผลการเรียกคิวรี่ UGC
    • ISteamUGC::GetQueryUGCMetadata - เรียกเมทาดาตาที่เกี่ยวกับชุดผู้พัฒนาของไอเท็มเวิร์กชอปแต่ละรายการ หลังจากได้รับผลการเรียกคิวรี่ UGC
    • ISteamUGC::GetQueryUGCChildren - รับ ID ของไอเท็มย่อยใด ๆ ของไอเท็มเวิร์กชอปแต่ละรายการ หลังจากได้รับผลการเรียกคิวรี่ UGC
    • ISteamUGC::GetQueryUGCStatistic - รับค่าสถิติหลายชนิดของไอเท็มเวิร์กชอปแต่ละรายการ หลังจากได้รับผลการเรียกคิวรี่ UGC
    • ISteamUGC::GetQueryUGCNumAdditionalPreviews และ ISteamUGC::GetQueryUGCAdditionalPreview - รับรายละเอียดของตัวอย่างเพิ่มเติมที่เชื่อมโยงกับไอเท็มเวิร์กชอปแต่ละรายการ หลังจากได้รับผลการเรียกคิวรี่ UGC
    • ISteamUGC::GetQueryUGCNumKeyValueTags และ ISteamUGC::GetQueryUGCKeyValueTag - รับรายละเอียดของแท็กคีย์-ค่าที่เชื่อมโยงกับไอเท็มเวิร์กชอปแต่ละรายการ หลังจากได้รับผลการเรียกคิวรี่ UGC
  7. เรียก ISteamUGC::ReleaseQueryUGCRequest เพื่อคืนหน่วยความจำทั้งหมดที่จัดสรรให้สำหรับการคิวรี่หรือรับผลลัพธ์

การเพจผลลัพธ์

การคิวรี่แต่ละครั้งจะคืนผลลัพธ์ได้ 50 รายการ คุณสามารถเพจผลลัพธ์เพิ่มได้โดยสร้างคิวรี่ที่เพิ่มค่าพารามิเตอร์ unPage (ซึ่งควรเริ่มต้นที่ 1)

การติดตามเวลาเล่น

หากต้องการติดตามเวลาเล่นของไอเท็มเวิร์กชอป ให้เรียก ISteamUGC::StartPlaytimeTracking ด้วย ID ของไอเท็มที่ต้องการติดตาม จากนั้น เมื่อไม่ได้ใช้ไอเท็มขณะเล่นแล้ว ให้เรียก ISteamUGC::StopPlaytimeTracking ด้วย ID ที่ต้องการหยุดติดตาม หรือเรียก ISteamUGC::StopPlaytimeTrackingForAllItems เพื่อหยุดติดตามเวลาเล่นไอเท็มทุกชิ้นพร้อมกัน
เมื่อแอปปิดทำงาน การติดตามเวลาเล่นจะหยุดโดยอัตโนมัติ

นอกจากนี้คุณยังสามารถเรียงไอเท็มตามเกณฑ์ชี้วัดเวลาการเล่นต่าง ๆ ได้ในคิวรี่ ISteamUGC::CreateQueryAllUGCRequest ต่อไปนี้คือประเภทการคิวรี่ตามเวลาเล่นที่คุณสามารถใช้งานได้:

การลบเนื้อหาของไอเท็มเวิร์กชอป

ในการลบไอเท็มเวิร์กชอป คุณสามารถเรียก ISteamUGC::DeleteItem กรุณาทราบว่าการกระทำนี้จะไม่ขึ้นเตือนผู้ใช้และจะไม่สามารถยกเลิกได้

ตัวอย่างการใช้งาน Steamworks – การผสานเมธอดในเกม SpaceWar

เอกสาร แอปพลิเคชันตัวอย่างของ Steamworks API (SpaceWar) ที่มาพร้อมกับ Steamworks SDK จะสาธิตการใช้งาน ISteamUGC API บางส่วน
  • CSpaceWarClient::LoadWorkshopItem จะสาธิตวิธีการตรวจสอบว่ามีการดาวน์โหลดและติดตั้งไอเท็มเวิร์กชอปบนดิสก์แล้วหรือยัง พร้อมขอข้อมูลเกี่ยวกับไอเท็มเวิร์กชอปด้วย ISteamRemoteStorage::PublishedFileId_t
  • CSpaceWarClient::LoadWorkshopItems จะสาธิตวิธีรับรายการไอเท็มเวิร์กชอปที่ผู้ใช้ปัจจุบันสมัครสมาชิกเอาไว้ สำหรับแอปพลิเคชัน SpaceWar
  • CSpaceWarClient::OnWorkshopItemInstalled สาธิตการใช้ตัวจัดการคอลแบ็กสำหรับ ISteamUGC::ItemInstalled_t

ข้อตกลงทางกฎหมายของเวิร์กชอป

โดยค่าเริ่มต้นแล้ว ไอเท็มเวิร์กชอปจะถูกซ่อนเอาไว้จนกว่าผู้ส่งผลงานจะยอมรับข้อตกลงทางกฎหมายของเวิร์กชอป Steam เพื่อให้ผู้ส่งผลงานสามารถเผยแพร่ไอเท็มต่อสาธารณะได้อย่างสะดวก กรุณาทำสิ่งต่อไปนี้
  1. ระบุข้อความถัดจากปุ่มที่ใช้ส่งไอเท็มไปยังเวิร์กชอป เพื่อแจ้งเนื้อหาลักษณะนี้: "จากการส่งไอเท็มนี้ถือว่าคุณได้ยอมรับข้อกำหนดในการให้บริการของเวิร์กชอป" (พร้อมระบุลิงก์)
  2. หลังจากผู้ใช้ส่งไอเท็ม ให้เปิดหน้าต่างเบราว์เซอร์ไปที่หน้าเวิร์กชอป Steam สำหรับไอเท็มนั้นโดยเรียก ISteamFriends::ActivateGameOverlayToWebPage โดยตั้งค่า pchURL เป็น steam://url/CommunityFilePage/<PublishedFileId_t>และแทนที่ <PublishedFileId_t> ด้วย ID ของไอเท็มเวิร์กชอป
ประโยชน์ของการทำเช่นนี้ก็คือ การพาผู้สร้างไอเท็มไปที่หน้าเวิร์กชอปเพื่อดูไอเท็มของตัวเองและกำหนดค่าเพิ่มเติมตามที่จำเป็น และช่วยให้ผู้สร้างไอเท็มอ่านและยอมรับข้อตกลงทางกฎหมายของเวิร์กชอป Steam ได้สะดวกขึ้น

Web API

นอกจากเมธอดเหล่านี้ เรายังมีชุดอินเตอร์เฟส Web API ที่ให้ฟังก์ชันการทำงานลักษณะเดียวกัน พร้อม API การกรองที่ทำงานโดยพิจารณาข้อมูลจากชุมชน ซึ่งใช้สำหรับแสดงรายการเนื้อหาที่แชร์ทั้งหมด กรุณาอ้างอิงเอกสารประกอบการใช้งานอินเตอร์เฟส ISteamRemoteStorage ในรายการ Web API

เซิร์ฟเวอร์เกมเฉพาะ

เซิร์ฟเวอร์เกมสามารถดาวน์โหลดและติดตั้งไอเท็มได้
  • โดยเซิร์ฟเวอร์เกมจำเป็นต้องทราบ PublishedFileId_t สำหรับใช้ขอไอเท็มเวิร์กชอป ซึ่งไคลเอนต์เกมอาจมอบให้ หรือผู้ควบคุมเซิร์ฟเวอร์เป็นผู้กำหนด จากนั้นให้เรียก ISteamUGC::DownloadItem เพื่อรับสำเนาไอเท็มเวิร์กชอปชั่วคราว
  • จากนั้นสามารถเรียก ISteamUGC::GetItemInstallInfo เพื่อรับข้อมูลที่ใช้สำหรับค้นหาและใช้ไอเท็มเวิร์กชอป
  • อ่านหัวข้อ การติดตั้งไอเท็ม ทางด้านบน เพื่อรับข้อมูลเพิ่มเติมเกี่ยวกับเมธอด API เหล่านี้

การผสานการทำงานกับ SteamCmd

นอกจาก ISteamUGC API แล้ว คุณยังสามารถใช้เครื่องมือป้อนบรรทัดคำสั่ง steamcmd.exe เพื่อสร้างและอัปเดตไอเท็มเวิร์กชอปที่ใช้ในการทดสอบ เครื่องมือนี้มีวัตถุประสงค์เพื่อการทดสอบเท่านั้น เนื่องจากผู้ใช้จะต้องป้อนข้อมูลประจำตัว Steam (ซึ่งเป็นสิ่งที่เราไม่ต้องการให้ลูกค้าทำ)

หากต้องการสร้างไอเท็มเวิร์กชอป Steam ชิ้นใหม่ด้วย steamcmd.exe จะต้องสร้างไฟล์ VDF ขึ้นมาก่อน โดย VDF คือไฟล์ข้อความธรรมดาที่ควรมีคีย์ต่อไปนี้
"workshopitem" { "appid" "480" "publishedfileid" "5674" "contentfolder" "D:\\Content\\workshopitem" "previewfile" "D:\\Content\\preview.jpg" "visibility" "0" "title" "Team Fortress Green Hat" "description" "A green hat for Team Fortress" "changenote" "Version 1.2" }

หมายเหตุ:
  • คีย์จะแมปกับเมธอด ISteamUGC::SetItem[...] หลายชนิด อ่านเอกสารประกอบการใช้งานด้านบนเพื่อรับรายละเอียดเพิ่มเติม
  • ค่าที่แสดงให้ดูนี้เป็นเพียงตัวอย่างเท่านั้น และควรได้รับการอัปเดตตามความเหมาะสม
  • หากต้องการสร้างไอเท็มใหม่ จะต้องตั้งค่า appid และจะต้องยกเลิกการตั้งค่า publishedfileid หรือตั้งค่าให้เป็น 0
  • หากต้องการอัปเดตไอเท็มที่มีอยู่ จะต้องตั้งค่าทั้ง appid และ publishedfileid
  • ควรรวมคู่คีย์/ค่าที่เหลืออยู่เอาไว้ใน VDF ด้วย ถ้าจะต้องอัปเดตคีย์
เมื่อสร้าง VDF แล้ว คุณจะสามารถเรียกใช้ steamcmd.exe ด้วยพารามิเตอร์ไฟล์ workshop_build_item <build config filename> ตัวอย่าง:
steamcmd.exe +login myLoginName myPassword +workshop_build_item workshop_green_hat.vdf +quit
ถ้าคำสั่งประสบความสำเร็จ ค่า publishedfileid ใน VDF จะได้รับการอัปเดตโดยอัตโนมัติให้มีข้อมูล ID ของไอเท็มเวิร์กชอป ด้วยวิธีนี้ การเรียก steamcmd.exe กับไฟล์ VDF เดิมในครั้งต่อ ๆ ไปจะทำให้เกิดการอัปเดตไม่ใช่การสร้างไอเท็มใหม่

ข้อผิดพลาดและการบันทึก

เมธอดส่วนใหญ่ของ ISteamUGC จะคืนค่า boolean หากต้องการรับข้อมูลเพิ่มเติมเกี่ยวกับข้อผิดพลาดแต่ละชนิด เรามีแหล่งข้อมูลในเรื่องนี้อยู่พอสมควร:
  • Steam\logs\Workshop_log.txt คือบันทึกการถ่ายโอนทั้งหมดที่เกิดขึ้นระหว่างการดาวน์โหลด
    และการติดตั้ง
  • Steam\workshopbuilds\depot_build_<appid>.log คือ บันทึกการกระทำทั้งหมดในระหว่างการอัปโหลดและอัปเดตไอเท็มเวิร์กชอป
  • ISteamUGC::SteamUGCQueryCompleted_t, ISteamUGC::CreateItemResult_t และ ISteamUGC::SubmitItemUpdateResult_t จะมีตัวแปร EResultที่สามารถตรวจสอบได้

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

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

ได้ คุณสามารถกำหนดค่าเวิร์กชอปของแอปพลิเคชันหลักให้สามารถรับเนื้อหาจากเครื่องมือแก้ไขหรือเผยแพร่เนื้อหา ซึ่งเป็นแอปพลิเคชันที่ทำงานแยกต่างหากได้

โดยให้ไปที่หัวข้อการกำหนดค่าเวิร์กชอปของแอปพลิเคชันหลัก แล้วเลื่อนไปที่ด้านล่างของหน้า กรอกไอดีแอปของแอปพลิเคชันที่ทำงานแยกต่างหากในหัวข้อ "สิทธิ์การเผยแพร่แอป" แล้วกด "เพิ่ม"

เมื่อการเผยแพร่ตั้งค่า Steamworks แล้ว แอปพลิเคชันสำหรับแก้ไขจะสามารถเผยแพร่เนื้อหาไปยังเวิร์กชอปของแอปพลิเคชันหลัก