PlayerProgressionService class
Single source of truth for one player's XP/level — persists
PlayerProgressionSnapshot.totalXpEarned (never level/xpIntoLevel
directly, both are always re-derived from it and the curve) plus a
bounded idempotency ledger, same pattern as EconomyWallet/
RewardTransactionPipeline (FEAT-31/FEAT-42): a corrupt save resets to
a fresh, never-exploitable state instead of throwing or trusting a
partially-decoded value.
- Inheritance
-
- Object
- GetLifeCycle
- DisposableInterface
- GetxService
- PlayerProgressionService
Constructors
-
PlayerProgressionService({required StorageService storage, required List<
LevelDefinition> levelCurve, RewardTransactionPipeline? pipeline, AsyncActionGuard? guard, String? storageKey, int capacity = 200})
Properties
- capacity → int
-
final
- hashCode → int
-
The hash code for this object.
no setterinherited
- initialized → bool
-
Checks whether the controller has already been initialized.
no setterinherited
- isClosed → bool
-
Checks whether the controller has already been closed.
no setterinherited
-
onDelete
→ InternalFinalCallback<
void> -
Internal callback that starts the cycle of this controller.
finalinherited
-
onLevelUp
→ Rx<
LevelUpEvent?> -
Fires once per level crossed by the most recent grantXp call —
nulluntil the first level-up. Not persisted (a UI popup trigger, not durable state); PlayerProgressionSnapshot is the durable source.final -
onStart
→ InternalFinalCallback<
void> -
Called at the exact moment the widget is allocated in memory.
It uses an internal "callable" type, to avoid any @overrides in subclases.
This method should be internal and is required to define the
lifetime cycle of the subclass.
finalinherited
- pipeline → RewardTransactionPipeline?
-
final
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
-
snapshot
→ Rx<
PlayerProgressionSnapshot> -
final
- storage → StorageService
-
final
Methods
-
$configureLifeCycle(
) → void -
inherited
-
grantXp(
{required int amount, required String transactionId}) → Future< SdkResult< PlayerProgressionSnapshot> > -
Grants
amountXP undertransactionId(idempotent — calling this again with the same id, even after a restart, is a no-op that returns the current snapshot). If this crosses one or more level thresholds, each newly-reached level's LevelDefinition.unlockRewardLines (if any) is granted exactly once through pipeline (when supplied), and onLevelUp fires once per level, in order — the level is capped at the curve's max level regardless of how much XP is granted past it. -
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
onClose(
) → void -
Called before
onDeletemethod.onClosemight be used to dispose resources used by the controller. Like closing events, or streams before the controller is destroyed. Or dispose objects that can potentially create some memory leaks, like TextEditingControllers, AnimationControllers. Might be useful as well to persist some data on disk.inherited -
onInit(
) → void -
Called immediately after the widget is allocated in memory.
You might use this to initialize something for the controller.
override
-
onReady(
) → void -
Called 1 frame after onInit(). It is the perfect place to enter
navigation events, like snackbar, dialogs, or a new route, or
async request.
inherited
-
toString(
) → String -
A string representation of this object.
inherited
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited
Static Properties
- maybe → PlayerProgressionService?
-
no setter