Steamworks 文献库
Steamworks API 示例应用程序(SpaceWar)

概览

为了帮助开发者了解 Steamworks API 的用法,我们在此提供了经典多人射击游戏 Spacewar! 全功能版的源代码。 这是一个简单的 2D 游戏,支持最多 4 位玩家,可以很好地展示 Steamworks SDK 中许多 API 的使用。

当您查看代码时,请记住,我们的目标是编写一个简单精炼的游戏,尽可能清楚地展示 Steamworks API 的用法。 您不会在这里看到任何壮观新颖的图形技术;相反,我们只是希望给您提供清晰的示例,说明如何将 Steamworks 功能深入地集成至您自己的项目。

在示例代码中展示的 API 及 Steamworks 功能包括:

  • 社区集成(头像、好友名称,等等)
  • 故障报告
  • 好友
  • HTML Surface
  • 库存
  • 排行榜
  • 比赛匹配(大厅和服务器浏览器)
  • 多人游戏验证(同时在游戏内支持 4 位玩家)
  • 联网
  • 统计与成就
  • 语音聊天

spacewar.png

生成并运行示例

要求:
  • Visual Studio 2005 或更新版本
  • DirectX SDK
  • Steamworks SDK (下载最新发行版本)

您下载并提取 Steamworks SDK 程序包后,找到其中命名为 SteamworksExample 的子目录。 在此子目录中,您会找到可用 Visual Studio 打开的 SteamworksExample.sln。 打开解决方案并对项目进行编译。 如果编译成功,则您已准备就绪,可以直接从 Visual Studio 运行此项目(您必须在后台运行 Steam)。 如果生成或执行失败,请尝试以下解决办法:

生成版本常见问题

  • 无法包含文件“d3d9.h”
    如果您遇到此错误,这说明您系统的包含路径中并未包含 D3D 包含路径,或您未安装 D3D SDK。 首先,请确保您已下载并安装了 DirectX SDK。 安装 SDK 后,您需要设置包含路径。 您可以通过 Visual Studio 的标准环境变量进行系统范围内的设置,或者是通过编辑项目属性,只针对 SteamworksExample 项目进行设置。
  • 致命错误 LNK1104:无法打开文件“d3d9.lib”
    如果您遇到此错误,这说明您系统的库路径未包含 D3D 库目录。 请参见上方说明,只是您需要更新库路径,而非包含路径。
  • 必须运行 Steam 才能玩此游戏(SteamAPI_Init 失败)。
    如果您运行游戏时遇到此错误,请确保已运行 Steam。 如果已运行 Steam,则确保存有游戏可执行文件的目录中有 steam_appid.txt 文件。 此文件与 SDK 示例一起发布,如果您从 Visual Studio 中或直接从 Debug 或 Release 子目录中运行游戏,此文件应该存在。

    您从游戏的可执行文件直接启动游戏时,此文件必须在 Steam UI 之外存在,且其中必须有一行是游戏的 AppID(Valve 会为您的每款游戏各分配一个 AppID,示例游戏的 AppID 是 480)。 您通过 Steam 发行自己的游戏时则不需要此文件,因为 Steam 会在启动游戏时自动检测您的 AppID。
  • 应用程序启动失败,因为未找到 steam_api.dll。 重新安装应用程序也许能修复这个问题。
    为了能成功运行,steam_api.dll 必须与示例游戏可执行文件位于同一目录中。 这对于您自己使用 Steamworks 的游戏同样如此。 Visual Studio 项目文件应在生成时将可执行文件置于正确目录中,但如果您使用的编译器不同,或者已经修改解决方案或项目文件,您也许需要自行复制文件。 您可以在推出自己的 Steamworks 游戏时重新分发 steam_api.dll
  • 应用程序启动失败,因为未找到 d3dx_??.dll。 重新安装应用程序也许能修复这个问题。
    示例依赖与 DirectX SDK 一起发布的 D3D9X 帮助程序库。 如果您运行示例使用的电脑即为您生成游戏所用的电脑,则应能自动找到库。 如果您将自己已编译的二进制文件复制到另一台电脑,则也许需要安装 D3D 可再发行文件,以便获取的 D3D9X 版本与您在开发电脑上编译时使用的相同。

代码概览

在编译并运行 Spacewar! 示例项目后,您可以开始查看代码。 如果您在 Visual Studio 解决方案资源管理器中浏览文件,您将看到代码已被分解为游戏(Game)和引擎(Engine)代码。 您可以忽略 Engine 文件夹中的代码——它通过 D3D 和基本的键盘输入支持基本 2D 渲染。 所有记录 Steamworks API 用途的重要代码都位于游戏(Game)文件夹中。

下文简要说明了查看代码时应该注意的重要方面:
  • Main.cpp:示例游戏的主要入口点。
    API 用法展示:
    • 客户端 API 初始化:您需要在应用启动过程中及早进行 API 初始化,然后可以在 Main.cpp 中的 RealMain() 函数里看到其完成方式。
    • API 错误/警告日志记录:在开发过程中,您也许希望从 Steam API 获取部分日志记录输出,以帮助调试问题。 您可以在 RealMain() 函数中查看设置调试日志记录的示例,其中调用了 ISteamClient::SetWarningMessageHook
    • 崩溃报告:您也许希望在自己的游戏中使用 Steam 的内置小型转储崩溃报告。 如果确实如此,您可以在 Main.cppWinMain()MiniDumpFunction() 里找到安装异常处理程序和设置小型转储写入的示例。
  • SpaceWarServer.cpp/h:示例游戏的服务器代码。
    API 用法展示:
    • Gameserver API 初始化:在游戏服务器中,您需要初始化没有已公开的个人用户界面的精简版 API。 此操作在 SpaceWarServer.cppCSpaceWarServer 构造函数中完成。
    • 运行 API 回调:在您的游戏中,您需要定期运行 Steam 回调,以处理 Steam 异步 API 调用的结果。 您可以在 CSpaceWarServer::RunFrame() 函数中找到通过 SteamGameServer_RunCallbacks 在游戏服务器中运行回调的示例,并能在 CSpaceWarServer 构造函数代码及头文件中找到处理个别回调并将其注册的示例。
    • 多人游戏验证(VAC 封禁处理):如果您的游戏为在线多人游戏,您需要在允许用户加入在线服务器前确认他们拥有游戏。 您可以在 SpaceWarServer.cpp 中找到出于这些目的而使用的回调处理程序以及对 ISteamGameServer API 进行的调用。 Steam 也许会因为用户并未拥有您的产品,或用户已受封禁或因作弊必须被踢出而向您发送拒绝和踢出响应,您也可以看到应该如何处理这些拒绝和踢出响应。
    • 网络 API:如果您正在创作一款在线游戏,您也许希望使用 Steam 内置的网络 API。 您可以通过在 SpaceWarServer.cpp 中使用 SteamGameServerNetworking() 访问器和回调的 ISteamNetworking API 调用,找到游戏服务器中服务器端用法的示例。
    • 比赛匹配和主机服务器通信:如果您正在创作一款多人游戏并希望使用 Steam 服务器浏览器,那么您的游戏服务器需要与 Steam 主机服务器进行通信。 您可以在 CSpaceWarServer 构造函数及 CSpaceWarServer::SendUpdatedServerDetailsToSteam() 方法中找到操作方法示例。
  • SpaceWarClient.cpp/h:示例游戏的客户端代码。
    API 用法展示:
    • 通过大厅进行比赛匹配:在您的在线游戏中,您也许希望除了服务器浏览器之外,还可以通过大厅进行比赛匹配,或只通过大厅进行比赛匹配。 您可以在 SpaceWarClient.cpp 中找到通过 ISteamMatchmaking 接口使用大厅代码和回调的示例。 您还应该查看 Lobby.cpp/h,其中包含了进入给定大厅后处理状态和回调的一些代码。
    • 好友和社区集成:Steam 允许您在自己的游戏内使用玩家的完整身份信息,包括玩家的昵称和个人头像。 您可以在 SpaceWarClient.cpp 中找到通过 ISteamFriends 接口将昵称和头像集成至计分板的示例。
    • 网络 API:您可以在 SpaceWarClient.cpp 中找到客户端使用 Steam 网络 API 的示例(请参见 SpaceWarServer.cpp 了解服务器端的实现)。
  • StatsAndAchievements.cpp/h:示例游戏的统计和成就处理。
    API 用法展示:
    • 统计与成就:您可以在 StatsAndAchievements.cpp 中找到统计与成就处理的实现方法。 此文件中包含 CStatsAndAchievements 类,用来自 CSpaceWarClient 的更新状态信息调用。 CStatsAndAchievements 收到来自游戏客户端的状态变更信息后,会通过 ISteamUserStats 接口通知 Steam 用户统计或成就的变更。
  • Lobby.cpp/h:通过大厅进行比赛匹配
    API 用法展示:
    • 通过大厅进行比赛匹配:您可以在 Lobby.cpp 中找到基于大厅实现比赛匹配的部分示例。 Lobby.cppSpaceWarClient.cpp 紧密配合处理比赛匹配,因此二者您都需要查看。 在查看大厅代码时,请特别注意对 ISteamMatchmaking 接口方法的回调和调用。
  • ServerBrowser.cpp/h:游戏内服务器浏览器
    API 用法展示:
    • 通过服务器浏览器进行比赛匹配:如果您支持通过服务器浏览器进行比赛匹配,那么您应该希望直接在游戏中提供服务器浏览器列表,对 Steam UI 提供的列表进行补充。 您可以在 ServerBrowser.cpp. 中找到为自己的游戏获取互联网服务器列表,并向用户显示的示例。
  • Inventory.cpp/h:Steam 库存服务
    API 用法展示:
    • Steam 库存:与可以访问 Steam 经济体Steam 库存 集成。 这样您可以轻松地将物品集成至自己的游戏。

如果您想继续使用您的游戏现有的验证和比赛匹配引擎,那么您需要将 USE_GS_AUTH_API 定义从 Spacewars.h 移除。 您移除此定义后,该示例将无法使用 Steam 验证或比赛匹配功能,但您仍旧可以访问其他 Steam 功能,如成就和好友信息。请查看代码了解详情。