Echo ClefCollection

Package: com.amanotes.echo.clefcollection v1.0.1
Unity: 2022.3+
Namespace: Amanotes.Echo.ClefCollection
Dependencies: com.amanotes.orchestra 0.2.41, com.amanotes.echo.foundation 1.0.0

Time-limited collectible event module for Echo games. Supports duration and weekly-schedule modes, milestone rewards, an optional grand prize, and auto/manual start modes.

Setup

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

   {
     "scopedRegistries": [
       {
         "name": "Amanotes",
         "url": "https://registry.npmjs.org",
         "scopes": ["com.amanotes"]
       }
     ],
     "dependencies": {
       "com.amanotes.echo.clefcollection": "1.0.1"
     }
   }

   com.amanotes.echo.foundation resolves automatically as a transitive dependency. No auth token needed — these are public packages on npmjs.org.
2. Run Echo → ClefCollection → Setup Wizard — generates the host-integration layer into your game's Assets/_Echo/ across 4 tabs: Prerequisites → Initialization (wires ClefCollectionManager.Initialize() into your loading sequence) → Host Setup (ClefCollectionBridge, ClefCollectionConfigBridge, SRCheat.ClefCollection) → Done.
3. Wire the generated bridge's // TODO: markers to your host systems (PlayerData, Ads, etc.).
4. Optional: gate the event behind a "Start" button. By default (ClefCollectionConfig start mode = Auto) the event starts immediately on unlock. Switch it to Manual in the ClefCollectionConfig asset inspector to instead show ClefEventStartPopup on unlock and wait for the player to press Start (ClefCollectionManager.StartEventManually()).
5. To try the module standalone with zero host code, open Packages/com.amanotes.echo.clefcollection/Samples/Scenes/ClefCollectionSample.unity and press Play — ClefCollectionSampleBootstrap initializes ClefCollectionManager and force-unlocks the event, and ClefCollectionDebugGUI gives you a toggleable cheat panel. Or import it via Package Manager → Echo ClefCollection → Samples → Import "ClefCollection Entry Point". This scene is for demoing/testing only.

Debug tooling

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

• With SRDebugger: SRCheat.ClefCollection.cs, generated by the Setup Wizard, adds a Force Unlock / Add Clef Token / Force End / Log Status panel to the SRDebugger overlay.
• Without SRDebugger: drop ClefCollectionDebugGUI (Scripts/Debug/ClefCollectionDebugGUI.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

ClefCollectionManager (logic) + ClefCollectionConfig (tunables) + ClefCollectionFileStorage (persistence) + ClefCollectionState (read model) + ClefCollectionService (facade). The module emits KEventBus events and never references host systems directly — all host coupling lives in the generated *Bridge files.

See ClefCollection.md for the full design doc.