bruce48x/Lakona / skills/lakona-define-rpc-contract
lakona-define-rpc-contract
VerifiedDefine or update Lakona Shared RPC service contracts, notification contracts, DTOs, and stable numeric IDs. Use when adding an RPC API, changing request or reply shapes, adding server-to-client callbacks, assigning service, method, or notification IDs, fixing contract generator diagnostics, or validating Unity and serializer compatibility.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.1 KB |
| agents/openai.yaml | config | 226 B |
| references/contract-shapes.md | markdown | 4.9 KB |
references/contract-shapes.md
View on GitHub# Lakona RPC Contract Shapes
Use project-local conventions when they differ from illustrative names below. Verify the installed Lakona package version and current source before assuming an API shape.
## Contract Ownership
Keep wire-facing declarations in Shared:
```csharp
public static partial class RpcContractIds
{
public static class Services
{
public const int Stage = 101;
}
public static class StageServiceMethods
{
public const int GetProgressAsync = 1;
}
public static class StageNotifications
{
public const int ProgressChanged = 1;
}
}
```
Large projects may split the partial ID registry by domain. Search the whole Shared assembly before assigning an ID.
## ID Stability
- Service IDs are globally unique within the application protocol and must be positive for business services.
- Method IDs are unique within their service.
- Notification IDs are unique within their notification contract.
- A published ID remains attached to the same semantic operation for the lifetime of that compatibility line.
- Reserve removed IDs. Add the next intentional value instead of filling an unexplained gap.
- Never derive a wire ID from declaration order, a hash, or a type name.
If project history does not establish whether an apparently unused value was
published, leave it reserved and continue with a value confirmed unused under
the project's allocation policy. Check the registry, reservations, and relevant
release history; a gap alone is not evidence of availability. Ask only when no
safe allocation can be established or the requested change requires reusing an
uncertain ID or changing a published contract.
## Service And Notification Shape
```csharp
[RpcService(
RpcContractIds.Services.Stage,
NotificationContract = typeof(IStageNotifications))]
public interface IStageService
{
[RpcMethod(RpcContractIds.StageServiceMethods.GetProgressAsync)]
ValueTask<GetStageProgressReply> GetProgressAsync(
GetStageProgressRequest request);
}
[RpcNotificationContract]
public interface IStageNotifications
{
[RpcNotification(RpcContractIds.StageNotifications.ProgressChanged)]
void ProgressChanged(StageProgressChanged notification);
}
```
An RPC method has exactly one request DTO and returns `ValueTask` or
`ValueTask<T>`. Use an explicit empty request DTO rather than omitting the request.
RPC notifications return `void` or non-generic `ValueTask` and take one DTO
payload, optionally followed by a `CancellationToken`. Prefer the simple `void`
shape above for new contracts when it fits project conventions; preserve valid
existing signatures.
Game publication through `IClientNotifications.ForSession<TCallback>` uses
generated extensions returning synchronous `ClientNotificationStatus` for local
admission. This remains separate from the RPC notification contract's return
type and does not require rewriting that contract to `void`.
## DTO Shape And Evolution
Follow the serializer already selected by the project. A current MemoryPack project may use:
```csharp
[MemoryPackable(GenerateType.VersionTolerant)]
public partial class GetStageProgressReply
{
[MemoryPackOrder(0)]
public bool Success { get; set; }
[MemoryPackOrder(1)]
public int Progress { get; set; }
[MemoryPackOrder(2)]
public string ErrorCode { get; set; } = string.Empty;
}
```
This is not permission to convert a project using another serializer. Preserve its annotations, partial-type requirements, nullability style, class-versus-struct convention, and versioning rules.
When evolving a DTO:
- preserve the meaning and serialized order of existing members
- append fields using the next valid order when the serializer supports compatible addition
- use Shared-safe primitives, enums, and DTOs
- choose names that describe protocol meaning rather than implementation storage
- model expected rejection or domain failure explicitly when callers need to act on it
Do not place `GameSessionKey`, `RpcSession`, actor instances or references, service providers, delegates, transport connections, or other server runtime objects in a DTO.
## Unity And Generation Constraints
Shared commonly targets `netstandard2.1` for Unity as well as the server target. Inspect its project file and obey its declared C# language version; Unity 2022 compatibility commonly means C# 9 syntax.
Contract generators run during compilation. Do not create a `Generated` source tree, copy generator output, add marker files, or introduce a separate code-generation script unless the repository explicitly owns that workflow.
For contract changes, validate the real project graph. These build targets may
be covered by a single build or focused test command when its dependency graph
and configuration include both:
```powershell
dotnet build <path-to-shared-project>
dotnet build <path-to-server-app-project>
```
Also compile the affected Unity or other client through its established validation path when the change alters client-visible contracts.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |