Skip to content

How-to: Nakama-RPC ergänzen

1. Contract definieren

Request/Response serverseitig als TypeScript-Interfaces in einer passenden Modeldatei unter src/server/nakama/modules/src/models definieren. Clientseitig DTOs im zuständigen Game3D-/Shared-Feature anlegen. Feldnamen, Optionalität, Enumstrings und Version explizit festlegen; keine Godot-Typen in Contracts.

2. RPC implementieren

Neue Datei unter modules/src/rpcs anlegen. Signatur nkruntime.RpcFunction. Für authentifizierte Calls zuerst requireUserId(ctx), dann parsePayload, typisieren, Pflichtfelder/Bounds/IDs/Version prüfen. Autoritative Werte aus Serverstate ableiten, nicht aus Client-XP/Score/UserId.

Storagezugriffe als Helper unter storage kapseln. Owner lesen (permissionRead: 1) und server-only schreiben (permissionWrite: 0), sofern kein anderer Vertrag bewusst nötig ist. Keys stabil und Ownership immer ctx.userId.

3. Registrieren und bauen

  1. Datei in korrekter Reihenfolge in src/server/nakama/modules/tsconfig.json aufnehmen; Helper vor RPC, RPC vor main.ts.
  2. In modules/src/main.ts mit stabiler ID initializer.registerRpc("rpc_<name>", handler) registrieren.
  3. npm run build; Ergebnis ist build/main.js.

4. Fehler und Logging

Syntax/Auth/Serverfehler dürfen werfen; erwartete fachliche Ablehnung konsistent als Response mit accepted/success, status, message und maschinenlesbarem Code modellieren. Keine Tokens/Secrets/Passwörter oder komplette Replaypayloads loggen. RunId/UserId nur soweit operationsrelevant.

5. Client-Service

IRpcService.CallAsync<TRequest,TResponse> über NakamaRpcService verwenden. Feature-Service kapselt RPC-ID, DTO und fachliche Fehler; UI ruft nicht direkt String-RPCs. Service in BootstrapBase registrieren und injizieren. Cancellation/Loading/Error-State berücksichtigen.

6. Lokal testen

Set-Location src/server/nakama/modules
npm run build
Set-Location ../..
docker compose --env-file ../.env -f ../docker-compose.yaml up --build -d nakama
docker compose --env-file ../.env -f ../docker-compose.yaml logs -f nakama

Mit authentifiziertem Local-Client Happy Path, invalid JSON, unauthenticated, missing fields, чужde Ownership, Duplicate/Idempotenz und Storage-Readback prüfen. Danach Fullstack-Integration. Automatisierte Nakama-Tests fehlen; für Progression/Score/Replay vor Produktion ergänzen.

Checkliste

  • [ ] C#- und TS-Contract synchron/versioniert
  • [ ] Auth/Ownership/Validation vor Write
  • [ ] server-only autoritative Werte
  • [ ] Storage permissions und Migration
  • [ ] tsconfig-Dateiliste und main-Registrierung
  • [ ] Client-Service/DI/UI-Fehlerpfad
  • [ ] npm build, Container rebuild, Logs, Integrationstest
  • [ ] RPC-Referenz aktualisiert