Documentation

Support

Services

Services

Seasonal Events

Create rotating seasonal events with limited-time content, rewards, and dynamic gameplay elements.
Read time 7 minutesLast updated 12 hours ago
Seasonal events can increase game sessions and overall interest in a game, because they give existing players new and fun content throughout the year to look forward to, and can entice new players to begin playing. This sample shows how you can set up seasonal events. It showcases four events, Fall, Winter, Spring, and Summer, however you can extend this example to configure events for anything you want. Each event displays the currency rewards you can win during the event, a countdown indicating how much time is left in the current event, and a Play Challenge button that opens a pop-up where players can collect their rewards for winning the challenge.

Prerequisites

To use this sample use case, you must download and install the UGS Use Cases project in your Unity project.

Overview

To see this use case in action, open the samples menu and navigate to Seasonal Events. To open this scene directly and interact with the use case:
  1. In the Unity Editor Project window, select Assets > Use Case Samples > Seasonal Events, then double-click 
    SeasonalEventsSample.unity
    to open the sample scene.
  2. Press Play to enter Play mode.

Initialization

The 
SeasonalEventsSceneManager.cs
script performs the following initialization tasks in its 
Start
function:
  1. Initializes Unity Gaming Services.
  2. Signs in the player anonymously using the Authentication service. If you’ve previously initialized any of the other sample scenes, Authentication will use your cached Player ID instead of creating a new one.
  3. Retrieves and updates the player's currency balances from the Economy service.
  4. Calls the 
    GetServerTime
    Cloud Code function in order to base Game Override and Remote Config data off the server time.
  5. Queries the Remote Config service to get the current values for event-related keys (see section on event parameters below).

Event parameters

The Remote Config service stores key-value data for displaying the active event name, the potential rewards for completing the event challenge. These keys are also used to retrieve the event’s themed interface visuals from the Addressables service. Remote Config also conveys when the event ends, which the 
CountdownManager.cs
script references to determine how much time remains for the current event. When that time runs out, it triggers a new call to Remote Config to get the updated values for the next event. Note: This sample determines which Game Override data to return based on the last digit of the number of minutes in the current server time. This is a simplification to be able to frequently observe the season change. In a real app, developers likely set up a Game Override to have specific start and end dates, then Remote Config determines when the Game Override is shown based on the server’s date and time. In that case, the client and server implementations can be a bit different.

Functionality

Collect Rewards

The Play Challenge button is an abstraction for gameplay that the player might engage in to earn event rewards. Clicking it opens a pop-up where players can collect rewards for "winning" the challenge. When you click the Collect Rewards button, the following occurs:
  1. The button’s 
    OnClick
    method calls the 
    SeasonalEvents_GrantEventReward.js
    Cloud Code script, which queries the Remote Config service to determine which rewards to distribute.     Note: Rewards could potentially differ from what the player expects, if they're altering their device clock or if they initiated their claim at the very end of an event.
  2. Cloud Code then calls the Economy service to grant the appropriate rewards and update the player’s currency and inventory balance.
  3. Once rewards are distributed, the calling script updates the currency HUD and closes the collect rewards pop-up.
You can only play the challenge once per active event, so after the Cloud Code script distributes rewards, it saves the current event name and timestamp to Cloud Save. The client uses this information to determine whether the current event has already been played, and if it has, to disable the Play Challenge button.

Setup

Requirements

To replicate this use case, you'll need the following Unity packages in your project:

Package

Role

AddressablesAllows asset retrieval by address. Wherever the asset resides (local or remote), the system will locate it and its dependencies and then return it. In this sample, it retrieves event-specific images and prefabs based on information from Remote Config.
AuthenticationAutomatically signs in the user anonymously to keep track of their data on the server side.
Cloud CodeContains important validation logic on the server side. In this sample, it distributes rewards for the event challenge. It also independently verifies the timestamp at the time of reward distribution on the server-side to confirm which event rewards to distribute.
Cloud SaveStores a flag for whether the current challenge has already been played, to prevent the player from participating multiple times.
DeploymentProvides a cohesive interface to deploy assets for Cloud Services.
EconomyRetrieves the player's starting and updated currency balances at runtime.
Game OverridesMaintains the four seasonal events and returns different values for certain keys based on which Game Override is deemed active.
Remote ConfigProvides key-value pairs that can be changed server-side, either manually or based on specific Game Overrides.
Note: Although it is listed as a package and requires separate Dashboard configuration, Game Overrides doesn't actually have an SDK to install from Package Manager. It is a server-side offering that affects values returned from other services. To use these services in your game, activate each service for your Organization and project in the Unity Dashboard.

Unity Cloud services configuration

To replicate this sample scene's setup in your own Unity project, configure the following items:
  • Cloud Code scripts
  • Economy items
  • Remote Config values
  • Remote Config Game Overrides
To configure these items you can use the Deployment package, or manually enter them using the Unity Dashboard. The recommended best practice is to use the Deployment package as it greatly accelerates this process.

Using the Deployment package

To deploy configurations using the Deployment package:
  1. Open the Deployment window.
  2. Check in 
    Common
    and 
    Seasonal Events
    .
  3. Click 
    Deploy Selection
    .
This deploys the following items:
  • Cloud Code scripts
  • Economy items
  • Remote Config values
The Deployment package doesn't support the following items:
  • Remote Config Game Overrides
To configure them, refer to Using the Unity Dashboard.

Using the Unity Dashboard

You can use the Unity Dashboard to manually configure your services by project and environment. Refer to the following sections to configure this sample.

Cloud Code

Publish the following scripts in the Unity Dashboard:

Script

Parameters

Description

Location in project

SeasonalEvents_GrantEventReward
NoneVerifies and distributes rewards.
Assets/Use Case Samples/Seasonal Events/Cloud Code/SeasonalEvents_GrantEventReward.js
SeasonalEvents_GetServerTime
NoneRetrieves the current timestamp from the server in order to base the UI on server-authoritative time.
Assets/Use Case Samples/Seasonal Events/Cloud Code/SeasonalEvents_GetServerTime.js
Note: The Cloud Code scripts included in the 
Cloud Code
folder are local copies because you cannot view the sample project's dashboard. Changes to these scripts do not affect the behavior of this sample because they are not automatically uploaded to the Cloud Code service.

Economy

Configure the following resources in the Unity Dashboard:

Resource type

Resource name

ID

Description

CurrencyCoin
COIN
A challenge reward during the fall, winter, and spring events.
CurrencyGem
GEM
A challenge reward during the winter and summer events
CurrencyPearl
PEARL
A challenge reward during the fall and summer events
CurrencyStar
STAR
A challenge reward during the spring and summer events

Remote Config

Set up the following config values in the Unity Dashboard:

Key

Type

Description

Value

EVENT_NAME
stringThe name of the event to display in the scene.
empty default value
EVENT_KEY
stringThe key used to look up event-specific values, such as the addresses for the specific images.
empty default value
EVENT_END_TIME
intThe last digit that matches in the Audience JEXL statement, i.e. the last digit of the latest timestamp that would return this campaign.
0
CHALLENGE_REWARD
JSONThe json that specifies what rewards are distributed when a challenge has been "won".
{"rewards": [{"id": "COIN","quantity": 100,"sprite_address": "Sprites/Currency/Coin"}]}

Game Overrides

Configure the following Overrides in the Unity Dashboard:
DetailsName the Override “
Fall Event
”.
TargetingSelect JEXL with the following JEXL code:
user.timestampMinutes % 10 == 0 || user.timestampMinutes % 10 == 1 || user.timestampMinutes % 10 == 2
ContentSelect Choose content type > Config Overrides, then enter override values for the following keys:
  • EVENT_NAME
    : “
    Fall Event
    ”
  • EVENT_KEY
    : “
    Fall
    ”
  • EVENT_END_TIME
    : 
    2
  • CHALLENGE_REWARD
    :
    {"rewards":[{"id": "COIN","quantity": 100,"spriteAddress": "Sprites/Currency/Coin"},{"id": "PEARL","quantity": 50,"spriteAddress": "Sprites/Currency/Pearl"}]}
SchedulingSet the following start and end dates:
  • Set Start Date to Update content immediately.
  • Set End Date to Run indefinitely.
StatusAfter finishing creating the Game Override, click Enable.
DetailsName the Override “
Winter Event
”.
TargetingSelect JEXL with the following JEXL code:
user.timestampMinutes % 10 == 3 || user.timestampMinutes % 10 == 4
ContentSelect Choose content type > Config Overrides, then enter override values for the following keys:
  • EVENT_NAME
    : “
    Winter Event
    ”
  • EVENT_KEY
    : “
    Winter
    ”
  • EVENT_END_TIME
    : 
    4
  • CHALLENGE_REWARD
    :
    {"rewards":[{"id": "COIN","quantity": 100,"spriteAddress": "Sprites/Currency/Coin"},{"id": "GEM","quantity": 50,"spriteAddress": "Sprites/Currency/Gem"}]}
SchedulingSet the following start and end dates:
  • Set Start Date to Update content immediately.
  • Set End Date to Run indefinitely.
StatusAfter finishing creating the Game Override, click Enable.
DetailsName the Override “
Spring Event
”.
TargetingSelect JEXL with the following JEXL code:
user.timestampMinutes % 10 == 5 || user.timestampMinutes % 10 == 6 || user.timestampMinutes % 10 == 7
ContentSelect Choose content type > Config Overrides, then enter override values for the following keys:
  • EVENT_NAME
    : “
    Spring Event
    ”
  • EVENT_KEY
    : “
    Spring
    ”
  • EVENT_END_TIME
    : 
    7
  • CHALLENGE_REWARD
    :
    {"rewards":[{"id": "COIN","quantity": 100,"spriteAddress": "Sprites/Currency/Coin"},{"id": "STAR","quantity": 50,"spriteAddress": "Sprites/Currency/Star"}]}
SchedulingSet the following start and end dates:
  • Set Start Date to Update content immediately.
  • Set End Date to Run indefinitely.
StatusAfter finishing creating the Game Override, click Enable.
DetailsName the Override “
Summer Event
”.
TargetingSelect JEXL with the following JEXL code:
user.timestampMinutes % 10 == 8 || user.timestampMinutes % 10 == 9
ContentSelect Choose content type > Config Overrides, then enter override values for the following keys:
  • EVENT_NAME
    : “
    Summer Event
    ”
  • EVENT_KEY
    : “
    Summer
    ”
  • EVENT_END_TIME
    : 
    9
  • CHALLENGE_REWARD
    :
    {"rewards":[{"id": "STAR","quantity": 50,"spriteAddress": "Sprites/Currency/Star"},{"id": "PEARL","quantity": 50,"spriteAddress": "Sprites/Currency/Pearl"},{"id": "GEM","quantity": 50,"spriteAddress": "Sprites/Currency/Gem"}]}
SchedulingSet the following start and end dates:
  • Set Start Date to Update content immediately.
  • Set End Date to Run indefinitely.
StatusAfter finishing creating the Game Override, click Enable.