Skip to content

Commit 0cb04b8

Browse files
mhijaziBmhijaziB
authored
Battle pass doc (#30)
* - new battle-pass document * - polish
1 parent 2ddccdd commit 0cb04b8

3 files changed

Lines changed: 180 additions & 0 deletions

File tree

‎docs/media/imgs/battlepass-content.jpg‎

50.8 KB
Loading

‎docs/unity/samples/SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
- [Game Type Matchmaking](game-type-matchmaking.md)
66
- [Android IAP](stores-android-iap.md)
77
- [Web Access](web-access.md)
8+
- [Battle Pass](battle-pass.md)
89
- Full Samples
910
- [Chat - GPW](gpw.md)
1011
- [Chat and Microstorage - GPW2](gpw2.md)

‎docs/unity/samples/battle-pass.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
# Building a Battle Pass
2+
3+
A battle pass is a common engagement feature for players. You can implement a Battle Pass for your game by utilizing
4+
Beamable's Custom Content capabilities. This is a quick guide for how to think about using Beamable for this feature.
5+
6+
-------------------
7+
8+
## Custom Content
9+
First, define a custom content type for the Battle Pass by creating a class that inherits from `ContentObject`.
10+
Each Battle Pass will have tiers, and each tier can have rewards.
11+
12+
```csharp
13+
[ContentType("battlepass")]
14+
public class Battlepass : ContentObject
15+
{
16+
public string Name;
17+
public string EndDate;
18+
public List<Tier> Tiers;
19+
}
20+
21+
[Serializable]
22+
public class Tier
23+
{
24+
public int Level;
25+
public List<Reward> Rewards;
26+
}
27+
28+
[Serializable]
29+
public class Reward
30+
{
31+
public string RewardName;
32+
public int Quantity;
33+
}
34+
```
35+
36+
### Content Setup
37+
38+
Once the custom type is defined, follow these steps to add a Battle Pass content object in the Beamable
39+
Content Manager:
40+
41+
- **Step 1: Open the Content Manager:**
42+
- Unity → Window → Beamable → Open Beam Content
43+
- **Step 2: Create a new content object of type Battlepass:**
44+
- Select "Battlepass" from the content type list.
45+
- Press the "Create" button.
46+
- Provide a name for the Battle Pass content.
47+
- **Step 3: Populate the fields in the Unity Inspector:**
48+
- Name the Battle Pass
49+
- Set the `EndDate` using the ISO 8601 format (e.g., `2024-12-31T23:59:59Z`).
50+
- Define the tiers and rewards (Example in screenshot)
51+
52+
![Battle Pass Content](docs/media/imgs/battlepass-content.jpg)
53+
54+
- **Step 4: Publish the content:**
55+
- Once the Battle Pass is configured, press the **Publish** button in the Content Manager to push the Battle Pass
56+
content live.
57+
58+
------------------------------------------------
59+
60+
## Fetching and Using the Battle Pass at Runtime
61+
62+
After the Battle Pass is defined and published, use Beamable’s features to fetch and use the content at runtime.
63+
In this example, we'll retrieve the Battle Pass.
64+
65+
```csharp
66+
// Fetch the Battle Pass content
67+
await battlepassRef.Resolve()
68+
.Then(content =>
69+
{
70+
_battlePass = content;
71+
Debug.Log($"Fetched Battle Pass: {_battlePass.Name}");
72+
})
73+
.Error(ex =>
74+
{
75+
Debug.LogError("Failed to fetch the Battle Pass content.");
76+
});
77+
78+
await DisplayBattlePassDetails();
79+
80+
private async Promise DisplayBattlePassDetails()
81+
{
82+
Debug.Log($"Battle Pass: {_battlePass.Name}");
83+
foreach (var tier in _battlePass.Tiers)
84+
{
85+
Debug.Log($"Tier {tier.Level}");
86+
foreach (var reward in tier.Rewards)
87+
{
88+
Debug.Log($"Reward: {reward.RewardName}, Quantity: {reward.Quantity}");
89+
}
90+
}
91+
// Parse and display the end date
92+
if (DateTime.TryParseExact(_battlePass.EndDate, "yyyy-MM-ddTHH:mm:ssZ", CultureInfo.InvariantCulture, DateTimeStyles.AssumeUniversal, out DateTime endDate))
93+
{
94+
Debug.Log($"Battle Pass End Date: {endDate}");
95+
}
96+
else
97+
{
98+
Debug.LogWarning("Failed to parse the Battle Pass End Date.");
99+
}
100+
101+
var isValid = await _service.BattlePassService_IsBattlepassValid(battlepassRef);
102+
Debug.Log($"Is Battle Pass Valid: {isValid}");
103+
}
104+
```
105+
106+
## Adding the Battle Pass to Player Inventory
107+
You can add the Battle Pass to a player's inventory using Beamable's Inventory system. Here's how you can use the
108+
`Inventory.Update` method to store the Battle Pass details, such as its name and end date.
109+
110+
To access `items.battlepass`, an item named `battlepass` should be created and published through the Content Manager.
111+
112+
```csharp
113+
private async Task AddBattlepassToInventory()
114+
{
115+
_beamContext = await BeamContext.Default.Instance;
116+
var inventory = _beamContext.Inventory;
117+
118+
// Add Battle Pass to the player's inventory
119+
await inventory.Update(builder => builder.AddItem("items.battlepass", new Dictionary<string, string>
120+
{
121+
{ "name", _battlePass.Name },
122+
{ "endDate", _battlePass.EndDate } // Add additional properties for the battle pass
123+
}));
124+
125+
Debug.Log("Battle Pass added to inventory!");
126+
}
127+
```
128+
129+
## Handling End Date and Expiration Validation in a Microservice
130+
131+
You can use Beamable’s Microservices to validate the Battle Pass expiration. Since `Battlepass` is a custom
132+
`ContentObject`, the type won't be findable by default in Microservices. You can create or move the `Battlepass`
133+
custom content script into the Beamable's `Common` folder, which is also referenced in the Microservices. The folder
134+
can be found in `Assets/Beamable/Common`.
135+
136+
Microservice method:
137+
```csharp
138+
[ClientCallable]
139+
public async Task<bool> IsBattlepassValid(ContentRef<Battlepass> battlepass)
140+
{
141+
var battlePass = await Services.Content.GetContent(battlepass);
142+
if (battlePass == null)
143+
{
144+
throw new Exception($"Battle Pass with ID {battlepass.GetId()} not found");
145+
}
146+
147+
var currentTime = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
148+
if (DateTimeOffset.TryParseExact(battlePass.EndDate, "yyyy-MM-ddTHH:mm:ssZ",
149+
CultureInfo.InvariantCulture, DateTimeStyles.AssumeUniversal, out var endDate))
150+
{
151+
long endDateUnix = endDate.ToUnixTimeSeconds();
152+
return currentTime <= endDateUnix;
153+
}
154+
else
155+
{
156+
throw new Exception("EndDate is not in a valid ISO 8601 format.");
157+
}
158+
}
159+
```
160+
------------------------------
161+
162+
Download the full sample code from [Beamable Battle Pass Sample](https://github.com/beamable/battle-pass-example).
163+
*Note*: This sample uses the latest Beamable SDK V5.0.0.
164+
165+
------------------------------
166+
167+
## Season Passes
168+
You can also create a season pass that can be used to unlock new content or features.
169+
Currently, there is no sample for this feature; however, here is how to do it. It is very similar to the Battle Pass.
170+
171+
1. **Create a `Season Pass` content object:** This will include the metadata needed for the season
172+
(its offerings, rewards, end time, etc.).
173+
174+
2. **Inventory or Stats services:** You can use these services to track per-player ownership of a season pass,
175+
whether they bought it or not.
176+
177+
3. **Microservices:** Here you can enforce the business side of the season pass (checking current date/time if
178+
it's within the window, granting the season's rewards, or performing a cleanup or reset at season boundaries).
179+

0 commit comments

Comments
 (0)