Skip to content

bruce48x/Lakona / skills/lakona-define-rpc-contract

lakona-define-rpc-contract

Verified

Define 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.

FileKindSize
SKILL.mdskill md5.1 KB
agents/openai.yamlconfig226 B
references/contract-shapes.mdmarkdown4.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.
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 implementationStars: 323kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 323kUpdated Claude CodeCodexVerifiedInstall
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 fallbackStars: 323kUpdated Claude CodeCodexVerifiedInstall
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 alwaysStars: 323kUpdated Claude CodeCodexVerifiedInstall