Seasonal events

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:

PackageRole
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 Cloud 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 Cloud 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 Cloud Dashboard.

Using the Unity Cloud Dashboard

You can use the Unity Cloud 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 Cloud Dashboard:

ScriptParametersDescriptionLocation in project
SeasonalEvents_GrantEventRewardNoneVerifies and distributes rewards.Assets/Use Case Samples/Seasonal Events/Cloud Code/SeasonalEvents_GrantEventReward.js
SeasonalEvents_GetServerTimeNoneRetrieves 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 Cloud Dashboard:

Resource typeResource nameIDDescription
CurrencyCoinCOINA challenge reward during the fall, winter, and spring events.
CurrencyGemGEMA challenge reward during the winter and summer events
CurrencyPearlPEARLA challenge reward during the fall and summer events
CurrencyStarSTARA challenge reward during the spring and summer events

Remote Config

Set up the following config values in the Unity Cloud Dashboard:

KeyTypeDescriptionValue
EVENT_NAMEstringThe name of the event to display in the scene.empty default value
EVENT_KEYstringThe key used to look up event-specific values, such as the addresses for the specific images.empty default value
EVENT_END_TIMEintThe 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_REWARDJSONThe 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 Cloud Dashboard:

DetailsName the Override “Fall Event”.
Targeting

Select JEXL with the following JEXL code:

user.timestampMinutes % 10 == 0 || user.timestampMinutes % 10 == 1 || user.timestampMinutes % 10 == 2
Content

Select 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"
	    }
	  ]
	}
Scheduling

Set the following start and end dates:

  • Set Start Date to Update content immediately.
  • Set End Date to Run indefinitely.
Status

After finishing creating the Game Override, click Enable.

DetailsName the Override “Winter Event”.
Targeting

Select JEXL with the following JEXL code:

user.timestampMinutes % 10 == 3 || user.timestampMinutes % 10 == 4
Content

Select 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"
    }
  ]
}
Scheduling

Set the following start and end dates:

  • Set Start Date to Update content immediately.
  • Set End Date to Run indefinitely.
Status

After finishing creating the Game Override, click Enable.

DetailsName the Override “Spring Event”.
Targeting

Select JEXL with the following JEXL code:

user.timestampMinutes % 10 == 5 || user.timestampMinutes % 10 == 6 || user.timestampMinutes % 10 == 7
Content

Select 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"
	}
  ]
}
Scheduling

Set the following start and end dates:

  • Set Start Date to Update content immediately.
  • Set End Date to Run indefinitely.
Status

After finishing creating the Game Override, click Enable.

DetailsName the Override “Summer Event”.
Targeting

Select JEXL with the following JEXL code:

user.timestampMinutes % 10 == 8 || user.timestampMinutes % 10 == 9
Content

Select 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"
	}
  ]
}
Scheduling

Set the following start and end dates:

  • Set Start Date to Update content immediately.
  • Set End Date to Run indefinitely.
Status

After finishing creating the Game Override, click Enable.

Unity logo Documentation
Copyright © 2024 Unity Technologies
"Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere (more info here). Other names or brands are trademarks of their respective owners.