API

Assembly: Spark.Progression Interface: IProgressionPlugin Implementation: ProgressionPlugin

Interface

public interface IProgressionPlugin
{
    // Create/destroy
    ProgressionInstance CreateProgression(string entityId,
        LevelingEntry levelingEntry, string progressionId = null);
    ProgressionInstance CreateProgressionFromInstance(string entityId,
        ProgressionInstanceEntry instanceEntry, string progressionId = null);
    bool DestroyProgression(string progressionId);

    // Queries
    ProgressionInstance GetProgression(string progressionId);
    ProgressionInstance GetEntityProgression(string entityId,
        string levelingId);
    ProgressionInstance GetEntityProgressionByInstance(string entityId,
        string progressionInstanceId);
    ProgressionInstance[] GetAllEntityProgressions(string entityId);

    // XP and leveling
    bool AwardExperience(string progressionId, int amount,
        string sourceId = null, GameObject source = null);
    bool SetLevel(string progressionId, int targetLevel,
        GameObject source = null);

    // State queries
    int GetLevel(string progressionId);
    int GetExperience(string progressionId);
    int GetExperienceForNextLevel(string progressionId);
    float GetLevelProgress(string progressionId);
    bool CanLevelUp(string progressionId);
    bool HasReachedLevelCap(string progressionId);

    // Persistence
    void LoadEntityProgressionsFromSave(string entityId);
}

Database Entries

LevelingEntry

Extends SparkDatabaseEntry. Defines an XP curve.

Field	Type	Description
progressionType	ProgressionType	Finite or Infinite
startingLevel	int	Initial level (default 1)
levelCap	int	Maximum level for Finite type
softCapLevel	int	Soft cap for Infinite type
postCapXpMultiplier	float	XP scaling after soft cap
curveType	ExperienceCurveType	Linear, Exponential, or Logarithmic
baseExperienceRequired	int	XP for first level-up
experienceGrowthFactor	float	Per-level scaling factor
logarithmicScale	float	Scale for logarithmic curve
customExperiencePerLevel	List<int>	Manual per-level XP values

Methods:

int GetExperienceRequiredForLevel(int level)
int GetTotalExperienceForLevel(int level)
bool IsValidLevel(int level)

ProgressionInstanceEntry

Extends SparkDatabaseEntry. Pre-configured progression template.

Field	Type	Description
levelingTemplate	LevelingEntry	XP curve reference
allowRuntimeAssignment	bool	Can unlock during gameplay
defaultUnlocked	bool	Starts unlocked
levelUpRewards	List<LevelUpReward>	Rewards on level-up

LevelUpReward

Rewards triggered at specific levels.

Field	Type	Description
level	int	Trigger at this level (or range start)
triggers	List<TriggerEntry>	Actions to execute

ProgressionInstance

Runtime progression state.

Field	Type	Description
progressionId	string	Unique identifier
entityId	string	Owner entity
progressionInstanceId	string	Reference to ProgressionInstanceEntry
levelingEntryId	string	Reference to LevelingEntry
currentLevel	int	Current level (1-based)
currentExperience	int	XP toward next level
createdTimestamp	long	When created
lastLevelUpTimestamp	long	When last leveled up

Methods:

void AddExperience(int amount)
void SetLevel(int level)
void SetExperience(int amount)
int GetExperienceRequiredForNextLevel()
float GetProgressToNextLevel()
bool CanLevelUp()
bool HasReachedLevelCap()
ProgressionSnapshot CreateSnapshot()
void RestoreFromSnapshot(ProgressionSnapshot snapshot)

Events

Event	Key Fields	Description
ExperienceGainedEvent	progressionId, amount, totalXp, currentLevel, sourceId	XP awarded
LevelUpEvent	progressionId, entityId, newLevel, previousLevel	Level increased via XP
LevelChangedEvent	progressionId, entityId, newLevel, oldLevel	Level set directly

Commands

Command	Fields	Description
AwardExperienceCommand	ProgressionId, Amount, SourceId	Award XP
SetLevelCommand	ProgressionId, TargetLevel	Set level directly

Components

ProgressionEntity

MonoBehaviour managing multiple progressions on an entity.

Field	Type	Description
isPersistent	bool	Save to disk
autoSaveOnChange	bool	Auto-save on XP/level change
loadOnStart	bool	Load from save on enable

Methods:

void UnlockProgression(ProgressionInstanceEntry entry)
bool IsProgressionUnlocked(string progressionInstanceId)
ProgressionInstance GetProgression(string levelingId)
ProgressionInstance GetProgressionByInstance(string instanceId)
ProgressionInstance[] GetAllProgressions()
void AwardExperience(string levelingId, int amount)
int GetLevel(string levelingId)
int GetExperience(string levelingId)
float GetLevelProgress(string levelingId)
void SaveProgressionState()
void LoadProgressionState()

Events: OnProgressionCreated, OnExperienceGained, OnLevelUp

Save Data

ProgressionSaveData stores ProgressionSnapshot objects per entity for persistence.

Usage

var progression = Spark.GetPlugin<IProgressionPlugin>();
if (progression != null)
{
    // Create a progression
    var instance = progression.CreateProgressionFromInstance(
        entityId, combatLevelingInstance);

    // Award XP
    progression.AwardExperience(instance.progressionId, 500, "quest_reward");

    // Check level
    int level = progression.GetLevel(instance.progressionId);
    float progress = progression.GetLevelProgress(instance.progressionId);

    // Set level directly
    progression.SetLevel(instance.progressionId, 10);
}