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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.6 KB |
| agents/openai.yaml | config | 227 B |
| references/actor-shapes.md | markdown | 7.4 KB |
references/actor-shapes.md
View on GitHub# Lakona Actor Shapes
Use repository evidence as the final authority. Lakona actors split stable
state from reloadable behavior.
## Stable App Shape
Declare a business key and an actor state shell in `Server.App`:
```csharp
using Lakona.Game.Server;
using Lakona.Game.Server.Actors;
public readonly record struct RoomId(string Value);
[NodeRole("battle")]
public sealed class RoomActor : Actor<RoomId>
{
internal readonly HashSet<string> Members = new(StringComparer.Ordinal);
internal RoomPhase Phase;
}
```
Prefer current project visibility conventions. The Hotfix assembly must be able
to reference the actor type, while mutable fields should normally remain
`internal`. Do not expose fields publicly unless they are an intentional public
contract.
For scheduled work that only needs Actor state, use the argument-free timer
overload with `TimerTick`; no timer DTO is needed.
Put request, reply, lifecycle, and timer DTOs that cross the stable/Hotfix or
node boundary in the stable App assembly. Follow the project's selected cluster
serializer. A routed actor request and reply must be serializable by the
cluster serializer even when the client endpoint uses a different serializer.
Do not create a separate actor contract interface unless the detected Lakona
version or project convention requires it. Current generated selectors derive
the callable surface from public Hotfix behavior methods.
Every stable Actor declares exactly one `[NodeRole]`. A process can host the
Actor only when that role appears in `Lakona:Node:Roles`; the same declaration
also limits Startup Actor replicas and ordinary placement. Choose the role from
the product topology, not from the caller, connection string, or current node.
## Hotfix Behavior Shape
Bind exactly one behavior class to the stable actor:
```csharp
[HotfixBehaviorOf(typeof(RoomActor))]
public sealed partial class RoomBehavior
{
public ValueTask<JoinRoomReply> JoinAsync(
RoomActor self,
JoinRoomRequest request)
{
self.Members.Add(request.PlayerId);
return new ValueTask<JoinRoomReply>(
new JoinRoomReply { Accepted = true });
}
}
```
Use public behavior methods as the generated actor API. Mutate only the target
actor's state during its turn; `self` is supplied by dispatch. Constructor-inject
`ActorAccess` for calls to other actors through generated selectors, plus concrete
HotfixComponent stores, notifiers, loggers, and policy helpers as needed. Do not
inject actor instances or access another actor's mutable state directly.
Follow repository `ValueTask` rules. Return `default` for a completed
non-generic operation and `new ValueTask<T>(value)` for an immediately
available reply when those are the established conventions.
## Actor Keys
Choose keys from stable product identity:
```text
user/player-123
room/room-456
matchmaking/default
leaderboard/current
```
The key type belongs in `Actor<TKey>`. The default actor ID uses the actor name
and key value. Use `[ActorName]` and `[ActorMethod]` only when a long-lived wire
contract must pin names or numeric IDs.
Do not use node IDs, transport addresses, session callback objects, or
connection IDs as actor identity. A connection ID may appear in request data
when the behavior genuinely needs it; it must not determine distributed actor
ownership accidentally.
## Select Actor Access
Use a direct static selector lambda:
Omit the optional `cancellationToken` argument from ordinary `CallAsync` and
`PostAsync` calls. Add it only when the operation explicitly needs cancellation.
```csharp
var reply = await actors
.Route<RoomActor>(roomId)
.CallAsync(
static behavior => behavior.JoinAsync,
request);
await actors
.Place<RoomActor>(roomId)
.EnsureAsync(cancellationToken);
await actors
.Place<RoomActor>(roomId)
.DestroyAsync(cancellationToken);
await actors
.Local<RoomActor>(roomId)
.PostAsync(
static behavior => behavior.RunTickAsync,
request);
```
Selection rules:
- `Route`: resolve normal business ownership and permit a remote owner.
- `Local`: invoke only the current process after ownership is already proven.
- `Place`: manage a logical actor through cluster-aware placement and
lifecycle.
`CreateAsync` requires the activation to be absent; `EnsureAsync` returns an
existing activation or creates one; `DestroyAsync` retires the exact
activation resolved by the operation and is idempotent when absent.
Placement never relocates an existing activation.
- `Startup`: access the state-owning replica for a business key in a group
declared by `[HotfixConfigureActors]` and `RegisterStartup<TActor, TKey>`.
- Direct `self`: continue work on the actor already executing the current turn.
Do not capture a behavior delegate. The static selector lets reload bind the
method on the active Hotfix generation.
## Lifecycle And Hosting
Put reloadable lifecycle work on the behavior. The `InitializeAsync` and
`CleanupAsync` calls below are private helpers, not public Actor entry methods;
they may receive the framework lifecycle token. Include only hooks with actual
business work; the Stop example is not needed solely for Actor-owned timers:
```csharp
[ActorStart]
public ValueTask StartAsync(RoomActor self, ActorStartCall call)
{
return InitializeAsync(self, new InitializeRoomRequest(), call.CancellationToken);
}
[ActorStop]
public ValueTask StopAsync(RoomActor self, ActorStopCall call)
{
return CleanupAsync(self, new CleanupRoomRequest(), call.CleanupCancellationToken);
}
```
Use generated `ActorAccess.Place<TActor>(key).CreateAsync` or `EnsureAsync` for
business-initiated provisioning. An external coordinator may use
`Place<TActor>(key).DestroyAsync()` when it owns the lifecycle decision. An
actor that completes its own business lifetime calls
`self.Context.RequestDeactivation()` during the active turn; the framework
starts destruction only after that turn succeeds, avoiding a self-mailbox
deadlock.
`ActorHosting` is the framework's internal current-node activation transaction
owner. Business code must not inject it, expose raw current-node destruction,
or manually publish or clear actor routes.
Use Startup Actors when each capable node needs one stateful replica, such as
a matchmaking queue, and each business key must keep using its assigned
replica. Register them from a `[HotfixStartup]` method marked
`[HotfixConfigureActors]`. The key identifies a state partition, not a physical
actor ID. Adding nodes, changing the selection policy, or reloading Hotfix does
not reassign existing keys while their owner remains alive. A new selection
policy applies to unassigned keys; moving existing state requires an explicit
application migration. Failover does not preserve the lost replica's in-memory
state, so use an application Store when that state must survive node loss.
## Failure And Validation
Handle expected `ActorCallException` statuses at a boundary that can make a
product decision. Do not turn `ActorNotFound`, timeout, backpressure, routing,
or serialization failures into silent success.
Validate the contracts affected by the change, reusing existing tests and adding
coverage only where it is missing:
- state transition and reply behavior
- sequential actor turn assumptions
- start and cleanup paths
- missing actor and cancellation behavior
- local versus routed placement intent
- `[NodeRole]` eligibility on the intended node types
- serialization for remote message DTOs
- no blocking waits, discarded required calls, or self-calls
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: 198k | 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 |