bruce48x/Lakona / skills/lakona-implement-timer
lakona-implement-timer
VerifiedCreate or update framework-owned Lakona Hotfix timers, stable timer arguments, callbacks, and actor lifecycle integration. Use when adding one-shot or periodic jobs, storing or destroying TimerId values, executing timer ticks in actors, repairing timer cleanup, or fixing Lakona timer callback and serialization errors.
Implement a Lakona Timer
Implement scheduled work with Actor timers so callbacks resolve against the active Hotfix generation and long-lived ownership remains in stable state.
Workflow
- Read
AGENTS.md, the project README, and scoped repository instructions. - Define the schedule, owner, first due time, repeat period, callback action, cancellation behavior, and cleanup condition. Decide whether the operation is one-shot or periodic. Lakona timers are process-memory scheduling: if the schedule must survive restart, use an application-selected persistent scheduler or Store instead of treating Actor timers as durable.
- Inspect existing timer argument DTOs,
[ActorTimer]Behavior methods,TimerIdfields, actor lifecycle hooks, and timer-focused tests. - Search for an existing timer with the same responsibility. Update its complete lifecycle instead of creating a competing schedule.
- Read timer-shapes.md before defining arguments, choosing callback placement, creating the timer, or writing cleanup.
- Choose whether the callback needs a creation-time business snapshot. If it
only needs
self, use the argument-free overload; do not create an empty DTO or repeat the owning Actor ID. Put any needed argument DTO and storedTimerIdin stable App state/types. Keep callbacks and scheduling in Hotfix. - Define an instance Behavior method marked
[ActorTimer], returningValueTaskand accepting(ActorType self, TimerTick tick)without business arguments, or(ActorType self, TimerTick<TArgs> tick)with arguments. Private callbacks are supported and excluded from RPC generation. - Create the timer in its owning Actor turn and active Hotfix scope with a direct static typed callback selector. Store the returned ID when later destruction or duplicate prevention is required.
- Make periodic creation idempotent for its owner. Activation shutdown cancels timers automatically. Store IDs only for early cancellation or duplicate prevention, and clear stored IDs before explicit cancellation.
- Access mutable Actor state directly through
selfin the callback. Do not forward a call to the same Actor. Ticks expose no cancellation token; timer destruction prevents pending and future callbacks without interrupting a callback already running. Choose any downstream cancellation policy explicitly. - Build the Hotfix project and run timer, actor lifecycle, and domain tests that cover creation, dispatch, repetition, and cleanup.
Non-Negotiable Boundaries
- Exceptions created inside Hotfix callbacks may remain in Hotfix when they
derive directly or indirectly from
System.Exception. Construct them withnewusing runtime data; they are neither timer argument DTOs nor DI components. Remove[HotfixComponent]whenLAKONA20060reports it. For older frameworks reportingLAKONA20037on exceptions, upgrade and verify compilation plus Hotfix loading before removing temporary suppressions. - Use
self.CreateOnceTimerorself.CreatePeriodicTimer. Do not introduceSystem.Threading.Timer,PeriodicTimer, fire-and-forget delay loops, orTask.Runschedulers for Hotfix business work. - Create and destroy timers only inside an active Hotfix execution scope. Do not call Actor timer extensions from stable App code, constructors, or work that escaped the scope.
- Use a static typed selector such as
static (RoomBehavior behavior) => behavior.TickAsync. Do not retain a Hotfix delegate or dispatch by a hand-written method-name string. - Keep timer arguments stable, concrete, bounded, and serializable. Do not put actors, services, callbacks, cancellation tokens, or arbitrary object graphs in timer arguments.
- Cancel early with
self.DestroyTimer(timerId)in the owning activation's active Hotfix turn. Other activations cannot cancel its registered timers. - Store cancellable timer ownership as
TimerIdin stable state. Do not manufacture IDs. - Keep mutable game state on the stable Actor. The callback already runs in its owning activation's mailbox.
- Do not retain transport callbacks, session callback objects, or old Hotfix generation objects across ticks.
- Explicit destruction stops queued and future callbacks. A running callback completes normally; destruction does not await it, so self-cancellation cannot deadlock.
TimerTickexposes onlyTimerId;TimerTick<TArgs>exposesTimerIdandArgs. Parameters are creation-time snapshots, not mutable state shared across ticks. Resolve dependencies by injection and obtain business time in the callback.- Lakona does not persist timers or rebuild them after process loss. Integrate a persistent scheduler as an application resource when the product requires durable calendar jobs; do not add persistence semantics to Actor timers.
Validation
Apply the validation steps to affected contracts, reusing existing coverage and adding tests only where meaningful coverage is missing. For non-behavioral, low-impact edits, use relevant static checks. A test command may also satisfy the build when it covers the same graph and configuration. Once relevant checks and required stage gates pass, stop unless new changes, failures, or a concrete unresolved risk justify more verification. Report any unverified outcomes.
Build the discovered Hotfix project:
dotnet build Server/Hotfix/Server.Hotfix.csproj
For the contracts affected by the change, reuse focused tests that prove the timer fires the intended callback, periodic creation is not duplicated, one-shot versus periodic behavior is correct, the argument round trip succeeds when arguments are used, and cleanup removes the timer. A successful build alone does not prove scheduling semantics. Add tests only where meaningful coverage is missing.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |