Files
Rail_Enterprise/docs/adr/0009-server-client-protocollo.md
T
Alby96andClaude Opus 5.5 c1a0049bcf
CI / Build e test (pull_request) Successful in 1m20s
CI / Immagine Docker (pull_request) Successful in 37s
Infrastruttura: nome «Rail Enterprise», CI e rilasci su Gitea, documentazione
Il progetto adotta il nome «Rail Enterprise» ovunque (codice RailEnterprise.*,
variabili RE_*, intestazioni RESV/RECL, immagine rail-enterprise-server) per
allinearsi al repository Gitea. Aggiunge Gitea Actions sul modello di Chronos:
CI su PR e main, rilascio da tag con gioco Windows (client Godot + server in
server/), server Windows/Linux e immagine Docker nel registro Gitea, nightly.
Aggiunge i riferimenti visivi 06–09, i modelli di PR e issue, l'ADR 0014 e
aggiorna README (comandi locali), STATE e CLAUDE.md. 120 test verdi.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-07 11:14:54 +01:00

5.4 KiB
Raw Blame History

ADR 0009 — Protocollo, server, client e collaudi (F3)

Stato: accettato (F3).

Contesto

La guida (sezione 14) fissa frame, elenco dei messaggi, configurazione del server, Docker e struttura del client, ma lascia aperti il contenuto dei messaggi di stato, il calcolo dei delta, la rappresentazione del moto dei treni, come il client calcola le anteprime con le stesse classi del server e come collaudare client e immagine in un ambiente senza grafica.

Decisione

  1. Evoluzione dei messaggi. Ogni messaggio e ogni record termina con un byte di estensione (0 oggi); i lettori ignorano i byte residui. I comandi viaggiano con il payload preceduto dalla lunghezza, così un lettore vecchio può saltarli. Tutti i 38 comandi hanno già un record in Core con il formato definitivo; quelli delle fasi future rispondono NotImplemented.

  2. Messaggio in più. SaveList (133) risponde a ListSaves e Save: la guida elenca le richieste ma non la risposta.

  3. Stato delle entità. EntitySnapshot alla connessione e dopo un caricamento; EntityDelta con i record il cui hash (XxHash64 del record serializzato) è cambiato rispetto all'ultimo invio a quella sessione, più le rimozioni. Si calcola dopo i comandi riusciti e ogni giorno. TrackWorks porta gli archi con i campioni a precisione piena (servono alle anteprime) in lotti sotto 1 MB, perché il frame massimo è 4 MB.

  4. Terreno. MapChunk 64×64 celle con altezze, tipi e larghezza dei fiumi compressi con Brotli; si inviano i chunk del viewport (con un chunk di margine) una sola volta per sessione e si rimandano quando cambia il loro hash (abitati che crescono, industrie che nascono o chiudono).

  5. Moto dei treni. TrainMotion porta i passi del percorso dalla coda al tratto prenotato, la distanza della testa lungo quei passi e la velocità; il client avanza la testa a velocità costante (al massimo mezzo secondo di estrapolazione). Si invia ogni 100 ms per i treni in moto nel viewport e una volta per quelli fermi; i moti si scartano per primi se la coda d'invio supera 256 KB (backpressure), mentre i messaggi affidabili chiudono la sessione oltre 64 MB.

  6. Una compagnia per tutte le sessioni. In F3 ogni sessione guida la compagnia del giocatore: più client sono più finestre sulla stessa partita. Le compagnie per giocatore arrivano con le IA.

  7. Copia del mondo nel client. ClientWorld e ProtocolClient stanno in RailEnterprise.Protocol (namespace Client): li usano il client Godot, i test di integrazione e railenterprise-tools smoke. ClientWorld ricostruisce un RailNetwork con gli stessi id del server; TrackPreview (Core) è lo stesso codice del comando BuildTrack, quindi l'anteprima coincide: il client manda il costo atteso e il server rifiuta con PreviewMismatch se differisce.

  8. Server. Il ciclo di gioco ha un thread suo; i messaggi delle sessioni entrano da una coda concorrente drenata a inizio giro. Se il tick medio moltiplicato per la velocità supera il 90 % del budget la velocità effettiva si dimezza e il resoconto segnala slow. All'avvio si riprende l'ultimo salvataggio automatico, se c'è. Le metriche Prometheus hanno i nomi della guida (tick_ms, trains, packets, contracts, sessions).

  9. Docker. L'immagine .NET 10 è Ubuntu 24.04: l'utente si crea con useradd invece di adduser (assente). Core e Protocol si compilano solo per net10.0 nell'immagine (-p:ReServerOnly=true): la build non scarica il targeting pack net8.0 e non ha bisogno di rete oltre alle immagini di base. IsTrimmable è stato tolto per lo stesso motivo (pacchetto ILLink).

  10. Client. Scena principale minima e nodi costruiti in codice (niente editor nel flusso di lavoro); tema dalla palette dell'immagine 05 con i font OFL in assets/fonts/; testi con l'italiano come lingua sorgente e traduzioni in assets/i18n/strings.csv caricate all'avvio; italiano predefinito. Scala dei simboli tarata sulle immagini 01 e 02: unità di mondo = 5,5·zoom^−0,56 (1 unità = 1 m da vicino). Rive curve: l'alfa della texture del terreno è il campo dell'acqua interpolato tra i centri delle celle e uno shader lo taglia a 0,5. Fumo con GpuParticles2D, alberi con MultiMeshInstance2D.

  11. Collaudi senza grafica. railenterprise-tools smoke gioca contro un server vero (locale o in Docker): trova un fiume, costruisce con l'anteprima, compra un treno e confronta la posizione estrapolata con quella del moto successivo. Il client ha un pilota automatico (-- --autopilot cartella, scripts/client-autopilot.sh) che fa lo stesso con la grafica vera (Godot sotto Xvfb con Mesa) e salva schermate.

  12. Replay. Con --record (o RE_RECORD) il server salva lo stato di partenza accanto al registro e vi accoda ogni comando eseguito con tick, emittente e payload del protocollo; railenterprise-tools replay li riapplica ai loro tick e confronta l'hash di stato.

Conseguenze

  • L'accettazione F3 è verificata in tre modi: test in processo (scarto tra client e server sotto 1 cm), smoke contro il container Docker e pilota automatico del client con schermate.
  • I fiumi larghi una cella mostrano ancora gradini nella vista d'insieme: servirà un disegno vettoriale dei corsi d'acqua.
  • I nodi Godot creati in codice hanno costruttori con parametri: vanno bene in gioco, ma l'editor non può ricrearli in caso di ricarica a caldo degli assembly.