SteamPipe 是 Valve 的工具，用于向 Steam 交付内容，以下是其使用指南。 若要了解更新您游戏的最佳实践的更多信息，请参见更新您的游戏——最佳实践
SteamPipe 是驱动 Steam 的游戏/应用程序内容系统。 SteamPipe 包括以下功能：
- Public and private "beta" branches, allowing multiple builds to be tested.
- 可以在开发过程中使用的 SteamPipe 本地内容服务器。
有数个概念和 SteamPipe 是不可分割的，在开始之前，您应当熟悉一下应用程序
文档中描述的所有概念。 就算只是大概了解各部分如何协调运作，也会对上传您的产品至 Steam 大有帮助。
Game Content Structure - Best Practices
SteamPipe was designed for both efficient downloading of initial game installs and efficient patching of updates. In general, it works well for a wide variety of game content structures. However, there are some important things to know in terms of optimization and avoiding situations that can cause inefficiency.
SteamPipe initially splits each file into roughly one megabyte (MB) chunks. Each chunk is then compressed and encrypted before being upload to the Steam content-delivery system. They remain compressed and encrypted until downloaded by each client, where they are decrypted and expanded and placed in the necessary file location(s).
When SteamPipe is processing an update for an existing game, it searches to find any such chunks that match the previous build of the game. This way, ideally only the new or modified portions of any file are turned into "new" chunks, and those new chunks are the only pieces a client must download to update their game.
Many game engines use "pack" files to coalesce game assets, and improve load times by allowing more efficient disk access. In general, this works well with SteamPipe. However, some pack file systems use or enable using behaviors that can cause problems. The effect of these problems is almost always that updates are much larger than necessary. They can also result in a quick download but a slow update process as large amounts of local disk IO are necessary.
If your game uses pack files, here are some general guidelines.
- Ensure asset changes are localized within the pack file as much as possible
- Avoid shuffling asset ordering with a pack file
- limit pack file size
- group assets by level / realm / feature into their own pack files, and consider adding new pack files for updates instead of modifying existing ones
- do not include any original filenames or file / build timestamps for each asset
The first point above refers to the scope of what bytes are changed within a file when a single asset is modified. If that asset's data is modified and/or grows or shrinks within the same location of the pack file, that is ideal. SteamPipe will only create new chunks for the portions of the file containing the asset data. However, all pack files need some sort of Table of Contents (TOC) as well so that the engine can locate the asset data. The structure of this TOC can have a large impact on the efficiency of SteamPipe patching. Ideally, there is one TOC or TOC tree near the beginning or end of the file. Because other assets may shift byte position within the file, their TOC entries will change as well. In this situation, SteamPipe will make new chunks for the modified asset data and the modified portions of the TOC.
However, what we have seen in some game engines is that the TOC information is distributed throughout the file. Even worse, it uses absolute byte-offset values. So if an asset at byte 3450 increases in size by 8 bytes, then the offset values for all assets after this in the file change. Even though each offset value is only 4 or 8 bytes in size, a change to an 8-byte number will result in a new 1MB chunk being created by SteamPipe. This can have catastrophic effects where even changing a few small assets in a pack file results in clients needing to download over half the entire file to update. If you know or suspect that your pack file structure is causing this issue, please contact your Valve representative as soon as possible. We have an alternate build algorithm that can help mitigate this issue, though it has tradeoffs.
Additionally, SteamPipe does not know about asset boundaries within a pack file. If sub-megabyte assets are shuffled, it will most likely not be able to detect this reordering as the previously determined 1-MB chunks will no longer be present within the file. So if, in the process of creating an update for your game, you wish to optimize load times by reordering assets within the pack file, be cognizant of the fact that it may result in a very large download for that update. We recommend only doing this if the performance improvements are significant.
Next - to update the pack file on a client device, SteamPipe builds the new version alongside the old version. When all new files are built, it then "commits" the update by deleting old files and moving the new files in. What this means is that to update a 25 GB pack file, SteamPipe will always build a new, 25GB file. If the update only requires 10 bytes of changes to that file, SteamPipe will need to copy almost the entire 25GB from the old file to the new file. Depending on the client storage hardware, this can be a very slow process. For this reason, we recommend two things.
First - limit the size of pack files. Probably one or two gigabytes (GB) is sufficiently large - more than enough to allow efficient disk reads when loading the game.
Second - keep the scope of assets within a single pack file fairly limited. Perhaps to a single game level, or unlockable feature. This way, updates that are focused on specific parts of your game don't cause the data from other parts to be copied around on the client machine. Additionally, when adding new functionality / levels / etc, these can and likely should be placed in their own new pack files. Clients downloading this update will have a simple download of new files, avoiding any of the issues mentioned above with pack file modifications.
When in doubt, you can use a local binary diff tool such as Beyond Compare to compare versions of your pack files. Verify that the differences shown are of the size you expect for the changed assets, and that there aren't perhaps dozens or hundreds of small changes spread out throughout the file. If what you see is unexpected, check your pack file tool settings. Compression
: Because Steam will compress all data for upload / storage / download, we generally don't recommend using general compression on pack files. However, if you are concerned about the on-disk size of your game, you may still want to use pack file compression. It will work OK with SteamPipe so long as the criteria listed above are met. Specifically, you should ensure that compression is per-asset as much as possible. Any compression that crosses asset boundaries will spread out changes and require clients to download more data than necessary.Encryption
: This is similar to compression - most likely unnecessary, and with the same risks mentioned above.
If you follow these rules you will minimize patch sizes and only new content will need to be downloaded. Your customers will thank you for that and you will be able to increase the quality of your product by shipping more updates.
If you suspect that your game packaging is not interacting well with the SteamPipe update process, please contact your Valve representative and we can look into enabling advanced features to help with this.
Steamworks Video Tutorial - Building Your Game in Steampipe
This tutorial introduces SteamPipe and steps through building a sample application for Steam via the Steamworks tools.https://www.youtube.com/watch?v=SoNH-v6aU9Q
Steamworks Video Tutorial - Adding New Platforms and Languages
This tutorial walks you through adding new platforms and languages to your game by adding depots to your app.https://www.youtube.com/watch?v=PShS32hcing
SteamPipe uses the HTTP protocol for content delivery. Since downloads are regular web traffic, any third-party HTTP cache between the customer and Steam servers will increase download speed. Content can be hosted by external CDN providers, which can be easily added to our content network. Most consumer firewalls allow HTTP traffic and won't block downloads.
SteamPipe has an efficient patching algorithm based on binary deltas, only changing the modified portions of existing content files. When this content is updated, only these deltas need be sent. This means both developer and user transfers are smaller and faster. Most partners will find that using a SteamPipe 本地内容服务器
not necessary since they can efficiently patch builds on private branches.
Steam Build Account
Before you can create any builds on Steam, you must have a Steam account in your Steamworks account with the "Edit App Metadata" and "Publish App Changes To Steam" permissions granted. For security reasons it's recommended that you have a dedicated build account with just those permissions, you may create a new Steam account for this purpose at https://store.steampowered.com/join
Any administrator of your Steamworks account can add a Steam account and grant the necessary permissions. More information on this process can be found in the 管理您的 Steamworks 帐户
documentation. An example of what this account might look like is:
Initial Setup for New SteamPipe Apps
Follow these steps to set up new SteamPipe apps:
- 找到您应用程序的 app ID（可以通过在您的 Steamworks 主页上选择该应用程序来找到）。
- 定义至少一个启动选项，即路径以及启动游戏所需的任意参数（可选）。 Hover over the (?) to learn more about each field.
The example below shows 5 launch options, 2 for Windows, 2 for macOS and 1 for Linux.
Launch option 3 will only be shown on Windows if the user also owns the DLC specified.
- 前往 Depot 页面，根据需要为此应用添加 depot。默认情况下，您的应用程序可能已经配置了一个 depot。
- 点击默认 depot，将其名称更改为合适且易于识别的名称（例如“基础内容”或“Windows 内容”）。
- 除非这是针对特定语言的 depot，否则保持语言设置为[所有语言]。
- 除非这是针对特定操作系统的 depot，否则保持操作系统设置为[所有操作系统]（如果应用适用于所有系统，或仅适用于 PC 或者 Mac，则保持设置为[所有操作系统]）。 仅指定针对特定操作系统的游戏 depot。
- 点击添加新 Depot 以创建更多 depot。
- 完成对 depot 的定义后，前往发布页面发布您所做的更改。
- 您新定义的 depot 需要纳入程序包中，才能授予您 depot 的所有权。 Steam 上的每款游戏都有一个 Developer Comp 程序包，会自动授予给您发行商组中列出的帐户。
您可以在关联程序包与 DLC 页面将新的 depot 添加至该程序包（和/或其他应有这些 depot 的程序包）。
Note: If your executable is in a sub-folder of the main installation folder, add the sub-folder name in the Executable field. 请勿使用前导斜杠或点。
Platform Note: As shown above, macOS applications may be launched by specifying either an app bundle (Game.app) or a script/binary (Game.app/Contents/MacOS/Game). In general the app bundle format should be preferred if possible as it allows macOS to more correctly determine launch parameters in the manner it would if launched manually outside of Steam.
One instance of this to note is that currently applications that are launched through an app bundle on Apple Silicon devices will launch the best architecture available in the application whereas direct binary launches will use the same architecture as the Steam process (currently x86_64).
Setting up the SDK for SteamPipe uploads
Download and unzip the latest version of the Steamworks SDK on the machine you will be uploading builds on.
The SteamPipe tools can be found within the SDK in the
folder which contains 2 relevant sub-directories.
directory is where your game content and SteamPipe build tools will live. This directory contains the following sub-directories:
- builder - This directory initially contains just steamcmd.exe which is the command line version of Steam.
- builder_linux - The linux version of steamcmd.
- builder_osx - The macOS version of steamcmd.
- content - This directory contains all game files that will be built into depots.
- output - This directory will be the location for build logs, chunk cache, and intermediate output. NOTE: This folder can be deleted or emptied at any time, but after it's deleted, the next upload time will take longer.
- scripts - This directory is where you'll place all of your build scripts for building your game depots.
It's recommended that you run steamcmd.exe directly in the builder folder for your platform once to bootstrap your build system. This should populate your builder directory with all the files it needs to build depots.
directory contains the tools for running your own SteamPipe 本地内容服务器
if you choose to do so.
macOS 上的 SteamCmd
To enable SteamCmd on macOS you must complete the following steps:
- From the terminal, browse to the tools\ContentBuilder\builder_osx
- 运行 chmod +x steamcmd。
- Type bash ./steamcmd.sh
- SteamCmd will then run and update to the latest build, leaving you in the SteamCmd prompt
- Type exit and press return to exit the prompt
You can then follow the rest of this documentation (substituting paths as appropriate) to create depot and app config files for uploading your content to Steam.
Creating SteamPipe Build Config Files
To upload files for your app with SteamPipe, you must create scripts which describe your build and each depot that will be included in it. The example scripts shown here are in the
folder in the Steamworks SDK.
SteamPipe GUI 工具
If you're running on Windows and would prefer a GUI tool to help create these config files and upload your builds you can use the SteamPipeGUI which is available in the tools folder of the Steamworks SDK. Included in the zip are additional instructions to get you started.
If you choose to use the GUI tool then reading the following sections is still recommended to help you become more familiar with how the SteamPipe system works.
Let's start with the most basic build script possible. In our example we have a game (AppID 1000) that has one depot (DepotID 1001) and want to upload all files from a content folder and it's subfolders. We just need a single build script for that, take a look at
included in the SDK :
"AppID" "1000" // 您的 AppID
"Desc" "This is a simple build script" // 此生成版本的内部描述
"ContentRoot" "..\content\" // 相对于此文件位置的根内容文件夹
"BuildOutput" "..\output\" // 生成版本日志和生成版本缓存文件的生成版本输出文件夹
"1001" // 您的 DepotID
"LocalPath" "*" // 来自内容根文件夹的所有文件
"DepotPath" "." // 映射到 depot 的根目录
"recursive" "1" // 包含所有子文件夹
Adjust the AppID and DepotID for your game as needed. To kick off a build you need to run steamcmd and pass a couple of parameters :
tools\ContentBuilder\builder\steamcmd.exe +login <account_name> <password> +run_app_build ..\scripts\simple_app_build.vdf +quit
Your first attempt at running a build may fail due to Steam Guard. If the login fails due to Steam Guard, check your email for the Steam Guard code, and run steamcmd as:
steamcmd.exe "set_steam_guard_code <code>"
, and try again. After logging in with Steam Guard once, a sentry file is used to verify the login is genuine.
If you are using steamcmd from a machine or VM that gets re-imaged frequently, you should include the config file in your image so you won't be prompted for a Steam Guard every time. The the config file is located in <Steam>\config\config.vdf.
The following steps occur during a SteamPipe build:
- Steamcmd.exe 会自我更新至最新版本。
- Steamcmd.exe 使用给定的用于创建生成版本的 Steam 帐户登录到 Steam 后端。
- 应用生成版本起始注册于 MDS（主 Depot 服务器），这将确保用户具有正确的权限来修改此应用。
- 对于应用生成版本中包含的每个 depot，会基于内容文件夹中的文件以及 depot 生成版本配置文件中定义的筛选规则，生成一个文件列表。
- 每个文件都经过扫描，并分割成约 1MB 的小型区块。 如果 depot 之前已经生成过，此分区将尽可能保留最多的区块不变。
- 对新的文件区块进行压缩、加密，然后上传到 MDS。
- 为此 depot 版本生成最终清单。每个清单由唯一的 64 位清单 ID 识别。
- 处理完所有 depot 后，MDS 会完成此应用生成版本的创建，并为其分配一个全局 BuildID。
- 生成版本完成后，生成版本输出文件夹中可能有 *.csm 和 *.csd 文件。 这些是临时文件，可以删除，但是它们可以缩短后续版本生成所用的时间。
Once the build is complete you can see it on your app builds page, in this case it would be https://partner.steamgames.com/apps/builds/1000
. There you can set that build live for the default branch or any beta branch and users will be able to download this update with a couple of minutes.
If your app has a lot of depots with complex file mapping rules, you can create a depot build script for each depot which will be referenced by the app build script. First let's take a look at available parameters in the app build script:
AppID - The AppID of your game. The uploading Steam partner account needs 'Edit App Metadata' privileges
Desc - The description is only visible to you in the 'Your Builds' section of the App Admin panel. This can be changed at any time after uploading a build on the 'Your Builds' page.
ContentRoot - The root folder of your game files, can be an absolute path or relative to the build script file.
BuildOutput - This directory will be the location for build logs, depot manifests, chunk caches, and intermediate output. For best performance, use a separate disk for your build output. This splits the disk IO workload, letting your content root disk handle the read requests and your output disk handle the write requests.
Preview - This type of build only outputs logs and a file manifest into the build output folder. Building preview builds is a good way to iterate on your upload scripts and make sure your file mappings, filters and properties work as intended.
Local - Set this to the htdocs path of your SteamPipe 本地内容服务器 (LCS). LCS builds put content only on your own HTTP server and allow you to test the installation of your game using the Steam client.
SetLive - Beta branch name to automatically set live after successful build, none if empty. Note that the 'default' branch can not be set live automatically. That must be done through the App Admin panel.
Depots - This section contains all file mappings, filters and file properties for each depot or references a separate script file for each depot
Example app build script
is using all options:
"AppID" "1000" // 您的 AppID
"Desc" "Your build description here" // 此生成版本的内部描述
"Preview" "1" // 只将此作为一个预览生成版本，未上传任何内容
"Local" "..\..\ContentServer\htdocs" // 将内容放入本地内容服务器，而不是上传至 Steam
"SetLive" "AlphaTest" // 将此生成版本设置为在测试版分支上线
"ContentRoot" "..\content\" // 相对于此脚本文件的内容根文件夹
"BuildOutput" "D:\build_output\" // 将生成版本缓存和日志文件放入另一个驱动器，以获得更佳性能
// 每个 depot 的文件映射说明位于单独的脚本文件中
This app build script references two depot build script files that specify all file mappings and file properties. The following instructions are available in a depot build script ( and also if the section is included directly into the app build script).
DepotID - The DepotID for this section
ContentRoot - Lets you optionally override the ContentRoot folder from the app build script on a per depot basis
FileMapping - This maps a single file or a set of files from the local content root into your depot. There can be multiple file mappings that add files to the depot. The
LocalPath parameter is a relative path to the content root folder and may contain wildcards like '?' or '*'. It will also apply to matching files in subfolders if
Recursive is enabled. The
DepotPath parameter specifies where the selected files should appear in the depot (use just '.' for no special mapping)
FileExclusion - will excluded mapped files again and can also contain wildcards like '?' or '*'
InstallScript - will mark a file as install scripts and will sign the file during the build process. The Steam client knows to run them for any application which mounts this depot.
FileProperties - will mark a file with special flags:
userconfig - This file is modified by the user or game. It cannot be overridden by an update, and it won't trigger a verification error if it's different from the previous version of the file.
versionedconfig - Similar to userconfig, however if the file is updated in the depot, it will be overwritten locally when the user's game updates. Only update the file in the depot when there is a necessary format change or bug fix.
Example depot build script
showing use of all options:
"ContentRoot" "C:\content\depot1002" // 从应用生成版本脚本覆盖 ContentRoot
// “.\bin”中的所有源文件和文件夹将会被映射至 depot 中的“.\executables”
"Recursive" "1" // 包含所有子文件夹
// 用德语版本覆盖 \\audio 中的音频文件
// 复制德语版本的安装脚本至 depot 根文件夹
"FileExclusion" "bin\server.exe" // 排除此文件
"FileExclusion" "*.pdb" // 在所有地方排除所有 .PDB 文件
"FileExclusion" "bin\tools*" // 排除 bin\tools\ 下的所有文件
"Attributes" "userconfig" // 此文件会在运行时中被修改
You can name these scripts what ever you want, but we use the names
for consistency. If you know that you'll be building apps on this machine, it might be a good idea to create sub-directories in your scripts directory for each application, to help organize each application's build scripts.
After your app releases to customers, your customers will be receiving the build marked as the Default build. When uploading a new build it's always a good idea to test it before shipping it to your customers, for more information on how to successfully do this see 在 Steam 上进行测试
Debugging Build Issues
If your build wasn't successful, you should look in your output directory for error information, not the console where the build script was run. Most error information can be found in the *.log files.
You can use these Steam client commands and client-side files to debug issues:
"app_status [appid]" - Shows the current state of the app on this client.
"app_info_print [appid]" - Shows the current Steamworks configuration for this game (depots, launch options, etc.).
"app_config_print [appid]" - Shows the current user configuration for this game (current language, install directory, etc.).
file "logs\content_log.txt" - Lists all logged SteamPipe operations and errors.
file "steamapps\appmanifest_[appid].acf" - Shows the current install state of this app (KeyValues).
To build retail install disc for SteamPipe games, you must first setup a build project file.
In this example, the SKU file is called "sku_goldmaster.txt":
"name" "Test Game Installer"
Some tips to keep in mind:
The process above will create a retail installer based on the default branch. If you need to create an installer based on a beta branch, you must first create a beta branch named "baseline". Then use the following command to build from the baseline branch:
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
In some circumstances, you may wish to create a retail installer that includes your DLC packages. In such cases, the process to create the installer requires only a few changes.
In "sku_goldmaster.txt", include the DLC AppIDs under the "included_depots" section. Once you have run the "build_installer" process, find the generated sku.sis file for the installer and open it with a text editor.
Add the DLC AppID in the "apps" section. For example, if I had a game with AppID 1000 and DLC AppID 1010, I would adjust the "apps" section as follows:
This will ensure that Steam checks for ownership of the DLC and prompt the user for a key if the DLC is not owned by the account that they are logging into on Steam.
在单张光盘/单个安装程序包上为多个 App ID 创建零售安装程序
To build a GM containing multiple Steam Pipe apps. Build each app installer one by one but point them all to the same output folder. Each build will merge itself with the already existing install image.
See Customizing a gold master
for more details on customizing your retail install disk.
By default, all content is always encrypted, on all retail discs and on all content servers. Switching a game to preload mode means owners can download the content, but it stays encrypted on the users' disk and can't be played. Once the game becomes officially released, Steam will decrypt the preloaded content and the user can play the game.
Switching a game to preload mode is recommended in these cases:
- Shipping retail discs with product keys before the game is actually available (0-day piracy).
- Games that run a pre-purchase and are larger than 20GBs in size.
Please submit a ticket to Steam Publishing if you believe your game requires preloading.
DLC is built as a depot of the base game. See the 可下载内容（DLC）
documentation for more information.
通过 steamcmd 登录时显示“Login Failure: Account Logon Denied Failed”
Cause: Probably SteamGuard is preventing login. Resolution:
- Check the email associated with the account you are trying to log on with and look for an email from Steam Support. Copy the code from that email.
- Run the following steamcmd:
- Re-Attempt login from steamcmd:
Steam>login <buildaccount> <password>
- Restart computer, modem, router, etc.
- Verify firewall settings. The new system requires port 80 (HTTP) and all other Steam ports, listed here.
- Temporarily disable local Anti-Virus or Spam-Blocker programs.
- Check the Steam download region under Settings->Downloads. It should match your location.
- Stop the download, uninstall, and reinstall the game (clear manifest caches).
- Exit Steam, delete the two folders appcache and depotcache in your Steam install folder.
- Try to set your Steam download region to some other location far away. This might work if a content server near you is serving bad data.
我的 Mac 和/或 Linux 生成版本未安装任何文件。 为什么？
If you're testing via Steam the installation of your game or application across multiple platforms, you may run into a situation where the build deploys on Windows but doesn't deploy any files on Mac or Linux despite your SteamPipe process being setup to upload Mac and/or Linux depots. There is a step that is easily missed which involves adding your alternate Depots to the Package being deployed. You can check what depots are included in a package via the following steps:
- 在“查看关联项目”栏目，点击“所有关联程序包、DLC、试用版及工具 ”。
- 查看已包含 Depot栏目。
- 使用添加/移除 Depot以确保分配到该程序包的 Depot 集正确。
There are a number of discussion threads about this that may also assist:
steamcmd.exe 运行时，出现以下错误：“SteamUpdater: Error: Steam needs to be online to update。 Please confirm your network connection and try again.”（Steam 需要在线进行更新。请确认您的网络连接正常，然后重试。）
Resolution: Go to Internet Options
and check Automatically detect settings
运行应用生成版本会导致以下错误：“ERROR! Failed 'DepotBuild for scriptname.vdf' - status = 6.”（错误！DepotBuild for scriptname.vdf 失败。- 状态 = 6。）
- Account does not have permissions for the app.
- Check that the app ID is correct in the app_build.vdf.
- Check that the build account has proper permissions to the app ID.
- Steamcmd cannot find the depot contents.
- Check that the "contentroot" value in the app_build script is a valid path relative to the location of the script file.
- Check that the "LocalPath" value in the depot_build script is a valid path relative to the path in the app_build script. Check that the path contains actual content.
运行应用生成版本会导致以下错误：“ERROR! Failed to get application info for app NNNNN (check login and subscription)”（错误！获取应用 NNNNN 的应用程序信息（检查登录和订阅）失败）
This means that Steam can't retrieve information about the app, either because it doesn't exist or the user doesn't have access to the app.
- Check that the NNNNN is the app ID you were assigned for the app.
- Check that the app ID is correct in the app_build.vdf.
- If it is a new app ID, check that the Steamworks app admin configuration has been published. New apps should have a Steam Pipe install directory on the config tab, a depot on the depot tab, and all changes published on the publish tab.
- If all of that looks right, make sure that your account owns the app ID.
在启动时出现：“An error occurred while installing [AppName] (Invalid content configuration)”（安装 [AppName] 时发生错误（无效的内容配置））
启动时显示“Error code 15”（错误代码 15）
This is the CEG servers rejecting the request to CEG the exe. Check the release state on the game page. If it is not 'playable', you will need to request Steam keys that override the release state.
“The Steam Servers are too busy to handle your request... Error Code (2)”（Steam 服务器过于繁忙，无法处理您的请求…错误代码（2））于启动时显示
This is the CEG servers failing to find a matching CEG exe. Double check that you have a working CEG executable on the CEG tab of your app admin. Click the 'status' button to make sure that it's propped.
我不记得 steamcmd 命令是什么或它是如何运作的
Use the 'find' command in steamcmd to search for any steamcmd command. It will do partial matching on the command name and it will list out the command syntax.
build_installer : <project file> <target folder> <beta key> <beta pwd>