punkfuncgames/achievement-module

AchievementModule Reference

Package: com.punkfuncgames.achievement | Define: PUNKFUNC_ACHIEVEMENT Location: Packages/com.punkfuncgames.achievement/Runtime/PunkFuncGames.Achievement/ Namespace: PunkFuncGames.Achievement

IAchievementService : IService, IAsyncInitializable, IResettable

Registration:

• Register(AchievementDefinition) — registers single definition, applies loaded save data
• Register(IEnumerable<AchievementDefinition>) — batch registration
• Unregister(AchievementDefinition) — removes from tracking and indexes

Queries:

• bool IsUnlocked(AchievementDefinition/string) — check unlock state
• float GetProgress(AchievementDefinition/string) — returns 0-1 progress (1 if unlocked)
• ReadOnlyReactiveProperty<bool> ObserveUnlocked(string) — reactive unlock observation
• AchievementDefinition GetDefinition(string) — lookup by DisplayNameKey
• IReadOnlyList<AchievementDefinition> GetAll() — all registered
• IReadOnlyList<AchievementDefinition> GetUnlocked() — unlocked only
• IReadOnlyList<AchievementDefinition> GetLocked() — locked only
• IReadOnlyList<AchievementDefinition> GetByCategory(string) — filter by category
• int RegisteredCount — total registered
• int UnlockedCount — total unlocked
• ReadOnlyReactiveProperty<int> UnlockedCountReactive — reactive unlocked count for UI binding

Evaluation:

• EvaluateAll() — force evaluate all achievements (gated by IsPlayable)
• UniTask SyncWithSteamAsync(CancellationToken) — bidirectional Steam sync

Events (MessagePipe)

All events are readonly struct in PunkFuncGames.GameTemplate.Runtime.AchievementModule.Event:

| Event | Fields | Published When | |-------|--------|---------------| | AchievementUnlockedEvent | Achievement, UnlockedAt | Achievement unlocks | | AchievementProgressChangedEvent | Achievement, NewProgress, PreviousProgress | Progress value changes |

AchievementDefinition (ScriptableObject)

[CreateAssetMenu(menuName = "PunkFuncGames/Achievement/Achievement Definition")]

| Field | Type | Purpose | |-------|------|---------| | DisplayNameKey | string | Localization key (auto-set from SO.name) | | DescriptionKey | string | Localization key (auto-set to name + "_desc") | | Category | string | Grouping: "Combat", "Exploration", etc. | | Icon | Sprite | Achievement icon | | Color | Color | Display color (default white) | | UnlockCondition | UnlockConditionConfig | Composable AND/OR/NOT condition | | IsProgressive | bool | Enables stat-driven progress tracking | | ProgressStat | StatsDefinition | Stat to track (DrawIf IsProgressive) | | ProgressTarget | SerializableBigDouble | Target value (DrawIf IsProgressive) | | SteamAchievementId | string | Steam API achievement name | | CurrencyRewards | AchievementCurrencyReward[] | Currency rewards on unlock | | StatRewards | AchievementStatReward[] | Stat rewards on unlock | | IsHidden | bool | Hidden from UI until unlocked | | SortOrder | int | Display ordering |

AchievementDatabaseConfig (ScriptableObject)

[CreateAssetMenu(menuName = "PunkFuncGames/Achievement/Achievement Database")]

Single source of truth — holds all AchievementDefinition[] for bulk registration. Serialized on ProjectLifetimeScope.

Reward Types

[Serializable]
public struct AchievementCurrencyReward
{
    public CurrencyDefinition Currency;
    public SerializableBigDouble Amount;
}

[Serializable]
public struct AchievementStatReward
{
    public StatsDefinition Stat;
    public SerializableBigDouble Amount;
}

Service Implementation Details

Class: AchievementService : IAchievementService, IAsyncStartable, ITickable, IDisposable

Constructor Dependencies (11): ISaveService, ILogService (nullable), IStatsService, IWalletService, ISteamAchievementService, IGameStateService, IObjectResolver, AchievementDatabaseConfig, IPublisher<AchievementUnlockedEvent>, IPublisher<AchievementProgressChangedEvent>, ISubscriber<StatChangedEvent>

Key Behaviors:

• Game State Gating: Evaluation paused when IGameStateService.IsPlayable is false
• Stat-Driven Evaluation: StatChangedEvent triggers O(1) lookup via progressive index
• Periodic Evaluation: Non-progressive achievements evaluated every 2s in Tick()
• Circular Guard: IsUnlocked check prevents re-unlock when stat rewards trigger new events
• Persistence: Dirty flag + 5s save interval, ISO 8601 DateTime serialization
• Steam Sync: Bidirectional (local→Steam, Steam→local), fire-and-forget on unlock
• Rewards: CurrencyChangeSource.Reward + StatChangeSource.Achievement

Progress Calculation:

• Progressive: Clamp01(statsService.GetValue(ProgressStat) / ProgressTarget)
• Non-progressive with condition: UnlockCondition.GetProgress(_objectResolver)
• Neither: 0f
• Guard: ProgressTarget <= BigDouble.Zero → 0f

Unlock Decision:

1. If UnlockCondition != null and not met → false
2. If progressive and progress < 1f → false
3. If non-progressive and no condition → false
4. Otherwise → true

Installer

public static class AchievementInstaller
{
    public static void Install(IContainerBuilder builder, MessagePipeOptions options)
    {
        builder.RegisterEntryPoint<AchievementService>().As<IAchievementService>();
        builder.RegisterMessageBroker<AchievementUnlockedEvent>(options);
        builder.RegisterMessageBroker<AchievementProgressChangedEvent>(options);
    }
}

ProjectLifetimeScope registration:

builder.RegisterInstance(_achievementDatabase);
AchievementInstaller.Install(builder, options);

Dependencies

| Module | Relationship | |--------|-------------| | UnlockConditionModule | UnlockConditionConfig for composable unlock conditions | | StatsModule | IStatsService for progress values, StatsDefinition for progressive tracking | | WalletModule | IWalletService for currency reward application | | SteamModule | ISteamAchievementService for platform sync | | GameStateModule | IGameStateService.IsPlayable for evaluation gating | | SaveModule | ISaveService for persistence | | LogModule | ILogService for diagnostic logging (nullable) |

Test Helpers

• MockFactory.CreateAchievementService() — mock with configurable counts
• TestFixtures.CreateAchievementDefinition() — SO with all fields configurable
• TestFixtures.CreateAchievementDatabaseConfig(params AchievementDefinition[]) — database config

File Structure

Packages/com.punkfuncgames.achievement/Runtime/PunkFuncGames.Achievement/
  Config/AchievementDatabaseConfig.cs
  Event/AchievementEvents.cs
  Installer/AchievementInstaller.cs
  Model/AchievementDefinition.cs
  Model/AchievementCurrencyReward.cs
  Model/AchievementStatReward.cs
  Service/IAchievementService.cs
  Service/AchievementService.cs
Packages/com.punkfuncgames.achievement/Tests/EditMode/
  AchievementDefinitionTests.cs
  AchievementServiceTests.cs