XP Guide

[DannyIsYog]

Add XP progression guide (Nakama + Hiro + Unity)

Summary

Adds the XP Guide companion project under Guides/: an end-to-end XP progression system built on Hiro's Achievements and Economy systems, with a Nakama server plugin and a Unity client.

The guide demonstrates how to model player levels as sub-achievements driven by an XP currency, so that granting XP anywhere in the game automatically advances the player's level without callers needing to know levelling exists.

How it works

XP is a currency, and levels are sub-achievements of a player_levels group, each with a max_count equal to the XP required to complete it (100, 200, ... 1000 for levels 1–10).

The flow:

1. The client calls rpc_grant_xp with a base amount.
2. The RPC rolls and grants a reward containing the xp currency via the Economy reward APIs, so active modifiers (e.g. a double-XP booster) apply.
3. XPLevelPublisher listens for the currencyGranted event on xp and advances the level sub-achievements by the actual granted amount.
4. XP overflows across levels in a single batched UpdateAchievements call, so one large grant can complete several levels and partially fill the next.
5. Levels are auto_claim, so completing one grants its gem reward immediately.

Routing progression through the publisher rather than the RPC means any future XP source gets levelling for free.

The quest group (defeat_thunder_world) exists to exercise the loop from a realistic source: its sub-quests grant XP, gems, and coins, and one of them grants a 2× XP reward modifier for 120 seconds, which the client surfaces as an active-booster badge.

Testing

• XPControllerTests pass against a local Nakama instance.
• Manually verified the full loop: grant XP → level up → auto-claimed gem reward, and completing defend_the_village activates the 2× booster badge and doubles subsequent XP grants.