Nakama und RPC-Entwicklung
Status: Online-Run-Pipeline (chunked Replay → Submit → Manual Leaderboard)
Struktur und Build
TypeScript wird als globale ES5-Datei kompiliert (module: none, outFile: build/runtime.js). src/server/nakama/modules/tsconfig.json listet jede Quelldatei explizit und ordnet Models/Helpers/Storage/RPCs vor main.ts. Neue Datei ohne Eintrag wird nicht gebündelt. Docker baut mit Node 20 und startet Nakama mit --runtime.js_entrypoint runtime.js (siehe Compose/Entrypoint).
Registrierte RPCs
| RPC | Implementierung | Zweck |
|---|---|---|
rpc_ping |
pingRpc.ts |
Health-/Payload-Echo; anonym möglich |
rpc_assign_user_handle |
assignUserHandleRpc.ts |
stabiler öffentlicher Handle im Account-Metadata |
rpc_start_run |
createOnlineRunSessionRpc.ts |
Online-Session, Seed/Versionen/Ticket |
rpc_notify_run_started |
notifyRunStartedRpc.ts |
Created → Started |
rpc_abort_run |
abortRunRpc.ts |
Created/Started → Aborted |
replay_upload_begin |
chunkedReplayRpcs.ts |
Chunked-Replay-Upload starten |
replay_chunk_upload |
chunkedReplayRpcs.ts |
Chunk schreiben |
replay_upload_status |
chunkedReplayRpcs.ts |
Upload-Status |
replay_upload_finalize |
chunkedReplayRpcs.ts |
Upload abschließen |
replay_upload_cleanup_owned |
chunkedReplayRpcs.ts |
eigene Uploads aufräumen |
replay_stream_begin |
chunkedReplayRpcs.ts |
Streaming-Session vor oder während eines Runs starten |
replay_stream_chunk |
chunkedReplayRpcs.ts |
versiegelten Replay-Chunk fortlaufend hochladen |
replay_stream_abort |
chunkedReplayRpcs.ts |
Streaming-Session abbrechen |
rpc_submit_run |
submitOnlineRunRpc.ts |
Validierung, Resultat, Manual-LB-Projektion |
rpc_get_run_submission |
submitOnlineRunRpc.ts |
Submission-Status lesen |
rpc_get_run_history |
runHistoryRpc.ts |
paginierte Run-Historie |
rpc_get_run_result |
runHistoryRpc.ts |
Resultat-Details |
rpc_get_player_run_profile |
runHistoryRpc.ts |
Profilaggregat |
leaderboard_get |
leaderboardGetRpc.ts |
Manual-Leaderboard lesen |
rpc_get_leaderboard_replay |
getLeaderboardReplayRpc.ts |
Replay zu LB-Eintrag |
rpc_register_pending_leaderboard |
registerPendingLeaderboardRpc.ts |
Pending-Validation-Zeile |
Mailbox_Get / rpc_mailbox_get |
mailboxRpcs.ts |
Postfach laden (Pagination, unread filter) |
Mailbox_Read / rpc_mailbox_read |
mailboxRpcs.ts |
Nachricht als gelesen markieren |
Mailbox_Delete / rpc_mailbox_delete |
mailboxRpcs.ts |
Nachricht entfernen |
Mailbox_Count / rpc_mailbox_count |
mailboxRpcs.ts |
Anzahl ungelesener Nachrichten |
Entfernt (kein Client mehr): rpc_complete_run, rpc_get_replay_payload, Legacy-Monolith-Replay-Uploads.
Contracts und Storage
Online-Session-Modelle liegen in models/onlineRunModels.ts. C#-Clientmodelle für Runs liegen in Features/Dungeons/Run; Feldnamen und Optionalität müssen manuell synchron gehalten werden.
Aktive Collections (Auszug): online_run_sessions, run_submissions, run_validations, replay_artifacts_v1, Chunked-Replay-Manifests/Chunks, run_results / History-Index / Profile, player_mailbox / player_mailbox_meta. Die alten Collections run_sessions / Events / Monolith-Replay werden nicht mehr geschrieben.
Fehlerbehandlung und Logging
Payloadsyntaxfehler/Unauthenticated werfen Error; fachliche Ablehnungen liefern häufig {accepted:false,status:"Rejected",message}. Der C#-Service muss beides unterscheiden. Logs enthalten Run-ID/User-Kontext, dürfen aber keine Tokens, Serverkeys oder vollständige sensible Payloads enthalten.
Runvalidierung
rpc_submit_run prüft Auth/Ownership, Online-Session, Ticket, Replay-Hash und Timeline und berechnet Score/Medaille serverseitig. Das ist kein vollständiges Anti-Cheat-System; die Replay-Pipeline ist die autoritative Quelle für Leaderboard-Eligibility. Validierungsergebnisse erzeugen Notifications über RunValidationNotificationHandler (ohne UI-/Chat-Kopplung im Validator).
Tests und lokale Prüfung
npm test im Modulordner baut und führt Node-Tests aus. Nach Moduländerung Container neu bauen/starten und Logs auf Init-/RPC-Fehler prüfen.
Anleitung: Nakama-RPC ergänzen. Verwandt: Manual Leaderboards, Run Completion.