# Rail Enterprise — Protocollo di rete Stato: **normativo da F3**. Ogni messaggio e ogni comando ha un test di round-trip (`tests/RailEnterprise.Tests/Protocol/ProtocolTests.cs`); decisioni in ADR 0009. ## 1. Trasporto - WebSocket su `ws://:/ws` (TLS a carico del reverse proxy: `wss://`). - Solo messaggi binari. Un messaggio WebSocket contiene esattamente un frame. - Porta predefinita 7400 (`RE_PORT`). Il primo messaggio del client dev'essere `Hello` entro 10 s. ## 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: frame più grandi chiudono la connessione (1009). - `SpanWriter`/`SpanReader` con `Write(ref SpanWriter)` / `Read(ref SpanReader)` per ogni messaggio. ### Tipi elementari | Tipo | Codifica | |---|---| | `bool` | 1 byte, 0 o 1 (altri valori: errore) | | `u8/u16/u32/u64`, `i16/i32/i64` | little endian a larghezza fissa | | `varuint` | LEB128 (lunghezze e conteggi) | | `f32/f64` | IEEE 754 little endian | | `string` | `varuint` lunghezza in byte + UTF-8 | | `bytes` | `varuint` lunghezza + byte | | `Money` | `i64` centesimi | | `Vec2` | due `f64` (metri) | | identità | `i32` (−1 = nessuna) | | liste | `varuint` conteggio + elementi | | `flags` | `u8` di estensione in coda a ogni messaggio e record (0 oggi) | ### Evoluzione - Gli id dei messaggi, dei comandi e l'ordine dei campi non cambiano mai. - I campi nuovi si aggiungono in coda, dopo il byte `flags`, che dice quali blocchi seguono. Un lettore vecchio ignora i byte residui; un messaggio vecchio senza `flags` vale 0. - `protocolVersion` (oggi 1) cresce solo per modifiche incompatibili. - Blocchi: il bit 0 di `flags` annuncia il blocco 1 (campi della fase F4), i bit successivi i blocchi delle fasi future. Messaggi e comandi nuovi prendono id nuovi; un lettore vecchio scarta i messaggi che non conosce. ## 3. Handshake ``` Client → Hello { protocolVersion: u16, clientVersion: string, token: string, resumeSessionId: u64, dataHash: u64 } Server → Welcome { sessionId: u64, summary: WorldSummary, dataHash: u64, difficulty: string } | Reject { code: u16, reason: string } ``` - `resumeSessionId` ≠ 0 riprende una sessione disconnessa da meno di 120 s (stato rimandato per intero). - `dataHash` ≠ 0 deve coincidere con l'hash dei dati del server. - Codici di `Reject`: 1 versione del protocollo, 2 token errato, 3 dati diversi, 4 server pieno, 5 nessuna partita. - `Welcome` può arrivare di nuovo durante la sessione (nuova partita o caricamento): il client azzera la copia del mondo. `WorldSummary { seed: u64, sizeKm: i32, startYear: i32, tick: i64, date: string, companyId: i32, companyName: string, regionId: string, widthCells: i32, heightCells: i32, cellSizeM: f64, chunkCells: i32, speed: u8, terrainHash: u64, costMultiplier: f64 }` ## 4. Messaggi Client → Server | id | Nome | Contenuto | |---|---|---| | 1 | Hello | vedi handshake | | 2 | Ping | `nonce: u64` | | 3 | Subscribe | `x0, y0, x1, y1: i32` (celle, estremi inclusi), `lod: u8` | | 4 | Command | `seq: u32`, `type: u16`, `payload: bytes` (vedi sotto) | | 5 | SetSpeed | `speed: u8` (0, 1, 2, 4, 8) | | 6 | ListSaves | — | | 7 | Save | `name: string` | | 8 | Load | `saveId: string` | | 9 | NewGame | `seed: u64`, `sizeKm: i32`, `startYear: i32` (0 = predefinito), `difficultyPreset: string`, `overrides: [(key: string, value: f64)]`, `endlessFlags: u32` | | 10 | RequestDetail | `kind: u8` (1 cartella di manutenzione di un treno, 2 registro officina di un deposito, 3 registro degli impieghi; dalla F5: 4 scheda di una compagnia, 5 scheda di un'industria, 6 Cronaca), `target: i32` (id del treno, del deposito, della compagnia o dell'industria; ignorato per 3 e 6). Aggiunto in F4 | ### Comandi (`Command.type`, payload in ordine) | type | Comando | Payload | |---|---|---| | 1 | BuildTrack | `polyline: [Vec2]`, `heightOffsetM: f64`, `allowBridges: bool`, `allowTunnels: bool`, `trackClass: string`, `doubleTrack: bool`, `electrified: bool`, `expectedCostCents: i64` (0 = non verificare) | | 2 | RenewTrack | `edge: i32` | | 3 | UpgradeTrack | `edge: i32`, `trackClass: string`, `doubleTrack: bool`, `electrified: bool` | | 4 | Demolish | `target: u8` (0 arco, 1 stazione, 2 deposito, 3 segnali), `id: i32` | | 5 | BuildStation | `position: Vec2`, `platforms: i32`, `name: bool + string` | | 6 | BuildDepot | `position: Vec2`, `size: string`, `name: bool + string` | | 7 | PlaceSignal | `edge: i32`, `positionM: f64` | | 8 | BuyVehicle | `vehicleType: string`, `depot: i32`, `count: i32` | | 9 | SellVehicle | `vehicle: i32` | | 10 | ComposeTrain | `depot: i32`, `vehicles: [i32]`, `name: bool + string` | | 11 | CreateLine | `name: string`, `color: string`, `stops: [LineStop]` | | 12 | EditLine | `line: i32`, `stops: [LineStop]`, `name: bool + string` | | 13 | AssignTrain | `train: i32`, `line: i32` (−1 = togli dal servizio) | | 14 | SendToDepot | `train: i32`, `depot: i32` | | 15 | SetReserve | `train: i32`, `reserve: bool` | | 16 | SetMaintenancePolicy | `scope: u8` (0 compagnia, 1 linea, 2 treno), `target: i32`, `policy: string` | | 17 | ScheduleService | `train: i32`, `intervention: string` | | 18 | OrderParts | `depot: i32`, `quantity: i32`; blocco 1 (F5): `industry: i32` (ricambi ordinati per un'industria posseduta, oltre la scorta della politica) | | 19 | TakeLoan | `amount: Money` | | 20 | RepayLoan | `loan: i32`, `amount: Money` | | 21 | AcceptAgreement | `agreement: i32` | | 22 | RejectAgreement | `agreement: i32` | | 23 | BuyGoods | `station: i32`, `good: string`, `units: i32`, `maxUnitPrice: Money` | | 24 | SellGoods | `station: i32`, `good: string`, `units: i32`, `minUnitPrice: Money` | | 25 | BuyIndustry | `industry: i32`, `offer: Money` | | 26 | SetIndustryPolicy | `industry: i32`, `budget: u8` (0 nessuno, 1 base, 2 alto) | | 27 | OverhaulIndustry | `industry: i32` | | 28 | UpgradeIndustry | `industry: i32` | | 29 | Ipo | `floatShare: f64` | | 30 | BuyShares | `company: i32`, `shares: i64`, `maxPrice: Money` | | 31 | SellShares | `company: i32`, `shares: i64`, `minPrice: Money` | | 32 | PayDividend | `perShare: Money` | | 33 | LaunchBid | `target: i32`, `pricePerShare: Money`, `targetShare: f64` | | 34 | RespondBid | `bid: i32`, `accept: bool`; blocco 1 (F5): `defense: u8` (0 nessuna, 1 riacquisto, 2 dividendo straordinario, 3 cavaliere bianco), `knight: i32` | | 35 | BuyConcession | `region: i32` | | 36 | AcceptContract | `contract: i32` | | 37 | FundResearch | `project: string`, `amount: Money` | | 38 | DelegateRegion | `region: i32`, `objective: string`, `budget: Money` | | 39 | MergeCompany | `subsidiary: i32` — fusione di una controllata dopo 360 giorni di controllo (aggiunto in F5) | `LineStop { station: i32, load: bool, unload: bool, waitFull: bool, maxWaitDays: i32 }`. Ogni payload termina con `flags`. I codici coincidono con l'enum `CommandType` di Core. Dalla F4 i comandi 15–18 e 21–22 sono attivi (`policy`: `economy`, `standard`, `thorough`, oppure `inherit` per togliere l'eccezione di linea o treno; `intervention`: `inspection`, `service`, `overhaul`; `OrderParts` fissa la scorta desiderata del deposito). Dalla F5 sono attivi anche 25–34 e 39 (industrie, borsa, offerte, fusioni; `LaunchBid` su una compagnia fallita è un'offerta all'asta degli attivi: prezzo per azione × azioni). Fino alla loro fase i comandi 23–24 e 35–38 rispondono `NotImplemented`. Il server imposta l'emittente in base alla sessione. ## 5. Messaggi Server → Client | id | Nome | Contenuto | |---|---|---| | 101 | Welcome | vedi handshake | | 102 | Reject | vedi handshake | | 103 | Pong | `nonce: u64`, `serverTick: u64` | | 110 | MapChunk | `cx, cy, width, height: i32`, `compression: u8` (1 = Brotli), `data: bytes` = altezze `u16` (dm) + tipi `u8` + larghezza fiumi `u8` | | 111 | EntitySnapshot | `tick: i64`, `EntityLists` | | 112 | EntityDelta | `tick: i64`, `EntityLists` (nuovi o cambiati), `removed: [(type: u8, id: i32)]` | | 113 | TrackWorks | `edges: [EdgeInfo]`, `removed: [i32]` (lotti sotto 1 MB) | | 114 | TrainMotion | `trainId: i32`, `tick: i64`, `state: u8`, `condition: f32`, `speed: f32` (m/s), `lengthM: f32`, `headDistance: f64`, `segments: [(edge: i32, forward: bool, fromS: f64, toS: f64)]` | | 120 | DailyDigest | `day: i64`, `tick: i64`, `date: string`, `cash: Money`, `netWorth: Money`, `rating: string`, `prices: [Money]`, `events: [EventInfo]`, `stateHash: u64`, `slow: bool`, `speed: u8`, `tickMs: f32` | | 121 | MaintenanceAlert | `train: i32`, `depot: i32`, `component: string`, `condition: f32`, `dueDays: i32`, `text: string` | | 122 | EmploymentReport | `day: i64`, `rows: [EmploymentRow]`; blocco 1: `agreements: [AgreementInfo]` (mensile, su richiesta e dopo Accept/RejectAgreement) | | 123 | MarketTape | `day: i64`, `shares: [SharePrice]`, `bids: [BidInfo]` | | 124 | MaintenanceCard | `train, day: i64, condition: f32, status: u8, policy: u8, policyOverride: u8, reserve, failure: u8, failedVehicle, failedComponent: string, rescueHours: f32, nextIntervention: string, nextDueDays: f32, plannedIntervention: string, maintenanceDepot, serviceKmPerDay: f32, costThisYear: Money, costLastYear: Money, failuresThisYear, failuresTotal, coveredBy, covering, vehicles: [VehicleCard], history: [MaintenanceRecordInfo]` (su richiesta, F4) | | 125 | WorkshopRegister | `depot, day: i64, stalls, jobsStaff, staffPresent: f32, workRate: f32, spareParts, partsTarget, partsReserved, jobs: [WorkshopJobInfo], booked: [WorkshopJobInfo]` (su richiesta, F4) | | 126 | CompanyCard | `company, totalShares: i64, treasury: i64, holdings: [HoldingInfo], priceHistory: [f64] (centesimi, mensile), history: [CompanyYearInfo], annualProfit, dividendsYear, debt, marketCap: Money, controlDays: i64, auctionMin, auctionBest: Money, auctionBestBidder, auctionEndDay: i64` (su richiesta, F5) | | 127 | IndustryCard | `industry, margin, conditionMultiplier, wearPerDay, recoveryPerDay: f32, maintenanceCostPerDay, maintenanceSpentYear: Money, partsTarget, partsPerMonth, partsOrdered, machineryRequired, upgradeCost, valuation, cash: Money, breakdownChancePerYear: f32, stops: [IndustryStopInfo]` (su richiesta, F5) | | 128 | Chronicle | `gameOver: bool, reason: u8 (1 fallimento, 2 scalata, 3 riscatto scaduto), text, winner, day: i64, company, foundedYear, prestige: i64, history: [CompanyYearInfo], records: [RecordInfo], highlights: [string]` (alla fine della partita e su richiesta, F5) | | 130 | CommandResult | `seq: u32`, `type: u16`, `error: u16`, `message: string`, `created: [i32]`, `tick: i64` | | 131 | Notification | `EventInfo` | | 132 | Newspaper | `day: i64`, `title: string`, `articles: [(headline: string, body: string)]` | | 133 | SaveList | `saves: [SaveInfo]` | Record (ognuno chiude con `flags`): - `EntityLists`: liste in quest'ordine di `CompanyInfo`, `TownInfo`, `IndustryInfo`, `HubInfo`, `NodeInfo`, `StationInfo`, `DepotInfo`, `LineInfo`, `VehicleInfo`, `TrainInfo`. - `CompanyInfo { id, name, color, isPlayer, cash: Money, netWorth: Money, rating, tier: u8, bankrupt }`; blocco 1: `maintenancePolicy: u8` (0 economica, 1 standard, 2 accurata); blocco 2 (F5): `personality: string, listed, sharePriceCents: f64, sentiment: f32, founderShare: f32, controlledBy: i32, merged, receivership, receivershipUntilDay: i64, annualProfit: Money` - `TownInfo { id, name, position: Vec2, population: i32, radiusCells: f64, satisfaction: f32, services: i32 }` - `IndustryInfo { id, type: string, name, position, footprintCells: i32, level: i32, closed, efficiency: f32, condition: f32, owner: i32 }`; blocco 1 (F5): `budget: u8 (0 nessuno, 1 base, 2 alto), spareParts, machinery, stoppedUntilDay: i64, stopKind: u8 (1 guasto, 2 incidente, 3 revisione, 4 ammodernamento), pendingWork: u8 (1 revisione, 2 ammodernamento), partsShort: bool` - `HubInfo { id, kind: string, name, position }` - `NodeInfo { id, position, heightM: f64, owner, station, depot, edges: [i32] }` - `StationInfo { id, owner, name, node, position, platforms: i32, waitingUnits: i32, industries: [i32], towns: [i32] }` - `DepotInfo { id, owner, name, node, position, size: string }`; blocco 1: `stalls, jobsStaff, staffPercent: u8, spareParts, partsTarget, jobs, waitingParts: bool` - `LineInfo { id, owner, name, color, stops: [LineStop] }`; blocco 1: `policy: u8` (255 = quella della compagnia) - `VehicleInfo { id, owner, type: string, depot, train, condition: f32 }` - `TrainInfo { id, owner, name, line, state: u8, vehicles: [i32], maxSpeedKmh: f32, lengthM: f32, load: i32, capacity: i32, depot: i32 }`; blocco 1: `condition: u8` (componente più debole), `maintenance: u8` (0 in servizio, 1 intervento prenotato, 2 in officina, 3 guasto lieve, 4 fermo in linea, 5 rimorchiato), `reserve: bool`, `policy: u8` (255 = ereditata), `nextIntervention: string`, `nextDueDays: i32`, `maintenanceDepot: i32` - `EdgeInfo { id, owner, a, b, trackClass: u8, doubleTrack, electrified, state: u8, condition: f32, structureCondition: f32, progress: f32, samples: [(s, x, y, h, ground: f64, kind: u8, speedLimitKmh: f64)], signals: [f64] }` - `EventInfo { day: i64, kind: u8, severity: u8, text, entity: u8, entityIndex: i32, company: i32 }` - `EmploymentRow { industry, jobsWorkers, jobsStaff, workersPresent: f32, staffPresent: f32, reason, sources: [EmploymentSource { town, homeStation, line, category: u8, headcount, coverage: f32 }] }`; blocco 1: `kind: u8` (0 industria, 1 deposito: `industry` è allora l'id del deposito), `workersReason: u8`, `staffReason: u8` (0 nessuno, 1 nessuna stazione, 2 nessuna città entro il tempo massimo, 3 nessun lavoratore libero, 4 città senza servizi per il personale, 5 capacità delle carrozze insufficiente), `workersReasonLine: i32`, `staffReasonLine: i32` - `AgreementInfo { id, industry, carrier, seatsPerDay, monthlyFee: Money, state: u8 (0 proposta, 1 attiva, 2 rifiutata, 3 scaduta, 4 saltata, 5 conclusa), proposedDay: i64, startDay: i64, endDay: i64, coverage: f32, shortDays }` - `VehicleCard { vehicle, type: string, odometerKm: f32, ageYears: f32, ageFactor: f32, components: [ComponentCard { component: string, condition: f32, wearPerDay: f32 }] }` - `MaintenanceRecordInfo { day: i64, intervention: string, cost: Money, depot, parts }` - `WorkshopJobInfo { train, intervention: string, inStall, started, progress: f32, days: f32, parts, queuedDay: i64 }` - `SharePrice { company, price: Money, change: f32, listed }`; blocco 1 (F5): `priceCents: f64, outstanding: i64, freeFloat: i64, founderShare: f32, controlledBy: i32` - `BidInfo { bid, bidder, target, pricePerShare: Money, targetShare: f64, expiresDay: i64 }`; blocco 1 (F5): `state: u8, committedShare: f64, defenses: u8 (bit per difesa usata), knight: i32, accepted: bool` (la compagnia della sessione ha aderito) - `HoldingInfo { holder: i32 (−1 fondatore, −2 mercato, altrimenti compagnia), shares: i64 }`, `CompanyYearInfo { year, netWorth, cash, revenue, profit: Money, tier: u8, trains, trackKm: f32, sharePrice: Money }` - `IndustryStopInfo { day: i64, days, kind: u8 }`, `RecordInfo { title, value: string, year }` - `SaveInfo { saveId, name, gameDate, sizeBytes: i64, savedUnixMs: i64, autosave }` ## 6. Flusso e interest management - Dopo il `Welcome` il server manda `EntitySnapshot` e tutti i `TrackWorks`; i chunk arrivano dopo il primo `Subscribe` (viewport con un chunk di margine), una volta per sessione, e si rimandano se cambiano. - `EntityDelta` e `TrackWorks` incrementali dopo ogni comando riuscito e a ogni cambio di giorno. - `TrainMotion` ogni 100 ms per i treni in moto con la testa nel viewport (più un chunk), una volta per quelli fermi: al massimo 10 aggiornamenti al secondo per treno. Il client avanza la testa a velocità costante tra un moto e l'altro (fattore 60: un tick = 3 s di orologio dei treni). - `DailyDigest` e `MarketTape` (listino delle compagnie attive e offerte in corso) a ogni giorno; `EmploymentReport` a ogni mese; `Notification` per gli eventi non informativi della compagnia della sessione; `MaintenanceAlert` quando un treno scende sotto le soglie d'avviso (40) o critica (30) e quando un'officina resta senza ricambi. - Dettagli su richiesta (F4): `MaintenanceCard`, `WorkshopRegister` ed `EmploymentReport` rispondono a `RequestDetail` per entità della compagnia della sessione (le richieste per entità altrui o inesistenti non hanno risposta). Il client li richiede mentre il pannello è aperto (una volta al secondo): i componenti di tutti i veicoli non viaggiano nei delta delle entità. Dalla F5 anche `CompanyCard` (qualunque compagnia), `IndustryCard` (qualunque industria aperta) e `Chronicle`; la Cronaca arriva da sola, una volta per sessione, quando la partita del giocatore finisce. - Backpressure: i moti si scartano oltre 256 KB in coda; oltre 64 MB di messaggi affidabili la sessione si chiude (il client può riprenderla). - Obiettivo di banda in regime: < 100 KB/s per client.