Groups¶
The Groups service allows players to play together in-game.
The purpose of this service is to allow players to play together in-game.
Players can create groups and interact in real-time. Interactions include donating currency between group members for spending on in-game items. Depending on the game design, group members may have shared goals where interaction and collaboration are a key part of success. Here are some common use cases for the Groups service:
• Collaboration - Group members may share resources to progress on common goals (such as quests) • Competition - All groups in the game community compete directly and indirectly for rewards • Communication - Groups functionality integrates with text chat. See Chat for more info
Here is the glossary of group-related terms.
| Name | Detail |
|---|---|
| Group | A collection of game players (e.g., a guild) |
| Group Member | A game player within the group |
| Group Member Role | Players within a group may have distinct roles to dictate gameplay limits and responsibilities |
Groups API¶
Unlike many Beamable services, Groups do not require a specific Beamable Feature Prefab to be used. The main entry point to this service is C# programming.
Learning Fundamentals
Before using this service, it is recommended to understand Beamable's fundamental concepts.
• See Beamable: Asynchronous Programming for more info
The main API highlights include GroupsService.
| Method Name | Detail |
|---|---|
| Subscribe | Callback to observe changes |
| CreateGroup | Create a new group |
| GetCurrent | Get list of all current groups |
| JoinGroup | Join a group |
| LeaveGroup | Leave the current group |
| MakeDonationRequest | Request a currency donation from group |
| Donate | Send a currency donation to group member |
| SetGroupProps | Sets the GroupUpdateProperties including...• Name - Group name• Slogan - External-facing group slogan• Motd - Internal-facing message for members• Tag - Optional 3 letter shorthand for group• EnrollmentType - restricted / open / closed- Restricted - By invitation or application only - Closed - By invitation only - Open - Anybody can join |
Creating groups¶
NOTE: The group tag must be 3 characters or less. Group tags that longer than this will throw an InvalidTag exception.
var groupCreateRequest= new GroupCreateRequest ("MyGroupName", "tag", "open", 0, 50);
await _beamContext.Api.GroupsService.CreateGroup (groupCreateRequest);
Requesting group donation¶
_beamContext.Api.GroupsService.MakeDonationRequest (groupId, currency);
Make group donation¶
_beamContext.Api.GroupsService.Donate (groupId, memberId, 10);
Sample code¶
In this example, the player can create a group and interact.
GroupsServiceExample.cs
using System.Collections.Generic;
using System.Threading.Tasks;
using Beamable.Common.Api;
using Beamable.Common.Api.Groups;
using UnityEngine;
using Beamable.Experimental.Api.Chat;
using UnityEngine.Events;
namespace Beamable.Examples.Services.GroupsService
{
/// <summary>
/// Holds data for use in the <see cref="GroupsServiceExampleUI"/>.
/// </summary>
[System.Serializable]
public class GroupsServiceExampleData
{
public List<string> GroupNames = new List<string>();
public List<string> GroupPlayerNames = new List<string>();
public List<string> RoomNames = new List<string>();
public List<string> RoomPlayerNames = new List<string>();
public List<string> RoomMessages = new List<string>();
public string GroupToCreateName = "";
public bool IsInGroup = false;
public bool IsInRoom = false;
public string MessageToSend = "";
}
[System.Serializable]
public class RefreshedUnityEvent : UnityEvent<GroupsServiceExampleData> { }
/// <summary>
/// Demonstrates <see cref="GroupsService"/>.
/// </summary>
public class GroupsServiceExample : MonoBehaviour
{
// Events ---------------------------------------
[HideInInspector]
public RefreshedUnityEvent OnRefreshed = new RefreshedUnityEvent();
// Fields ---------------------------------------
private ChatView _chatView = null;
private GroupsView _groupsView = null;
private BeamContext _beamContext;
private ChatService _chatService;
private GroupsServiceExampleData _data = new GroupsServiceExampleData();
// Unity Methods --------------------------------
private async void Start()
{
Debug.Log("Start()");
await SetupBeamable();
}
// Methods --------------------------------------
private async Task SetupBeamable()
{
_beamContext = await BeamContext.Default.Instance;
_chatService = _beamContext.ServiceProvider.GetService<ChatService>();
Debug.Log($"beamContext.UserId = {_beamContext.UserId}");
// Observe GroupsService Changes
_beamContext.Api.GroupsService.Subscribe(async groupsView =>
{
_groupsView = groupsView;
_data.IsInGroup = _groupsView.Groups.Count > 0;
Debug.Log("GroupsService.Subscribe 1: " + _groupsView.Groups.Count);
_data.GroupNames.Clear();
_data.GroupPlayerNames.Clear();
foreach(var groupView in groupsView.Groups)
{
string groupName = $"Name = {groupView.Group.name}, Players = {groupView.Group.members.Count}";
_data.GroupNames.Add(groupName);
foreach (var member in groupView.Group.members)
{
string groupPlayerName = $"Name = {member.gamerTag}";
_data.GroupPlayerNames.Add(groupPlayerName);
}
// Create a new chat room for the group
string roomName = $"Room For {groupView.Group.name}";
await _chatService.CreateRoom(roomName, false,
new List<long> {_beamContext.PlayerId});
}
Refresh();
});
// Observe ChatService Changes
_chatService.Subscribe(chatView =>
{
_chatView = chatView;
int roomsWithPlayers = 0;
_data.RoomNames.Clear();
_data.RoomPlayerNames.Clear();
foreach(RoomHandle room in chatView.roomHandles)
{
// Optional: Only setup non-empty rooms
if (room.Players.Count > 0)
{
roomsWithPlayers++;
string roomName = $"Name = {room.Name}, Players = {room.Players.Count}";
_data.RoomNames.Add(roomName);
foreach (var roomPlayerDbid in room.Players)
{
string roomPlayerName = $"Player = {roomPlayerDbid}";
_data.RoomPlayerNames.Add(roomPlayerName);
}
room.Subscribe().Then(_ =>
{
_data.RoomMessages.Clear();
foreach (var message in room.Messages)
{
string roomMessage = $"{message.gamerTag}: {message.content}";
_data.RoomMessages.Add(roomMessage);
}
room.OnMessageReceived += RoomHandle_OnMessageReceived;
Refresh();
});
}
}
_data.IsInRoom = roomsWithPlayers > 0;
Debug.Log("ChatService.Subscribe 1: " + roomsWithPlayers);
Refresh();
});
}
public async Task<EmptyResponse> SendGroupMessage()
{
foreach(RoomHandle room in _chatView.roomHandles)
{
await room.SendMessage(_data.MessageToSend);
}
return new EmptyResponse();
}
public async Task<EmptyResponse> CreateGroup ()
{
// Leave any existing group
await LeaveGroups();
string groupName = _data.GroupToCreateName;
string groupTag = "t01";
string enrollmentType = "open";
// Search existing group
var groupSearchResponse = await _beamContext.Api.GroupsService.Search(groupName,
new List<string> {enrollmentType});
// Join or Create new group
if (groupSearchResponse.groups.Count > 0)
{
foreach (var group in groupSearchResponse.groups)
{
var groupMembershipResponse = await _beamContext.Api.GroupsService.JoinGroup(group.id);
}
}
else
{
var groupCreateRequest = new GroupCreateRequest(groupName, groupTag, enrollmentType, 0, 50);
await _beamContext.Api.GroupsService.CreateGroup(groupCreateRequest);
}
// HACK: Force refresh here (0.10.1)
// Wait (arbitrary milliseconds) for refresh to complete
_beamContext.Api.GroupsService.Subscribable.ForceRefresh();
await Task.Delay(300);
Refresh();
return new EmptyResponse();
}
public async Task<EmptyResponse> LeaveGroups()
{
// Leave any existing room
await LeaveRooms();
// Leave any existing groups
foreach(var group in _groupsView.Groups)
{
var result = await _beamContext.Api.GroupsService.LeaveGroup(group.Group.id);
}
// HACK: Force refresh here (0.10.1)
// Wait (arbitrary milliseconds) for refresh to complete
_beamContext.Api.GroupsService.Subscribable.ForceRefresh();
await Task.Delay(300);
Refresh();
return new EmptyResponse();
}
public async Task<EmptyResponse> LeaveRooms()
{
Debug.Log("_chatView 1: " + _chatView.roomHandles.Count);
foreach(var room in _chatView.roomHandles)
{
var result = await _chatService.LeaveRoom(room.Id);
}
Debug.Log("_chatView 2: " + _chatView.roomHandles.Count);
_data.RoomMessages.Clear();
Refresh();
return new EmptyResponse();
}
public void Refresh()
{
// Create new mock message
int messageIndex = _data.RoomMessages.Count + 1;
_data.MessageToSend = $"Hello {messageIndex:000}!";
// Create new mock group name
int groupIndex = _data.GroupNames.Count + 1;
_data.GroupToCreateName = $"Group{groupIndex:000}";
string refreshLog = $"Refresh() ...\n" +
$"\n * GroupNames.Count = {_data.GroupNames.Count}" +
$"\n * GroupPlayerNames.Count = {_data.GroupPlayerNames.Count}" +
$"\n * RoomNames.Count = {_data.RoomNames.Count}" +
$"\n * RoomUserNames.Count = {_data.RoomPlayerNames.Count}" +
$"\n * IsInGroup = {_data.IsInGroup}" +
$"\n * IsInRoom = {_data.IsInRoom}\n\n";
//Debug.Log(refreshLog);
// Send relevant data to the UI for rendering
OnRefreshed?.Invoke(_data);
}
// Event Handlers -------------------------------
private void RoomHandle_OnMessageReceived(Message message)
{
string roomMessage = $"{message.gamerTag}: {message.content}";
_data.RoomMessages.Add(roomMessage);
Refresh();
}
}
}
Adding group chat¶
The chat service includes full functionality for groups. Players can send chat messages within their group. Players can also send chat messages globally, within rooms, and directly to a specific player. See Chat for more info.
Adding group events¶
The events service includes full functionality for groups. Players can collaborate with group members and get group rewards. See Events for more info.