- 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
4.3 KiB
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 flagsche dice quali blocchi opzionali seguono. Un lettore vecchio ignora i byte residui del payload. protocolVersioncresce 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
TrainMotionsolo 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.