Jeu Multijoueur

IMPORTANT : Avant de faire quoi que ce soit, vous DEVEZ lire BASE_SKILL.md dans le répertoire de cette compétence. Il contient des conseils essentiels sur le débogage, la gestion des erreurs, la gestion d'état, le déploiement et la configuration du projet. Ces règles et modèles s'appliquent à tous les travaux RivetKit. Tout ce qui suit suppose que vous avez déjà lu et compris ces informations.

Modèles pour construire des jeux multijoueurs avec RivetKit, destinés à être une checklist pratique que vous pouvez adapter par genre.

Code de démarrage

Commencez par l'un des exemples fonctionnels sur GitHub et adaptez-le à votre jeu. Ne commencez pas de zéro pour les flux d'appairage et de cycle de vie.

Simulation serveur

Boucle de jeu et fréquences de tick

Physics

Commencez par une logique cinématique personnalisée pour les jeux simples. Passez à un moteur physics complet lorsque vous avez besoin de joints, corps empilés, haute densité de collision ou formes complexes (polygones tournés, capsules, enveloppes convexes, mailles triangulaires).

Choisissez un moteur par simulation. Gardez les libs frontend hors des chemins de simulation backend et traitez l'état serveur comme faisant autorité.

Indexation spatiale

Pour les requêtes spatiales non-physics, utilisez un index dédié au lieu de vérifications naïves O(n^2) :

Réseautage et synchronisation d'état

Netcode

Modèle de données temps réel

• Snapshots et diffs : Publiez l'état comme événements. Envoyez un snapshot complet à la connexion/resync, puis des diffs par tick pour les mises à jour régulières.
• Batch par tick : Gardez les événements petits et typés. Groupez les mises à jour haute fréquence par tick.
• Évitez l'état du framework UI pour les mises à jour de jeu : Utilisez requestAnimationFrame ou une boucle Canvas/Three.js pour la simulation, pas l'état React. Réservez l'état du framework UI pour les menus, HUD et formulaires.
• Broadcast vs par-connexion : Utilisez c.broadcast(...) pour les mises à jour partagées et conn.send(...) pour les données privées/par-joueur.

Logique de simulation partagée

La logique de simulation partagée s'exécute à la fois sur le client et sur le serveur. Par exemple, une fonction applyInput(state, input, dt) qui intègre la vélocité et limite aux limites du monde peut s'exécuter sur le client pour la prédiction et sur le serveur pour la validation.

• Modes hybrides : Le client exécute le mouvement partagé comme autorité principale, le serveur l'exécute pour la validation anti-cheat.
• Modes sous autorité serveur : Le client utilise la logique partagée pour l'interpolation et la prédiction uniquement.
• Gardez-la pure : Intégration de mouvement, transformations d'entrée, assistants de collision et constantes uniquement.
• Mettez le code partagé dans src/shared/ : Gardez les assistants déterministes dans src/shared/sim/* sans effets secondaires.

Gestion des intérêts

Contrôlez ce que chaque client reçoit pour réduire la bande passante et empêcher les fuites d'informations.

Filtres de réplication par joueur

• Filtrez par pertinence : Envoyez à chaque client uniquement l'état pertinent pour ce joueur (proximité, line-of-sight, équipe ou phase de jeu).
• Shooters et jeux d'action : Limitez la réplication par proximité et vérifications optionnelles de champ de vision.
• Côté serveur uniquement : Les clients ne doivent jamais recevoir de données qu'ils ne devraient pas voir.

Mondes fragmentés

• Partitionnez les grands mondes : Utilisez des acteurs chunk avec clé worldId:chunkX:chunkY.
• Abonnez-vous aux chunks proches : Les clients se connectent uniquement aux partitions proches (par exemple une fenêtre chunk 3x3).
• À utiliser avec parcimonie : Seulement quand le monde est grand et lourd en état (constructeurs sandbox, MMO), pas par défaut pour les petits matchs.

Infrastructure backend

Persistance

• État en mémoire : Idéal pour l'état du jeu temps réel qui change chaque tick (positions des joueurs, entrées, phase du match, scores).
• SQLite (rivetkit/db) : Mieux pour l'état volumineux ou table-like qui nécessite des requêtes, index ou persistance long-terme (tuiles, inventaire, pools d'appairage). Sérialisez le travail DB via une queue puisque plusieurs actions peuvent frapper le même acteur simultanément.

Modèles d'appairage

Blocs de construction communs utilisés dans les modèles d'architecture ci-dessous.

Topologie d'acteur

Stratégie de file d'attente

• Plusieurs joueurs peuvent frapper le matchmaker en même temps, donc les actions comme find/create, queue/unqueue et close doivent être sérialisées via les queues d'acteur pour éviter les courses.
• Les actions locales au match (gameplay, scoring) n'ont pas besoin de queueing sauf si elles écrivent de nouveau vers le matchmaker.

Sécurité et anti-cheat

Commencez par cette ligne de base, puis renforcez davantage pour les environnements compétitifs ou à haut risque.

Checklist de base

• Identité : Utilisez c.conn.id comme identité transport faisant autorité. Traitez playerId/username dans les paramètres comme entrée non fiable et liez via assignment/join tickets émis par le serveur.
• Autorisation : Validez que l'appelant est autorisé à muter l'entité cible (adhésion au salon, propriété de tour, actions réservées à l'hôte).
• Validation d'entrée : Limitez les tailles/longueurs, validez les énumérations et validez les noms d'utilisateur (longueur, caractères autorisés, évitez Unicode illimité).
• Limite de débit : Limites de débit par connexion pour les actions spammy (chat, join/leave, fire, mises à jour de mouvement).
• Intégrité d'état : Le serveur recalcule l'état dérivé (scores, conditions de victoire, placements). Ne laissez jamais les modifications d'inventaire/devise/totaux du leaderboard faire autorité au client.

Validation du mouvement

Pour n'importe quel mode avec mouvement faisant autorité au client (flux hybrides), les clients peuvent envoyer les mises à jour de position/rotation pour la fluidité, mais le serveur doit :

• Appliquer le delta max par mise à jour (plafond de vitesse) en fonction du temps écoulé.
• Rejeter ou limiter les téléportations.
• Appliquer les limites du monde (et collision basique si applicable).
• Limiter la fréquence de mise à jour (par exemple 20 Hz max).

Modèles d'architecture

Chaque type de jeu ci-dessous commence par une table récapitulative rapide, puis détaille les acteurs et le cycle de vie.

Battle Royale

Acteurs

• Clé : matchmaker["main"]

• Responsabilité : Trouve ou crée des lobbies, suit les réservations en attente et maintient l'occupation.

• Actions

  • findMatch
  • pendingPlayerConnected
  • updateMatch
  • closeMatch

• Queues

  • findMatch
  • pendingPlayerConnected
  • updateMatch
  • closeMatch

• État

  • SQLite
  • matches
  • pending_players
  • player_count inclut joueurs connectés et en attente

• Clé : match[matchId]

• Responsabilité : Exécute les phases lobby/live/finished, possède l'état des joueurs, progression de zone et éliminations.

• Actions

  • connect
  • Actions de mouvement et combat

• Queues

  • Aucune

• État

  • JSON
  • phase
  • players
  • zone
  • eliminations
  • snapshot data

Cycle de vie

sequenceDiagram
    participant C as Client
    participant MM as matchmaker
    participant M as match

    C->>MM: findMatch()
    alt no open lobby
        MM->>M: create(matchId)
    end
    MM-->>C: {matchId, playerId}
    C->>M: connect(playerId)
    M->>MM: pendingPlayerConnected(matchId, playerId)
    MM-->>M: accepted
    Note over M: lobby countdown -> live
    M-->>C: snapshot + shoot events
    M->>MM: closeMatch(matchId)

Arena

Acteurs

• Clé : matchmaker["main"]

• Responsabilité : Exécute les files d'attente mode, construit les matchs complets, assigne les équipes et publie les assignments.

• Actions

  • queueForMatch
  • unqueueForMatch
  • matchCompleted

• Queues

  • queueForMatch
  • unqueueForMatch
  • matchCompleted

• État

  • SQLite
  • player_pool
  • matches
  • assignments indexés par connexion et joueur

• Clé : match[matchId]

• Responsabilité : Exécute les phases de match et l'état joueur/équipe dans le match pour score et conditions de victoire.

• Actions

  • connect
  • Actions de gameplay

• Queues

  • Aucune

• État

  • JSON
  • phase
  • players
  • team assignments
  • score and win state

Cycle de vie

sequenceDiagram
    participant C as Client
    participant MM as matchmaker
    participant M as match

    C->>MM: queueForMatch(mode)
    Note over MM: enqueue in player_pool
    Note over MM: fill when capacity reached
    MM->>M: create(matchId, assignments)
    Note over MM: persist assignments
    MM-->>C: assignmentReady
    C->>M: connect(playerId)
    Note over M: waiting -> live when all players connect
    M->>MM: matchCompleted(matchId)

IO Style

Acteurs

• Clé : matchmaker["main"]

• Responsabilité : Route les joueurs dans le lobby ouvert le plus rempli et suit les réservations et l'occupation.

• Actions

  • findLobby
  • pendingPlayerConnected
  • updateMatch
  • closeMatch

• Queues

  • findLobby
  • pendingPlayerConnected
  • updateMatch
  • closeMatch

• État

  • SQLite
  • matches
  • pending_players
  • L'occupation inclut les réservations en attente

• Clé : match[matchId]

• Responsabilité : Exécute la simulation de mouvement par match et diffuse les snapshots.

• Actions

  • connect
  • setInput

• Queues

  • Aucune

• État

  • JSON
  • players
  • inputs
  • movement state
  • snapshot cache

Cycle de vie

sequenceDiagram
    participant C as Client
    participant MM as matchmaker
    participant M as match

    C->>MM: findLobby()
    alt no open lobby
        MM->>M: create(matchId)
    end
    MM-->>C: {matchId, playerId}
    C->>M: connect(playerId)
    M->>MM: pendingPlayerConnected(matchId, playerId)
    MM-->>M: accepted
    Note over M: fixed tick simulation
    M-->>C: snapshot events
    M->>MM: closeMatch(matchId)

Open World

Acteurs

• Clé : chunk[worldId,chunkX,chunkY]
• Responsabilité : Possède les joueurs locaux chunk, les blocs, le tick de mouvement et l'adhésion chunk.
• Actions
  • connect
  • enterChunk
  • addPlayer
  • setInput
  • leaveChunk
  • removePlayer
• Queues
  • Aucune
• État
  • JSON
  • connections
  • players
  • blocks limité à une clé chunk

Cycle de vie

sequenceDiagram
    participant C as Client
    participant CH as chunk

    Note over C: resolve chunk keys from world position
    loop each visible chunk
        C->>CH: connect(worldId, chunkX, chunkY, playerId)
        Note over CH: store connection metadata
    end
    C->>CH: enterChunk/addPlayer
    loop movement updates
        C->>CH: setInput(...)
        CH-->>C: snapshot
    end
    C->>CH: leaveChunk/removePlayer or disconnect
    Note over CH: remove membership and metadata

Party

Acteurs

• Clé : matchmaker["main"]

• Responsabilité : Traite le flux de création/join de party, valide les tickets de join et suit la taille de party.

• Actions

  • createParty
  • joinParty
  • verifyJoin
  • updatePartySize
  • closeParty

• Queues

  • createParty
  • joinParty
  • verifyJoin
  • updatePartySize
  • closeParty

• État

  • SQLite
  • parties
  • join_tickets pour recherche de party et validation de join

• Clé : match[matchId]

• Responsabilité : Possède les membres de party, rôle d'hôte, drapeaux ready et transitions de phase.

• Actions

  • connect
  • startGame
  • finishGame

• Queues

  • Aucune

• État

  • JSON
  • members
  • host
  • ready state
  • phase
  • party events

Cycle de vie

Flux hôte

sequenceDiagram
    participant H as Host Client
    participant MM as matchmaker
    participant M as match

    H->>MM: createParty()
    MM-->>H: {matchId, partyCode, playerId, joinToken}
    H->>M: connect(playerId, joinToken)
    M->>MM: verifyJoin(...)
    MM-->>M: allowed
    M->>MM: updatePartySize(playerCount)
    H->>M: startGame() / finishGame()
    M->>MM: closeParty(matchId)

Flux joigneur

sequenceDiagram
    participant J as Joiner Client
    participant MM as matchmaker
    participant M as match

    J->>MM: joinParty(partyCode)
    MM-->>J: {matchId, playerId, joinToken}
    J->>M: connect(playerId, joinToken)
    M->>MM: verifyJoin(...)
    MM-->>M: allowed / denied
    M->>MM: updatePartySize(playerCount)

Ranked

Acteurs

• Clé : matchmaker["main"]

• Responsabilité : Exécute la file d'attente basée note, l'appairage, la persistance d'assignment et le fanout de complétion.

• Actions

  • queueForMatch
  • unqueueForMatch
  • matchCompleted

• Queues

  • queueForMatch
  • unqueueForMatch
  • matchCompleted

• État

  • SQLite
  • player_pool
  • matches
  • assignments avec fenêtre de note et scoping de connexion

• Clé : match[matchId]

• Responsabilité : Exécute la phase du match classé, le score et le report du gagnant.

• Actions

  • connect
  • Actions de gameplay

• Queues

  • Aucune

• État

  • JSON
  • phase
  • players
  • score
  • winner
  • completion payload

• Clé : player[username]

• Responsabilité : Stocke le MMR canonique du joueur et le profil win/loss.

• Actions

  • initialize
  • getRating
  • applyMatchResult

• Queues

  • Aucune

• État

  • JSON
  • rating
  • wins
  • losses
  • match counters

• Clé : leaderboard["main"]

• Responsabilité : Stocke et serve les joueurs top-rankers.

• Actions

  • updatePlayer

• Queues

  • Aucune

• État

  • SQLite
  • Lignes de score leaderboard
  • Tri de listes top

Cycle de vie

sequenceDiagram
    participant C as Client
    participant MM as matchmaker
    participant P as player
    participant M as match
    participant LB as leaderboard

    C->>MM: queueForMatch(username)
    MM->>P: initialize/getRating
    P-->>MM: rating
    Note over MM: store queue row + retry pairing
    MM->>M: create(matchId, assigned players)
    MM-->>C: assignmentReady
    C->>M: connect(username)
    M->>MM: matchCompleted(...)
    MM->>P: applyMatchResult(...)
    MM->>LB: updatePlayer(...)
    Note over MM: remove matches + assignments rows

Turn-Based

Acteurs

• Clé : matchmaker["main"]

• Responsabilité : Traite invite-privée et appairage de public-queue pour matchs asynchrones.

• Actions

  • createGame
  • joinByCode
  • queueForMatch
  • unqueueForMatch
  • closeMatch

• Queues

  • createGame
  • joinByCode
  • queueForMatch
  • unqueueForMatch
  • closeMatch

• État

  • SQLite
  • matches
  • player_pool
  • assignments pour mapping invite et queue

• Clé : match[matchId]

• Responsabilité : Possède l'état du plateau, l'ordre des tours, la validation des mouvements et le résultat final.

• Actions

  • connect
  • makeMove

• Queues

  • Aucune

• État

  • JSON
  • board
  • turns
  • players
  • connection presence
  • result

Cycle de vie

File d'attente publique

sequenceDiagram
    participant A as Client A
    participant B as Client B
    participant MM as matchmaker
    participant M as match

    A->>MM: queueForMatch()
    B->>MM: queueForMatch()
    Note over MM: pair first two queued players
    MM->>M: create(matchId) + seed X/O players
    MM-->>A: assignment/match info
    MM-->>B: assignment/match info
    A->>M: connect(playerId)
    B->>M: connect(playerId)
    A->>M: makeMove()
    B->>M: makeMove()
    opt all players disconnected for timeout
        Note over M: destroy after idle timeout
    end
    M->>MM: closeMatch(matchId)

Invite privée

sequenceDiagram
    participant A as Client A
    participant B as Client B
    participant MM as matchmaker
    participant M as match

    A->>MM: createGame()
    MM-->>A: {matchId, playerId, inviteCode}
    B->>MM: joinByCode(inviteCode)
    MM->>M: create(matchId) + seed X/O players
    MM-->>A: assignment/match info
    MM-->>B: assignment/match info
    A->>M: connect(playerId)
    B->>M: connect(playerId)
    A->>M: makeMove()
    B->>M: makeMove()
    M->>MM: closeMatch(matchId)

Idle

Acteurs

• Clé : world[playerId]

• Responsabilité : Possède la progression d'un joueur, les bâtiments, la planification de production et les mises à jour d'état.

• Actions

  • initialize
  • build
  • collectProduction

• Queues

  • Aucune

• État

  • JSON
  • Bâtiments par joueur
  • resources
  • timers
  • progression state

• Clé : leaderboard["main"]

• Responsabilité : Stocke les scores globaux et serve les mises à jour leaderboard.

• Actions

  • updateScore

• Queues

  • updateScore

• État

  • SQLite
  • Tableau scores indexé par joueur
  • Totaux leaderboard courants

Cycle de vie

sequenceDiagram
    participant C as Client
    participant W as world
    participant LB as leaderboard

    C->>W: getOrCreate(playerId) + initialize()
    Note over W: seed state + schedule collection
    W-->>C: stateUpdate
    loop gameplay loop
        C->>W: build() / collectProduction()
        W->>LB: updateScore(...)
    Note over LB: upsert scores
    LB-->>C: leaderboardUpdate
    W-->>C: stateUpdate
    end

Carte de référence

Acteurs

• Contrôle d'accès
• Actions
• Clés d'acteur
• Planification d'acteur
• Statuts d'acteur
• Acteurs IA et générés par l'utilisateur Rivet
• Authentification
• Démarrage rapide Cloudflare Workers
• Communiquer entre acteurs
• Connexions
• Débogage
• Modèles de conception
• Destruction d'acteurs
• Variables éphémères
• Erreurs
• Base de données SQL externe
• Gestionnaire Fetch et WebSocket
• Types assistants
• Icônes et noms
• État en mémoire
• Paramètres d'entrée
• Cycle de vie
• Limites
• Gestionnaire de requête HTTP bas niveau
• Stockage KV bas niveau
• Gestionnaire WebSocket bas niveau
• Métadonnées
• Démarrage rapide Next.js
• Démarrage rapide Node.js et Bun
• Queues et boucles Run
• Démarrage rapide React
• Temps réel
• Acteur Sandbox
• Mise à l'échelle et concurrence
• Partage et adhésion à l'état
• SQLite
• SQLite + Drizzle
• Tests
• Dépannage
• Types
• API HTTP vanille
• Versions et mises à jour
• Workflows

Agent Os

• Communication agent-à-agent
• agentOS vs Sandbox
• Authentification
• Benchmarks
• Configuration
• Paquet principal
• Tâches Cron
• Déploiement
• Passerelle LLM intégrée
• Événements
• Système de fichiers
• Limitations
• Credentials LLM
• Multijoueur
• Réseautage et aperçus
• Aperçu
• Permissions
• Persistance et sommeil
• Processus et shell
• Queues
• Démarrage rapide
• Montage Sandbox
• Sécurité et authentification
• Modèle de sécurité
• Sessions
• Logiciels
• SQLite
• Prompt système
• Outils
• Webhooks
• Automatisation workflow

Clients

• Node.js et Bun
• React
• Swift
• SwiftUI

Connexion

• Déployer sur Amazon Web Services Lambda
• Déploiement sur AWS ECS
• Déploiement sur Cloudflare Workers
• Déploiement sur Freestyle
• Déploiement sur Google Cloud Run
• Déploiement sur Hetzner
• Déploiement sur Kubernetes
• Déploiement sur Railway
• Déploiement sur Rivet Compute
• Déploiement sur Vercel
• Déploiement sur VMs et bare metal
• Supabase

Cookbook

• Jeu multijoueur

Général

• Configuration d'acteur
• Architecture
• Partage de ressources cross-origin
• Documentation pour LLMs et IA
• Réseautage edge
• Endpoints
• Variables d'environnement
• Serveur HTTP
• Logging
• Checklist de production
• Configuration de registre
• Modes runtime

Auto-hébergement

• Configuration
• Docker Compose
• Conteneur Docker
• Système de fichiers
• FoundationDB (Enterprise)
• Installation du moteur Rivet
• Kubernetes
• Multi-région
• PostgreSQL
• Checklist de production
• Déploiement Railway
• Déploiement Render