Files
Rail_Enterprise/docs/ARCHITECTURE.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

15 KiB
Raw Blame History

Rail Enterprise — Architettura

Questo documento descrive come è fatto il codice. Va aggiornato a ogni fase: le parti non ancora implementate sono marcate (pianificato, Fn).

1. Progetti e dipendenze

RailEnterprise.Core      (net10.0; net8.0)  simulazione deterministica, dati, mappa, economia, rete, salvataggi
RailEnterprise.Protocol  (net10.0; net8.0)  frame binari, messaggi, SpanWriter/SpanReader       → Core
RailEnterprise.Server    (net10.0, Web SDK) Kestrel, WebSocket, GameLoop, API HTTP, autosave    → Core, Protocol
RailEnterprise.Tools     (net10.0)          railenterprise-tools: validate-data, genmap, profile, simulate, bench, smoke, replay → Core, Protocol
RailEnterprise.Tests     (net10.0)          harness interno, test di unità, scenari             → Core, Protocol, Server
client/RailEnterprise.Client (Godot .NET)   rendering, input, UI; anteprime con Core            → Core, Protocol

Regole:

  • Nessun PackageReference (controllato da scripts/check-nuget.sh). Il solo SDK esterno è Godot.NET.Sdk nel client, fuori dalla soluzione principale.
  • Core e Protocol compilano anche per net8.0 perché il client Godot li referenzia direttamente: niente API successive a .NET 8 in questi due progetti (per esempio System.Threading.Lock).
  • Il client non decide nulla: invia comandi, riceve stato, e usa Core solo per anteprime (profilo del binario, stime nei tooltip) che il server ricalcola.

2. Core: struttura dei namespace

Namespace Contenuto
RailEnterprise.Core.Common Rng (xoshiro256**), StableHash, XxHash64, DMath (funzioni trascendenti deterministiche), Money, identità tipizzate, Vec2.
RailEnterprise.Core.Time GameClock, GameDate, costanti di calendario.
RailEnterprise.Core.Data Definizioni immutabili caricate da data/*.json (GameData), contesto JSON con source generator, validatore di schema e validatore semantico.
RailEnterprise.Core.Map Terrain (altezze ushort in decimetri, tipi cella byte, larghezza dei fiumi), MapGenerator (ADR 0005), ValueNoise, TerrainSampler, NameGenerator, chunk 64×64.
RailEnterprise.Core.Economy Città, industrie, hub, mercato, compagnie, registro contabile a partita doppia, finanza.
RailEnterprise.Core.Rail TrackGeometry (raccordi), TrackPlanner (profilo a 25 m, opere, costi, tempi, vincoli per era), RailNetwork (nodi, archi campionati, stazioni, depositi, cantieri, indice spaziale), Pathfinder (A* sugli archi orientati), veicoli, treni, linee, pacchetti, LineGraph con maschere dei carichi (ADR 0007, 0008).
RailEnterprise.Core.Commands Comandi di gioco (record immutabili) ed esiti. Sono l'unico modo di cambiare il mondo dall'esterno, anche per le IA.
RailEnterprise.Core.Simulation World, WorldContext, SystemPipeline e Systems/, WorldFactory, IndustryPlacer, CommandProcessor e gestori dei comandi, Corporate (fusioni, liquidazioni, fine partita), Estimators (stime condivise da IA e tooltip), ChronicleReport, Ai/ (agenti delle compagnie IA, ricerca del percorso sulle celle), eventi in uscita.
RailEnterprise.Core.Persistence SaveWriter/SaveReader, SaveFile (Brotli), StateHasher.

3. Il tick

World.Tick() esegue i sistemi in ordine fisso (SystemPipeline.CreateDefault) e poi avanza l'orologio. L'ordine della guida è:

Clock → Commands → Construction → Trains → Signals → Stations → Maintenance (treni)
→ Demand (giornaliero) → Commuting → Industries → IndustryMaintenance → Towns → Market
→ Finance → StockMarket → AiAgents (mensile) → Events → Contracts → Hash (giornaliero)

Sistemi implementati (F1–F5), nella loro posizione:

Sistema Frequenza Cosa fa
ClockSystem tick calcola una volta gli indicatori di giorno, mese, trimestre, anno
CommandSystem tick drena la coda dei comandi (CommandProcessor), registra esiti ed eventualmente il log per il replay
ConstructionSystem giorno squadre e cantieri, usura e manutenzione del binario, ispezioni e invecchiamento di ponti e gallerie
TrainSystem tick percorsi, prenotazioni di blocchi, versi e binari di stazione fino al punto sicuro, fisica, soste, carico e scarico (StationWork), Stalled
StationSystem giorno bacini (mensili), scadenze dei pacchetti, consegne in attesa del consumatore, ritiro della produzione verso la destinazione migliore
LocalTransportSystem giorno trasporto locale su strada tra produttori, consumatori e hub entro 3 km (posto di «Stations», ADR 0004)
FleetMaintenanceSystem giorno usura per componente in km di servizio, rischio e guasti (lieve, grave con soccorso, deragliamento), pianificatore predittivo e prenotazioni, officine con stalli, ricambi e personale, riserve, avvisi (posto di «Maintenance», ADR 0010); formule senza stato in Fleet
DemandSystem giorno domanda delle città (con elasticità) e input richiesti dalle industrie
EmploymentSystem giorno/mese servizi cittadini, lavoratori in sede, contratti a piedi e su rotaia per industrie e depositi (IWorkplace, abbinamento mensile sul LineGraph), motivi dei posti scoperti, convenzioni, pacchetti giornalieri dei pendolari, presenze e coperture (posto di «Commuting», ADR 0008 e 0010)
IndustrySystem giorno/trimestre/anno produzione (nulla durante i fermi), esaurimento giacimenti, salari, crescita delle industrie servite, chiusure, nascite
IndustryMaintenanceSystem giorno/mese condizione degli impianti (usura con l'utilizzo, recupero del budget), consumo di ricambi, fermi e incidenti, revisioni e ammodernamenti in attesa di macchinari, scelte dei proprietari privati, conguaglio con il proprietario (ADR 0011)
TownSystem giorno/mese/anno consumo e soddisfazione, crescita, migrazione, espansione dell'abitato
MarketSystem giorno prezzi globali con componente mondiale e shock, domanda insoddisfatta
FinanceSystem giorno/mese/anno costi di esercizio di veicoli, stazioni e depositi, valori di libro, cassa negativa e bancarotta, rate dei prestiti, rating, livelli (Tiers), utile mensile nell'anello dei 12 mesi, chiusura dei conti
StockMarketSystem giorno/mese/anno prezzi e sentiment, valore delle partecipazioni, offerte pubbliche (adesioni, esito), controllo e utili delle controllate, amministrazione controllata del giocatore, fallimenti e aste, storico annuale, nuovi concorrenti (ADR 0012)
AiSystem giorno/mese agenti delle compagnie IA: progetti, stalli, offerte; una volta al mese (giorno diverso per IA) finanza, treni aggiuntivi, borsa, industrie, linee dei ricambi e nuovi progetti, tutto con i comandi (ADR 0013)
HashSystem giorno hash dello stato dinamico
  • Ogni sistema implementa ISimSystem.Step(WorldContext ctx); i sistemi giornalieri o mensili controllano ctx.IsNewDay / ctx.IsNewMonth e ritornano subito negli altri tick: nei 239 tick su 240 lavora solo TrainSystem.
  • SystemPipeline.Profile misura tempo e allocazioni per sistema (usato da bench).
  • WorldContext espone il mondo, i dati e il calendario; gli eventi in uscita (notifiche, notizie) vanno in World.Events, che il server svuota.
  • I comandi arrivano in una coda; il server la riempie dai socket e il sistema Commands la drena a inizio tick. Le IA eseguono i loro comandi direttamente con CommandProcessor dal sistema AiAgents (stesse validazioni, esito immediato, numeri di sequenza ≥ 0x80000000, non registrati per il replay: le IA si rigiocano da sole). Per il replay si registrano (tick, comando) in World.CommandLog.
  • I flussi pseudo-casuali dei sottosistemi si ottengono con World.Stream(nome) (derivati dalla radice con Rng.Fork, salvati per nome).

4. Determinismo

Requisito: stesso seme + stessi comandi agli stessi tick ⇒ stesso hash di stato, su Windows e Linux.

  • Un solo generatore pseudo-casuale, Rng (xoshiro256**), con un flusso per sottosistema ottenuto da Fork(nome); i flussi fanno parte del salvataggio.
  • Vietati nella simulazione: System.Random, Guid.NewGuid, DateTime.Now, Environment.TickCount, string.GetHashCode, iterazione su Dictionary/HashSet per produrre effetti, parallelismo che cambia l'ordine delle operazioni.
  • Aritmetica in virgola mobile IEEE a doppia precisione solo con operazioni elementari (+ − × ÷ √), che .NET garantisce identiche su x64 e ARM64. Le funzioni trascendenti (exp, log, pow, sin, cos, atan2) passano da DMath, implementata in Core, perché le librerie C delle piattaforme possono differire nell'ultimo bit (ADR 0003).
  • Denaro in long centesimi (Money); quantità di merci intere, con accumulatori frazionari per la produzione.
  • Lo stato è in liste ordinate per id; i dizionari sono solo indici.
  • StateHasher calcola ogni giorno un XxHash64 dello stato dinamico serializzato (il terreno, immutabile salvo opere, ha un proprio hash calcolato alla generazione e alle modifiche).

5. Dati

  • File in data/*.json, schema in data/schema/*.schema.json (sottoinsieme di JSON Schema validato da Core senza librerie esterne), deserializzazione rigorosa (proprietà sconosciute vietate, proprietà required), validazione semantica (id univoci, riferimenti risolti, limiti) in DataValidator (ADR 0002).
  • Caricamento con System.Text.Json e source generator (DataJsonContext), nessuna reflection.
  • GameData.Hash (XxHash64 dei file normalizzati) viaggia nel Welcome: client e server devono avere gli stessi dati.

6. Economia e contabilità

  • Entità in RailEnterprise.Core.Economy: Town, Industry, Hub, ResourceSite, Company (con Loan), CommuteContract, Market, Tariffs.
  • Ogni movimento di denaro passa dal registro (MoneyLedger.Transfer) tra conti: compagnie, industrie e il conto Esterno (famiglie, clienti delle tariffe, mercato mondiale). La somma di tutti i saldi è sempre zero: è l'invariante «denaro» dei test. Le voci del conto economico delle compagnie (LedgerEntry) si accumulano per mese e per anno.
  • Ogni unità di merce sta in un magazzino tracciato (industrie, città, pacchetti in stazione e a bordo dei treni) e GoodsCounters registra prodotto, consumato, deperito, importato, esportato: giacenza = prodotto + importato − consumato − deperito − esportato. È l'invariante «merci».
  • Interpretazioni delle formule della guida: ADR 0004.

7. Salvataggi

  • SaveFile: intestazione RESV leggibile senza decomprimere, corpo Brotli scritto da WorldSerializer con SaveWriter (little endian, nessuna reflection).
  • Definizioni salvate per id testuale e rimappate al caricamento; terreno salvato per intero.
  • StateHasher = XxHash64 di WorldSerializer.WriteDynamic (stato senza terreno, impostazioni ed eventi; il terreno entra con il suo hash). Dettagli: ADR 0006.
  • Corpo versione 2 (F4): MaintenanceSerializer aggiunge in coda allo stato dinamico manutenzione di veicoli e treni, officine, politiche, convenzioni e motivi dei posti scoperti; i salvataggi della versione 1 si migrano (ADR 0010).
  • Corpo versione 3 (F5): CorporateSerializer aggiunge manutenzione e proprietà delle industrie, libro dei soci, prezzi, controllo e storico delle compagnie, offerte, aste, fine partita e stato degli agenti IA (progetti, candidati scartati); i salvataggi precedenti si migrano (ADR 0012).

8. Server

  • ServerProgram: Kestrel minimale, log JSON su stdout, configurazione da ambiente (ServerConfig: RE_PORT, RE_TOKEN, RE_DATA_DIR, RE_TICK_MS, RE_AUTOSAVE_MIN, RE_SEED, RE_MAP_SIZE, RE_DIFFICULTY, RE_LOG_LEVEL) e argomenti --local (127.0.0.1 su porta casuale, stampa LISTENING porta), --healthcheck, --token, --port, --data.
  • GameHost: possiede il mondo su un thread dedicato. Ogni giro drena la coda delle azioni (messaggi delle sessioni, richieste HTTP), esegue i tick dovuti con un accumulatore (velocità 0/1/2/4/8, budget RE_TICK_MS), adegua la velocità effettiva se i tick costano troppo (slow), pubblica e fa l'autosave a rotazione.
  • Session / SessionEndpoint: WebSocket su /ws, primo frame Hello, coda d'invio a due classi (affidabili e moti scartabili), ripresa con sessionId entro 120 s.
  • Projection: mondo → record del protocollo (entità, archi, chunk, moto dei treni, resoconti, cartelle di manutenzione, registri officina, Registro degli impieghi); i delta per sessione si calcolano con gli hash dei record; i dettagli F4 si mandano su RequestDetail, gli avvisi di manutenzione (World.Alerts) come MaintenanceAlert.
  • SaveStore: salvataggi .vfsave in $RE_DATA_DIR/saves, ultimi cinque automatici; all'avvio si riprende il più recente.
  • HTTP: /health, /metrics (Prometheus), GET/POST /api/saves, GET /api/saves/{id}.
  • Docker: docker/Dockerfile (build in due stadi, utente non root, healthcheck), docker-compose.yml, unraid-template.xml; scripts/publish-image.sh per il registry Gitea.

9. Client

  • Progetto Godot 4.7 .NET in client/RailEnterprise.Client (fuori dalla soluzione), compilato con Godot.NET.Sdk; referenzia Core e Protocol (net8.0). I file dati e gli schemi si copiano in res://data a ogni build.
  • Main → MenuScreen / ConnectScreen / GameScreen. LocalServerLauncher avvia il server come processo figlio per la partita locale.
  • GameSession applica i messaggi a ClientWorld (Protocol) sul thread principale; i comandi sono l'unico modo di cambiare il mondo; le anteprime del tracciato usano TrackPreview di Core.
  • MapView (Node2D + Camera2D): TerrainLayer (texture per chunk con fasce, ombreggiatura, sponde e curve di livello; shader per le rive), EntityLayer (case, industrie, stazioni, depositi, alberi in MultiMesh), TrackLayer (massicciata, traversine, rotaie, opere, cantieri, segnali), TrainLayer (veicoli interpolati, fumo, avvisi), ToolOverlay; LabelLayer disegna le etichette in coordinate schermo.
  • HUD: TopBar, Toolbar, pannello destro (pannelli degli strumenti e schede) con Minimap, Ticker. Pannelli: binari con profilo, stazione, deposito, treni, linee, officine (politica della flotta, avvisi, flotta per condizione, cartella di manutenzione, Registro officina, scorta di ricambi, mappa di calore), impieghi (Registro degli impieghi e convenzioni), mercato, finanze, scheda dell'entità (con manutenzione del treno, lavoratori dell'industria, dove lavorano gli abitanti).
  • Collaudo: pilota automatico (-- --autopilot cartella, scripts/client-autopilot.sh) con schermate.

10. Prestazioni

  • Treni e pacchetti in liste di struct riutilizzate; nel tick ordinario si alloca meno di 1 KB (crescita delle liste), nessuna raccolta gen0 durante bench.
  • Sistemi giornalieri e mensili distribuiti: i calcoli pesanti (abbinatore del pendolarismo, pianificatore di manutenzione, IA) girano una volta al giorno o al mese.
  • Misure reali in docs/STATE.md.