《Steam 游戏平台:开发与商业化》5.2 好友与群组

好友与群组是覆盖层里社交关系的接口侧:GetFriendCount/GetFriendByIndex 枚举好友、GetFriendPersonaName/State 读资料、GetFriendsGroup* 管分组、GetClan* 读群组、Rich Presence 共享状态。本节讲好友接口的工程语义,lab 用 C++ 模拟好友枚举、分组与富状态。

5.2 好友与群组

覆盖层里最核心的社交数据是好友与群组。接入要回答的工程问题:好友列表怎么枚举、资料怎么读、分组与群组怎么区分、富状态(Rich Presence)怎么共享。

本卷所有接口口径以 Steamworks SDK v1.65(2026-07-23) 为准。本节摘录的签名对照该版本 public/steam/isteamfriends.h。

本章与站内既有内容的分工

  • Steam 发行专题 (操作手册)讲「后台社区设置」;本节讲「代码里读好友与群组的接口语义」。
  • 卷一讲好友关系如何构成社交留存;本节讲好友枚举、分组、富状态的工程语义。
  • lab 用纯 C++ 模拟好友数据与富状态,不依赖 Steam 客户端运行。

好友枚举与资料

// isteamfriends.h:GetFriendCount / GetFriendByIndex(SDK v1.65 头文件摘录,已删减)
virtual int GetFriendCount( int iFriendFlags ) = 0;
virtual CSteamID GetFriendByIndex( int iFriend, int iFriendFlags ) = 0;
// isteamfriends.h:GetFriendRelationship / GetFriendPersonaState / GetFriendPersonaName / GetFriendSteamLevel(SDK v1.65 头文件摘录,已删减)
virtual EFriendRelationship GetFriendRelationship( CSteamID steamIDFriend ) = 0;
virtual EPersonaState GetFriendPersonaState( CSteamID steamIDFriend ) = 0;
virtual const char *GetFriendPersonaName( CSteamID steamIDFriend ) = 0;
virtual int GetFriendSteamLevel( CSteamID steamIDFriend ) = 0;

工程语义:

  1. GetFriendCount(flags) 按 EFriendFlags 过滤:k_EFriendFlagImmediate=0x04 是「常规好友」、k_EFriendFlagBlocked=0x01 是拉黑名单、k_EFriendFlagAll=0xFFFF 是全部;GetFriendByIndex 必须用同一个 flags 枚举。
  2. 资料函数以 CSteamID 为参数:GetFriendPersonaName 保证非空;GetFriendPersonaState 只在好友在列表里时有意义。
  3. 关系判定:EFriendRelationship(None=0、Blocked=1、Friend=3…)区分陌生人、拉黑、好友;HasFriend 做快速归属判定。
// isteamfriends.h:EFriendFlags(SDK v1.65 头文件摘录,已删减)
enum EFriendFlags
{
	k_EFriendFlagNone			= 0x00,
	k_EFriendFlagBlocked		= 0x01,
	k_EFriendFlagImmediate		= 0x04,			// "regular" friend
	k_EFriendFlagAll			= 0xFFFF,
};

好友分组与群组

分组(Friends Group)与群组(Clan)是两套概念:

// isteamfriends.h:GetFriendsGroupCount / GetFriendsGroupIDByIndex / GetFriendsGroupName / GetFriendsGroupMembersCount / GetFriendsGroupMembersList(SDK v1.65 头文件摘录,已删减)
virtual int GetFriendsGroupCount() = 0;
virtual FriendsGroupID_t GetFriendsGroupIDByIndex( int iFG ) = 0;
virtual const char *GetFriendsGroupName( FriendsGroupID_t friendsGroupID ) = 0;
virtual int GetFriendsGroupMembersCount( FriendsGroupID_t friendsGroupID ) = 0;
virtual void GetFriendsGroupMembersList( FriendsGroupID_t friendsGroupID, CSteamID *pOutSteamIDMembers, int nMembersCount ) = 0;
// isteamfriends.h:GetClanCount / GetClanByIndex / GetClanName / GetClanTag(SDK v1.65 头文件摘录,已删减)
virtual int GetClanCount() = 0;
virtual CSteamID GetClanByIndex( int iClan ) = 0;
virtual const char *GetClanName( CSteamID steamIDClan ) = 0;
virtual const char *GetClanTag( CSteamID steamIDClan ) = 0;

工程语义:

  1. 好友分组是「用户自己整理的好友标签」:GetFriendsGroupCount 枚举分组,GetFriendsGroupIDByIndex 拿 ID,GetFriendsGroupMembersList 拿成员;无效分组 ID 返回 k_FriendsGroupID_Invalid。
  2. 群组(Clan)是「社区/公会」:GetClanCount/GetClanByIndex 枚举,GetClanName/GetClanTag 读名称与短标签。
  3. 两类用途不同:分组服务个人整理(同玩圈子),群组服务公开社区(运营活动、公告)。

富状态与状态变化

Rich Presence 让好友看到「我在玩什么、当前在干嘛」:

// isteamfriends.h:SetRichPresence / GetFriendRichPresence / RequestFriendRichPresence(SDK v1.65 头文件摘录,已删减)
virtual bool SetRichPresence( const char *pchKey, const char *pchValue ) = 0;
virtual const char *GetFriendRichPresence( CSteamID steamIDFriend, const char *pchKey ) = 0;
virtual void RequestFriendRichPresence( CSteamID steamIDFriend ) = 0;

工程语义:

  1. SetRichPresence 以键值方式设置:传 NULL 或空串即删除该键(头文件注释明文);connect 键承载「加入连接串」——好友点击即触发 join 流程(5.3)。
  2. 读好友富状态需先请求:RequestFriendRichPresence 发起后数据异步到达;请求前 GetFriendRichPresence 返回空串。
  3. 状态变化走 PersonaStateChange_t 回调:好友上线/改签名/改名时通知,游戏刷新列表。
// isteamfriends.h:PersonaStateChange_t(SDK v1.65 头文件摘录,已删减)
struct PersonaStateChange_t
{
	enum { k_iCallback = k_iSteamFriendsCallbacks + 4 };
	uint64		m_ulSteamID;			// steamID of the friends that changed
	int			m_nChangeFlags;			// what's changed
};

接口签名对照

头文件条目语义
isteamfriends.hGetFriendCount/GetFriendByIndex按 flags 枚举好友
isteamfriends.hGetFriendRelationship/GetFriendPersonaState/GetFriendPersonaName/GetFriendSteamLevel好友资料
isteamfriends.hHasFriend快速归属判定
isteamfriends.hGetFriendsGroup*好友分组
isteamfriends.hGetClanCount/GetClanByIndex/GetClanName/GetClanTag群组
isteamfriends.hSetRichPresence/GetFriendRichPresence/RequestFriendRichPresence富状态
isteamfriends.hPersonaStateChange_t状态变化回调

数据口径与来源

  • 接口签名、EFriendFlags/EFriendRelationship/EPersonaState 枚举值、PersonaStateChange_t 字段:SDK v1.65 public/steam/isteamfriends.h 可实证。
  • 「SetRichPresence 空串删除键」「GetFriendRichPresence 未设置返回空串」:头文件注释明文。
  • 具体好友数、群组数据:运行时数据,非头文件可实证;以 Steam 客户端实际为准。

以上接口口径撰写时对照 Steamworks SDK v1.65 头文件与 partner.steamgames.com 官方文档核对;登录后可见数据以官方当前为准。

可运行产物:C++ 最小验证

下面的仿真复现「好友与群组」的工程语义:按 EFriendFlags 过滤的好友枚举、关系/资料/等级读取、好友分组与群组两套结构、SetPlayedWith、富状态的请求-读取时序、PersonaStateChange_t 状态变化。它与 src/05-2-friends-groups.cpp 逐字节一致,mock 签名对照 SDK v1.65 头文件:

// file: src/05-2-friends-groups.cpp
// tier: L1
// verify: clang++ -std=c++20 -Wall -I. src/05-2-friends-groups.cpp -o bin/05-2-friends-groups && ./bin/05-2-friends-groups
//
// mock:复现好友与群组的工程语义——GetFriendCount/GetFriendByIndex、
// GetFriendRelationship/GetFriendPersonaState/GetFriendPersonaName/
// GetFriendSteamLevel、好友分组(GetFriendsGroup*)、群组
// (GetClanCount/GetClanName/GetClanTag)、HasFriend、SetPlayedWith、
// Rich Presence(SetRichPresence/GetFriendRichPresence/RequestFriendRichPresence)、
// PersonaStateChange_t。签名对照 SDK v1.65 isteamfriends.h,非 Valve 实现。
#include "verify.h"

#include <cstdint>
#include <map>
#include <string>
#include <vector>

namespace steam_repro {

// EFriendRelationship / EPersonaState / EFriendFlags 对照 isteamfriends.h
static constexpr int kRelationshipNone = 0;
static constexpr int kRelationshipBlocked = 1;
static constexpr int kRelationshipFriend = 3;
static constexpr int kPersonaStateOffline = 0;
static constexpr int kPersonaStateOnline = 1;
static constexpr int kPersonaStateLookingToPlay = 6;
static constexpr int kFlagBlocked = 0x01;
static constexpr int kFlagImmediate = 0x04;
static constexpr int kFlagAll = 0xFFFF;
static constexpr int kFriendsGroupIDInvalid = -1;
static constexpr int kPersonaChangeStatus = 0x0002;

struct MockFriendRec {
  uint64_t steamId = 0;
  std::string name;
  int state = kPersonaStateOffline;
  int level = 0;
  int relationship = kRelationshipNone;
};

struct MockFriendsGroup {
  int id = 0;
  std::string name;
  std::vector<uint64_t> members;
};

struct MockClan {
  uint64_t steamId = 0;
  std::string name;
  std::string tag;
};

// PersonaStateChange_t 结构字段对照 isteamfriends.h
struct MockPersonaChange {
  uint64_t steamId = 0;
  int changeFlags = 0;
};

class MockSteamFriends {
 public:
  MockSteamFriends() {
    friends_.push_back({76561197960287930ull, "Aya", kPersonaStateOnline, 42,
                        kRelationshipFriend});
    friends_.push_back({76561197960287931ull, "Bing", kPersonaStateLookingToPlay, 12,
                        kRelationshipFriend});
    friends_.push_back({76561197960287932ull, "Cici", kPersonaStateOffline, 7,
                        kRelationshipFriend});
    blocked_.push_back({76561197960287933ull, "Troll", kPersonaStateOffline, 0,
                        kRelationshipBlocked});
    groups_.push_back({1, "评测团", {friends_[0].steamId, friends_[1].steamId}});
    clans_.push_back({76561197960287940ull, "独立开发者同盟", "DEV"});
  }

  // isteamfriends.h:GetFriendCount:按 EFriendFlags 过滤(All 含全部)
  int getFriendCount(int iFriendFlags) const {
    if ((iFriendFlags & kFlagAll) == kFlagAll) {
      return static_cast<int>(friends_.size() + blocked_.size());
    }
    if (iFriendFlags & kFlagBlocked) return static_cast<int>(blocked_.size());
    if (iFriendFlags & kFlagImmediate) return static_cast<int>(friends_.size());
    return 0;
  }

  // isteamfriends.h:GetFriendByIndex
  uint64_t getFriendByIndex(int iFriend, int iFriendFlags) const {
    if ((iFriendFlags & kFlagBlocked) && ((iFriendFlags & kFlagAll) != kFlagAll)) {
      if (iFriend < 0 || static_cast<size_t>(iFriend) >= blocked_.size()) return 0;
      return blocked_[iFriend].steamId;
    }
    if (iFriend < 0 || static_cast<size_t>(iFriend) >= friends_.size()) return 0;
    return friends_[iFriend].steamId;
  }

  // isteamfriends.h:GetFriendRelationship
  int getFriendRelationship(uint64_t steamIDFriend) const {
    for (const MockFriendRec& f : friends_) {
      if (f.steamId == steamIDFriend) return f.relationship;
    }
    for (const MockFriendRec& b : blocked_) {
      if (b.steamId == steamIDFriend) return b.relationship;
    }
    return kRelationshipNone;
  }

  // isteamfriends.h:GetFriendPersonaState / GetFriendPersonaName / GetFriendSteamLevel
  int getFriendPersonaState(uint64_t steamIDFriend) const {
    for (const MockFriendRec& f : friends_) {
      if (f.steamId == steamIDFriend) return f.state;
    }
    return kPersonaStateOffline;
  }
  const char* getFriendPersonaName(uint64_t steamIDFriend) const {
    for (const MockFriendRec& f : friends_) {
      if (f.steamId == steamIDFriend) return f.name.c_str();
    }
    return "";
  }
  int getFriendSteamLevel(uint64_t steamIDFriend) const {
    for (const MockFriendRec& f : friends_) {
      if (f.steamId == steamIDFriend) return f.level;
    }
    return 0;
  }

  // isteamfriends.h:HasFriend:任选一组 EFriendFlags
  bool hasFriend(uint64_t steamIDFriend, int iFriendFlags) const {
    if (iFriendFlags & kFlagBlocked) {
      for (const MockFriendRec& b : blocked_) {
        if (b.steamId == steamIDFriend) return true;
      }
      return false;
    }
    if (iFriendFlags & kFlagImmediate) {
      for (const MockFriendRec& f : friends_) {
        if (f.steamId == steamIDFriend) return true;
      }
      return false;
    }
    return false;
  }

  // isteamfriends.h:好友分组
  int getFriendsGroupCount() const { return static_cast<int>(groups_.size()); }
  int getFriendsGroupIDByIndex(int iFG) const {
    if (iFG < 0 || static_cast<size_t>(iFG) >= groups_.size()) return kFriendsGroupIDInvalid;
    return groups_[iFG].id;
  }
  const char* getFriendsGroupName(int friendsGroupID) const {
    for (const MockFriendsGroup& g : groups_) {
      if (g.id == friendsGroupID) return g.name.c_str();
    }
    return nullptr;
  }
  int getFriendsGroupMembersCount(int friendsGroupID) const {
    for (const MockFriendsGroup& g : groups_) {
      if (g.id == friendsGroupID) return static_cast<int>(g.members.size());
    }
    return 0;
  }
  void getFriendsGroupMembersList(int friendsGroupID, uint64_t* pOutSteamIDMembers,
                                  int nMembersCount) const {
    for (const MockFriendsGroup& g : groups_) {
      if (g.id != friendsGroupID) continue;
      int n = std::min(nMembersCount, static_cast<int>(g.members.size()));
      for (int i = 0; i < n; ++i) pOutSteamIDMembers[i] = g.members[i];
      return;
    }
  }

  // isteamfriends.h:群组(Clan)
  int getClanCount() const { return static_cast<int>(clans_.size()); }
  uint64_t getClanByIndex(int iClan) const {
    if (iClan < 0 || static_cast<size_t>(iClan) >= clans_.size()) return 0;
    return clans_[iClan].steamId;
  }
  const char* getClanName(uint64_t steamIDClan) const {
    for (const MockClan& c : clans_) {
      if (c.steamId == steamIDClan) return c.name.c_str();
    }
    return "";
  }
  const char* getClanTag(uint64_t steamIDClan) const {
    for (const MockClan& c : clans_) {
      if (c.steamId == steamIDClan) return c.tag.c_str();
    }
    return "";
  }

  // isteamfriends.h:SetPlayedWith:标记一起玩过
  void setPlayedWith(uint64_t steamIDUserPlayedWith) {
    playedWith_.push_back(steamIDUserPlayedWith);
  }
  bool playedWith(uint64_t steamId) const {
    for (uint64_t s : playedWith_) {
      if (s == steamId) return true;
    }
    return false;
  }

  // isteamfriends.h:SetRichPresence:设置本地富状态并共享给好友
  bool setRichPresence(const char* pchKey, const char* pchValue) {
    localPresence_[pchKey] = pchValue;
    for (const MockFriendRec& f : friends_) {
      friendPresence_[f.steamId][pchKey] = pchValue;
    }
    return true;
  }

  // isteamfriends.h:RequestFriendRichPresence:好友状态需请求后异步到达
  void requestFriendRichPresence(uint64_t steamIDFriend) {
    presenceLoaded_[steamIDFriend] = true;
  }

  // isteamfriends.h:GetFriendRichPresence:未加载返回 ""
  const char* getFriendRichPresence(uint64_t steamIDFriend, const char* pchKey) const {
    auto loadIt = presenceLoaded_.find(steamIDFriend);
    if (loadIt == presenceLoaded_.end() || !loadIt->second) return "";
    auto friendIt = friendPresence_.find(steamIDFriend);
    if (friendIt == friendPresence_.end()) return "";
    auto keyIt = friendIt->second.find(pchKey);
    if (keyIt == friendIt->second.end()) return "";
    return keyIt->second.c_str();
  }

  // 模拟好友状态变化 → PersonaStateChange_t
  void changeFriendState(uint64_t steamId, int newState) {
    for (MockFriendRec& f : friends_) {
      if (f.steamId == steamId) {
        f.state = newState;
        personaChanges_.push_back(MockPersonaChange{steamId, kPersonaChangeStatus});
        return;
      }
    }
  }

  const std::vector<MockPersonaChange>& personaChanges() const { return personaChanges_; }

 private:
  std::vector<MockFriendRec> friends_;
  std::vector<MockFriendRec> blocked_;
  std::vector<MockFriendsGroup> groups_;
  std::vector<MockClan> clans_;
  std::vector<uint64_t> playedWith_;
  std::map<std::string, std::string> localPresence_;
  std::map<uint64_t, std::map<std::string, std::string>> friendPresence_;
  std::map<uint64_t, bool> presenceLoaded_;
  std::vector<MockPersonaChange> personaChanges_;
};

}  // namespace steam_repro

int main() {
  using namespace steam_repro;
  MockSteamFriends sf;

  const uint64_t aya = 76561197960287930ull;
  const uint64_t troll = 76561197960287933ull;
  const uint64_t unknown = 76561197960287999ull;

  // 1. 好友数量:Immediate 3 个
  CHECK(sf.getFriendCount(kFlagImmediate) == 3);

  // 2. GetFriendByIndex 返回对应 SteamID
  CHECK(sf.getFriendByIndex(0, kFlagImmediate) == aya);

  // 3. 昵称与状态
  CHECK(std::string(sf.getFriendPersonaName(aya)) == "Aya");
  CHECK(sf.getFriendPersonaState(aya) == kPersonaStateOnline);

  // 4. 好友等级
  CHECK(sf.getFriendSteamLevel(aya) == 42);

  // 5. 关系判定:好友 / 拉黑 / 陌生人
  CHECK(sf.getFriendRelationship(aya) == kRelationshipFriend);
  CHECK(sf.getFriendRelationship(troll) == kRelationshipBlocked);
  CHECK(sf.getFriendRelationship(unknown) == kRelationshipNone);

  // 6. HasFriend:按不同 flags 过滤
  CHECK(sf.hasFriend(aya, kFlagImmediate));
  CHECK(!sf.hasFriend(troll, kFlagImmediate));
  CHECK(sf.hasFriend(troll, kFlagBlocked));

  // 7. 好友分组
  CHECK(sf.getFriendsGroupCount() == 1);
  CHECK(sf.getFriendsGroupIDByIndex(0) == 1);
  CHECK(std::string(sf.getFriendsGroupName(1)) == "评测团");
  CHECK(sf.getFriendsGroupMembersCount(1) == 2);
  uint64_t members[4] = {0, 0, 0, 0};
  sf.getFriendsGroupMembersList(1, members, 4);
  CHECK(members[0] == aya);
  CHECK(members[1] == 76561197960287931ull);

  // 8. 越界分组 ID 返回 k_FriendsGroupID_Invalid
  CHECK(sf.getFriendsGroupIDByIndex(9) == kFriendsGroupIDInvalid);

  // 9. 群组(Clan)
  CHECK(sf.getClanCount() == 1);
  CHECK(sf.getClanByIndex(0) == 76561197960287940ull);
  CHECK(std::string(sf.getClanName(76561197960287940ull)) == "独立开发者同盟");
  CHECK(std::string(sf.getClanTag(76561197960287940ull)) == "DEV");

  // 10. SetPlayedWith 记录一起玩过
  sf.setPlayedWith(aya);
  CHECK(sf.playedWith(aya));

  // 11. 好友富状态:未请求时为空,请求后读到
  CHECK(std::string(sf.getFriendRichPresence(aya, "status")).empty());
  CHECK(sf.setRichPresence("status", "在玩 3-2"));
  sf.requestFriendRichPresence(aya);
  CHECK(std::string(sf.getFriendRichPresence(aya, "status")) == "在玩 3-2");

  // 12. 状态变化触发 PersonaStateChange_t
  CHECK(sf.personaChanges().empty());
  sf.changeFriendState(aya, kPersonaStateLookingToPlay);
  CHECK(sf.personaChanges().size() == 1);
  CHECK(sf.personaChanges()[0].steamId == aya);
  CHECK(sf.personaChanges()[0].changeFlags == kPersonaChangeStatus);

  // 13. Blocked 好友计数的 All 口径
  CHECK(sf.getFriendCount(kFlagAll) == 4);

  return lab::report("05-2 好友与群组");
}

本机实测(Apple clang 16,clang++ -std=c++20 -Wall):编译通过(零警告),断言 31/31 通过。

小结

  • 好友枚举:按 EFriendFlags 过滤,All 含全部。
  • 分组 vs 群组:个人标签 vs 公开社区。
  • 富状态:键值共享,connect 串驱动 join;请求前读不到。
  • 状态变化:PersonaStateChange_t 回调刷新列表。

阅读导航:上一节:5.1 覆盖层机制 · 下一节:5.3 覆盖层的产品意义 。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图