@aqian0/dsh-unity 0.0.0-stage → 0.1.0

package/skills/build-live-game/references/battlepass.md

@@ -0,0 +1,904 @@
+# Battle Pass Blueprint
+
+## Table of Contents
+
+- [Architecture Overview](#architecture-overview)
+- [Free Track vs Premium Track](#free-track-vs-premium-track)
+- [Multiple Concurrent Passes](#multiple-concurrent-passes)
+- [Data Models](#data-models)
+- [API Notes](#api-notes)
+  - [Namespace Aliases](#namespace-aliases-required)
+  - [ProtectedReadAccessClassOptions](#protectedreadaccessclassoptions)
+  - [Why Tier Thresholds Live in the Module](#why-tier-thresholds-live-in-the-module)
+  - [Source Whitelist Enforcement](#source-whitelist-enforcement)
+  - [Error Handling](#error-handling)
+- [Cloud Code Module Functions](#cloud-code-module-functions)
+- [Load Pass Definitions from Remote Config](#load-pass-definitions-from-remote-config)
+- [Load Player Progress](#load-player-progress)
+- [Client to Cloud Code Calls](#client-to-cloud-code-calls)
+- [Full Client Implementation](#full-client-implementation)
+- [BattlePassTester](#battlepasstester)
+- [Cloud Code Module Implementation](#cloud-code-module-implementation)
+  - [BattlePassModule.cs](#battlepassmodulecs)
+  - [Server-Side Models](#server-side-models-inside-battlepassmodulecs)
+- [Cloud Resources](#cloud-resources)
+- [Deployment Checklist](#deployment-checklist)
+- [Validation](#validation)
+- [Asset Store & Sample Projects](#asset-store--sample-projects)
+
+---
+
+## Architecture Overview
+
+| Concern | Service | Key |
+|---|---|---|
+| Pass definitions | Remote Config | `"battle_passes"` |
+| Per-player progress | Cloud Save (Protected) | `"battle_pass_progress"` |
+| Award XP | Cloud Code | `BattlePassModule.AwardXp` |
+| Claim reward | Cloud Code | `BattlePassModule.ClaimReward` |
+| Purchase premium | Cloud Code | `BattlePassModule.PurchasePremium` (integration stub; always throws until you add purchase validation) |
+
+```
+Remote Config                Cloud Save (Protected)           Cloud Code Module
+"battle_passes"              "battle_pass_progress"           BattlePassModule
+       |                            |                               |
+       v                            v                               v
+BattlePassDefinition[]       { passId: Progress }            AwardXp
+  PassId, Name,              Server-writes only               ClaimReward
+  StartDate, EndDate,                                         PurchasePremium
+  Tiers[]
+       |                            ^                               |
+       |                            |                               |
+       +------- client reads -------+------- server writes ---------+
+```
+
+**Key principle:** The client reads pass definitions from Remote Config and player progress from Cloud Save (Protected bucket). All mutations -- awarding XP, claiming rewards, purchasing premium -- go through the Cloud Code module, which is the only writer to the Protected bucket.
+
+---
+
+## Free Track vs Premium Track
+
+Every tier in a battle pass has **two parallel reward tracks**:
+
+- **Free track** -- available to all players who reach the tier.
+- **Premium track** -- visible to all players but **locked** unless the player has purchased the premium pass (`HasPremium = true`).
+
+Premium rewards are displayed in the UI alongside free rewards so non-premium players can see what they are missing, encouraging upgrade. The Cloud Code module enforces the lock: `ClaimReward` with `rewardType = "premium"` throws if `HasPremium` is false.
+
+---
+
+## Multiple Concurrent Passes
+
+The system supports multiple battle passes running simultaneously:
+
+- Each pass has a unique `PassId` (e.g. `"season_03"`, `"easter_2026"`).
+- Passes may overlap in time. A player can have active progress in several passes at once.
+- Progress and premium status are tracked **independently per pass**. The Cloud Save key `"battle_pass_progress"` stores a `Dictionary<string, BattlePassProgress>` keyed by `PassId`.
+- **Date filtering is client-side.** The client fetches all pass definitions from Remote Config and filters to those whose `StartDate <= now <= EndDate`.
+- Expired passes remain in the progress dictionary. The client simply stops showing them. Clean up stale entries via a scheduled Cloud Code trigger if desired.
+
+---
+
+## Data Models
+
+### BattlePassDefinition (client-side, from Remote Config)
+
+```csharp
+[Serializable]
+public class BattlePassDefinition
+{
+    public string PassId;
+    public string Name;
+    public string StartDate;    // ISO 8601, e.g. "2026-04-01T00:00:00Z"
+    public string EndDate;      // ISO 8601
+    public List<BattlePassTier> Tiers;
+}
+```
+
+### BattlePassTier (client-side, from Remote Config)
+
+```csharp
+[Serializable]
+public class BattlePassTier
+{
+    public int TierNumber;
+    public int XpRequired;      // cumulative XP to reach this tier (not delta from previous)
+    public string FreeRewardId;
+    public string PremiumRewardId;
+}
+```
+
+### BattlePassProgress (defined once, in the cloud assembly)
+
+Stored in Cloud Save Protected, one entry per pass, keyed by `PassId` in the progress dictionary at Cloud Save key `"battle_pass_progress"`. Define it once, in `BattlePassModule.cs` (see [Server-Side Models](#server-side-models-inside-battlepassmodulecs)), as a class of public settable members. The source generator emits a data-only stub of the same name and namespace, `BattlePassModule.Cloud.BattlePassProgress`, into the client assembly, so client code uses that type and never declares its own copy. `ClaimedRewards` holds keys such as `"tier_1_free"` and `"tier_2_premium"`.
+
+`BattlePassTierThreshold` is a server-only helper that mirrors the `Tiers` in `BattlePasses.rc`. It never appears in an endpoint signature, so it has no client stub.
+
+---
+
+## API Notes
+
+### Namespace Aliases (Required)
+
+Cloud Save has multiple types named `LoadOptions`, `SaveOptions`, and `DeleteOptions` across
+different namespaces. Always declare these aliases at the top of any file that uses Cloud Save:
+
+```csharp
+using PlayerLoadOptions   = Unity.Services.CloudSave.Models.Data.Player.LoadOptions;
+using PlayerSaveOptions   = Unity.Services.CloudSave.Models.Data.Player.SaveOptions;
+using PlayerDeleteOptions = Unity.Services.CloudSave.Models.Data.Player.DeleteOptions;
+```
+
+Without these aliases, the compiler will report ambiguous type references.
+
+### ProtectedReadAccessClassOptions
+
+Use `ProtectedReadAccessClassOptions` when loading player progress. This reads the current
+player's own Protected data — no player ID parameter is required; it always reads the signed-in
+player's data.
+
+> **Common mistake:** Reading from the wrong access class (e.g. using default `LoadOptions`
+> instead of `ProtectedReadAccessClassOptions`) will return no data, because the progress
+> is stored in the Protected bucket by the Cloud Code module.
+
+### Why Tier Thresholds Live in the Module
+
+Remote Config is not accessible from inside Cloud Code modules, and anything the client sends is
+untrusted: a client that supplies its own tier thresholds can set a tier-three threshold of zero
+and reach tier three with 1 XP. The module therefore holds the thresholds in a server-side
+constant (`PassTiers` in `BattlePassModule.cs`) and `AwardXp` takes no tier data from the client.
+Pass dates get the same treatment: `PassWindows` holds each pass's UTC start and end, and `AwardXp`
+and `ClaimReward` reject any pass outside `[Start, End)` using server time, so an expired pass cannot
+gain XP and a staged future pass cannot be claimed early. Rewards must be claimed while the pass is
+active. Keep `PassTiers` and `PassWindows` in sync with the `XpRequired`, `StartDate` and `EndDate`
+values in `BattlePasses.rc` whenever you change a pass. Passes missing from either are rejected.
+
+### Source Whitelist Enforcement
+
+The Cloud Code module maintains a server-side whitelist of allowed XP source strings:
+
+```csharp
+static readonly Dictionary<string, int> MaxXpPerSource = new()
+{
+    ["match_complete"] = 200,
+    ["daily_login"] = 50,
+    ["quest_complete"] = 300
+};
+```
+
+Any `AwardXp` call with an unrecognized source throws an exception, and each source has a
+per-call XP cap (`MaxXpPerSource`). Add or remove entries as needed for your game. The whitelist
+and caps prevent clients from inventing XP sources or awarding themselves arbitrary amounts.
+For full protection, derive XP from server-verified events instead of a client-supplied `amount`.
+
+### Error Handling
+
+Cloud Code and Cloud Save errors surface as typed exceptions on the client:
+
+```csharp
+try
+{
+    var progress = await AwardXpAsync(passId, 100, "match_complete");
+}
+catch (CloudCodeException ex)
+{
+    // ex.Reason: CloudCodeExceptionReason (e.g. ScriptError for module-thrown exceptions)
+    Debug.LogError($"[BattlePass] Cloud Code error: {ex.Reason} — {ex.Message}");
+}
+catch (CloudSaveException ex)
+{
+    // ex.Reason: CloudSaveExceptionReason
+    // A 403 on the Protected bucket means the client attempted a direct write —
+    // all writes must go through the Cloud Code module.
+    Debug.LogError($"[BattlePass] Cloud Save error: {ex.Reason} — {ex.Message}");
+}
+```
+
+| Error | Cause | Fix |
+| :-- | :-- | :-- |
+| `CloudCodeException` with reason `ScriptError` | The module threw, for example on a failed validation | Read `ex.Message`, then correct the arguments or the player's state |
+| `CloudSaveException` with a `403` | The client attempted a direct write to the Protected bucket | Route the write through the Cloud Code module |
+
+---
+
+## Cloud Code Module Functions
+
+| Function | Parameters | Behavior |
+|---|---|---|
+| `AwardXp` | `passId`, `amount`, `source` | Validates `source` against a whitelist (`MaxXpPerSource` keys), rejects non-positive amounts and amounts above the source's cap, rejects unknown passes, adds XP to the pass progress, recalculates the current tier from the server-side `PassTiers`, saves to Cloud Save Protected |
+| `ClaimReward` | `passId`, `tierNumber`, `rewardType` | Validates the tier exists in the server-side `PassTiers` and the player's XP meets its threshold, validates premium ownership if `rewardType` is `"premium"`, checks reward is not already claimed, records the claim as `"tier_N_type"` (e.g. `"tier_2_premium"`), saves to Cloud Save Protected |
+| `PurchasePremium` | `passId` | **Integration stub.** Returns the existing progress if `HasPremium` is already true; otherwise the sample always throws, because nothing in the blueprint sets `HasPremium`. Add server-side purchase validation that sets `HasPremium = true` before premium purchasing works; do not deploy this path as-is. It fails closed and never grants premium unverified. |
+
+All three functions return the updated `BattlePassProgress` for the given pass.
+
+---
+
+## Load Pass Definitions from Remote Config
+
+```csharp
+struct UserAttributes {}
+struct AppAttributes {}
+
+async Task<List<BattlePassDefinition>> LoadActivePassesAsync()
+{
+    var result = await RemoteConfigService.Instance.FetchConfigsAsync(
+        new UserAttributes(), new AppAttributes());
+
+    var token = result.config["battle_passes"];
+    if (token == null) return new List<BattlePassDefinition>();
+
+    var allPasses = token.ToObject<List<BattlePassDefinition>>();
+
+    var now = DateTime.UtcNow;
+    return allPasses
+        .Where(p =>
+            DateTime.Parse(p.StartDate, null, DateTimeStyles.RoundtripKind) <= now &&
+            DateTime.Parse(p.EndDate,   null, DateTimeStyles.RoundtripKind) >= now)
+        .ToList();
+}
+```
+
+- `FetchConfigsAsync` downloads all Remote Config entries.
+- `result.config["battle_passes"]` returns a `JToken` for the JSON array stored under that key.
+- Date filtering is performed client-side by comparing `StartDate` and `EndDate` against `DateTime.UtcNow`.
+
+---
+
+## Load Player Progress
+
+```csharp
+using Unity.Services.CloudSave;
+using Unity.Services.CloudSave.Models;
+using Unity.Services.CloudSave.Models.Data.Player;
+using PlayerLoadOptions = Unity.Services.CloudSave.Models.Data.Player.LoadOptions;
+
+async Task<Dictionary<string, BattlePassProgress>> LoadProgressAsync()
+{
+    var result = await CloudSaveService.Instance.Data.Player.LoadAsync(
+        new HashSet<string> { "battle_pass_progress" },
+        new PlayerLoadOptions(new ProtectedReadAccessClassOptions()));
+
+    if (!result.TryGetValue("battle_pass_progress", out var item))
+        return new Dictionary<string, BattlePassProgress>();
+
+    return JsonConvert.DeserializeObject<Dictionary<string, BattlePassProgress>>(
+        item.Value.GetAsString())
+        ?? new Dictionary<string, BattlePassProgress>();
+}
+```
+
+**Important:** Use `ProtectedReadAccessClassOptions` because the Cloud Code module writes to the Protected bucket. Reading from the wrong access class will return no data.
+
+> **Stale entries:** Expired pass entries remain in the dictionary indefinitely but are inert —
+> the client ignores any PassId not present in the current active pass list.
+
+---
+
+## Client to Cloud Code Calls
+
+### AwardXpAsync
+
+```csharp
+public async Task<BattlePassProgress> AwardXpAsync(string passId, int amount, string source)
+{
+    if (!ActivePasses.Any(p => p.PassId == passId))
+        throw new InvalidOperationException(
+            $"Pass '{passId}' is not in the active passes list. Call LoadAsync first.");
+
+    var progress = await m_Client.AwardXp(passId, amount, source);
+
+    Progress[passId] = progress;
+    return progress;
+}
+```
+
+The client sends no tier data; the server recalculates the player's tier from its own `PassTiers`. The active-pass check above is UX only; the module enforces pass dates itself. `m_Client` is the generated `BattlePassModuleClient`, created after sign-in.
+
+### ClaimRewardAsync
+
+```csharp
+public async Task<BattlePassProgress> ClaimRewardAsync(
+    string passId, int tierNumber, string rewardType)
+{
+    var progress = await m_Client.ClaimReward(passId, tierNumber, rewardType);
+
+    Progress[passId] = progress;
+    return progress;
+}
+```
+
+### PurchasePremiumAsync
+
+Calls the `PurchasePremium` integration stub. It throws for any player without `HasPremium` until you add a validated purchase flow to the module.
+
+```csharp
+public async Task<BattlePassProgress> PurchasePremiumAsync(string passId)
+{
+    var progress = await m_Client.PurchasePremium(passId);
+
+    Progress[passId] = progress;
+    return progress;
+}
+```
+
+---
+
+## Full Client Implementation
+
+`BattlePassManager` is a `MonoBehaviour` that initializes services, loads pass definitions and player progress, and exposes methods for XP awards, reward claims, and premium purchases. Attach it to a GameObject in your scene.
+
+```csharp
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.Linq;
+using System.Threading.Tasks;
+using BattlePassModule.Client;
+using BattlePassModule.Cloud;
+using Newtonsoft.Json;
+using Unity.Services.Authentication;
+using Unity.Services.CloudSave;
+using Unity.Services.CloudSave.Models;
+using Unity.Services.CloudSave.Models.Data.Player;
+using PlayerLoadOptions = Unity.Services.CloudSave.Models.Data.Player.LoadOptions;
+using Unity.Services.Core;
+using Unity.Services.RemoteConfig;
+using UnityEngine;
+
+public class BattlePassManager : MonoBehaviour
+{
+    BattlePassModuleClient m_Client;
+
+    public List<BattlePassDefinition> ActivePasses { get; private set; } = new();
+    public Dictionary<string, BattlePassProgress> Progress { get; private set; } = new();
+
+    public event Action Loaded;
+
+    async void Start()
+    {
+        try
+        {
+            await UnityServices.InitializeAsync();
+            if (!AuthenticationService.Instance.IsSignedIn)
+            {
+                await AuthenticationService.Instance.SignInAnonymouslyAsync();
+            }
+            m_Client = new BattlePassModuleClient();
+            await LoadAsync();
+            Debug.Log($"BattlePassManager: Loaded {ActivePasses.Count} passes.");
+            Loaded?.Invoke();
+        }
+        catch (Exception ex)
+        {
+            Debug.LogError($"BattlePassManager: Error during loading: {ex.Message}\n{ex.StackTrace}");
+        }
+    }
+
+    public async Task LoadAsync()
+    {
+        ActivePasses = await LoadActivePassesAsync();
+        Progress     = await LoadProgressAsync();
+    }
+
+    struct UserAttributes {}
+    struct AppAttributes {}
+
+    async Task<List<BattlePassDefinition>> LoadActivePassesAsync()
+    {
+        var result = await RemoteConfigService.Instance.FetchConfigsAsync(
+            new UserAttributes(), new AppAttributes());
+
+        var token = result.config["battle_passes"];
+        if (token == null) return new List<BattlePassDefinition>();
+
+        var allPasses = token.ToObject<List<BattlePassDefinition>>();
+
+        var now = DateTime.UtcNow;
+        return allPasses
+            .Where(p =>
+                DateTime.Parse(p.StartDate, null, DateTimeStyles.RoundtripKind) <= now &&
+                DateTime.Parse(p.EndDate,   null, DateTimeStyles.RoundtripKind) >= now)
+            .ToList();
+    }
+
+    async Task<Dictionary<string, BattlePassProgress>> LoadProgressAsync()
+    {
+        var result = await CloudSaveService.Instance.Data.Player.LoadAsync(
+            new HashSet<string> { "battle_pass_progress" },
+            new PlayerLoadOptions(new ProtectedReadAccessClassOptions()));
+
+        if (!result.TryGetValue("battle_pass_progress", out var item))
+            return new Dictionary<string, BattlePassProgress>();
+
+        return JsonConvert.DeserializeObject<Dictionary<string, BattlePassProgress>>(
+            item.Value.GetAsString())
+            ?? new Dictionary<string, BattlePassProgress>();
+    }
+
+    public async Task<BattlePassProgress> AwardXpAsync(string passId, int amount, string source)
+    {
+        if (!ActivePasses.Any(p => p.PassId == passId))
+            throw new InvalidOperationException(
+                $"Pass '{passId}' is not in the active passes list. Call LoadAsync first.");
+
+        var progress = await m_Client.AwardXp(passId, amount, source);
+
+        Progress[passId] = progress;
+        return progress;
+    }
+
+    public async Task<BattlePassProgress> ClaimRewardAsync(
+        string passId, int tierNumber, string rewardType)
+    {
+        var progress = await m_Client.ClaimReward(passId, tierNumber, rewardType);
+
+        Progress[passId] = progress;
+        return progress;
+    }
+
+    // Requires the PurchasePremium integration stub to be completed server-side.
+    public async Task<BattlePassProgress> PurchasePremiumAsync(string passId)
+    {
+        var progress = await m_Client.PurchasePremium(passId);
+
+        Progress[passId] = progress;
+        return progress;
+    }
+}
+```
+
+---
+
+## BattlePassTester
+
+Attach to the same GameObject as `BattlePassManager` in your test scene. Wire `m_Manager` via
+the Inspector, or let it fall back to `GetComponent`.
+
+```csharp
+using System.Text;
+using UnityEngine;
+
+/// <summary>
+/// Attach alongside BattlePassManager to run a quick in-Editor smoke test.
+/// On load: logs all active pass states.
+/// Then: awards 100 XP to the first active pass via Cloud Code and logs the result.
+/// </summary>
+public class BattlePassTester : MonoBehaviour
+{
+    [SerializeField] BattlePassManager m_Manager;
+
+    void Start()
+    {
+        if (m_Manager == null)
+            m_Manager = GetComponent<BattlePassManager>();
+        m_Manager.Loaded += OnLoaded;
+    }
+
+    async void OnLoaded()
+    {
+        LogState("Initial state");
+
+        if (m_Manager.ActivePasses.Count == 0)
+        {
+            Debug.Log("[BattlePassTester] No active passes — nothing to award.");
+            return;
+        }
+
+        var firstPass = m_Manager.ActivePasses[0];
+        Debug.Log($"[BattlePassTester] Awarding 100 XP to '{firstPass.PassId}' " +
+            $"(source: match_complete) ...");
+
+        var result = await m_Manager.AwardXpAsync(firstPass.PassId, 100, "match_complete");
+
+        Debug.Log($"[BattlePassTester] After award — " +
+            $"XP={result.CurrentXp}, Tier={result.CurrentTier}");
+    }
+
+    void LogState(string label)
+    {
+        var sb = new StringBuilder();
+        sb.AppendLine($"[BattlePassTester] {label} — {m_Manager.ActivePasses.Count} active pass(es):");
+
+        foreach (var pass in m_Manager.ActivePasses)
+        {
+            m_Manager.Progress.TryGetValue(pass.PassId, out var progress);
+            sb.AppendLine($"  [{pass.PassId}] {pass.Name}: " +
+                $"XP={progress?.CurrentXp ?? 0}, " +
+                $"Tier={progress?.CurrentTier ?? 1}, " +
+                $"Premium={progress?.HasPremium ?? false}, " +
+                $"Claimed={progress?.ClaimedRewards?.Count ?? 0}");
+        }
+
+        Debug.Log(sb.ToString());
+    }
+}
+```
+
+---
+
+## Cloud Code Module Implementation
+
+> **Create the module with the Editor, not by hand.** Right-click a folder under `Assets/` ->
+> **Create > Services > Cloud Code Module Script** and name it `BattlePassModule`. See
+> the Creating a Cloud Code Module section of `references/cloud-code-modules.md`.
+>
+> The Editor generates the following. Use the list to check what you got — there is nothing here to
+> type out, and no `.sln`, `.csproj`, `.pubxml` or test project:
+>
+> - [ ] `Assets/CloudCode/BattlePassModule/BattlePassModule.ccmu` (holds the two asmdef GUIDs)
+> - [ ] `Cloud/BattlePassModule.asmdef` — Editor-only, `noEngineReferences`, `autoReferenced: false`
+> - [ ] `Cloud/BattlePassModule.cs` — rename/replace with the `[CloudCodeFunction]` endpoints below
+> - [ ] `Client/BattlePassModuleClient.asmdef` — references the cloud assembly
+> - [ ] `Client/BattlePassModuleClient.cs` — `[CloudModuleClient(typeof(BattlePassModule))]` partial
+>
+> One file the Editor does **not** generate, which this module needs because its endpoints inject
+> `IGameApiClient`:
+>
+> - [ ] `Cloud/CloudSetup.cs` — an `ICloudCodeSetup` calling `config.AddGameApiClient()`
+> - [ ] `Newtonsoft.Json.dll` added to `precompiledReferences` in `Cloud/BattlePassModule.asmdef` — the generated asmdef ships that array empty, and this module's code uses `JsonConvert` (see `references/cloud-code-modules.md`)
+>
+> The deployed module name is the **cloud asmdef's name** (`BattlePassModule`), not the `.ccmu` filename.
+>
+> The client calls the module through the generated `BattlePassModuleClient`. The assembly that holds `BattlePassManager` must reference the module's client assembly; the Editor creates it auto-referenced, so the default game assembly already does.
+
+### BattlePassModule.cs
+
+```csharp
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading.Tasks;
+using Newtonsoft.Json;
+using Unity.Services.CloudCode.Apis;
+using Unity.Services.CloudCode.Core;
+using Unity.Services.CloudSave.Model;
+
+namespace BattlePassModule.Cloud
+{
+    public class BattlePassModule
+    {
+        const string ProgressKey = "battle_pass_progress";
+
+        static readonly Dictionary<string, int> MaxXpPerSource = new()
+        {
+            ["match_complete"] = 200,
+            ["daily_login"] = 50,
+            ["quest_complete"] = 300
+        };
+
+        // Keep in sync with the Tiers in BattlePasses.rc; clients are never trusted for thresholds.
+        static readonly Dictionary<string, List<BattlePassTierThreshold>> PassTiers = new()
+        {
+            ["season_03"] = new()
+            {
+                new BattlePassTierThreshold { TierNumber = 1, XpRequired = 0 },
+                new BattlePassTierThreshold { TierNumber = 2, XpRequired = 500 },
+                new BattlePassTierThreshold { TierNumber = 3, XpRequired = 1200 }
+            },
+            ["easter_2026"] = new()
+            {
+                new BattlePassTierThreshold { TierNumber = 1, XpRequired = 0 },
+                new BattlePassTierThreshold { TierNumber = 2, XpRequired = 300 }
+            }
+        };
+
+        // Keep in sync with StartDate/EndDate in BattlePasses.rc. UTC, End is exclusive.
+        static readonly Dictionary<string, (DateTime Start, DateTime End)> PassWindows = new()
+        {
+            ["season_03"] = (new DateTime(2024, 1, 1, 0, 0, 0, DateTimeKind.Utc),
+                             new DateTime(2026, 7, 1, 0, 0, 0, DateTimeKind.Utc)),
+            ["easter_2026"] = (new DateTime(2026, 4, 1, 0, 0, 0, DateTimeKind.Utc),
+                               new DateTime(2026, 4, 22, 0, 0, 0, DateTimeKind.Utc))
+        };
+
+        // ── AwardXp ──────────────────────────────────────────────────────────────
+
+        [CloudCodeFunction("AwardXp")]
+        public async Task<BattlePassProgress> AwardXp(
+            [CloudCodeService] IExecutionContext context, [CloudCodeService] IGameApiClient client,
+            string passId, int amount, string source)
+        {
+            if (!MaxXpPerSource.TryGetValue(source, out var maxXp))
+                throw new Exception(
+                    $"Invalid XP source: '{source}'. Allowed: {string.Join(", ", MaxXpPerSource.Keys)}");
+
+            if (amount <= 0 || amount > maxXp)
+                throw new Exception($"XP amount must be between 1 and {maxXp} for source '{source}'.");
+
+            if (!PassTiers.TryGetValue(passId, out var tiers))
+                throw new Exception($"Unknown pass '{passId}'.");
+
+            RequireActive(passId);
+
+            var allProgress = await LoadProgressAsync(context, client);
+
+            if (!allProgress.TryGetValue(passId, out var progress))
+                progress = new BattlePassProgress { CurrentTier = 1, ClaimedRewards = new List<string>() };
+
+            progress.CurrentXp += amount;
+
+            progress.CurrentTier = CalculateTier(progress.CurrentXp, tiers);
+
+            allProgress[passId] = progress;
+            await SaveProgressAsync(context, client, allProgress);
+
+            return progress;
+        }
+
+        // ── ClaimReward ──────────────────────────────────────────────────────────
+
+        [CloudCodeFunction("ClaimReward")]
+        public async Task<BattlePassProgress> ClaimReward(
+            [CloudCodeService] IExecutionContext context, [CloudCodeService] IGameApiClient client,
+            string passId, int tierNumber, string rewardType)
+        {
+            if (rewardType != "free" && rewardType != "premium")
+                throw new Exception(
+                    $"Invalid rewardType: '{rewardType}'. Must be 'free' or 'premium'.");
+
+            RequireActive(passId);
+
+            var allProgress = await LoadProgressAsync(context, client);
+
+            if (!allProgress.TryGetValue(passId, out var progress))
+                throw new Exception($"No progress found for pass '{passId}'. Award XP first.");
+
+            if (!PassTiers.TryGetValue(passId, out var tiers))
+                throw new Exception($"Unknown pass '{passId}'.");
+
+            var tier = tiers.FirstOrDefault(t => t.TierNumber == tierNumber)
+                ?? throw new Exception($"Tier {tierNumber} does not exist in pass '{passId}'.");
+
+            if (progress.CurrentXp < tier.XpRequired)
+                throw new Exception(
+                    $"Tier {tierNumber} not yet reached ({progress.CurrentXp}/{tier.XpRequired} XP).");
+
+            if (rewardType == "premium" && !progress.HasPremium)
+                throw new Exception("Premium pass not owned. Purchase premium first.");
+
+            var rewardKey = $"tier_{tierNumber}_{rewardType}";
+            if (progress.ClaimedRewards.Contains(rewardKey))
+                throw new Exception($"Reward '{rewardKey}' already claimed.");
+
+            progress.ClaimedRewards.Add(rewardKey);
+            allProgress[passId] = progress;
+            await SaveProgressAsync(context, client, allProgress);
+
+            return progress;
+        }
+
+        // ── PurchasePremium ──────────────────────────────────────────────────────
+
+        [CloudCodeFunction("PurchasePremium")]
+        public async Task<BattlePassProgress> PurchasePremium(
+            [CloudCodeService] IExecutionContext context, [CloudCodeService] IGameApiClient client, string passId)
+        {
+            var allProgress = await LoadProgressAsync(context, client);
+
+            if (!allProgress.TryGetValue(passId, out var progress))
+                progress = new BattlePassProgress { CurrentTier = 1, ClaimedRewards = new List<string>() };
+
+            if (progress.HasPremium)
+                return progress;   // idempotent -- already owns premium
+
+            // Replace this throw with server-side purchase validation, then set HasPremium.
+            throw new Exception("PurchasePremium requires server-side purchase validation.");
+        }
+
+        // ── Helpers ──────────────────────────────────────────────────────────────
+
+        static void RequireActive(string passId)
+        {
+            if (!PassWindows.TryGetValue(passId, out var window))
+                throw new Exception($"Unknown pass '{passId}'.");
+
+            var now = DateTime.UtcNow;
+            if (now < window.Start || now >= window.End)
+                throw new Exception($"Pass '{passId}' is not active.");
+        }
+
+        static int CalculateTier(int currentXp, List<BattlePassTierThreshold> tiers)
+        {
+            var reached = tiers
+                .Where(t => currentXp >= t.XpRequired)
+                .OrderByDescending(t => t.TierNumber)
+                .FirstOrDefault();
+
+            return reached?.TierNumber ?? 1;
+        }
+
+        async Task<Dictionary<string, BattlePassProgress>> LoadProgressAsync(
+            IExecutionContext context, IGameApiClient client)
+        {
+            var result = await client.CloudSaveData.GetProtectedItemsAsync(
+                context, context.ServiceToken, context.ProjectId,
+                context.PlayerId!, new List<string> { ProgressKey });
+
+            var value = result.Data?.Results?.FirstOrDefault()?.Value?.ToString();
+            if (string.IsNullOrEmpty(value))
+                return new Dictionary<string, BattlePassProgress>();
+
+            return JsonConvert.DeserializeObject<Dictionary<string, BattlePassProgress>>(value)
+                ?? new Dictionary<string, BattlePassProgress>();
+        }
+
+        async Task SaveProgressAsync(
+            IExecutionContext context, IGameApiClient client,
+            Dictionary<string, BattlePassProgress> progress)
+        {
+            var json = JsonConvert.SerializeObject(progress);
+            var body = new SetItemBody(ProgressKey, json);
+            await client.CloudSaveData.SetProtectedItemAsync(
+                context, context.ServiceToken, context.ProjectId, context.PlayerId!, body);
+        }
+    }
+}
+```
+
+### Server-Side Models (inside BattlePassModule.cs)
+
+The single definition of both types, in the module's `Cloud` namespace. Use public members with a public getter and setter, as the auto-properties below: the generator copies only those into the client stub of `BattlePassProgress`, as `{ get; set; }` properties, and `Newtonsoft.Json` serializes them for Cloud Save. Do not declare a second `BattlePassProgress` in client code.
+
+```csharp
+namespace BattlePassModule.Cloud
+{
+    public class BattlePassProgress
+    {
+        public int CurrentXp { get; set; }
+        public int CurrentTier { get; set; }
+        public bool HasPremium { get; set; }
+        public List<string> ClaimedRewards { get; set; } = new();
+    }
+
+    public class BattlePassTierThreshold
+    {
+        public int TierNumber { get; set; }
+        public int XpRequired { get; set; }
+    }
+}
+```
+
+---
+
+## Cloud Resources
+
+### Remote Config `.rc` File
+
+Place at `Assets/BattlePasses.rc`. Contains pass definitions as a JSON array under the `"battle_passes"` key. Example with two concurrent passes:
+
+```json
+{
+  "$schema": "https://ugs-config-schemas.unity3d.com/v1/remote-config.schema.json",
+  "entries": {
+    "battle_passes": [
+      {
+        "PassId": "season_03",
+        "Name": "Season 3",
+        "StartDate": "2024-01-01T00:00:00Z",
+        "EndDate": "2026-06-30T23:59:59Z",
+        "Tiers": [
+          { "TierNumber": 1, "XpRequired": 0,    "FreeRewardId": "item_bronze_badge",      "PremiumRewardId": "item_gold_frame" },
+          { "TierNumber": 2, "XpRequired": 500,  "FreeRewardId": "item_xp_boost",          "PremiumRewardId": "item_rare_skin_fragment" },
+          { "TierNumber": 3, "XpRequired": 1200, "FreeRewardId": "item_silver_badge",      "PremiumRewardId": "item_legendary_skin" }
+        ]
+      },
+      {
+        "PassId": "easter_2026",
+        "Name": "Easter Event 2026",
+        "StartDate": "2026-04-01T00:00:00Z",
+        "EndDate": "2026-04-21T23:59:59Z",
+        "Tiers": [
+          { "TierNumber": 1, "XpRequired": 0,    "FreeRewardId": "item_egg_basket",     "PremiumRewardId": "item_golden_egg" },
+          { "TierNumber": 2, "XpRequired": 300,  "FreeRewardId": "item_bunny_ears",     "PremiumRewardId": "item_bunny_mount" }
+        ]
+      }
+    ]
+  },
+  "types": {
+    "battle_passes": "JSON"
+  }
+}
+```
+
+**Rules:**
+
+- `PassId` must be unique across all passes and stable over time — it is the key used in player
+  progress records. Never rename a `PassId` after launch.
+- `XpRequired` is **cumulative** XP to reach the tier, not a delta from the previous tier.
+  Tier 1 must always have `XpRequired: 0` so it is immediately reachable.
+- `FreeRewardId` / `PremiumRewardId` are arbitrary strings. The client reads these IDs and maps
+  them to display names/icons locally. `ClaimReward` records the claim in `ClaimedRewards`; the game grants what
+  the ID stands for — unlock it client-side from the claimed set, or have the module grant it through
+  Cloud Save Protected or another Cloud Code call alongside the claim.
+  - Treat a claim as an entitlement only if the XP behind it is trustworthy. The sample `AwardXp`
+    accepts any `amount` up to the `MaxXpPerSource` cap from a signed-in client, so before
+    granting anything valuable, derive XP from server-verified events (or make `AwardXp`
+    non-client-callable and drive it from server-validated events).
+  - Make the grant idempotent and retryable from the saved claim: if the grant fails after the claim
+    is saved, a retry of `ClaimReward` fails its duplicate-claim check, so grant from the stored claim
+    (or persist claim and grant in one recoverable operation) rather than only on the first call.
+  - `ClaimedRewards` stores keys such as `tier_1_free`, not reward IDs. Keep reward IDs immutable
+    for the life of a pass, or store the granted reward ID with the claim, so a changed ID cannot
+    unlock a different reward for an old claim.
+- Date filtering happens **client-side** after fetch. Add passes to the file before their
+  `StartDate` — they will be ignored by the client until the start time is reached.
+
+### Cloud Code Module
+
+> Create the module files listed in [Cloud Code Module Implementation](#cloud-code-module-implementation) above.
+> See the Creating a Cloud Code Module section of `references/cloud-code-modules.md`
+> for the generic templates; replace `MyModule` with `BattlePassModule`.
+>
+> The `.ccmu` is deployed by the Deployment Window like any other cloud asset, but its code is compiled by
+> Unity — a project that does not compile has nothing to deploy.
+
+### Access Control
+
+**No Access Control (`.ac`) file is needed for the battle pass.** The Cloud Save Protected bucket is inherently server-only for writes -- only Cloud Code (using `IGameApiClient` with the service token) can write to it. Clients can read Protected data but cannot modify it.
+
+> **Contrast with achievements:** The achievements skill offered a direct-write dev path using
+> the Public bucket, which required an explicit Access Control policy to lock down in production.
+> Battle pass has no direct-write path, so there is nothing to lock down.
+
+### `manifest.json` Entries
+
+Ensure these packages are listed in `Packages/manifest.json`:
+
+```json
+{
+  "dependencies": {
+    "com.unity.services.authentication": "3.6.1",
+    "com.unity.services.cloudcode": "3.0.0",
+    "com.unity.services.cloudsave": "3.4.0",
+    "com.unity.services.core": "1.16.0",
+    "com.unity.services.deployment": "1.7.2",
+    "com.unity.remote-config": "4.2.5",
+    "com.unity.services.tooling": "1.4.1",
+    "com.unity.nuget.newtonsoft-json": "3.2.2"
+  }
+}
+```
+
+> `com.unity.services.cloudcode` **`3.0.0`** is the native-authoring line, which the `.ccmu` module
+> below requires — see the Requirements section of `references/cloud-code-modules.md`. The `2.10.x` line
+> deploys legacy `.ccmr` modules only; use it when maintaining one, not for new work.
+
+
+`com.unity.nuget.newtonsoft-json` is required for `JsonConvert` used in serialization of tier data and progress.
+
+---
+
+## Deployment Checklist
+
+- [ ] All packages added to `Packages/manifest.json`
+- [ ] Remote Config `.rc` file created with `"battle_passes"` entry and at least one active pass
+- [ ] Cloud Code module authored as a `.ccmu`: module asset, `Cloud/` + `Client/` asmdefs, endpoint class, `CloudSetup.cs` (see file list in [Cloud Code Module Implementation](#cloud-code-module-implementation))
+- [ ] `BattlePassModule.cs` added to the module project with `AwardXp`, `ClaimReward`, `PurchasePremium` functions
+- [ ] Environment selected in **Services > Deployment** settings
+- [ ] Deploy all via the Deployment Window: select `BattlePasses.rc` and `BattlePassModule.ccmu`, click **Deploy**
+- [ ] Project linked in **Edit > Project Settings > Services**
+
+---
+
+## Validation
+
+After implementing the battle pass feature, verify:
+
+1. **Project compiles** without errors — the module's Editor-only cloud assembly is compiled with the rest of the Unity project.
+2. **Initialization order** is correct: `UnityServices.InitializeAsync()` then `AuthenticationService.Instance.SignInAnonymouslyAsync()` then service calls.
+3. **Protected bucket reads** use `ProtectedReadAccessClassOptions` -- using the wrong access class returns no data.
+4. **Client bindings resolve**: the game assembly references the module's client assembly and calls `BattlePassModuleClient`. The deployed module name is the **cloud asmdef name**, `BattlePassModule` (the `name` field of `Cloud/BattlePassModule.asmdef`), not the `.ccmu` filename.
+5. **One progress definition**: `BattlePassProgress` is declared only in the Cloud Code module, as `{ get; set; }` properties, and the client uses its generated stub.
+6. **No direct client writes** to `"battle_pass_progress"` -- all mutations go through Cloud Code.
+7. **No client-supplied tier data**: `AwardXp` and `ClaimReward` use the module's server-side `PassTiers`, which matches the `XpRequired` values in `BattlePasses.rc`, and reject passes outside the server-side `PassWindows` (matching `StartDate`/`EndDate`).
+8. **Date filtering** uses `DateTime.UtcNow` with `DateTimeStyles.RoundtripKind` for consistent UTC parsing.
+9. **Cloud resources** are present and deployable: `BattlePasses.rc` and `BattlePassModule.ccmu` appear in the Deployment Window.
+10. **PurchasePremium is an integration stub** -- it returns existing progress when `HasPremium` is already true and otherwise throws until you add purchase validation.
+11. **ClaimReward validates** the pass window (`PassWindows`), tier reach (against `PassTiers`) and premium ownership before recording the claim.
+12. **Premium purchasing is not deployable until a validated purchase flow sets `HasPremium`** -- keep the fail-closed throw until then.
+
+---
+
+## Asset Store & Sample Projects
+
+- **Use Case Samples — Battle Pass:** The official [Use Case Samples](https://github.com/Unity-Technologies/com.unity.services.samples.use-cases) repository includes a complete Battle Pass sample with seasonal reward tiers, free/premium tracks, time-limited rewards, and server-authoritative progression via Cloud Code. Clone the repo and open the "Battle Pass" scene for a working reference.