Questions about brainCloud Friends and Social Leaderboard behavior

gyutaelee

Context

Hello brainCloud team,

We are designing a follow/friend system for our game and would like to confirm a few details before implementation.

Our intended model is:

We maintain our own FOLLOW Custom Entity as the source of truth.
A game “friend” is defined only when two users follow each other mutually.
When mutual follow is established, we plan to call FriendService.AddFriends([targetProfileId]).
When either side unfollows, we plan to call FriendService.RemoveFriends([targetProfileId]).
We may later use brainCloud Friends as an optimized source for social leaderboards.

Questions

1. Friend Relationship Direction

Are AddFriends and RemoveFriends bidirectional for internal brainCloud friends?

If user A calls AddFriends([B]), will B also see A in ListFriends("brainCloud")?
Will both A and B see each other in GetSocialLeaderboard results if they both have leaderboard scores?
If A calls RemoveFriends([B]), is the friend relationship removed from both users?

2. Idempotency

Are AddFriends and RemoveFriends idempotent?

What happens if AddFriends([B]) is called when A and B are already friends?
What happens if RemoveFriends([B]) is called when they are not friends?

3. Consistency and Caching

Are friend changes immediately visible?

After AddFriends or RemoveFriends, should ListFriends("brainCloud") and GetSocialLeaderboard reflect the change immediately?
Or is there any eventual consistency or caching delay we should expect?

4. Friend Count Limits

Is there a hard or recommended limit for the number of brainCloud friends per user?

We could not find a documented hard cap.
Are there practical performance limits we should design around?

5. `GetSocialLeaderboard` Behavior With Many Friends

How does GetSocialLeaderboard behave when a user has many friends?

Does it return all recognized friends plus self, with no paging or limit?
Is there any hidden maximum result count or payload limit?
Are pacers included in this result as well?

6. Recommended API for Top-N Friend Leaderboards

What is the recommended API for a top-N friends leaderboard?

Can we use GetMultiSocialLeaderboard([leaderboardId], leaderboardResultCount, replaceName) with a single leaderboard ID?
Is leaderboardResultCount applied after social filtering and score sorting?
Is there a maximum allowed value for leaderboardResultCount?
Is this API preferred over GetSocialLeaderboard when we only need the top 50 friends?

7. Social Leaderboard Pagination

Is regular pagination supported for social leaderboards?

We found GetGlobalLeaderboardPage for global leaderboards, but did not find an equivalent offset/page API for social leaderboards.
Is there any supported way to retrieve friend leaderboard entries 51-100, 101-150, etc., without requesting all prior entries?

8. Billing and API Counts

Is GetSocialLeaderboard counted as one API call regardless of the number of friends returned?

Are there additional billing or performance considerations based on response size or number of leaderboard entries returned?

9. Recommended Usage

Are brainCloud Friends suitable as an app-specific “mutual follow friend cache”?

We will not use brainCloud Friends for unrelated gameplay relationships.
We plan to keep FOLLOW as our source of truth and use brainCloud Friends only as a derived mirror/cache for mutual follow relationships.
Does this align with recommended brainCloud usage?

Thank you.

JasonL

Hi @gyutaelee ,

Thanks for the detailed questions.

1. Friend Relationship Direction - Yes, bidirectional

AddFriends: When user A calls AddFriends([B]), both A and B see each other in ListFriends("brainCloud")
Both A and B will appear in each other's GetSocialLeaderboard results (if they have scores)
RemoveFriends: Removes the relationship from both users atomically

2. Idempotency - Yes, both are idempotent

Calling AddFriends([B]) when already friends: No-op, no error thrown (skips DB write)
Calling RemoveFriends([B]) when not friends: No-op, no error thrown

3. Consistency and Caching - Immediate

Friend changes are persisted immediately to the database (no write-behind caching)
ListFriends("brainCloud") and GetSocialLeaderboard reflect changes immediately after AddFriends/RemoveFriends
No eventual consistency or caching delay

4. Friend Count Limits - No hard cap

No code-enforced limit on brainCloud friends per user
Practical consideration: Friend IDs stored as array on UserProfile; very large arrays (>10K) may impact read/write performance

5. `GetSocialLeaderboard` Behavior - Returns all friends + self + pacers, no limit

Returns all recognized friends + self + pacers
No hidden maximum result count
Pacers are included (if leaderboard has pacers configured)
Warning: Response payload grows linearly with friend count

6. Recommended API for Top-N - Yes, use `GetMultiSocialLeaderboard`

GetMultiSocialLeaderboard with a single leaderboard ID is a correct approach for top-N results
leaderboardResultCount is applied after social filtering and score sorting
leaderboardResultCount is capped by maxMultipleLeaderboardScoreLimit app property (default 10, can be raised in app-basis)
Preferred over GetSocialLeaderboard for top-N because it has built-in truncation

7. Social Leaderboard Pagination - Not supported

No GetSocialLeaderboardPage API exists (only GetGlobalLeaderboardPage for global leaderboards)
Social leaderboards always return the full friend set (potentially truncated by leaderboardResultCount only in the multi variant)
I will forward your pagination request for team review

8. Billing and API Counts - 1 API call per request

GetSocialLeaderboard = 1 API call regardless of friends/entries returned
GetMultiSocialLeaderboard = 1 API call even with multiple leaderboards
AddFriends/RemoveFriends = 1 API call even though they modify both users' profiles