Files
Rail_Enterprise/docs/PROTOCOL.md
T
Alby96andClaude Opus 5.5 2992e7cc36 F6: mercato globale, storico prezzi a 24 mesi e previsione
Prima parte della F6: il pannello «Mercato globale» dell'immagine di
riferimento 06, con i dati calcolati dal server.

- Lo storico dei prezzi globali passa da 360 a 720 giorni. I salvataggi
  con lo storico di un anno si migrano al caricamento allungando la
  finestra (RollingWindow.Extended), senza cambiare formato.
- MarketOutlook (Core) è un'analisi in sola lettura del mondo: storico
  mensile, variazione a 30 giorni, offerta e domanda con la quota
  mondiale, scorte in mesi, indice materie prime, previsione a 4 mesi
  dalla componente mondiale con banda, destinazioni di vendita ordinate
  per prezzo con la linea che le collega, hub, evento in corso e
  avanzamento verso la compravendita in proprio. Parametri nuovi in
  balance.json (market.outlook); interpretazioni nell'ADR 0015.
- Protocollo: DetailKind.Market (7) e MarketReport (129); il server
  risponde su richiesta, il client lo mostra in un pannello a tutto
  schermo e il pilota automatico ne fa la schermata 16_mercato.
- Test: finestra allungata e migrazione, storico mensile, previsione
  deterministica ed entro i limiti, evento, analisi su Valdoria,
  round-trip del messaggio e quadro via WebSocket.

La simulazione non cambia: l'analisi non scrive nel mondo e
l'accettazione F4 dà gli stessi numeri di prima.

Closes #29.

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

18 KiB
Raw Blame History

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://<host>:<porta>/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; dalla F6: 7 quadro del mercato globale), target: i32 (id del treno, del deposito, della compagnia o dell'industria; ignorato per 3, 6 e 7). 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)
129 MarketReport day: i64, index: f32 (100 = prezzi base), indexChange: f32, goods: [GoodMarketInfo], hubs: [HubMarketInfo], eventGood: i32 (−1 nessuno), eventShock: f32 (con segno, frazione del prezzo base), eventMonths: f32, tradingUnlocked: bool, tradingTier: u8, tradingProgress: f32, netWorth, netWorthRequired: Money, townsConnected, townsRequired, townPopulation: i32, rating, ratingRequired: string, ratingMet: bool (su richiesta, F6; ADR 0015)
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 }
  • GoodMarketInfo { good, available, price: f64 (centesimi), change: f32 (30 giorni), supplyMonth, demandMonth, worldSupplyMonth, worldDemandMonth, stockUnits: f64, stockMonths: f32 (−1 senza domanda), history: [PricePointInfo { day: i64, price: f64 }] (un campione per mese, l'ultimo è oggi), forecast: [ForecastInfo { months: u8, price, low, high: f64 }], sellPlaces: [SellPlaceInfo { kind: u8 (0 industria, 1 hub), target, price: f64, line: i32 (−1 non collegato) }] }
  • HubMarketInfo { hub, kind: u8 (0 porto, 1 valico), monthlyCapacity, duty: f32, usedThisMonth, line: i32 (−1 non collegato) }

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. Dalla F6 MarketReport (quadro del mercato globale per la compagnia della sessione), che il pannello chiede all'apertura e a ogni nuovo giorno; il server non lo manda da solo.
  • 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.