ProgressionKit

A reusable progression engine that turns player performance into configurable XP, levels, and unlocks across games and apps. 📈

ProgressionKit is a pure Swift package for apps and games that need deterministic progression logic without coupling progression rules to storage or UI frameworks.

It models:

• XP gain from successful performance.
• Player levels derived from total XP.
• Track-scoped mastery across distinct content.
• Tier unlocks such as beginner, intermediate, and advanced.

The package is deliberately content-agnostic. Host apps decide what a track, content item, and tier mean, then feed those identifiers into ProgressionKit.

Implemented APIs

• PKEngine: applies a progression event to a profile and returns the updated profile plus derived progress values.
• PKProfile: persisted progression state for a player.
• PKConfig: tunable progression rules such as level size, XP reward, tier order, and unlock thresholds.
• PKEvent: a single outcome emitted by the host app.
• PKUpdate: the result of applying one event.

Structure

flowchart TB
  subgraph HOST["Host App/Game"]
    EVENTS["Performance Events"]
    STORAGE["Storage Layer"]
    UI["UI / HUD / XP Bar"]
  end

  subgraph PK[" "]
    ENGINE["ProgressionKit"]
    PROFILE["PKProfile"]
    CONFIG["PKConfig"]
    UPDATE["PKUpdate"]
  end

  EVENTS --> ENGINE
  CONFIG --> ENGINE
  ENGINE --> PROFILE
  ENGINE --> UPDATE
  PROFILE --> STORAGE
  UPDATE --> UI

Loading

Integration

Xcode

Use Xcode's built-in support for SPM.

or...

Package.swift

In your Package.swift, add ProgressionKit as a dependency:

dependencies: [
    .package(
        url: "https://github.com/thatfactory/progressionkit",
        from: "0.1.0"
    )
]

Associate the dependency with your target:

targets: [
    .target(
        name: "YourTarget",
        dependencies: [
            .product(
                name: "ProgressionKit",
                package: "progressionkit"
            )
        ]
    )
]

Run: swift build