Echo Leaderboard

Package: com.amanotes.echo.leaderboard v1.0.7
Unity: 2022.3+
Namespace: Amanotes.Echo.Leaderboard
Dependencies: com.amanotes.orchestra 0.2.41, com.amanotes.echo.foundation 1.0.1, visual-state-2 0.9.3, com.annulusgames.lit-motion 2.0.1 (com.mukarillo.dynamicscrollrect is vendored under ThirdParty/DynamicScrollRect/ — no separate install needed)

Mock-player leaderboard system for Echo games. Includes time-based contests, global/local rankings, bot profiles, an optional gated ("Manual") contest-start flow, and a setup wizard for host-project integration.

Setup

1. Add the package: it's already embedded under Packages/ in this repo, or install it into another project via scoped registries. In that project's Packages/manifest.json:

   {
     "scopedRegistries": [
       {
         "name": "Amanotes",
         "url": "https://registry.npmjs.org",
         "scopes": ["com.amanotes"]
       },
       {
         "name": "OpenUPM",
         "url": "https://package.openupm.com",
         "scopes": ["com.annulusgames.lit-motion"]
       }
     ],
     "dependencies": {
       "com.amanotes.echo.leaderboard": "1.0.7"
     }
   }

   • com.amanotes.echo.foundation resolves automatically as a transitive dependency. No auth token needed — these are public packages on npmjs.org.
   • The OpenUPM registry covers com.annulusgames.lit-motion (rank-change animation — replaces DOTween, which can't be redistributed since it's a paid Asset Store plugin).
   • visual-state-2 has no registry of its own — it isn't published anywhere (npmjs.org, OpenUPM, or otherwise). Installing via a scoped registry (as above) only works if your project already has visual-state-2 present (e.g. embedded under its own Packages/visual-state-2/), otherwise Unity's Package Manager fails to resolve it. If you don't already have it, install via the exported .unitypackage instead (Echo → Leaderboard → Export Package, or Echo → Export All Modules…) — its ExportPackageOptions.Recurse bundles the module's visual-state-2 asset dependencies into the .unitypackage automatically, no separate step needed. (Same caveat applies to every other Echo module depending on visual-state-2 — see the DailyReward package's README.)
2. Run Echo → Leaderboard → Setup Wizard — generates the host-integration layer into your game's Assets/_Echo/ across 4 steps: Prerequisites → Initialization (wires LeaderboardManager.Initialize() into your loading sequence) → Host Setup (Tab or Full-Screen integration) → Done. Every patch it makes is reversible via Remove All Integration.
3. Wire the generated bridge's // TODO: markers to your host systems (PlayerData, currency rewards). The shipped LeaderboardIconUI (a floating icon Button) self-manages visibility and routes taps through LeaderboardManager.OpenLeaderboard() — a single entry point that opens LeaderboardView if the contest is running, or re-shows the pending-start popup if it's unlocked but not yet started. No host code needed beyond assigning the button/container references.
4. Optional: gate the contest behind a "Start" button. By default (LeaderboardConfig.StartMode = Auto) the contest starts immediately on unlock. Set it to Manual in the LeaderboardConfig asset inspector to instead show LeaderboardStartEventPopup on unlock and wait for the player to press Start (LeaderboardManager.StartEventManually()). Dismissing the popup without pressing Start just leaves it pending — LeaderboardManager.HasPendingEventStart stays true until the player opts in.
5. To try the module standalone with zero host code, import the Leaderboard Entry Point sample (Package Manager → Echo Leaderboard → Samples) and open Samples/Scenes/LeaderboardSample.unity — or, if the package is embedded in your project, open that scene directly (embedded packages are fully writable, unlike a package resolved into Library/PackageCache/, which Unity mounts read-only). Press Play: LeaderboardSampleBootstrap initializes LeaderboardManager and force-unlocks it; tap the floating LeaderboardIcon to open LeaderboardView. This scene is for demoing/testing only — the Setup Wizard ignores it when scanning your project so it doesn't get mistaken for a real host integration.

Debug tooling

Two interchangeable options — both call the same LeaderboardManager public API, so their cheats never drift out of sync:

• With SRDebugger: SRCheat.Leaderboard.cs, generated by the Setup Wizard, adds a Force Unlock / Add Score / Force Contest End / Log TimeBased Status panel to the SRDebugger overlay. It's the only file in this module that depends on the third-party SRDebugger plugin and isn't declared as a package dependency — if your target project doesn't have SRDebugger, either install it, use LeaderboardDebugGUI instead, skip bundling SRCheat.Leaderboard.cs (uncheck it in the Exporter's "Optional host-side files" list, or delete it after import), or define DISABLE_SRDEBUGGER to strip it without deleting the file (it's already gated behind #if !DISABLE_SRDEBUGGER).
• Without SRDebugger: drop LeaderboardDebugGUI (Scripts/Debug/LeaderboardDebugGUI.cs, ships with the module, zero third-party dependencies) onto any scene GameObject for the same cheats via a plain OnGUI() toggle panel. Already included in the sample scene.

Architecture

LeaderboardManager (logic) + LeaderboardConfig (tunables, bot profiles, event start mode) + time-based contest services + DynamicScrollRect-backed ranking UI. The module emits KEventBus events and never references host systems directly.

See Leaderboard.md for the full design doc.