ภาพรวม

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

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

ฟังก์ชันของกระดานผู้นำทั้งหมดจะอยู่ใน ISteamUserGameStats.h และในตัวอย่าง Steamworks นั้นจะมีการใช้งานกระดานผู้นำตัวอย่างอยู่ด้วยกัน 2 กระดาน คุณสามารถดูและดูแลกระดานผู้นำของเกมของคุณได้ในส่วนผู้ดูแลเกม Steamworks

ก่อนที่จะเริ่ม

ฟังก์ชันกระดานผู้นำแบบอะซิงโครนัสทั้งหมด จะคืนค่าตัวจัดการไปยังผลลัพธ์การเรียก Steam API คุณสามารถดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีการรับผลลัพธ์เหล่านี้ได้จาก หัวข้อผลลัพธ์การเรียก (Call Result) ของเอกสาร \วิธีการเริ่มต้นใช้งาน\

การสร้างกระดานผู้นำ

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

การสร้างผ่านทางหน้าเว็บ

คุณสามารถสร้างและดูแลจัดการกระดานผู้นำในผู้ดูแลแอปของ Steamworks ของไอดีแอปของคุณได้โดยไปที่ สถิติและรางวัลความสำเร็จ -> กระดานผู้นำ


ในการกำหนดค่ากระดานผู้นำนั้น ช่องข้อมูลดังต่อไปนี้จะต้องมีข้อมูลครบถ้วน:

• Name - ให้ตั้งค่าเป็นชื่อที่อ่านออกเข้าใจได้ที่ถือเป็นส่วนหนึ่งของการพัฒนาภายใน
  
• Community Name - หากว่าจะแสดงกระดานผู้นำเอาไว้ในศูนย์กลางชุมชน ให้ตั้งชื่อที่จะแสดงต่อสาธารณะได้ที่นี่ หากว่าไม่ใส่ชื่อเอาไว้ กระดานผู้นำก็จะไม่ปรากฏขึ้นมา
  
• Sort Method - มีไว้เพื่อตั้งค่าการอันดับวิธีเรียงก่อนหลังของกระดานผู้นำ สำหรับกระดานผู้นำประเภทไล่ตำแหน่งอันดับ ให้ใช้การเรียงจากน้อยไปมาก สำหรับกระดานผู้นำประเภทคะแนนสูงสุด ให้ใช้การเรียงจากมากไปน้อย
  
• Display Type - มีไว้เพื่อใช้กำหนดประเภทของข้อมูลที่จะแสดงบนกระดานผู้นำ ให้เลือกว่าเป็นตัวเลข วินาที หรือ มิลลิวินาที
  
• Writes - หากว่าตั้งค่านี้ให้เป็นเชื่อถือได้ ไคลเอนต์จะไม่สามารถตั้งค่าคะแนนของกระดานผู้นำได้ และจะต้องตั้งค่าผ่านทางการใช้ SetLeaderboardScore WebAPI เท่านั้น ค่าเริ่มต้นคือ false
  
• Reads - หากว่าตั้งค่านี้เป็นเพื่อน เกมจะสามารถอ่านได้แต่คะแนนกระดานผู้นำของเพื่อนของผู้ใช้ ส่วน WebAPI จะสามารถอ่านคะแนนทั้งหมดได้เสมอ ค่าเริ่มต้นคือ false

การสร้างผ่านทาง API

คุณสามารถสร้างกระดานผู้นำของเกมของคุณได้ผ่านทางการใช้ ผู้ดูแลแอป Steamworks หรือผ่านทางการเขียนโปรแกรมด้วยการเรียก ISteamUserStats::FindOrCreateLeaderboard ใน Steam กระดานผู้นำของเกมของ Steamworks จะถูกระบุไว้ด้วยชื่อที่ไม่ซ้ำกัน จะใช้ชื่อของกระดานผู้นำในการระบุอัตลักษณ์ตัวตนใน Steamworks API เท่านั้น และจะไม่นำเสนอให้ผู้ใช้เห็นในชุมชน Steam ในเวลาที่คุณสร้างกระดานผู้นำ คุณจำเป็นจะต้องเลือก:

• วิธีจัดเรียง - k_ELeaderboardSortMethodAscending (รายการแรกสุดคือผู้ใช้ผู้มีคะแนนที่สูงที่สุด) หรือ k_ELeaderboardSortMethodDescending (รายการแรกสุดคือผู้ใช้ผู้มีคะแนนที่สูงที่สุด)
  
• ชนิดการแสดงผล - ELeaderboardDisplayType มีไว้ใช้เพื่ออธิบายความหมายของคะแนนของกระดานผู้นำ และจะถูกใช้โดยชุมชนเพื่อจัดรูปแบบคะแนนของกระดานผู้นำเวลาแสดงผล

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

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

การอัปโหลดคะแนน

หากต้องการอัปโหลดคะแนนของกระดานผู้นำ ให้เรียก ISteamUserStats::UploadLeaderboardScoreพร้อมส่งตัวจัดการของกระดานผู้นำเป้าหมาย (ที่ได้มาจาก FindLeaderboard) พร้อมคะแนนของผู้ใช้ พร้อมส่งข้อมูลที่เกี่ยวข้องที่เกิดขึ้นขณะตั้งค่าคะแนนใหม่ หากจำเป็น หากมีการอัปเดตคะแนนกระดานผู้นำของผู้ใช้ ข้อมูลที่เกี่ยวข้องที่ส่งให้ ISteamUserStats::UploadLeaderboardScore จะเข้าไปแทนที่ข้อมูลใด ๆ ที่ได้จัดเก็บเอาไว้ก่อนหน้า เวลาที่อัปโหลดคะแนนกระดานผู้นำของผู้ใช้ คุณสามารถเลือกใช้งานเมธอดได้สองตัวดังนี้:

• ISteamUserStats::k_ELeaderboardUploadScoreMethodKeepBest - Steam จะเทียบคะแนนใหม่ของผู้ใช้กับคะแนนเดิมของผู้ใช้ที่จัดเก็บเอาไว้ในกระดานผู้นำ แล้วก็จะเก็บเอาไว้เฉพาะคะแนนที่ดีที่สุดของผู้ใช้ (ซึ่งก็คือคะแนนที่ต่ำที่สุดในกระดานผู้นำหากใช้การเรียงจากน้อยไปมาก และคะแนนที่สูงที่สุดในกระดานผู้นำหากเรียงจากมากไปน้อย)
  
• ISteamUserStats::k_ELeaderboardUploadScoreMethodForceUpdate - Steam จะแทนที่คะแนนเก่าของผู้ใช้ด้วยคะแนนใหม่เข้าไปในกระดานผู้นำเสมอ
  
• ISteamUserStats::UploadLeaderboardScore เป็นการเรียกแบบอะซิงโครนัส และผลลัพธ์ของการอัปโหลดจะถูกส่งคืนมาในผลลัพธ์การเรียก LeaderboardScoreUploaded_t ผลลัพธ์จะประกอบด้วยธงที่กำกับว่าคะแนนผู้ใช้เปลี่ยนไปหรือไม่ รวมถึงอันดับโดยรวมเก่าและใหม่ของผู้ใช้ โดยเมื่ออัปโหลดแล้ว กระดานผู้นำ Steamworks จะได้รับการอัปเดตโดยทันทีเพื่อแสดงค่าคะแนนใหม่ แล้วก็จะสามารถเรียกรับการเรียงรายการข้อมูลใหม่ได้โดยใช้ DownloadLeaderboardEntries

การแนบเนื้อหาที่สร้างโดยผู้ใช้

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

เมื่อแนบแล้ว เนื้อหาจะสามารถใช้งานได้เสมอ แม้ว่าไฟล์ของระบบคลาวด์ที่อยู่เบื้องหลังจะมีการเปลี่ยนแปลงหรือถูกผู้ใช้ลบออกไป

การเรียกรายการข้อมูลกระดานผู้นำ

ISteamUserStats::DownloadLeaderboardEntries มีไว้ใช้เพื่อเรียกรับรายการข้อมูลกระดานผู้นำ โดยจะใช้ตัวจัดการกระดานผู้นำที่มาจาก ISteamUserStats::FindLeaderboard

เมื่อคุณได้เรียกรายการข้อมูลที่ดาวน์โหลดมาจาก GetDownloadedLeaderboardEntry แล้วนั้น รายการข้อมูลจะถูกปลดปล่อยออก และ SteamLeaderboardEntries_t ใน LeaderboardScoresDownloaded_t จะไม่สามารถใช้ได้อีกต่อไป

การเรียกข้อมูลกระดานผู้นำ

เมื่อมีตัวจัดการกระดานผู้นำคืนค่ามาจาก FindLeaderboard คุณจะสามารถเรียกข้อมูลเกี่ยวกับกระดานผู้นำได้ผ่านทางการใช้งานคำสั่งดังต่อไปนี้:

ISteamUserStats::GetLeaderboardName
ISteamUserStats::GetLeaderboardEntryCount
ISteamUserStats::GetLeaderboardSortMethod
ISteamUserStats::GetLeaderboardDisplayType