Files
Rail_Enterprise/docs/PROTOCOL.md
T
Claude 290a1d886c F0: fondamenta della soluzione, script, documenti e harness di test
- ViaFerrea.sln con Core e Protocol (net10.0 + net8.0), Server, Tools, Tests
- Directory.Build.props con versione unica e warning come errori
- Script build/test/check-nuget/publish-image (+ build.ps1)
- Documenti: GUIDA, GDD, ARCHITECTURE, PROTOCOL (bozza), STATE, ADR 0001
- Harness di test interno con i primi test su Rng (xoshiro256**)
- Immagini di riferimento 01-05

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0191R7vXgtbAvSV4V8tj8uzL
2026-10-01 21:50:41 +00:00

4.3 KiB
Raw Blame History

Via Ferrea — Protocollo di rete (bozza)

Stato: bozza F0. Diventa normativo in F3, quando ogni messaggio avrà il test di round-trip.

1. Trasporto

  • WebSocket su ws://<host>:<porta>/ws (TLS a carico del reverse proxy: wss://).
  • Solo messaggi binari. Un messaggio WebSocket contiene esattamente un frame.
  • Porta predefinita 7400 (VF_PORT).

2. Frame

offset  tipo   campo
0       u32    length      lunghezza di messageId + payload (byte)
4       u16    messageId   identificativo stabile del messaggio
6       ...    payload     corpo serializzato a mano
  • Little endian. Dimensione massima 4 MB (length ≤ 4 194 298): frame più grandi chiudono la connessione con codice 1009.
  • Serializzazione con SpanWriter/SpanReader (Write(ref SpanWriter) / Read(ref SpanReader) per ogni messaggio). Nessuna reflection, nessun JSON.

Tipi elementari

Tipo Codifica
bool 1 byte, 0 o 1
u8/u16/u32/u64, i8…i64 little endian a larghezza fissa
varuint LEB128 (lunghezze e conteggi)
f32/f64 IEEE 754 little endian
string varuint lunghezza in byte + UTF-8
Money i64 centesimi
identità (StationId…) i32
liste varuint conteggio + elementi

Evoluzione

  • Gli id dei messaggi e l'ordine dei campi non cambiano mai.
  • I campi nuovi si aggiungono in coda, dopo un u8 flags che dice quali blocchi opzionali seguono. Un lettore vecchio ignora i byte residui del payload.
  • protocolVersion cresce solo per modifiche incompatibili.

3. Handshake

Client → Hello   { protocolVersion: u16, clientVersion: string, token: string, resumeSessionId: u64 (0 = nuova) }
Server → Welcome { sessionId: u64, worldSummary, dataHash: u64, difficulty: string }
       | Reject  { code: u16, reason: string }

Codici di Reject: 1 versione del protocollo, 2 token errato, 3 dati diversi, 4 server pieno, 5 partita non caricata.

4. Messaggi Client → Server

id Nome Contenuto
1 Hello vedi handshake
2 Ping nonce: u64
3 Subscribe viewport (rettangolo in celle), livello di dettaglio
4 Command seq: u32, type: u16, payload del comando
5 SetSpeed speed: u8 (0, 1, 2, 4, 8)
6 ListSaves —
7 Save name: string
8 Load id: string
9 NewGame seed, size, startYear, difficultyPreset, overrides, endlessFlags

Comandi (Command.type)

BuildTrack, RenewTrack, UpgradeTrack, Demolish, BuildStation, BuildDepot, PlaceSignal, BuyVehicle, SellVehicle, ComposeTrain, CreateLine, EditLine, AssignTrain, SendToDepot, SetReserve, SetMaintenancePolicy, ScheduleService, OrderParts, TakeLoan, RepayLoan, AcceptAgreement, RejectAgreement, BuyGoods, SellGoods, BuyIndustry, SetIndustryPolicy, OverhaulIndustry, UpgradeIndustry, Ipo, BuyShares, SellShares, PayDividend, LaunchBid, RespondBid, BuyConcession, AcceptContract, FundResearch, DelegateRegion.

I codici numerici dei comandi coincidono con l'enum CommandType di Core e non cambiano mai.

5. Messaggi Server → Client

id Nome Contenuto
101 Welcome vedi handshake
102 Reject vedi handshake
103 Pong nonce: u64, serverTick: u64
110 MapChunk coordinate del chunk 64×64, altezze, tipi cella
111 EntitySnapshot stato completo delle entità visibili
112 EntityDelta variazioni dall'ultimo snapshot
113 TrackWorks opere per arco: tipo, altezze, stato del cantiere
114 TrainMotion trainId, segmenti di moto, stato, condizione
120 DailyDigest data, cassa, patrimonio, rating, prezzi, eventi, stateHash, slow
121 MaintenanceAlert treno o deposito, componente, scadenza
122 EmploymentReport mensile
123 MarketTape giornaliero: prezzi delle azioni, offerte in corso
130 CommandResult seq, esito, codice di errore, messaggio
131 Notification livello, testo, riferimento all'entità
132 Newspaper mensile: la «Cronaca»

6. Interest management

  • TrainMotion solo per i treni nel viewport sottoscritto più un chunk di margine, al massimo 10 aggiornamenti al secondo per treno.
  • I chunk della mappa si inviano su richiesta implicita (viewport) e una sola volta per sessione, salvo modifiche.
  • Obiettivo di banda in regime: < 100 KB/s per client.