Tài liệu Steamworks
Tải nội dung lên Steam
Sau đây là hướng dẫn sử dụng SteamPipe, công cụ của Valve để phân phối nội dung đến Steam. Để tìm thêm thông tin về các phương pháp tối ưu để cập nhật trò chơi, xem Cập nhật trò chơi - Phương pháp tối ưu.

Giới thiệu về hệ thống nội dung SteamPipe

SteamPipe là hệ thống nội dung trò chơi/ứng dụng dùng để vận hành Steam. SteamPipe gồm những tính năng sau:
  • Phân phối nội dung hiệu quả và nhanh chóng.
  • Các nhánh "beta" công khai và riêng tư cho phép thử nghiệm nhiều bản build.
  • Công cụ quản lý build trên web giúp phát hành bản build mới hoặc khôi phục về bản build trước đó chỉ với vài cú nhấp chuột.
  • Khả năng nhìn thấy kích thước bản build trước khi phát hành chính thức.
  • Khả năng chia sẻ nội dung giữa nhiều ứng dụng.
  • Khả năng ghi bộ cài vào đĩa với nội dung công khai hay beta.
  • Dù đã bắt đầu tải bản cập nhật, trò chơi/ứng dụng vẫn có thể được dùng khi ngắt mạng.
  • Tất cả nội dung đều được mã hóa, và khách hàng sẽ không nhìn thấy các phiên bản không hoạt động.
  • Một SteamPipe Local Content Server có thể được dùng trong quá trình phát triển.
LƯU Ý: SteamPipe có một số khái niệm chủ chốt. Trước khi bắt đầu, bạn nên làm quen với mọi khái niệm được liệt kê trong tài liệu Ứng dụng này. Nắm được dù chỉ là kiến thức cơ bản cách hoạt động của các khái niệm này sẽ rất hữu dụng khi bạn tải sản phẩm lên Steam.

Cấu trúc nội dung trò chơi - Phương pháp tối ưu


SteamPipe được thiết kế để tối ưu quá trình tải trò chơi lần đầu cũng như khi cập nhật nội dung. Tóm lại, nó hoạt động hiệu quả với nhiều kiểu cấu trúc nội dung trò chơi. Tuy nhiên, có những điều quan trọng cần biết về mặt tối ưu và để tránh các trường hợp có thể gây hiệu suất kém.

Lưu ý: Nếu trò chơi của bạn sử dụng Unreal Engine, vui lòng xem ghi chú dành cho các file gói ở cuối mục này.

SteamPipe ban đầu chia mỗi file thành các mảnh nhỏ có kích thước 1 megabyte (MB). Mỗi mảnh sau đó được nén và mã hóa trước khi tải lên hệ thống phân phối nội dung của Steam. Chúng vẫn được nén và mã hóa cho đến khi được tải về bởi phần mềm, sau đó sẽ được giải mã và giải nén rồi đặt vào nơi lưu trữ file cần thiết.

Khi SteamPipe đang thực hiện cập nhật cho một trò chơi hiện hữu, nó sẽ tìm tất cả các mảnh khớp với bản build trước đó của trò chơi. Bằng cách này, chỉ có những phần mới hoặc có thay đổi trong các file mới được chuyển thành các mảnh "mới", và phần mềm chỉ cần tải các mảnh mới này để cập nhật trò chơi.

Rất nhiều engine trò chơi dùng file "gói" để tổng hợp tư liệu trò chơi, và cải thiện thời gian nạp bằng cách cho phép truy cập ổ cứng hiệu quả hơn. Tóm lại, nó hoạt động hiệu quả với SteamPipe. Tuy nhiên, một số hệ thống file gói dùng hoặc tạo điều kiện cho các hành vi có thể gây ra vấn đề. Ảnh hưởng của các vấn đề đó thường khiến bản cập nhật có kích thước lớn hơn cần thiết. Một kết quả khác là nội dung tải về nhanh nhưng cập nhật lại chậm vì ngốn nhiều tốc độ đọc và ghi của ổ cứng trên máy.

Nếu trò chơi của bạn dùng file gói, sau đây là một vài hướng dẫn chung.

  • Đảm bảo các thay đổi về tư liệu được gói gọn trong file gói hết sức có thể.
  • Tránh xáo trộn thứ tự tư liệu với file gói
  • Giới hạn kích thước file gói
  • Nhóm tư liệu theo màn chơi / thế giới / tính năng vào các file gói riêng, và cân nhắc thêm file gói mới khi có cập nhật thay vì chỉnh sửa file có sẵn.
  • Đừng thêm bất kỳ tên file hay mốc thời gian của file / build gốc nào vào mỗi tư liệu

Ý đầu tiên ở trên nói về byte nào trong file được thay đổi khi một tư liệu được chỉnh sửa. Lý tưởng nhất là dữ liệu của tư liệu được chỉnh sửa và/hoặc tăng hay giảm kích thước trong cùng vị trí của file gói. SteamPipe chỉ tạo mảnh mới cho các bộ phận của file có chứa dữ liệu tư liệu. Tuy nhiên, mọi file gói đều cần một bảng mục lục (Table of Contents - TOC) để giúp engine có thể tìm thấy dữ liệu tư liệu. Cấu trúc của TOC có thể tạo ra tác động lớn đến tính hiệu quả khi cập nhật SteamPipe. Lý tưởng nhất là có một TOC hoặc cây TOC ở gần đầu hoặc cuối file. Vì các tư liệu khác có thể dịch chuyển vị trí byte trong một file, các mục TOC của chúng cũng sẽ thay đổi. Trong trường hợp này, SteamPipe sẽ tạo các mảnh mới cho dữ liệu tư liệu được chỉnh sửa và phần TOC được thay đổi.

Tuy nhiên, chúng tôi nhận thấy trong một số engine trò chơi, thông tin TOC được phân bổ ở khắp file. Tệ hơn nữa, nó dùng các giá trị lệch byte tuyệt đối. Vì thế, nếu một tư liệu tại byte 3450 tăng kích cỡ thêm 8 byte, thì giá trị lệch của mọi tư liệu sau đó trong file sẽ thay đổi. Cho dù mỗi giá trị offset chỉ có kích cỡ 4 hay 8 byte, khi một con số 8 byte có thay đổi, một mảnh có kích cỡ 1MB sẽ được tạo bởi SteamPipe. Điều này có thể gây hậu quả cực kỳ xấu, khi mà thay đổi một vài tư liệu nhỏ trong file gói có thể khiến phần mềm phải tải về hơn một nửa file để cập nhật. Nếu bạn biết hoặc nghi ngờ cấu trúc file gói của mình đang gây ra vấn đề này, vui lòng liên hệ với đại diện của Valve sớm nhất có thể. Chúng tôi có một thuật toán build thay thế có thể giúp hạn chế vấn đề này, nhưng sẽ có những đánh đổi.

Thêm vào đó, SteamPipe không biết về ranh giới của tư liệu trong một file gói. Nếu tư liệu dưới một megabyte được xáo trộn, khả năng cao SteamPipe sẽ không thể phát hiện sự thay đổi thứ tự này vì các mảnh 1-MB được quyết định trước đây không còn nằm trong file. Vì thế trong quá trình tạo bản cập nhật trò chơi, nếu bạn muốn tối ưu thời gian nạp bằng cách thay đổi thứ tự tư liệu trong file gói, hãy biết rằng kích thước của bản cập nhật có thể trở nên rất lớn. Chúng tôi khuyến nghị bạn chỉ nên làm vậy nếu hiệu suất được cải thiện đáng kể.

Kế đến - để cập nhật file gói trên thiết bị của người dùng, SteamPipe sẽ tạo phiên bản mới tồn tại song song phiên bản cũ. Khi build xong toàn bộ file mới, nó sẽ "thực hiện" việc cập nhật bằng cách xóa file cũ và chuyển file mới vào. Điều này có nghĩa, để cập nhật file gói nặng 25GB, SteamPipe sẽ luôn tạo một file mới nặng 25GB. Nếu bản cập nhật chỉ cần thay đổi 10 byte trong file đó, SteamPipe sẽ cần chép gần như toàn bộ 25GB của file cũ vào file mới. Tùy vào thiết bị lưu trữ của người dùng, quá trình này có thể diễn ra rất chậm. Vì lý do này, chúng tôi đề xuất hai điều sau.

Thứ nhất - giới hạn kích cỡ của file gói. Có thể một hay hai gigabyte (GB) là đủ lớn - đủ để giúp ổ cứng đọc file hiệu quả khi nạp trò chơi.

Thứ hai - giới hạn phạm vi của tư liệu trong cùng một file gói. Có thể là với một màn chơi, hoặc một tính năng có thể mở khóa. Bằng cách này, các bản cập nhật tập trung vào một phần nhất định của trò chơi sẽ không làm dữ liệu các phần khác bị chép lên máy người dùng. Chưa hết, khi thêm tính năng / màn chơi / v.v., chúng có thể và nên được đặt trong file gói được tạo mới và riêng biệt. Máy người dùng khi tải bản cập nhật này sẽ đơn giản chỉ tải các file mới, tránh được các vấn đề được nhắc đến ở trên khi thay đổi file gói.

Khi không chắc, bạn có thể dùng công cụ so sánh sự khác biệt trong binary trên máy, chẳng hạn như Beyond Compare, để so sánh các phiên bản của file gói. Hãy xác minh rằng các khác biệt bạn nhìn thấy là đúng với các thay đổi mong muốn trong tư liệu, và không có hàng chục hoặc hàng trăm thay đổi nhỏ nằm khắp file. Nếu bạn nhìn thấy thay đổi không mong muốn, hãy kiểm tra thiết lập của công cụ file gói.

Nén: Vì Steam sẽ nén toàn bộ dữ liệu khi tải lên / lưu trữ / tải xuống, nên nhìn chung chúng tôi khuyên bạn không nên tự nén file gói. Tuy nhiên, nếu quan ngại về kích cỡ trên ổ đĩa của trò chơi, bạn vẫn có thể nén trước file gói. Nó sẽ hoạt động ĐƯỢC với SteamPipe, miễn là bạn tuân theo các điều kiện ở trên. Cụ thể hơn, bạn nên đảm bảo hết mức có thể rằng việc nén là theo từng tư liệu một. Nếu nén nhiều tư liệu có ranh giới khác nhau, các thay đổi sẽ bị phân tán và yêu cầu máy người dùng phải tải về nhiều dữ liệu hơn cần thiết.

Mã hóa: Giống như việc nén dữ liệu - điều này thường không cần thiết, và mang rủi ro như đã nhắc đến ở trên.

Nếu làm theo các quy tắc này, bạn sẽ giảm được kích cỡ của bản cập nhật và chỉ có nội dung mới sẽ được tải về. Khách hàng sẽ cảm kích bạn vì điều đó và bạn sẽ có thể nâng cao chất lượng của sản phẩm bằng cách tạo ra nhiều cập nhật hơn.

Nếu bạn nghi ngờ việc đóng gói trò chơi của mình không hoạt động tốt với quá trình cập nhật của SteamPipe, vui lòng liên hệ với đại diện từ Valve và chúng tôi có thể cân nhắc bật các tính năng nâng cao để hỗ trợ bạn.

Unreal Engine - Lưu ý đặc biệt

Một số phiên bản của Unreal Engine dùng "căn chỉnh phần đệm" (padding alignment) cho tư liệu trong file gói, điều này có thể ảnh hưởng lớn đến kích cỡ cập nhật SteamPipe. Quá trình căn chỉnh này có thể khiến tư liệu dịch chuyển đồng loạt khi tạo phiên bản mới, đặc biệt nếu bật chức năng nén file gói. Dùng căn chỉnh phần đệm có giá trị 1MB (1048576) đảm bảo quá trình căn chỉnh lại sẽ làm dịch chuyển tư liệu theo hệ số các khối kích cỡ bằng nhau mà SteamPipe dùng để tính toán delta.

Ví dụ, để thay đổi hoặc chỉ định căn chỉnh phần đệm khi "cook" file gói của trò chơi, bạn cần thay đổi một dòng trong file UnrealEngine/Engine/Source/Programs/AutomationTool/Win/WinPlatform.Automation.cs. File đó chứa một hàm GetPlatformPakCommandLine -- bên trong hàm đó, đổi dòng này:

string PakParams = " -patchpaddingalign=2048";

thành:

string PakParams = " -patchpaddingalign=1048576 -blocksize=1048576";

Với thay đổi này, bạn sẽ có thể bật tính năng nén file gói mà vẫn tối ưu được hành vi cập nhật SteamPipe.

Unreal Engine là nhãn hiệu hoặc nhãn hiệu đã đăng ký tại Mỹ và các nơi khác.

Video hướng dẫn Steamworks - Dựng trò chơi trong SteamPipe

Hướng dẫn này giới thiệu SteamPipe và đi qua các bước dựng một ứng dụng mẫu cho Steam qua công cụ Steamworks.
https://www.youtube.com/watch?v=SoNH-v6aU9Q

Video hướng dẫn Steamworks - Thêm nền tảng và ngôn ngữ mới

Hướng dẫn sẽ giúp thêm nền tảng và ngôn ngữ mới cho trò chơi bằng cách thêm các depot vào ứng dụng của bạn.
https://www.youtube.com/watch?v=PShS32hcing

Chi tiết kỹ thuật SteamPipe

SteamPipe dùng giao thức HTTP để phân phối nội dung. Vì việc tải về là lưu lượng web thông thường, bất kỳ bộ nhớ cache nào của bên thứ ba giữa khách hàng và máy chủ Steam sẽ làm tăng tốc độ tải xuống. Nội dung có thể được lưu bởi nhà cung cấp máy chủ phân phối nội dung (CDN) bên ngoài, chúng có thể dễ dàng được thêm vào mạng lưới nội dung của chúng tôi. Đa phần tường lửa của người tiêu dùng cho phép lưu thông HTTP và sẽ không chặn việc tải xuống.

SteamPipe có một thuật toán hiệu quả để tạo bản cập nhật dựa trên các delta của binary, chỉ thay đổi các phần có điều chỉnh thuộc file nội dung hiện hữu. Khi nội dung này được cập nhật, chỉ các delta này cần được gửi. Điều này có nghĩa việc truyền tải của cả nhà phát triển và người dùng trở nên nhanh và gọn hơn. Hầu hết các đối tác sẽ thấy việc dùng SteamPipe Local Content Server là không cần thiết vì họ có thể cập nhật build một cách hiệu quả trên các nhánh riêng tư.

Tài khoản Steam tạo build

Trước khi có thể tạo build nào trên Steam, bạn phải có tài khoản Steam trong tài khoản Steamworks đã được trao quyền "Sửa Metadata ứng dụng" và "Phát hành các thay đổi của ứng dụng trên Steam". Vì lý do an ninh, chúng tôi khuyến nghị bạn nên có một tài khoản chuyên cho tạo build với chỉ các quyền đó, bạn có thể tạo một tài khoản Steam mới cho mục đích này tại https://store.steampowered.com/join.

Bất kỳ quản trị viên nào cho tài khoản Steamworks của bạn cũng có thể thêm một tài khoản Steam và trao các quyền cần thiết. Để tìm hiểu thêm về quá trình này, vui lòng đọc tài liệu Quản lý tài khoản Steamworks của bạn. Ví dụ về tài khoản này sẽ trông như thế nào:

create_build_account.png
Lưu ý: Nếu tài khoản Steam cần phát hành bản build cho ứng dụng đã ra mắt, sẽ cần số điện thoại hoặc ứng dụng Steam di động liên kết với tài khoản. Các phương thức này sẽ được dùng để xác thực việc phát hành bản build cho một ứng dụng đã ra mắt. Thêm vào đó, nếu tài khoản Steam có thay đổi về bảo mật (email, số điện thoại, v.v.), thì bạn sẽ cần đợi 3 ngày trước khi có thể phát hành bản build cho ứng dụng đã ra mắt. Hành động này giúp ngăn không cho tài khoản bị xâm nhập có thể quản lý các build đã phát hành của ứng dụng.

Cài đặt ban đầu cho ứng dụng SteamPipe mới

Làm theo các bước sau để thiết lập ứng dụng SteamPipe mới:
  1. Tìm appID cho ứng dụng của bạn (có thể thấy bằng cách chọn ứng dụng trên trang chủ Steamworks)
  2. Đến trang Thiết lập cài đặt tổng quan cho ứng dụng của bạn.
  3. Định nghĩa ít nhất một tùy chọn khởi động (đường dẫn, và bất kỳ cú pháp nào cần thiết để chạy trò chơi). Di chuyển lên trên (?) để hiểu thêm về mỗi mục.

    Ví dụ bên dưới có 5 tùy chọn khởi động, 2 cho Windows, 2 cho macOS và 1 cho Linux.
    Tùy chọn khởi động 3 sẽ chỉ hiện trên Windows nếu người dùng cũng sở hữu DLC chỉ định.

    updatedlaunchoptions_3.png
  4. Đến trang Depots và thêm các depot cần thiết cho ứng dụng này. Mặc định, một depot có thể đã được thiết lập cho ứng dụng của bạn.
    1. Nhấp vào depot mặc định và thay đổi tên của depot thành một tên hoàn chỉnh và nhận diện được (ví dụ như "Nội dung gốc" hay "Nội dung Windows").
    2. Để thiết lập ngôn ngữ thành [Tất cả ngôn ngữ] trừ phi đấy là depot cụ thể cho một ngôn ngữ.
    3. Đặt hệ điều hành thành [Tất cả HĐH] trừ phi đây là depot cụ thể cho một hệ điều hành (nếu ứng dụng là tất cả trong một, hoặc nếu chỉ là cho PC hay Mac, nó nên được để thành [Tất cả HĐH]. Chỉ nên chỉ định cho các depot trò chơi theo hệ điều hành cụ thể.
    4. Nhấp vào Thêm depot mới để tạo thêm depot.
    5. Nhấp vào Lưu để giữ lại các thay đổi đã thực hiện.
  5. Sau khi định nghĩa xong depot, phát hành các thay đổi bạn đã thực hiện từ trang Phát hành.
  6. Các depot bạn vừa mới định nghĩa sẽ cần được thêm vào một gói để trao bạn quyền sở hữu chúng. Mỗi trò chơi trên Steam nên có một gói Developer Comp vốn tự động trao cho tài khoản được liệt kê trong nhóm nhà phát hành của bạn.
    Bạn có thể thêm depot mới vào gói đó (và/hoặc các gói khác nên có những depot đấy) tại trang Gói & DLC liên quan.
Lưu ý: Nếu file thực thi nằm trong một thư mục phụ của thư mục cài đặt chính, thêm tên thư mục phụ vào mục 'Thực thi'. Đừng sử dụng dấu gạch chéo và dấu chấm ở đầu.
Lưu ý về nền tảng: Như đã chỉ bên trên, các ứng dụng macOS có thể được khởi chạy bằng cách chỉ định một bộ ứng dụng (Game.app) hay một đoạn mã/binary (Game.app/Contents/MacOS/Game). Nhìn chung, định dạng bộ ứng dụng nên được ưu tiên nếu có thể do nó cho phép macOS xác định đúng hơn các tham số khởi chạy theo cách như thể nếu nó được chạy thủ công bên ngoài Steam.

Một ví dụ để lưu ý là hiện tại ứng dụng được khởi động qua một bộ ứng dụng trên thiết bị Apple Silicon sẽ chạy kiến trúc tốt nhất hiện hữu trong ứng dụng, trong khi đó chạy trực tiếp binary sẽ dùng kiến trúc tương tự như process Steam (hiện tại là x86_64).

Thiết lập SDK cho các phiên tải lên SteamPipe

Tải về và giải nén phiên bản Steamworks SDK mới nhất về máy mà bạn sẽ dùng để tải lên các build.

Công cụ SteamPipe có thể được tìm thấy bên trong SDK tại thư mục tools, trong đó lại chứa hai thư mục con liên quan.

Thư mục ContentBuilder là nơi nội dung trò chơi của bạn và các công cụ build SteamPipe sẽ hiện diện. Thư mục này lại chứa các nhóm con sau:
  • builder - Ban đầu chỉ chứa steamcmd.exe là phiên bản command line của Steam.
  • builder_linux - Phiên bản linux của steamcmd.
  • builder_osx - Phiên bản macOS của steamcmd.
  • content - Thư mục này chứa toàn bộ file nội dung trò chơi mà sẽ được dựng thành các depot.
  • output - Thư mục này sẽ là vị trí nhật ký build, mảnh cache, và thành phẩm trung gian. LƯU Ý: Thư mục này có thể được xóa và làm trống bất kỳ lúc nào, nhưng sau khi bị xóa, lần tải lên tiếp theo sẽ tốn nhiều thời gian hơn.
  • scripts - Thư mục này là nơi bạn sẽ đặt tất cả đoạn mã của build để dựng các depot trò chơi.
steampipebuilddir.png

Chúng tôi khuyến nghị bạn chạy steamcmd.exe trực tiếp ít nhất một lần từ thư mục builder cho nền tảng của mình để bootstrap build hệ thống. Nó sẽ đưa các file cần thiết để dựng depot vào thư mục builder của bạn.

Thư mục ContentServer chứa công cụ để tự chạy SteamPipe Local Content Server của bạn nếu muốn.

SteamCmd trên macOS

Để bật SteamCmd trên macOS bạn phải hoàn thành các bước sau:
  1. Từ terminal, đi tới tools\ContentBuilder\builder_osx
  2. Chạy chmod +x steamcmd
  3. Gõ bash ./steamcmd.sh
  4. SteamCMD sẽ khởi chạy và cập nhật lên build mới nhất, rồi dừng lại ở prompt SteamCMD
  5. Gõ exit và nhấn Return để thoát prompt
Sau đó, bạn có thể làm theo phần còn lại của tài liệu này (thay đổi đường dẫn nếu cần) để tạo file thiết lập ứng dụng và depot cho việc tải nội dung lên Steam.

Tạo file thiết lập build SteamPipe

Để tải lên file cho ứng dụng với SteamPipe, bạn phải tạo mã mô tả bản build và từng depot được bao gồm trong đó. Mã ví dụ được hiện ở đây nằm ở thư mục Tools\ContentBuilder\scripts trong Steamworks SDK.

Công cụ SteamPipe có giao diện

Nếu đang chạy Windows và thích sử dụng một công cụ giao diện đồ họa người dùng (GUI) để giúp tạo các file thiết lập và tải lên bản build, bạn có thể dùng SteamPipeGUI có trong thư mục công cụ của Steamworks SDK. Bên trong file zip là các hướng dẫn khác để giúp bạn bắt đầu.

Nếu chọn dùng công cụ GUI thì bạn vẫn nên đọc các mục sau vì chúng sẽ giúp bạn làm quen với cách hoạt động của hệ thống SteamPipe.

Mã build đơn giản


Hãy bắt đầu với mã build đơn giản nhất có thể. Trong ví dụ này, chúng tôi có trò chơi (AppID 1000) có một depot (DepotID 1001) và muốn tải lên toàn bộ file từ một thư mục nội dung với các thư mục con. Chúng ta chỉ cần một mã build đơn giản cho trường hợp này, hãy xem "simple_app_build.vdf" nằm trong SDK:

"AppBuild" { "AppID" "1000" // AppID của bạn "Desc" "Đây là một mã build đơn giản" // mô tả nội bộ cho bản build "ContentRoot" "..\content\" // thư mục nội dung gốc, so với vị trí của file này "BuildOutput" "..\output\" // thư mục đầu ra chứa nhật ký và file cache của bản build "Depots" { "1001" // DepotID của bạn { "FileMapping" { "LocalPath" "*" // tất cả file từ thư mục contentroot "DepotPath" "." // gán vào thư mục gốc của depot "recursive" "1" // bao gồm tất cả thư mục con } } } }

Điều chỉnh AppID và DepotID cho trò chơi của bạn nếu cần. Để bắt đầu một bản build, bạn cần chạy SteamCMD và truyền vào vài tham số:
tools\ContentBuilder\builder\steamcmd.exe +login <account_name> <password> +run_app_build ..\scripts\simple_app_build.vdf +quit

Các bước sau xảy ra trong quá trình tạo bản build của SteamPipe:
  1. steamcmd.exe sẽ tự cập nhật lên phiên bản mới nhất.
  2. steamcmd.exe đang đăng nhập vào backend Steam bằng tài khoản Steam dùng bởi công cụ build.
  3. Phần đầu của bản build ứng dụng được đăng ký với MDS (Máy chủ depot chính), điều này đảm bảo người dùng có đúng quyền hạn để chỉnh sửa ứng dụng này.
  4. Với mỗi depot nằm trong bản build ứng dụng, một danh sách file sẽ được tạo dựa trên các file có trong thư mục nội dung và quy tắc bộ lọc được định nghĩa trong file thiết lập build depot.
  5. Mỗi file được quét và chia nhỏ thành các mảnh có kích cỡ 1MB. Nếu depot từng được build qua, phân vùng này sẽ giữ lại nhiều nhất có thể các mảnh không có thay đổi nào.
  6. Các mảnh file mới sẽ được nén, mã hóa, rồi tải lên MDS.
  7. Một manifest sau cùng được tạo cho phiên bản depot này; mỗi manifest được xác định bằng một ID manifest 64-bit độc nhất.
  8. Khi toàn bộ depot đã được xử lý, MDS hoàn tất bản build ứng dụng và gán cho nó một BuildID chung.
  9. Sau khi thực hiện xong bản build, có thể có các file *.csm và *.csd trong thư mục đầu ra của bản build. Đấy là file tạm và có thể xóa, nhưng chúng tăng thời gian xây dựng các bản build tiếp theo.


Khi bản build hoàn tất, bạn có thể tìm thấy nó trong trang bản build của ứng dụng, trong trường hợp này sẽ là https://partner.steamgames.com/apps/builds/1000. Tại đó, bạn có thể phát hành bản build cho nhánh default hoặc bất kỳ nhánh beta nào và người dùng sẽ có thể tải về bản cập nhật trong vòng vài phút.

Mã build nâng cao


Nếu ứng dụng có rất nhiều depot với quy tắc gán file phức tạp, bạn có thể tạo mã build depot cho từng depot, được liên kết bởi mã build ứng dụng. Đầu tiên, hãy nhìn vào các tham số có trong mã build ứng dụng:

  • AppID - AppID của trò chơi của bạn. Tài khoản đối tác Steam dùng để tải nội dung cần quyền 'Sửa Metadata ứng dụng'
  • Desc - Mô tả chỉ bạn mới nhìn thấy trong mục 'Build của bạn' tại bảng Quản trị ứng dụng. Nội dung này có thể được thay đổi vào bất kỳ lúc nào sau khi tải bản build lên trang 'Build của bạn'.
  • ContentRoot - Thư mục gốc của file trò chơi, có thể là đường dẫn tuyệt đối hoặc tương đối so với file mã build.
  • BuildOutput - Thư mục này sẽ là nơi chứa nhật ký build, manifest của depot, mảnh cache, và thành phẩm trung gian. Để có hiệu suất tốt nhất, hãy dùng một ổ đĩa khác cho đầu ra bản build. Hành động này sẽ chia khối lượng công việc ghi và đọc của ổ đĩa, giúp ổ đĩa nội dung gốc xử lý các yêu cầu đọc, còn ổ đĩa đầu ra sẽ xử lý các yêu cầu ghi.
  • Preview - Kiểu build này chỉ tạo ra nhật ký và file manifest trong thư mục đầu ra bản build. Dựng các bản build preview là cách hay để thử đi thử lại các mã tải lên của bạn và đảm bảo rằng cách gán file, bộ lọc và đặc tính hoạt động như dự định.
  • Local - Đặt thành đường dẫn htdocs của bạn SteamPipe Local Content Server (LCS). Các bản build LCS đưa nội dung lên máy chủ HTTP của riêng bạn và cho phép bạn kiểm thử việc cài đặt trò chơi bằng phần mềm Steam.
  • SetLive - Tên nhánh beta để tự động phát hành sau khi tạo thành công bản build, không có nếu để trống. Lưu ý: nhánh 'default' không thể được đặt thành tự động phát hành. Phải vào trang Quản trị ứng dụng để thực hiện.
  • Depots - Mục này chứa toàn bộ cách gán file, bộ lọc và đặc tính file cho từng depot hoặc liên kết đến một file mã riêng cho từng depot

Ví dụ, mã tạo bản build ứng dụng "app_build_1000.vdf" dùng mọi tùy chọn:
"AppBuild" { "AppID" "1000" // AppID của bạn "Desc" "Mô tả của bản build tại đây" // mô tả nội bộ của bản build "Preview" "1" // đặt bản build này là 'preview', không có gì được tải lên "Local" "..\..\ContentServer\htdocs" // đưa nội dung lên một máy chủ nội dung trên máy thay vì tải lên Steam "SetLive" "AlphaTest" // phát hành bản build này trên một nhánh beta "ContentRoot" "..\content\" // địa chỉ thư mục gốc nội dung so với file mã này "BuildOutput" "D:\build_output\" // đặt cache bản build và file nhật ký trên một ổ đĩa khác để tăng hiệu suất "Depots" { // hướng dẫn gán file cho từng depot được đặt trong các file mã riêng biệt "1001" "depot_build_1001.vdf" "1002" "depot_build_1002.vdf" } }

Mã tạo bản build ứng dụng này liên kết tới hai file mã build depot chỉ định mọi cách gán file và đặc tính file. Các hướng dẫn sau có trong mã tạo bản build depot (và cũng có khi mục này được thêm trực tiếp vào mã tạo bản build ứng dụng).

  • DepotID - DepotID cho mục này
  • ContentRoot - Cho phép bạn chọn ghi đè thư mục ContentRoot từ mã tạo bản build ứng dụng, theo từng depot
  • FileMapping - Dùng để gán một file hay một bộ file từ thư mục gốc nội dung trên máy đến depot của bạn. Có thể có nhiều chỉ dẫn gán file để thêm nhiều file vào depot đó. Tham số LocalPath là một đường dẫn tương đối so với thư mục gốc nội dung và có thể chứa các ký tự đại diện như '?' hay '*'. Cũng sẽ áp dụng cho các file khớp quy tắc cú pháp trong thư mục con nếu Recursive được bật. Tham số DepotPath chỉ định nơi các file được chọn xuất hiện trong depot (chỉ cần dùng '.' nếu không có cách gán đặc biệt)
  • FileExclusion - sẽ loại ra các file được gán một lần nữa và cũng có thể chứa các ký tự đại diện như '?' hoặc '*'
  • InstallScript - sẽ đánh dấu một file là mã cài đặt và sẽ ký xác nhận file trong quá trình tạo bản build. Phần mềm Steam biết cách chạy chúng cho bất kỳ ứng dụng nào gắn depot này.
  • FileProperties - sẽ thêm các đánh dấu đặc biệt cho một file:
    • userconfig - File này được chỉnh sửa bởi người dùng hay trò chơi. Nó không thể bị ghi đè bởi một cập nhật, và sẽ không kích hoạt lỗi xác thực nếu nó khác với phiên bản trước của file.
    • versionedconfig - Tương tự như userconfig, tuy nhiên nếu file này được cập nhật trong depot, nó sẽ bị ghi đè trên máy của người dùng khi trò chơi cập nhật. Chỉ cập nhật file này trong depot khi việc thay đổi định dạng hay vá lỗi là cần thiết.

Ví dụ, mã tạo bản build depot depot_build_1002.vdf hiện trường hợp dùng toàn bộ các tùy chọn:
"DepotBuild" { "DepotID" "1002" "ContentRoot" "C:\content\depot1002" // ghi đè ContentRoot từ mã tạo bản build ứng dụng "FileMapping" { // tất cả mọi file và thư mục gốc trong ".\bin" sẽ được gán vào thư mục ".\executables" trong depot "LocalPath" "bin\*" "DepotPath" "executables\" "Recursive" "1" // bao gồm mọi thư mục con } "FileMapping" { // ghi đè file âm thanh trong \\âm thanh phiên bản tiếng Đức "LocalPath" "localization\german\audio\*" "DepotPath" "audio\" } "FileMapping" { // chép mã cài đặt cho phiên bản tiếng Đức vào thư mục depot gốc "LocalPath" "localization\german\german_installscript.vdf" "DepotPath" "." } "FileExclusion" "bin\server.exe" // loại trừ file này "FileExclusion" "*.pdb" // loại trừ toàn bộ file .PDB ở mọi nơi "FileExclusion" "bin\tools*" // loại trừ toàn bộ file nằm trong bin\tools\ "InstallScript" "localization\german\german_installscript.vdf" "FileProperties" { "LocalPath" "bin\setup.cfg" "Attributes" "userconfig" // file này sẽ được thay đổi trong thời điểm chạy } }

LƯU Ý: Bạn có thể tùy ý đặt tên cho các mã này, nhưng chúng tôi dùng app_build_<AppID>depot_build_<DepotID> để bảo đảm tính nhất quán. Nếu bạn biết mình sẽ tạo bản build ứng dụng trên máy tính này, có lẽ bạn nên tạo các thư mục con trong thư mục chứa mã cho từng ứng dụng, để giúp sắp xếp mã tạo bản build cho từng ứng dụng.

Sử dụng SteamPipe trong môi trường CI/CD


Để cài đặt SteamCMD cho việc tích hợp liên tục (CI), hoặc cài đặt trên máy tính hay máy ảo thường xuyên cài mới lại, bạn sẽ cần thêm vào file cấu hình có chứa token đăng nhập của mình. Làm theo các bước sau để giúp token đăng nhập ban đầu của bạn được lưu đúng cách:

  1. Chạy "steamcmd.exe +login <username>" trên máy sẽ thực thi bản build
  2. Nhập mật khẩu của bạn, và token SteamGuard
  3. Gõ "info", và bạn sẽ thấy tài khoản được liệt kê là "đã kết nối"
  4. Gõ "quit"
  5. Với mỗi lần chạy trong tương lai, đừng nhập mật khẩu. Chỉ cần chạy "steamcmd.exe +login <username>"
  6. Hãy chắc rằng file cấu hình lưu trong <Steam>\config\config.vdf được lưu và duy trì giữa các lần chạy, vì file này có thể được cập nhật sau khi đăng nhập thành công

LƯU Ý: Nếu bạn đăng nhập lại và cung cấp mật khẩu, một token SteamGuard mới sẽ được cấp và yêu cầu đăng nhập.

Quản lý cập nhật

Sau khi phát hành ứng dụng tới khách hàng, họ sẽ nhận build được đánh dấu làm build mặc định (Default). Khi tải lên bản build mới, bạn nên kiểm thử trước khi ra mắt tới khách hàng, để biết thêm thông tin về cách thực hiện thành công việc này, hãy xem Thử nghiệm trên Steam.

Gỡ lỗi các vấn đề với bản build

Nếu tạo bản build không thành công, bạn nên tìm xem thông tin về lỗi trong thư mục đầu ra, không phải trong bảng console dùng để chạy mã tạo bản build. Đa số thông tin về lỗi có thể được tìm thấy trong các file *.log.
Bạn có thể dùng các lệnh phần mềm Steam và file trên máy người dùng sau để gỡ lỗi:
  • "app_status [appid]" - Hiện trạng thái của ứng dụng trên máy người dùng này.
  • "app_info_print [appid]" - Hiện thiết lập Steamworks hiện tại cho trò chơi này (depot, tùy chọn khởi động, v.v.).
  • "app_config_print [appid]" - Hiện thiết lập của người dùng hiện tại cho trò chơi này (ngôn ngữ hiện tại, thư mục cài đặt, v.v.).
  • file "logs\content_log.txt" - Liệt kê toàn bộ hoạt động và lỗi của SteamPipe.
  • file "steamapps\appmanifest_[appid].acf" - Hiện trạng thái cài đặt hiện tại của ứng dụng này (KeyValues).

Tạo bản build cho đĩa cài đặt bán lẻ

Để tạo bản build cho đĩa cài đặt bán lẻ với trò chơi SteamPipe, trước tiên bạn phải cài đặt một file dự án tạo bản build.
Trong ví dụ này, file SKU được gọi là "sku_goldmaster.txt":
"sku" { "name" "Bộ cài trò chơi thử nghiệm" "appid" "202930" "disk_size_mb" "640" "included_depots" { "1" "202931" "2" "202932" } }
Một số mẹo hay nên ghi nhớ:
  • Tạo một thư mục mới làm nơi chứa các image của đĩa bán lẻ sau khi ghi, ví dụ "D:\retail_disks". Chỉ có depot trong mục included_depots mới được thêm vào; không còn mục loại trừ nữa.
  • Bạn có thể dùng Steam.exe (với tham số dòng lệnh -dev và -console) hoặc steamcmd.exe để dựng image cho bộ cài đặt. Trong cả hai trường hợp, hãy dùng lệnh "build_installer".
  • Đăng nhập bằng tài khoản Steam sở hữu trò chơi và toàn bộ depot bạn muốn đưa vào đĩa bán lẻ. Ngoài ra, tài khoản không cần có quyền hạn đặc biệt, nên ai cũng có thể tạo bản build cho đĩa cài đặt.
  • Nếu bạn dùng Steam.exe, hãy dừng mọi mục tải về khác.
  • Vào trang console rồi chạy lệnh build_installer:
    build_installer sku_goldmaster.txt "D:\retail_disks"
    Bản build có thể mất một lúc vì mọi depot sẽ được tải về lại cho lần đầu tiên.
  • Nếu bạn đang tạo bản build GM (Gold Master) bằng máy chủ nội dung trên máy, hãy chạy:
    @localcontentserver "webserver"
    build_installer sku_goldmaster.txt "D:\retail_disks" local
    Nội dung đầu ra nhắc đến bản 'sao lưu' vì 'đĩa cài đặt bán lẻ' và bản sao lưu trò chơi trên máy cơ bản là giống nhau.
  • Khi bạn thấy câu "Backup finished for AppID...", thì image đĩa cài đặt đã sẵn sàng. Bạn có thể tìm thêm thông tin về bản build sao lưu trong logs\backup_log.txt.
  • Có các thư mục mới (Disk_1, Disk_2, v.v.) trong "D:\retail_disks", mỗi thư mục không lớn hơn 640 MB, như đã được chỉ định với "disk_size_mb". Mỗi thư mục trong đĩa chứa một file "sku.sis" và .csd và .csm cho từng depot. Các depot lớn hơn có thể nằm ở nhiều đĩa. Mọi nội dung trong đĩa cài đặt bán lẻ luôn được mã hóa (khác với file sao lưu trò chơi trên máy). Chép các file cài đặt SDK GM (setup.exe, setup.ini, etc.) vào thư mục của đĩa đầu tiên và bộ cài đặt đĩa bán lẻ đã hoàn tất.
  • Khi tạo GM cho macOS, hãy chắc rằng bạn mở image đĩa goldmaster/disk_assets/SteamRetailInstaller.dmg trên một máy Mac. Rồi chép ứng dụng trong đó vào thư mục gốc của đĩa. Bạn có lẽ sẽ muốn đổi tên của ứng dụng cài đặt, thay đổi biểu tượng và trang trí cửa sổ sao cho chỉ hiện bộ cài đặt.
  • Khi tạo một GM gồm nhiều đĩa trên macOS, hãy chắc rằng tên của từng ổ đĩa khớp với nhau. Tên của ổ đĩa trở thành một phần của đường dẫn gắn, và nếu các tên không khớp nhau, bộ cài đặt sẽ không thể tìm đĩa kế tiếp.

Bạn cũng có thể chọn tạo bản build cho bộ cài đặt bán lẻ từ nhánh beta

Quá trình trên sẽ tạo bộ cài đặt bán lẻ dựa trên nhánh default. Nếu cần tạo bộ cài đặt dựa trên nhánh beta, bạn trước tiên phải tạo một nhánh beta được đặt tên là "baseline". Sau đó dùng câu lệnh sau để tạo bản build từ nhánh baseline:
build_installer <project file> <target folder> <beta key> <beta pwd> steamcmd ex: build_installer sku_goldmaster.txt "D:\retail_disks" baseline superSecret script ex: steamcmd.exe +login user_name password +build_installer "..\Build\GameDataSku.txt" c:\destination beta_key beta_password +exit

Cài DLC từ bộ cài đặt bán lẻ

Trong một số trường hợp, bạn có thể sẽ muốn tạo bộ cài đặt bán lẻ bao gồm các gói DLC. Khi đó, quá trình tạo bộ cài đặt chỉ cần có vài thay đổi.
Trong "sku_goldmaster.txt", thêm các AppID của DLC vào mục "included_depots". Khi bạn đã chạy quá trình "build_installer", hãy tìm file sku.sis được tạo cho bộ cài đặt và mở bằng một công cụ soạn thảo văn bản.
Thêm AppID của DLC vào mục "apps". Ví dụ, nếu có một trò chơi với AppID là 1000 và AppID của DLC là 1010, chỉ cần thay đổi mục "apps" như sau:
"apps" { "0" "1000" "1" "1010" }
Điều này đảm bảo Steam sẽ kiểm tra quyền sở hữu DLC và hỏi người dùng mã sản phẩm nếu tài khoản đang đăng nhập vào Steam không phải là chủ sở hữu DLC.

Tạo bản build bộ cài đặt bán lẻ cho nhiều App ID trên một đĩa/gói cài đặt duy nhất

Để tạo GM chứa nhiều ứng dụng SteamPipe. Tạo bộ cài đặt cho từng ứng dụng một, nhưng đều chỉ đến một thư mục đầu ra. Mỗi bản build sẽ tự hợp nhất với image đĩa cài đặt có sẵn.

Tùy chỉnh đĩa cài đặt bán lẻ

Xem Tùy chỉnh đĩa gold master để biết thêm về cách tùy chỉnh đĩa cài đặt bán lẻ.

Tải trò chơi trước khi phát hành

Mặc định, tất cả nội dung luôn được mã hóa trên mọi đĩa bán lẻ và máy chủ nội dung. Chuyển một trò chơi sang chế độ tải trước đồng nghĩa những người sở hữu trò chơi có thể tải về nội dung, nhưng trò chơi vẫn được mã khóa và không thể chơi. Khi trò chơi được phát hành chính thức, Steam sẽ giải mã nội dung tải trước và người dùng có thể trải nghiệm trò chơi.

Chúng tôi khuyến nghị chuyển trò chơi sang chế độ tải trước trong các trường hợp sau:
  • Phân phối đĩa bán lẻ với mã sản phẩm trước khi trò chơi có thể chơi được (bản lậu trong ngày phát hành).
  • Trò chơi cho phép đặt mua trước và có kích cỡ lớn hơn 20GB.

Hãy gửi một phiếu hỗ trợ tới Steam Publishing nếu bạn tin rằng trò chơi cần được tải trước.

Dựng DLC

DLC được tạo ra như một depot của trò chơi gốc. Xem tài liệu Nội dung tải thêm (DLC) để biết thêm chi tiết.

Xử lý sự cố SteamPipe

"Login Failure: Account Login Denied Failed" khi đăng nhập qua steamcmd

Nguyên nhân: Có thể Steam Guard đang chặn đăng nhập. Giải pháp:
  • Kiểm tra email liên kết với tài khoản bạn đang cố đăng nhập vào và tìm một email gửi bởi đội hỗ trợ Steam. Chép mã từ email đó.
  • Chạy steamcmd sau: set_steam_guard_code <code>
  • Thử đăng nhập lại từ steamcmd: Steam>login <buildaccount> <password>

Xử lý sự cố chung cho vấn đề tải xuống

  • Khởi động lại máy tính, modem, router, v.v.
  • Xác minh thiết lập tường lửa. Hệ thống mới yêu cầu port 80 (HTTP) và tất cả các port Steam khác, được liệt kê tại đây.
  • Tạm tắt các chương trình chống vi-rút hoặc chặn spam trên máy.
  • Kiểm tra khu vực tải xuống trên Steam tại Thiết lập->Tải xuống. Nó nên khớp với vị trí của bạn.
  • Dừng tiến trình tải xuống, gỡ cài đặt, và cài đặt lại trò chơi (dọn bộ nhớ cache file manifest).
  • Thoát Steam, xóa hai thư mục appcache và depotcache trong thư mục cài đặt Steam của bạn.
  • Thử đặt khu vực tải xuống trên Steam ra xa hơn. Sẽ hiệu quả nếu máy chủ nội dung gần bạn đang truyền dữ liệu kém.

Build Mac và/hoặc Linux của tôi không cài đặt file nào. Tại sao thế?

Nếu đang thử nghiệm cài đặt trò chơi hoặc ứng dụng trên đa nền tảng thông qua Steam, bạn có thể gặp phải tình huống build triển khai trên Windows nhưng không triển khai file nào trên Mac hay Linux, dù SteamPipe được thiết lập để tải lên depot Mac và/hoặc Linux. Có một bước dễ bị bỏ qua: thêm depot phụ vào gói đang được triển khai. Hãy kiểm tra xem depot nào bao gồm trong gói bằng những bước sau:
  1. Điều hướng đến trang Quản trị ứng dụng
  2. Từ mục Xem sản phẩm liên kết, nhấp Tất cả những gói, DLC, demo và công cụ có liên quan0>
  3. Nhấp vào tên gói bạn đang tìm cách tải về
  4. Xem lại mục Đã bao gồm depot
  5. Dùng Thêm/gỡ depot để đảm bảo đúng bộ depot được chỉ định cho gói
Một số chủ đề thảo luận hữu ích về vấn đề này:

Chạy steamcmd.exe gây ra lỗi sau: "SteamUpdater: Error: Steam needs to be online to update. Please confirm your network connection and try again".

Giải pháp: Đến Internet Options->Connections->Lan Settings và kiểm tra Automatically detect settings.

Chạy build ứng dụng gây ra lỗi sau: "ERROR! Failed 'DepotBuild for scriptname.vdf' - status = 6".

Nguyên nhân khả thi:
  • Tài khoản không có quyền hạn phù hợp cho ứng dụng.
    • Kiểm tra xem app ID có chính xác trong file app_build.vdf chưa.
    • Kiểm tra xem tài khoản build quyền hạn phù hợp đối với app ID.
  • Steamcmd không thể tìm thấy nội dung depot.
    • Kiểm tra xem giá trị "contentroot" trong mã app_build là đường dẫn hợp lệ so với vị trí file mã lập trình.
    • Kiểm tra xem giá trị "LocalPath" trong mã depot_build là đường dẫn hợp lệ so với đường dẫn trong mã app_build. Đảm bảo đường dẫn đó chứa nội dung thực.

Chạy build ứng dụng gây ra lỗi sau: "ERROR! Failed to get application info for app NNNNN (check login and subscription)"

Điều này có nghĩa Steam không thể lấy thông tin về ứng dụng, có thể vì ứng dụng không tồn tại hay người dùng không có quyền truy cập vào ứng dụng.
  • Kiểm tra xem NNNNN có phải là app ID mà bạn được gán cho ứng dụng không.
  • Kiểm tra xem app ID có chính xác trong file app_build.vdf chưa.
  • Nếu đó là một app ID mới, kiểm tra xem thiết lập quản trị ứng dụng Steamworks đã được đăng tải chưa. Ứng dụng mới nên có thư mục cài đặt SteamPipe cũng như depot, cả hai có thể được tìm thấy trong "Chỉnh sửa thiết lập Steamworks"; thư mục cài đặt nằm trong "Cài đặt tổng quan" của thẻ "Cài đặt", còn các depot nằm trong thẻ SteamPipe. Việc đăng tải thay đổi được thực hiện thông qua thẻ "Phát hành".
  • Nếu mọi thứ đều không có vấn đề, hãy chắc rằng tài khoản của bạn là chủ sở hữu app ID.

"An error occurred while installing [AppName] (Invalid content configuration)" khi khởi động

Nguyên nhân khả thi:
  • Không có bản build nào hiện phát hành trên nhánh mà bạn đang thử dùng để cài đặt.
    Giải pháp: Phát hành một bản build trên một nhánh bằng cách vào https://partner.steamgames.com/apps/builds/<YourGameAppId>, và chọn nhánh nằm trong phần mềm Steam (như mô tả ở đây).
  • Tùy chọn khởi động trò chơi không hợp lệ.
    Giải pháp: Kiểm tra các tùy chọn khởi động trên thẻ Cài đặt trong trang quản trị ứng dụng cho trò chơi của bạn tại https://partner.steamgames.com/apps/config/<YourGameAppId>.
  • Bạn không sở hữu Depot ID làm thành phần trong trò chơi.
    Giải pháp: Kiểm tra chắc chắn các depot cần thiết đã được thêm vào phần đăng ký dành cho phát triển (Xem Editing packages để biết thêm thông tin chi tiết).

Tôi không nhớ đó là lệnh steamcmd nào và nó hoạt động ra sao

Dùng lệnh 'find' trong steamcmd để tìm các lệnh của steamcmd. Nó sẽ so sánh từng phần của tên lệnh và liệt kê ra các cú pháp lệnh.
Steam>find build_installer ConVars: Commands: build_installer : <project file> <target folder> <beta key> <beta pwd>