YappersHQ.Progression.Shared 1.0.1

<div align="center"> <h1><strong>Progression</strong></h1> <p>Missions, achievements and a season pass for CS2 — one counting engine, driven by whatever your gamemodes emit.</p> </div>

<p align="center"> <a href="https://github.com/Kxnrl/modsharp-public"><img src="https://img.shields.io/badge/framework-ModSharp-5865F2?logo=github" alt="ModSharp"></a> <img src="https://img.shields.io/badge/game-CS2-orange" alt="CS2"> </p>

Players earn progress by playing. Objectives are defined as an event plus a filter — "10 AK headshots", "kills in Long A", "3 bomb plants" — so a new mission is authored, not coded. Daily, weekly, monthly, all-time achievements and a seasonal pass are all the same machinery with different reset rules.

🧩 How it fits together

Core contains no game knowledge. It does not know what a kill is. Every event source is a satellite — including the CS2 one — so adding a gamemode needs no change to Core. Deleting Progression.Events.CS2 leaves Core building and running.

🔌 Emitting from your gamemode

Reference YappersHQ.Progression.Shared with ExcludeAssets="runtime", resolve in OnAllModulesLoaded, and declare what you can emit:

var progression = moduleManager
    .GetOptionalSharpModuleInterface<IProgressionShared>(IProgressionShared.Identity)?.Instance;

progression?.RegisterEvent("duels.arena_won",
[
    new ProgField("arena",  ProgFieldKind.Int),
    new ProgField("weapon", ProgFieldKind.String),
]);

// later, when it happens
progression?.Emit("duels.arena_won", steamId, new Dictionary<string, object?>
{
    ["arena"]  = arenaId,
    ["weapon"] = weaponName,
});

Missions filtering on duels.arena_won can then be authored on the website with no code change — that is the entire point of the split.

Event keys are permanent. They are stored in mission definitions that live in a database for months, so namespace them by owner and never derive one from a runtime id.

Deploying it for the first time: docs/DEPLOY.md — ordered steps, each with a way to tell whether it worked, because several failures here are silent by construction (a wrong catalogue is empty, not an error).

💾 Storage — pick one

Progression stores nothing itself. Choose how it persists:

With Progression.Database, docs/example-missions.sql gives you eight working missions to start from — run it after the first boot, since objectives are only served for events a server has reported it can emit.

Writing your own is one project implementing IProgressionStore, registered in PostInit. Core resolves it in OnAllModulesLoaded and prefers it over HTTP.

You do not implement delivery. Buffering, idempotency keys, disk spill and retry stay in Core — a store is asked to write deltas and say what completed, never to re-derive exactly-once semantics. What it must guarantee is in docs/BACKEND_PROTOCOL.md.

⚙️ Configuration

Copy the examples in .assets/configs/ to <sharp>/configs/ and edit.

progression.json — Core:

progression-database.json — only if using Progression.Database:

progression-ui.json — only if using Progression.Ui:

🔧 How it works

Servers match filters locally and post only progress deltas — posting raw events would turn every kill on every server into an HTTP call. Gameplay never blocks on the network: emissions land in a buffer, a timer flushes, and a backend outage spills to disk and replays rather than losing progress.

Rewards are decided by the backend but must run on a server, so pending grants ride back in the response to the flush the server already made. No RCON, no inbound connection, no port to open.

Every delta carries an idempotency key generated at enqueue time, so replaying a batch that partially landed is safe rather than merely unlikely to double-count.

⌨️ Commands

Uses MenuManager when present and falls back to a chat listing when not. Mission titles resolve as locale keys, so a mission set can ship translations; a plain literal title still works.

📦 Build

dotnet build -c Release

Outputs .build/modules/ and .build/shared/Progression.Shared/.

To verify the MySQL store against a throwaway database (it writes rows — never point it at production):

dotnet run --project tools/StoreSelfTest -- "Server=127.0.0.1;User ID=u;Password=p;Database=throwaway"

29 checks covering idempotent replay, compare-and-swap progress, single-claim completion, grant leasing and period boundaries.

<div align="center">

Made with ❤️ by yappershq

</div>