EnergyService class
Energy/lives system that refills over time (Candy Crush-style "hearts").
Current energy is computed lazily from elapsed time since the last
baseline checkpoint, using nowMsClamped — never DateTime.now()
directly — so the same anti-cheat clamp utils/clamped_clock.dart gives
daily rewards/streaks also protects energy: winding the device clock
back can't farm free refills (see that file's doc comment for exactly
what the clamp does and doesn't defend against — a one-way forward jump
still isn't prevented, same as everywhere else that uses it).
- Inheritance
-
- Object
- GetLifeCycle
- DisposableInterface
- GetxService
- EnergyService
Constructors
- EnergyService({int maxEnergy = 5, Duration refillInterval = const Duration(minutes: 30)})
Properties
- currentEnergy → int
-
Current energy, after crediting any whole refill ticks earned since
the last checkpoint. Capped at maxEnergy.
no setter
- debugLastRegenMs → int
-
The current regen baseline timestamp — exposed for tests that need to
assert an exact elapsed-time expectation without drifting against the
real wall clock.
no setter
-
debugPendingSaves
→ Future<
void> -
Awaits every save queued so far — lets a test deterministically wait
for a burst of rapid
consumeEnergy/regen writes to fully settle instead of guessing a delay (same convention as the sibling ledger services fixed in BUG-45).no setter - hashCode → int
-
The hash code for this object.
no setterinherited
- hasInfiniteLives → bool
-
True while a grantInfiniteLives window is still active.
no setter
- initialized → bool
-
Checks whether the controller has already been initialized.
no setterinherited
- isClosed → bool
-
Checks whether the controller has already been closed.
no setterinherited
- maxEnergy → int
-
final
-
onDelete
→ InternalFinalCallback<
void> -
Internal callback that starts the cycle of this controller.
finalinherited
-
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
- refillInterval → Duration
-
final
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
- timeUntilNextEnergy → Duration
-
Time remaining until the next energy point regens.
Duration.zerowhen already full (maxEnergy reached) or while hasInfiniteLives is active. Mirrors_regen's own math exactly (same tick-remainder computation) rather than approximating, so a UI countdown built on this never drifts out of sync with when currentEnergy actually ticks up.no setter
Methods
-
$configureLifeCycle(
) → void -
inherited
-
consumeEnergy(
[int amount = 1]) → bool -
Consumes
amountenergy. Returns false — and deducts nothing — if there isn't enough. Always succeeds without deducting while hasInfiniteLives is active. -
grantInfiniteLives(
Duration duration) → Future< void> -
Grants temporary unlimited energy for
duration—consumeEnergysucceeds without deducting until it elapses. -
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.
inherited
-
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 → EnergyService?
-
Gets the instance if already registered (safe to call from call sites
that may run before/without energy registered, e.g. widget tests).
no setter