The creator-centric platform for building live games in Unity

Easily add social, commerce, and content management features to your live game with low-code, drag-and-drop prefabs fully integrated with your Unity workflow.

Events

Allow game maker to set up a one-time competition

Overview

The purpose of this feature is to allow the game maker to set up a on-time EventsEvents - A one-time competition between all players within a game's community, rewarding based on score and score ranking. competition for players.

This page includes everything needed to use this feature in the "Beamable SDK for Unity".

šŸ“˜

Live Events

Live events can have a significant multiplier effect on engagement and revenue. Beamable offers two out of the box features that support this.

ā€¢ 1. Tournaments - A social/competitive feature, but with an additional layer of meta game and progression. Unlike Events, Tournaments are cyclical. This means that you compete on a periodic basis, and the results of that cycle feed into progression into new Stages and Tiers (i.e. Leagues). See Tournament Flow for more info

ā€¢ 2. Events - A social/competitive feature that allows players to compete over a finite duration, where their in-game actions contribute a score to an event leaderboard. Events can have one or more phases, each with a defined duration. These phases can be interpreted by the game to mean whatever it wants. Continue reading below for more info

User Experience

When setup properly, the user experience in the game project will be as follows.

Glossary

Here is the glossary of EventsEvents - A one-time competition between all players within a game's community, rewarding based on score and score ranking. competition terms.

Name

Detail

Partition Size

The number of Event players in direct competition (e.g. 50)

Phase

Each phase is a unique time period within the event.

Example: Phase I could be "collect gems", whereas Phase II could be "collect swords" -- these actions ultimately contribute to a single score on a Leaderboard.

Phrase Duration

The duration of time between each phase (e.g. 24 Hrs). The sum duration of all phases is the Event duration

Rank

The position of a player score, relative to the game's community

Reward

The extrinsic payoff to the player, calculated score and score rank

Note: Currency ContentContent - The primary data concept within the Beamable Content Manager and/or Item ContentContent - The primary data concept within the Beamable Content Manager may be rewarded

Rule

Rules are applied to the player. See Advanced for more info

Score

The in-game performance of a player, often represented as a number (e.g. "100" points)

Steps

Follow these steps to get started.

Step

Detail

  1. Open the "Toolbox" Window

ā€¢ Unity ā†’ Window ā†’ Beamable ā†’ Open Beamable Toolbox

  1. Open the Content Manager Window

ā€¢ Unity ā†’ Window ā†’ Beamable ā†’ Open Content Manager

  1. Create the "Event" content
ā€¢ Select the content type in the list ā€¢ Press the "Create" button ā€¢ Populate the content name
  1. Select the "Event" asset

ā€¢ Click the asset in the Content Manager Window
ā€¢ View the asset in the Unity Inspector Window

  1. Populate all fields

Note: The few fields shown are the minimum requirement. See Advanced for more info.

  1. Save the Unity Project

ā€¢ Unity ā†’ File ā†’ Save Project

Best Practice: If you are working on a team, commit to version control in this step.

  1. Publish the content

ā€¢ Press the "Publish" button in the Content Manager Window

Examples

Code

šŸ“˜

Beamable SDK Examples

ā€¢ This and all examples are available for download at GitHub.com/Beamable_SDK_Examples

The EventsServiceExample.cs snippet demonstrates common API for Beamable's EventService.cs.

using System.Collections.Generic;
using Beamable.Common;
using Beamable.Common.Api.Events;
using UnityEngine;
using UnityEngine.Events;

namespace Beamable.Examples.Services.EventsService
{
   /// <summary>
   /// Holds data for use in the <see cref="EventsServiceExampleUI"/>.
   /// </summary>
   [System.Serializable]
   public class EventsServiceExampleData
   {
      public long Dbid = 0;
      public int Score = 0;
      public List<string> RunningEventsLogs = new List<string>();
      public List<string> SetScoreLogs = new List<string>();
      public List<string> ClaimLogs = new List<string>();
   }
   
   /// <summary>
   /// Dispatch event, observed by <see cref="EventsServiceExampleUI"/>.
   /// </summary>
   [System.Serializable]
   public class RefreshedUnityEvent : UnityEvent<EventsServiceExampleData> { }
   

   /// <summary>
   /// Demonstrates <see cref="EventsService"/>.
   /// </summary>
   public class EventsServiceExample : MonoBehaviour
   {
      //  Events  ---------------------------------------
      [HideInInspector]
      public RefreshedUnityEvent OnRefreshed = new RefreshedUnityEvent();
      
      //  Fields  ---------------------------------------
      private IBeamableAPI _beamableAPI;

      private EventsServiceExampleData _data = new EventsServiceExampleData();

      //  Unity Methods  --------------------------------
      protected void Start()
      {
         Debug.Log($"Start()");

         SetupBeamable();
      }

      //  Methods  --------------------------------------
      private async void SetupBeamable()
      { 
         _beamableAPI = await Beamable.API.Instance;

         _data.Dbid = _beamableAPI.User.id;
         Debug.Log($"beamableAPI.User.id = {_data.Dbid}");

         // Fetch All Events
         _beamableAPI.EventsService.Subscribe(eventsGetResponse =>
         {
            _data.RunningEventsLogs.Clear();
            int index = 0;
            foreach (EventView eventView in eventsGetResponse.running)
            {
               index++;
               string endTime = $"{eventView.endTime.ToShortDateString()} at " +
                                $"{eventView.endTime.ToShortTimeString()}";
               string currentPhase = eventView.currentPhase.name;
               string rulesCount = eventView.currentPhase.rules.Count.ToString();

               string log = $"Event #{index}" +
                            $"\n\tname = {eventView.name}" + 
                            $"\n\tendTime = {endTime}" +
                            $"\n\tcurrentPhase = {currentPhase}" +
                            $"\n\trulesCount = {rulesCount}";
               _data.RunningEventsLogs.Add(log);
            }
            Refresh();
         });

         Refresh();
      }

      public async void SetScoreInEvents()
      {
         _data.Score += 1;
         _data.SetScoreLogs.Clear();
         
         // SetScore() in **ALL** events.
         // Typical usage is to SetScore() in just one event.
         EventsGetResponse eventsGetResponse = await _beamableAPI.EventsService.GetCurrent();
         foreach (EventView eventView in eventsGetResponse.running)
         {
            Unit unit = await _beamableAPI.EventsService.SetScore(
               eventView.id, _data.Score, false, new Dictionary<string, object>());

            string log = $"SetScore()" +
                         $"\n\tname = {eventView.name}" +
                         $"\n\tscore = {_data.Score}";
            _data.SetScoreLogs.Add(log);
         }
      }
      
      public async void ClaimRewardsInEvents()
      {
         _data.ClaimLogs.Clear();
         
         // Claim() in **ALL** events.
         // Typical usage is to Claim() in just one event.
         EventsGetResponse eventsGetResponse = await _beamableAPI.EventsService.GetCurrent();
         foreach (EventView eventView in eventsGetResponse.running)
         {
            EventClaimResponse eventClaimResponse = await _beamableAPI.EventsService.Claim(eventView.id);

            string log = $"Claim()" +
                         $"\n\tname = {eventView.name}" +
                         $"\n\tscoreRewards = {eventClaimResponse.view.scoreRewards.Count}" +
                         $"\n\trankRewards = {eventClaimResponse.view.rankRewards.Count}";
            _data.ClaimLogs.Add(log);
         }
      }
      
      public void Refresh()
      {
         Debug.Log($"Refresh()");
         Debug.Log($"\trunningEventsLogs.Count = {_data.RunningEventsLogs.Count}");
         Debug.Log($"\tsetScoreLogs.Count = {_data.SetScoreLogs.Count}");
         Debug.Log($"\tclaimLog.Count = {_data.ClaimLogs.Count}");
         
         // Send relevant data to the UI for rendering
         OnRefreshed?.Invoke(_data);
         
      }
   }
}

Advanced

In this image and tables are example name/value pairs to demonstrate how to populate the Event content object. The actual name and values used depend on the specific needs of the game project.

Adding Rules

Event rules are optional and are not parsed by the client side. However, they are powerful to place to create and maintain server-authoritative logic.

Name

Value

Detail

"collect_gems"

10

Create custom client logic to parse the name and value.

Require that players meet this rule.

Example: Limit which players may enter the Event or limit which players may claim rewards

"idle_content"

< some content id >

Create custom client logic to parse the name and value.

Require that players meet this rule.

Example: Limit which players may enter the Event or limit which players may claim rewards

Adding Rewards

Event rewards are optional but they are a fundamental part of marketing the live Event. Rewards encourage player participation.

The criteria for a reward may be either a certain score or a certain score rank.

The reward give to the player may be of currency type, of item type, or both.

Name

Value

Detail

"currency.Currency01"

10

Ex. Each player who meets the criteria will earn 10 gems.

"items.BronzeArmor"

1

Ex. Each player who meets the criteria will earn 1 Bronze Armor inventory item.

Adding Stores

Event stores are optional but they are a fundamental part of monetizing of the live event. Game makers can make a limited time offer within in-game stores to encourage player purchase behavior.

This creates effective monetization because there is an urgency and sense of purpose to the related purchases.

Name

Value

Detail

"Store Id"

stores.LimitedStore01

Ex. Each player in the Event will see a special "LimitedStore" version of the in-game store. Game makers can offer new items or can offer existing items at an exclusive price.

Updated 9 days ago


Events


Allow game maker to set up a one-time competition

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.