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;
工程语义:
GetFriendCount(flags)按EFriendFlags过滤:k_EFriendFlagImmediate=0x04是「常规好友」、k_EFriendFlagBlocked=0x01是拉黑名单、k_EFriendFlagAll=0xFFFF是全部;GetFriendByIndex必须用同一个 flags 枚举。- 资料函数以 CSteamID 为参数:
GetFriendPersonaName保证非空;GetFriendPersonaState只在好友在列表里时有意义。 - 关系判定:
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;
工程语义:
- 好友分组是「用户自己整理的好友标签」:
GetFriendsGroupCount枚举分组,GetFriendsGroupIDByIndex拿 ID,GetFriendsGroupMembersList拿成员;无效分组 ID 返回k_FriendsGroupID_Invalid。 - 群组(Clan)是「社区/公会」:
GetClanCount/GetClanByIndex枚举,GetClanName/GetClanTag读名称与短标签。 - 两类用途不同:分组服务个人整理(同玩圈子),群组服务公开社区(运营活动、公告)。
富状态与状态变化
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;
工程语义:
SetRichPresence以键值方式设置:传 NULL 或空串即删除该键(头文件注释明文);connect键承载「加入连接串」——好友点击即触发 join 流程(5.3)。- 读好友富状态需先请求:
RequestFriendRichPresence发起后数据异步到达;请求前GetFriendRichPresence返回空串。 - 状态变化走
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.h | GetFriendCount/GetFriendByIndex | 按 flags 枚举好友 |
isteamfriends.h | GetFriendRelationship/GetFriendPersonaState/GetFriendPersonaName/GetFriendSteamLevel | 好友资料 |
isteamfriends.h | HasFriend | 快速归属判定 |
isteamfriends.h | GetFriendsGroup* | 好友分组 |
isteamfriends.h | GetClanCount/GetClanByIndex/GetClanName/GetClanTag | 群组 |
isteamfriends.h | SetRichPresence/GetFriendRichPresence/RequestFriendRichPresence | 富状态 |
isteamfriends.h | PersonaStateChange_t | 状态变化回调 |
数据口径与来源
- 接口签名、
EFriendFlags/EFriendRelationship/EPersonaState枚举值、PersonaStateChange_t字段:SDK v1.65public/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 覆盖层的产品意义 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。