Hướng dẫn các trò chơi trong workshop

Steam Workshop giúp bạn đăng các mô hình 3D hoàn chỉnh một cách dễ dàng hơn bao giờ hết để chúng có cơ hội được chấp nhận và trở thành một phần của trò chơi. Để đăng vật phẩm lên workshop cho việc đánh giá, trước tiên hãy đọc tài liệu chính thức được dẫn ở phía bên phải, sau đó nhấn nút Steam Workshop trong mục chính của trò chơi.

Steam Workshop khiến cho việc khám phá hoặc chia sẻ các nội dung thuộc về trò chơi hoặc phần mềm trở nên dễ dàng hơn. Mỗi mục trong Steam Workshop đều hỗ trợ các nội dung khác nhau ẩn chứa bên trong. Vì vậy, bạn nên kiểm tra các tài liệu chính thống để biết thêm chi tiết về những thứ bạn có thể tạo và chia sẻ trong thư mục đó.

Khi thấy nội dung dưới thanh Vật phẩm sẵn sàng sử dụng mà bạn muốn thêm vào trong trò chơi, xin vui lòng nhấn nút "đăng ký". Gần như trong mọi trường hợp, nội dung đó sẽ tự động xuất hiện khi bạn bắt đầu trò chơi. Tuy nhiên, một số nội dung yêu cầu bạn đến từng khu vực của trò chơi hoặc phần mềm để kích hoạt hoặc truy cập các nội dung mới này.

Tính năng đã kích hoạt

Đây là các tính năng của Steam Workshop được sử dụng bởi Leadwerks Game Engine:

Vật phẩm đã sẵn sàng để sử dụng

Nội dung được đăng trong Workshop tại thẻ Vật phẩm sẵn sàng sử dụng đã sẵn sàng để sử dụng ngay. Nhấn vào nút Đăng ký trên trang thông tin để thấy nội dung đó. Nội dung này sẽ khả dụng khi bạn khởi động Leadwerks Game Engine.

Lựa chọn những vật phẩm đã được tuyển chọn

Vật phẩm được đăng lên Workshop trong thẻ Vật phẩm để thẩm định không được sử dụng ngay lập tức trong Leadwerks Game Engine. Các nhà phát triển sẽ nhờ cộng đồng bỏ phiếu cho vật phẩm mà họ muốn mua hay mở trong Leadwerks Game Engine. Cuối cùng, nhà phát triển sẽ chọn các vật phẩm để thêm vào Leadwerks Game Engine.

Doanh số vật phẩm

Các vật phẩm đã được chấp nhận từ Workshop sẽ có thể được mua hoặc mở khóa ngay trong Leadwerks Game Engine.

Người tạo vật phẩm có thể hưởng tiền hoa hồng

Một phần lợi nhuận từ doanh thu của các vật phẩm trên Workshop, nếu được chấp nhận để bán, sẽ được trích ra để trả cho tác giả.

Người cung cấp dịch vụ có thể nhận tiền hoa hồng

Tác giả Workshop có thể lựa chọn từ danh sách chấp thuận trước của các tổ chức, người sử dụng, và người làm công cụ nhận được một tỷ lệ phần trăm doanh thu của Valve từ việc bán vật phẩm của họ. Các tổ chức, cá nhân cụ thể được liệt kê dưới đây.

Bạn có phải là người tạo nội dung và biết một tổ chức hay cá nhân khác bạn muốn chia sẻ thành công cho việc bán sản phẩm của mình? Xin vui lòng cho chúng tôi biết tại đây.

Steam Workshop khiến việc phát hiện và chia sẻ các nội dung mới dành cho trò chơi và phần mềm của bạn trở nên dễ dàng hơn. Không phải trò chơi nào cũng hỗ trợ cùng một loại nội dung trong Workshop. Vì vậy, để biết thêm chi tiết về những gì có thể được tạo ra và chia sẻ, bạn nên tham khảo tài liệu chính thức.

Khi tìm nội dung mà bạn muốn thêm vào trò chơi của mình, nhấn nút "đăng ký". Thường thì nội dung sẽ tự động có sẵn trong lần tiếp theo bạn khởi động trò chơi. Tuy nhiên, một số sản phẩm yêu cầu bạn vào một khu vực riêng trong trò chơi (hoặc phần mềm) để kích hoạt hoặc truy cập vào nội dung mới.

Tính năng đã kích hoạt

Đây là các tính năng của Steam Workshop được sử dụng bởi Game Dev Studio:

Vật phẩm đã sẵn sàng để sử dụng

Vật phẩm được đăng trên Workshop này đã sẵn sàng để sử dụng ngay lập tức. Nhấn nút đăng ký theo dõi trên trang thông tin dành cho sản phẩm và nó sẽ có sẵn ngay khi bạn bắt đầu Game Dev Studio.

Giới thiệu

Steam Workshop là một hệ thống kết hợp lưu trữ phía hệ thống (back-end) và trang mạng phía người dùng (front-end) nhằm đơn giản hóa việc lưu trữ, tổ chức, sắp xếp, đánh giá và tải nội dung cho trò chơi hay ứng dụng.

Trang này cung cấp chi tiết kỹ thuật về việc triển khai Steam Workshop trên sản phẩm của bạn. Để có thêm thông tin và định nghĩa về các loại hình tích hợp của Workshop mà bạn có thể sử dụng cũng như cách dùng tối ưu các công cụ của Steam, hãy xem qua phần Tổng quan về Steam Workshop trước khi bắt đầu tích hợp Steam Workshop vào trò chơi.

Trong một thiết lập điển hình, khách hàng sẽ sử dụng công cụ cung cấp bởi chính bạn sau khi mua trò chơi, để tiến hành chỉnh sửa hoặc tạo ra một nội dung mới. Họ sẽ đăng gửi nội dung đó đến Steam Workshop bằng cách sử dụng biểu mẫu đã được tích hợp vào phần công cụ. Các khách hàng khác có thể duyệt, sắp xếp, xếp hạng hoặc đăng ký các vật phẩm mà họ muốn thêm vào trò chơi của họ bằng cách ghé thăm Steam Workshop trong cộng đồng Steam. Những vật phẩm đó sẽ được tải xuống thông qua Steam. Nếu bạn đã đăng ký lệnh gọi lại ISteamUGC::ItemInstalled_t trong trò chơi, bạn có thể gọi ISteamUGC::GetItemInstallInfo để lấy thông tin về nơi cài đặt cũng như đọc dữ liệu trực tiếp từ thư mục đó. Nội dung mới sẽ được trò chơi nhận dạng theo bất cứ cách nào phù hợp với trò chơi và nội dung được tạo ra.

Các loại hình Steam Workshop, phương pháp kiếm tiền & cách thực hiện tối ưu

Để biết thêm thông tin và định nghĩa về các loại hình tích hợp Workshop mà bạn có thể sử dụng cũng như cách dùng tối ưu các công cụ của Steam, hãy xem Steam Workshop tài liệu này.

Quản lý độ hiển thị Steam Workshop

Steam Workshop là một trang web lưu trữ trên Steam, trên đó liệt kê các nội dung được chia sẻ cũng như cho phép người dùng bầu chọn và bình luận về các nội dung hiển thị tới cộng đồng. Theo mặc định, ứng dụng không được kích hoạt hiển thị công khai trên Workshop. Điều này ngăn chặn nội dung vốn không dành để chia sẻ qua cổng Steam Workshop khỏi bị nhìn thấy, trừ phi workshop đang được chỉnh ở chế độ công khai.
Thiết lập chế độ hiển thị của workshop qua các bước sau:

Duyệt tìm trang đáp ứng dụng trên Steamworks
Nhấp vào Chỉnh sửa thiết lập Steamworks
Trong thẻ Workshop, chọn Tổng quát
Ở bên phải, tìm mục Trạng thái hiển thị.
Dùng nút radio để chọn mức hiển thị mong muốn, bao gồm chế độ Chỉ riêng nhà phát triển, Nhà phát triển & người thử nghiệm, Khách hàng & nhà phát triển và Mọi người
Trong thẻ Phát hành, nhấp vào Chuẩn bị phát hành
Nhấp vào Phát hành lên Steam để hoàn tất quy trình công bố thay đổi.

Chú ý: Để đổi chế độ hiển thị sang Mọi người, cần phải hoàn thành chặng mục Workshop, trong đó gồm có quảng bá, tiêu đề, mô tả và ít nhất một nội dung công khai.

Tổng quát công nghệ

Quy trình chia sẻ và tiêu thụ nội dung tạo bởi người dùng (UGC) đòi hỏi sử dụng API ISteamUGC, có thể được tìm thấy ở Steamworks SDK. Phương pháp trên nêu ra một cách để chia sẻ nội dung vật phẩm workshop mà sau này sẽ được tìm thấy thông qua Steam Workshop hay trải nghiệm trong ứng dụng.

Workshop API phải được truy cập thông qua giá trị con trỏ (pointer) được trả về từ SteamUGC().

Ví dụ:

SteamAPICall_t hSteamAPICall = SteamUGC()->CreateItem( SteamUtils()->GetAppID(), k_EWorkshopFileTypeMicrotransaction );

Kích hoạt ISteamUGC cho trò chơi hoặc ứng dụng

Trước khi các vật phẩm workshop được tải lên Steamworks phía máy chủ, có hai cài đặt cấu hình cần thực hiện: thiết lập hạn mức Steam Cloud và kích hoạt ISteamUGC API.

Tính năng Steam Cloud được dùng để lưu trữ hình ảnh xem trước được kèm theo vật phẩm workshop. Hạn mức của Steam Cloud có thể được thiết lập thông qua các bước sau:

Di chuyển tới trang Cài đặt Steam Cloud trong bảng Quản trị ứng dụng.
Chỉnh Hạn mức byte mỗi người dùng và Số lượng tệp cho mỗi người dùng đến giá trị phù hợp để lưu trữ hình ảnh xem trước
Nhấp vào nút Lưu
Trong thẻ Phát hành, nhấp chọn Chuẩn bị phát hành
Nhấp vào Phát hành lên Steam để hoàn tất quy trình công bố thay đổi.

Kích hoạt ISteamUGC API có thể được thực hiện thông qua các bước sau:

Di chuyển tới trang Thiết lập Steam Workshop trong bảng Quản trị ứng dụng.
Tìm mục Các tùy chọn thiết lập bổ sung.
Đánh dấu Bật ISteamUGC để đưa tệp.
Nhấp vào nút Lưu.
Trong thẻ Phát hành, nhấp vào Chuẩn bị phát hành.
Nhấp vào Phát hành lên Steam để hoàn tất quy trình công bố thay đổi.

Một khi các cài đặt đã hoàn tất, nội dung workshop có thể được tải lên thông qua API.

Tạo và đăng tải nội dung

Tạo và đăng tải nội dung workshop là một quá trình đơn giản và lặp đi lặp lại, theo như sơ đồ bên dưới.

Tạo vật phẩm workshop

Toàn bộ vật phẩm workshop được sinh ra bằng cách gọi ISteamUGC::CreateItem
- Biến nConsumerAppId cần bao gồm App ID cho trò chơi hoặc ứng dụng. Đừng nhập vào App ID của công cụ tạo vật phẩm workshop nếu nó là một App ID riêng biệt.
- EWorkshopFileType có chức năng liệt kê dùng để xác định cách thức mà một tệp sẽ được chia sẻ như thế nào trong cộng đồng. Các giá trị hợp lệ bao gồm:
  - k_EWorkshopFileTypeCommunity - Đây là loại được dùng để miêu tả các tệp được đăng lên bởi người dùng và có thể được tải xuống bởi bất cứ ai trong cộng đồng. Chức năng thường gặp của loại này là để chia sẻ mod tạo bởi người dùng.
  - k_EWorkshopFileTypeMicrotransaction - Đây là loại dùng để mô tả các tệp được đăng lên bởi người dùng, nhưng dành riêng để trò chơi cân nhắc thêm vào làm nội dung chính thức. Các tệp này sẽ không được người dùng tải về thông qua Workshop nhưng lại được nhìn thấy và đánh giá bởi cộng đồng.
    Đây là cách thức mà Team Fortress 2 sử dụng.
Đăng ký trình xử lý kết quả cuộc gọi (call result handler) cho CreateItemResult_t
Trước hết, kiểm tra m_eResult để đảm bảo vật phẩm đã được tạo thành công.
Khi trình xử lý kết quả cuộc gọi được thực thi, đọc giá trị của m_nPublishedFileId và trữ lại (ví dụ: trong một tệp dự án liên kết với công cụ tạo mới) cho những cập nhật vật phẩm workshop trong tương lai.
Biến m_bUserNeedsToAcceptWorkshopLegalAgreement cũng cần được kiểm tra và nếu true gì, người dùng sẽ được chuyển hướng để chấp nhận thỏa thuận pháp lý. Xem qua phần Thỏa thuận pháp lý về Workshop để biết thêm thông tin.

Đăng tải vật phẩm workshop

Một khi vật phẩm workshop được tạo và giá trị PublishedFileId_t được trả về, bạn có thể điền vào nội dung của vật phẩm workshop đó rồi đăng tải lên Steam Workshop.
Cập nhật vật phẩm bắt đầu bằng việc gọi ISteamUGC::StartItemUpdate
Dùng UGCUpdateHandle_t được ISteamUGC::StartItemUpdate trả về, các cuộc gọi có thể được thực hiện nhằm cập nhật Đề tựa, Mô tả, Độ hiển thị, Thẻ, Nội dung và Hình ảnh xem trước của vật phẩm thông qua nhiều phương thức ISteamUGC::SetItem[...] đa dạng.
- ISteamUGC::SetItemTitle - Thiết lập tựa đề mới cho vật phẩm.
- ISteamUGC::SetItemDescription - Thiết lập mô tả mới cho vật phẩm.
- ISteamUGC::SetItemUpdateLanguage - Thiết lập ngôn ngữ cho tiêu đề và mô tả trong lần cập nhật này.
- ISteamUGC::SetItemMetadata - Thiết lập metadata tùy ý cho vật phẩm. Loại metadata ở trên có thể được trả về từ truy vấn mà không cần phải tải hoặc cài đặt nội dung thực tế.
- ISteamUGC::SetItemVisibility - Thiết lập độ hiển thị của vật phẩm.
- ISteamUGC::SetItemTags - Thiết lập thẻ tùy ý dành riêng cho nhà phát triển cho vật phẩm.
- ISteamUGC::AddItemKeyValueTag - Bổ sung thẻ là một cặp khóa-giá trị cho vật phẩm. Khóa ánh xạ tương ứng với nhiều giá trị khác nhau (mối quan hệ 1-nhiều).
- ISteamUGC::RemoveItemKeyValueTags - Loại bỏ môt thẻ khóa-giá trị hiện có khỏi vật phẩm.
- ISteamUGC::SetItemContent - Tạo một thư mục lưu trữ nội dung vật phẩm.
- ISteamUGC::SetItemPreview - Thiết lập hình ảnh xem trước chính cho vật phẩm.
Một khi các cuộc gọi cập nhật hoàn tất, gọi đến ISteamUGC::SubmitItemUpdate sẽ bắt đầu quy trình đăng tải lên Steam Workshop.
- Đăng ký trình xử lý kết quả cuộc gọi cho SubmitItemUpdateResult_t
- Khi trình xử lý kết quả cuộc gọi được thực thi, kiểm tra m_eResult để xác nhận rằng việc tải lên đã hoàn tất.
- Chú ý: Không có phương thức nào để hủy cập nhật và đăng tải vật phẩm một khi đã gọi lệnh.
Nếu muốn, tiến độ tải lên có thể được theo dõi bằng cách dùng ISteamUGC::GetItemUpdateProgress
- EItemUpdateStatus xác định tiến độ tải lên và cập nhật.
- punBytesProcessed và punBytesTotal được dùng để cung cấp thông tin đầu vào cho các cơ chế điều khiển giao diện người dùng, như thanh tiến độ để chỉ ra tiến độ của việc tải lên.
- punBytesTotal có thể cập nhật trong quá trình đăng tải dựa trên giai đoạn của việc cập nhật vật phẩm.
Cũng giống như cách Tạo vật phẩm workshop, hãy xác nhận xem người dùng đã chấp nhận thỏa thuận pháp lý chưa. Điều này là cần thiết trong trường hợp người dùng không tạo mới vật phẩm nhưng chỉ chỉnh sửa vật phẩm hiện có.

Ghi chú bổ sung

Vật phẩm workshop trước đây được chỉ định là tệp đơn. Với ISteamUGC, một vật phẩm workshop đại diện tương ứng một thư mục tập tin.
Nếu một vật phẩm workshop được ứng dụng tiêu thụ yêu cầu metadata bổ sung để sử dụng, bạn có thể đính kèm metadata vào vật phẩm bằng lệnh ISteamUGC::SetItemMetadata. Metadata này có thể được trả về trong các truy vấn mà không cần phải tải xuống hay cài đặt nội dung vật phẩm đó.
Trước đây, chúng tôi khuyên bạn nên lưu lại metadata này vào một tệp trong thư mục vật phẩm workshop, điều này bây giờ bạn vẫn có thể làm được.

Tiêu thụ nội dung

Tiêu thụ nội dung workshop rơi vào hai thể loại: đăng ký vật phẩm và cài đặt vật phẩm.

Đăng ký vật phẩm

Phần lớn các đăng ký vật phẩm workshop được thực hiện qua cổng Steam Workshop. Đây là một vị trí được biết đến nhiều, thường dùng cho tất cả trò chơi và ứng dụng, và vì thế mà người dùng nhiều khả năng tìm và đăng ký vật phẩm thường xuyên trên trang workshop.

Tuy nhiên, ISteamUGC cung cấp hai phương thức để đăng ký và hủy đăng ký vật phẩm workshop một cách có hệ thống để hỗ trợ việc quản lý đăng ký vật phẩm trong trò chơi.

ISteamUGC::SubscribeItem - Đăng ký một vật phẩm workshop. Nó sẽ được tải xuống và cài đặt ngay khi có thể.
ISteamUGC::UnsubscribeItem - Hủy đăng ký một vật phẩm workshop. Nó sẽ khiến vật phẩm bị gỡ bỏ sau khi thoát trò chơi.

Hai phương thức nữa cũng tồn tại để điểm qua các vật phẩm một người dùng đăng ký.

ISteamUGC::GetNumSubscribedItems - Lấy con số tổng các vật phẩm người dùng hiện tại đăng ký trong trò chơi hay ứng dụng xác định.
ISteamUGC::GetSubscribedItems - Lấy danh sách tất cả các vật phẩm người dùng hiện tại đăng ký cho trò chơi xác định.

Nhận thông báo cho hành động đăng ký bên ngoài

Có thể nhận thông báo trong trò chơi khi người dùng đăng ký hoặc hủy đăng ký khỏi một tệp thông qua bất cứ một cơ chế nào đó (ví dụ ISteamUGC, trang web Steam Workshop):

Đăng ký trình xử lý lệnh gọi lại (callback handler) cho RemoteStoragePublishedFileSubscribed_t và RemoteStoragePublishedFileUnsubscribed_t
Cấu trúc sẽ được lấp đầy với ISteamRemoteStorage::PublishedFileId_t rồi sau đó có thể được dùng để truy cập thông tin về vật phẩm workshop.
Cấu trúc cũng có chứa ID ứng dụng (m_unAppID) đi kèm với vật phẩm workshop đó. Cũng nên so sánh nó với ID ứng dụng hiện hành vì trình xử lý sẽ được gọi cho tất cả các đăng ký vật phẩm mà không màng ứng dụng đang chạy là gì.

Cài đặt vật phẩm

Một khi đã xác định thông tin đăng ký vật phẩm, những phương thức tiêu thụ còn lại có thể được sử dụng. Những phương thức này đưa thông tin tới trò chơi về trạng thái của việc tải xuống và cài đặt vật phẩm. Những đợt tải xuống vật phẩm workshop được thực hiện thông qua phần mềm Steam và xảy ra tự động, dựa theo những quy tắc sau:

Khi phần mềm Steam chỉ ra một trò chơi hay ứng dụng sắp khởi động, mọi depot ứng dụng đã cập nhật trước đó sẽ được tải xuống và cài đặt.
Tất cả vật phẩm workshop đã được cài đặt hiện có sẽ được cập nhật nếu cần thiết
Trò chơi hay ứng dụng sau đó khởi động
Những vật phẩm workshop mới được đăng ký mà vẫn chưa được tải xuống sau đó sẽ được tải về và cài đặt dưới nền.
- Những tệp đã đăng ký sẽ được tải xuống cho khách hàng theo thứ tự chúng được đăng ký.
- Trang tải xuống Steam sẽ hiện lượt tải các vật phẩm workshop với một biểu ngữ cụ thể để chỉ ra việc tải về vật phẩm workshop đang diễn ra.

Chú ý: sử dụng tính năng "Kiểm tra lại dữ liệu trò chơi" trong phần mềm Steam sẽ khiến các vật phẩm workshop được tải về.

Vì trò chơi sẽ bắt đầu trước khi các nội dung đăng ký được tải về và cài đặt, các phương thức tiêu thụ còn lại hiện diện để hỗ trợ việc kiểm tra và quản lý quá trình cài đặt. Chúng cũng có thể được dùng khi vật phẩm được đăng ký trong trò chơi để cung cấp trạng thái cài đặt theo thời gian thực.

Tình trạng của vật phẩm workshop

ISteamUGC::GetItemState - Lấy tình trạng hiện tại của vật phẩm trên phần mềm này.

Tiến độ tải về vật phẩm workshop

ISteamUGC::GetItemDownloadInfo - Lấy thông tin về một bản tải xuống đang xử lý mà đã có k_EItemStateNeedsUpdate thiết lập.

Khởi tạo hoặc tăng độ ưu tiên tải xuống vật phẩm workshop

ISteamUGC::DownloadItem
- Đặt bHighPriority thành true để tạm dừng bất cứ việc tải xuống nào khác hiện có và ngay lập tức bắt đầu tải xuống vật phẩm workshop này.
- Nếu giá trị trả về là true thì hãy đăng ký và đợi lệnh gọi lại ISteamUGC::DownloadItemResult_t trước khi gọi ISteamUGC::GetItemInstallInfo hay truy cập vật phẩm workshop trên ổ đĩa.
- Nếu người dùng không đăng ký vật phẩm (ví dụ như một máy chủ trò chơi đăng nhập ẩn danh), vật phẩm workshop đó sẽ được tải xuống và lưu vào bộ nhớ đệm tạm thời.
- Nếu vật phẩm workshop có ISteamUGC::EItemState là k_EItemStateNeedsUpdate, ISteamUGC::DownloadItem cần được gọi để bắt đầu cập nhật. Đừng truy cập vật phẩm workshop trên ổ đĩa cho tới khi lệnh gọi lại ISteamUGC::DownloadItemResult_t được thực hiện.
- Phương thức này chỉ hoạt động với các vật phẩm workshop được tạo ra bởi ISteamUGC. Nó sẽ không hoạt động với các vật phẩm workshop tạo bởi ISteamRemoteStorage kiểu cũ.
- Cấu trúc lệnh gọi lại ISteamUGC::DownloadItemResult_t có chứa ID ứng dụng (m_unAppID) đi kèm với vật phẩm workshop đó. Cũng nên so sánh nó với ID ứng dụng hiện hành vì trình xử lý sẽ được gọi cho tất cả đợt tải xuống vật phẩm mà không màng ứng dụng đang chạy là gì.

Thu thập thông tin về một bản sao chép cục bộ của vật phẩm workshop

ISteamUGC::GetItemInstallInfo - Lấy thông tin nội dung vật phẩm workshop được cài đặt hiện tại trên ổ đĩa mà có k_EItemStateInstalled được thiết lập.

Thông báo khi một vật phẩm workshop được cài đặt hay cập nhật

Đăng ký một trình xử lý lệnh gọi lại cho ISteamUGC::ItemInstalled_t.

Truy vấn nội dung

Giao diện ISteamUGC cung cấp một cách linh hoạt để liệt kê các loại UGC trên Steam (ví dụ: vật phẩm Workshop, ảnh chụp màn hình, video, v.v...)

Đăng ký trình xử lý kết quả cuộc gọi cho SteamUGCQueryCompleted_t.
Có một vài phương thức dùng để tạo truy vấn tùy trường hợp yêu cầu như Truy vấn theo nội dung liên quan tới người dùng, Truy vấn tất cả nội dung, hay tìm tất cả chi tiết các nội dung theo ID bạn có.
- ISteamUGC::CreateQueryUserUGCRequest - Truy vấn UGC có liên quan tới một người dùng nào đó. Bạn có thể dùng phương thức này để liệt kê các UGC mà người dùng đó đã đăng ký ngoài những thông tin khác.
- ISteamUGC::CreateQueryAllUGCRequest - Truy vấn tất cả UGC trùng khớp. Bạn có thể dùng phương thức này để liệt kê tất cả UGC có sẵn cho ứng dụng của bạn.
- ISteamUGC::CreateQueryUGCDetailsRequest - Truy vấn chi tiết của vật phẩm workshop cụ thể.
Tùy chỉnh truy vấn cho phù hợp bằng cách gọi các phương thức cài đặt tùy chọn:
- Khi truy vấn UGC của người dùng
  - ISteamUGC::SetCloudFileNameFilter - Đặt để truy vấn UGC đang chờ xử lý trả kết quả vật phẩm có tên tệp cụ thể.
- Khi truy vấn tất cả UGC
  - ISteamUGC::SetMatchAnyTag - Đặt cho truy vấn UGC có trả về vật phẩm workshop dựa theo việc chúng cần trùng khớp một thẻ hoặc hơn hay phải trùng khớp tất cả các thẻ hay không.
  - ISteamUGC::SetSearchText - Đặt cho truy vấn UGC một chuỗi thông tin trùng khớp với tiêu đề hoặc mô tả của vật phẩm.
  - ISteamUGC::SetRankedByTrendDays - Đặt cho truy vấn UGC về viêc có cập nhật thứ tự của kết quả dựa theo số ngày được xếp hạng thịnh hành của vật phẩm hay không.
- Khi truy vấn một trong hai loại UGC
  - ISteamUGC::AddRequiredTag - Thêm vào truy vấn UGC một thẻ bắt buộc trùng. Phương thức này chỉ trả về UGC có gắn thẻ được chỉ định.
  - ISteamUGC::AddExcludedTag - Thêm vào truy vấn UGC một thẻ cần được bỏ ra. Phương thức này chỉ trả về UGC không có gắn thẻ được chỉ định.
  - ISteamUGC::AddRequiredKeyValueTag - Thêm vào truy vấn UGC một thẻ khóa-giá trị bắt buộc. Phương thức này chỉ trả về các vật phẩm workshop có một khóa = [param]pKey[/param] và một giá trị = [param]pValue[/param].
  - ISteamUGC::SetReturnOnlyIDs - Đặt cho truy vấn UGC về việc liệu chỉ trả về ID thay vì tất cả chi tiết. Phương thức này hữu dụng nếu bạn không cần tất cả thông tin (ví dụ: nếu bạn chỉ muốn tìm ID của vật phẩm thuộc danh sách yêu thích của một người dùng).
  - ISteamUGC::SetReturnKeyValueTags - Đặt cho truy vấn UGC về việc có trả về bất cứ thẻ khóa-giá trị nào gắn với vật phẩm hay không.
  - ISteamUGC::SetReturnLongDescription - Đặt cho truy vấn UGC về việc có trả về toàn bộ mô tả của vật phẩm hay không.
  - ISteamUGC::SetReturnMetadata - Đặt cho truy vấn UGC về việc có trả về metadata do nhà phát triển xác định hay không.
  - ISteamUGC::SetReturnChildren - Đặt cho truy vấn UGC về việc có trả về ID của các vật phẩm con trong vật phẩm gốc hay không.
  - ISteamUGC::SetReturnAdditionalPreviews - Đặt cho truy vấn UGC về việc có trả về thêm bất cứ hình ảnh/video nào kèm theo vật phẩm hay không.
  - ISteamUGC::SetReturnTotalOnly - Đặt cho truy vấn UGC về việc có trả về con số tổng các vật phẩm trùng khớp hay không. Những vật phẩm thực chất sẽ không được trả về khi ISteamUGC::SteamUGCQueryCompleted_t được gọi.
  - ISteamUGC::SetLanguage - Đặt ngôn ngữ cho truy vấn UGC trả về tiêu đề và mô tả của vật phẩm.
  - ISteamUGC::SetAllowCachedResponse - Đặt cho truy vấn UGC về việc có trả kết quả từ bộ nhớ đệm cache trong một khoảng thời gian xác định hay không.
Gửi truy vấn tới Steam bằng cách dùng ISteamUGC::SendQueryUGCRequest. Nó sẽ gọi trình xử lý kết quả cuộc gọi ISteamUGC::SendQueryUGCRequest được đăng ký ở bước 1.
Trong trình xử lý kết quả cuộc gọi cho ISteamUGC::SteamUGCQueryCompleted_t, gọi ISteamUGC::GetQueryUGCResult để thu thập chi tiết cho từng mục được trả về.
Bạn cũng có thể gọi những hàm sau để thu thập thêm thông tin cho từng mục (một phần dữ liệu này không được trả về theo mặc định nên bạn cần phải thiết lập truy vấn của bạn cho phù hợp):
- ISteamUGC::GetQueryUGCPreviewURL - Thu thập đường dẫn tới ảnh xem trước của một vật phẩm workshop sau khi nhận được kết quả truy vấn UGC.
- ISteamUGC::GetQueryUGCMetadata - Thu thập metadata do nhà phát triển lập của một vật phẩm workshop sau khi nhận được kết quả truy vấn UGC.
- ISteamUGC::GetQueryUGCChildren - Thu thập ID của bất cứ vật phẩm con nào trong vật phẩm workshop gốc sau khi nhận được kết quả truy vấn UGC.
- ISteamUGC::GetQueryUGCStatistic - Thu thập các con số thống kê của một vật phẩm workshop sau khi nhận được kết quả truy vấn UGC.
- ISteamUGC::GetQueryUGCNumAdditionalPreviews và ISteamUGC::GetQueryUGCAdditionalPreview - Thu thập chi tiết mục xem trước khác có liên quan tới một vật phẩm workshop sau khi nhận được kết quả truy vấn UGC.
- ISteamUGC::GetQueryUGCNumKeyValueTags và ISteamUGC::GetQueryUGCKeyValueTag - Thu thập chi tiết về một thẻ khóa-giá trị có liên quan tới một vật phẩm workshop sau khi nhận được kết quả truy vấn UGC.
Gọi ISteamUGC::ReleaseQueryUGCRequest để giải phóng bộ nhớ được phân bổ khi truy vấn hay thu thập kết quả.

Phân trang kết quả

Mỗi truy vấn có thể trả về tối đa 50 kết quả. Có thể tạo truy vấn với tham số unPage tăng dần (nên bắt đầu từ 1) để tạo thêm các trang kết quả.

Theo dõi số giờ chơi

Để theo dõi số giờ chơi của vật phẩm Workshop, đơn giản gọi ISteamUGC::StartPlaytimeTracking với ID của vật phẩm bạn muốn theo dõi. Đến khi vật phẩm bị gỡ bỏ khỏi trò chơi, hãy gọi ISteamUGC::StopPlaytimeTracking với ID bạn muốn ngưng theo dõi hoặc gọi ISteamUGC::StopPlaytimeTrackingForAllItems để dừng theo dõi số giờ chơi cho tất cả vật phẩm cùng một lúc.
Khi ứng dụng đóng lại, việc theo dõi số giờ chơi sẽ tự động ngừng.

Bạn cũng có thể xếp vật phẩm theo các số liệu về số giờ chơi qua truy vấn ISteamUGC::CreateQueryAllUGCRequest. Sau đây là các loại truy vấn về số giờ chơi bạn có thể dùng:

k_EUGCQuery_RankedByPlaytimeTrend - Xếp theo tổng số giờ chơi trong giai đoạn "thịnh hành" từ cao tới thấp (thiết lập với ISteamUGC::SetRankedByTrendDays)
k_EUGCQuery_RankedByTotalPlaytime - Xếp theo tổng số giờ chơi từ trước tới nay từ cao tới thấp.
k_EUGCQuery_RankedByAveragePlaytimeTrend - Xếp theo số giờ chơi trung bình trong giai đoạn "thịnh hành" từ cao tới thấp (thiết lập với ISteamUGC::SetRankedByTrendDays)
k_EUGCQuery_RankedByLifetimeAveragePlaytime - Xếp theo số giờ chơi trung bình từ trước tới nay, từ cao tới thấp
k_EUGCQuery_RankedByPlaytimeSessionsTrend - Xếp theo số lượt chơi trong giai đoạn "thịnh hành" từ cao tới thấp (thiết lập trong ISteamUGC::SetRankedByTrendDays)
k_EUGCQuery_RankedByLifetimePlaytimeSessions - Xếp theo số lượt chơi từ trước tới nay từ cao tới thấp

Xóa nội dung vật phẩm Workshop

Để xóa một vật phẩm Workshop, bạn có thể gọi ISteamUGC::DeleteItem. Xin chú ý rằng việc này sẽ không được báo với người dùng và không thể hoàn tác.

Ví dụ Steamworks - Tích hợp SpaceWar

Steamworks API Example Application (SpaceWar) đi kèm với Steamworks SDK làm rõ một phần của API ISteamUGC.

CSpaceWarClient::LoadWorkshopItem thể hiện cách kiểm tra liệu vật phẩm workshop đã được tải về và cài đặt vào ổ đĩa cũng như yêu cầu thông tin về vật phẩm workshop bằng ISteamRemoteStorage::PublishedFileId_t
CSpaceWarClient::LoadWorkshopItems thể hiện việc truy xuất danh sách các vật phẩm workshop được đăng ký của người dùng hiện tại cho ứng dụng SpaceWar
CSpaceWarClient::OnWorkshopItemInstalled thể hiện một trình xử lý lệnh gọi lại cho ISteamUGC::ItemInstalled_t

Thỏa thuận pháp lý về Steam Workshop

Theo mặc định, những vật phẩm workshop sẽ bị ẩn cho tới khi người đóng góp đồng ý với Thỏa thuận pháp lý về Steam Workshop. Để việc hiển thị vật phẩm công khai trở nên dễ dàng hơn cho người đóng góp, xin hãy làm những điều sau.

Kèm thêm một đoạn văn bản bên cạnh nút dùng để đăng gửi vật phẩm vào workshop, đại loại như là: "Với việc đăng gửi vật phẩm này, bạn đồng ý với điều khoản dịch vụ workshop" (kèm theo đường dẫn)
Sau khi người dùng đã đăng gửi vật phẩm, mở một cửa sổ trình duyệt tới trang Steam Workshop cho vật phẩm đó bằng cách gọi ISteamFriends::ActivateGameOverlayToWebPage với pchURL được đặt là steam://url/CommunityFilePage/ rồi thay bằng ID vật phẩm workshop đó.

Điều này có lợi trong việc dẫn hướng tác giả tới trang workshop để họ có thể thấy vật phẩm đó và tạo ra các thiết lập cần thiết khác nếu cần, giúp việc đọc và chấp nhận Thỏa thuận pháp lý về Steam Workshop dễ dàng hơn cho người dùng.

Web API

Ngoài những phương thức này, còn có một số Web API cũng cung cấp những tính năng tương tự cùng với các API có chức năng lọc do cộng đồng tạo ra để liệt kê tất cả nội dung được chia sẻ. Xin tham khảo tài liệu cho giao diện ISteamRemoteStorage trong danh sách Web API.

Máy chủ trò chơi chuyên dụng

Các máy chủ trò chơi cũng có thể tải xuống và cài đặt vật phẩm.

Máy chủ trò chơi sẽ cần biết PublishedFileId_t để yêu cầu vật phẩm workshop, nó có thể được cung cấp bởi phần mềm trò chơi hoặc đặt bởi nhà điều hành máy chủ. Sau đó gọi ISteamUGC::DownloadItem để lấy một bản sao tạm thời của vật phẩm workshop đó.
Một cuộc gọi tới ISteamUGC::GetItemInstallInfo sẽ được tiến hành để lấy thông tin nhằm định vị và sử dụng vật phẩm workshop.
Xem phần Cài đặt vật phẩm bên trên để biết thêm chi tiết về các phương thức API này.

Tích hợp SteamCmd

Cùng với API ISteamUGC, công cụ viết dòng lệnh (command line tool) steamcmd.exe có thể được dùng để tạo và cập nhật vật phẩm workshop nhằm mục đích kiểm tra. Nó chỉ nên được dùng cho mục đích kiểm tra vì công cụ này yêu cầu người dùng nhập vào thông tin đăng nhập Steam (điều mà chúng tôi không muốn khách hàng phải làm).

Để tạo vật phẩm Steam Workshop mới thông qua steamcmd.exe, một tệp VDF phải được tạo ra trước. Tệp VDF là một tệp văn bản đơn thuần có chứa các khóa sau:

"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" }

Chú ý:

Các khóa ánh xạ tương ứng với một số phương thức ISteamUGC::SetItem[...]. Xem tài liệu ở trên để biết thêm chi tiết.
Các giá trị hiển thị chỉ là ví dụ và nên được cập nhật một cách phù hợp.
Để tạo vật phẩm mới, appid phải được thiết lập và publishedfileid bị gỡ bỏ hoặc chỉnh về 0.
Để cập nhật một vật phẩm đã có sẵn, cả appid và publishedfileid đều phải được thiết lập.
Các khóa/cặp giá trị còn lại phải được bao gồm trong VDF nếu khóa đó cần được cập nhật.

Một khi tệp VDF đã được tạo ra, steamcmd.exe có thể được chạy bằng các tham số tệp của workshop_build_item . Ví dụ:

steamcmd.exe +login tênĐăngNhập mậtKhẩu +workshop_build_item workshop_green_hat.vdf +quit

Nếu lệnh đặt thành công, giá trị publishedfileid trong tệp VDF sẽ tự động được cập nhật để chứa ID của vật phẩm workshop đó. Bằng cách này, các đợt đặt lệnh tiếp theo trên steamcmd.exe với cùng tệp VDF sẽ ra kết quả là một cập nhật thay vì một vật phẩm mới.

Lỗi và nhật ký

Phần lớn phương thức trong ISteamUGC trả về giá trị boolean. Để xem thêm thông tin về các lỗi cụ thể, có vài nguồn bạn có thể xem xét qua:

Steam\logs\Workshop_log.txt là nhật ký cho tất cả lượt chuyển giao xảy ra trong khi tải về và cài đặt vật phẩm từ workshop
.
Steam\workshopbuilds\depot_build_.log là nhật ký cho tất cả các tác vụ diễn ra khi tải lên và cập nhật vật phẩm workshop.
ISteamUGC::SteamUGCQueryCompleted_t, ISteamUGC::CreateItemResult_t và ISteamUGC::SubmitItemUpdateResult_t chứa các biến EResult có thể được kiểm tra.

Hỏi đáp thường gặp

Hỏi: Một ứng dụng riêng có thể đăng nội dung lên trang Workshop trò chơi không?

Có. Một ứng dụng riêng biệt cho các công cụ chỉnh sửa hoặc phát hành có thể được thiết lập với workshop của ứng dụng gốc để chấp nhận nội dung từ ứng dụng chỉnh sửa đó.

Để thiết lập, hãy vào phần Thiết lập Workshop của ứng dụng gốc và kéo tới cuối trang. Nhập vào App ID của ứng dụng riêng vào ô nằm dưới "Quyền phát hành ứng dụng" và nhấn "Thêm vào".

Một khi các thiết lập Steamworks đã được phát hành, ứng dụng chỉnh sửa đó sẽ có thể đăng tải nội dung lên workshop của ứng dụng gốc.