bruce48x/Lakona / skills/lakona-implement-actor
lakona-implement-actor
VerifiedCreate or update Lakona game actors across stable Server.App state shells and reloadable Server.Hotfix behavior. Use when modeling long-lived mutable game state, declaring an Actor NodeRole, adding messages or lifecycle hooks, choosing actor keys and Local Route Place or Startup access, implementing cross-actor calls, or fixing Lakona actor and Hotfix analyzer errors.
Implement a Lakona Actor
Model one long-lived mutable game entity as a stable actor state shell plus one reloadable Hotfix behavior. Keep the actor boundary explicit and preserve sequential turn execution.
Use HotfixComponent for tools whose ordinary calls may run concurrently and need no actor identity or mailbox. Use Actor + Behavior for serialized mutable state and timers; a Startup Actor is not a general resource-initialization mechanism.
Workflow
- Read
AGENTS.md, the project README, and scoped repository instructions. - Identify the business identity, state ownership, commands, queries, lifecycle, placement role, persistence needs, and callers. Confirm that an actor is the right concurrency boundary rather than an RPC DTO, transient service, or database record. Actor memory is not persistence: state which must survive process loss belongs in an application-owned store.
- Inspect existing actors, App-side message DTOs, Hotfix behavior classes, startup declarations, serializer conventions, and tests.
- Search for an existing actor and
[HotfixBehaviorOf]binding. Extend the existing pair rather than creating duplicate state or a second behavior class. - Read actor-shapes.md before choosing the key, creating App contracts, selecting Local versus Route versus Place versus Startup, or adding lifecycle hooks.
- Define stable identity, state, and cross-boundary message DTOs in
Server.App. Mark the Actor with exactly one[NodeRole("...")]matching the processes allowed to host it. Keep the actor class focused on state; place game decisions inServer.Hotfix. - Implement public behavior entry methods on the unique class marked
[HotfixBehaviorOf(typeof(...))]. Use the target actor as the first parameter and a stable request DTO as the second. Do not add aCancellationTokenparameter: caller cancellation only stops waiting. - Call other actors through generated selectors with a direct static lambda. Use the selector whose routing semantics match known ownership.
- Manage a logical actor lifecycle through generated
ActorAccess.Place<TActor>(key): useCreateAsyncwhen absence is required,EnsureAsyncwhen an existing activation is acceptable, andDestroyAsyncfor an external lifecycle decision. An actor ending its own business lifetime requests post-turn cleanup throughself.Context.RequestDeactivation(). - Add
[ActorStart]and[ActorStop]hooks only for real lifecycle work. Release application-owned long-lived handles during cleanup. Activation shutdown automatically cancels its timers; useDestroyTimeronly when business logic needs early cancellation. Do not add[ActorStop]solely to destroy timers. - Reuse focused tests for affected state transitions, replies, lifecycle, placement assumptions, and failure behavior; add or update tests only where meaningful coverage is missing.
- Build the Hotfix project and run the focused actor tests. Treat analyzer diagnostics as boundary violations to fix, not warnings to suppress.
Non-Negotiable Boundaries
- Hotfix business exceptions deriving directly or indirectly from
System.Exceptionare created withnewusing runtime error data. They need no role or DI registration;[HotfixComponent]is for DI-owned helpers. Remove a mistaken marker reported byLAKONA20060. If an older framework reportsLAKONA20037on an exception, upgrade and verify compilation plus Hotfix loading before removing temporary suppressions. Ordinary classes still require a role. - Use a stable business key. Do not encode a node, endpoint, transport, callback, RPC Session, or incidental connection in an actor ID.
- Every stable Actor declares exactly one
[NodeRole]. Do not infer placement from connection strings or repeat role policy in Hotfix registration. - Keep long-lived in-memory state on the stable App actor. Do not store it in Hotfix instance fields, static fields, callbacks, or background tasks. Use an application Store when state must survive process or cluster loss.
- Do not put business methods on the stable actor merely to bypass Hotfix.
- Mutate non-public actor state only from the actor itself or its unique Hotfix
behavior. Do not make fields public just to evade
LAKONA20031. - Do not self-call through
ActorAccess. Continue the current actor turn directly when operating on the same actor. - Use
Route<TActor>(key)for the normal distributed business path. UseLocal<TActor>(key)only after proving current-node ownership. UseStartup(key)only for a declared startup actor group. - Use
Place<TActor>(key)for cluster-aware creation, ensure, and logical destruction. External coordinators useDestroyAsync; an actor deciding its own lifetime usesself.Context.RequestDeactivation()during its active turn. Do not inject the internalActorHostingservice, expose current-node destruction, or mutate the actor directory or cache. Normal calls and timer callbacks must not implicitly create missing actors. - Use
CallAsyncwhen the caller needs completion or a reply. UsePostAsynconly when mailbox acceptance is sufficient. - Do not block on actor work, discard required completion, or hand-write string dispatch and raw route plumbing.
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; it references the stable App project and therefore validates both halves in the normal project shape:
dotnet build Server/Hotfix/Server.Hotfix.csproj
Run existing actor or domain tests. Verify state transitions, configured role eligibility, and lifecycle behavior, not only source shape. If routed calls are introduced, validate the project's serializer and cluster test surface as well.
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: 197k | 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: 194k | 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: 194k | 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: 194k | Updated | Claude CodeCodex | Verified | Install |