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>
15 KiB
15 KiB
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 dascripts/check-nuget.sh). Il solo SDK esterno èGodot.NET.Sdknel 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 controllanoctx.IsNewDay/ctx.IsNewMonthe ritornano subito negli altri tick: nei 239 tick su 240 lavora soloTrainSystem. SystemPipeline.Profilemisura tempo e allocazioni per sistema (usato dabench).WorldContextespone il mondo, i dati e il calendario; gli eventi in uscita (notifiche, notizie) vanno inWorld.Events, che il server svuota.- I comandi arrivano in una coda; il server la riempie dai socket e il sistema
Commandsla drena a inizio tick. Le IA eseguono i loro comandi direttamente conCommandProcessordal sistemaAiAgents(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)inWorld.CommandLog. - I flussi pseudo-casuali dei sottosistemi si ottengono con
World.Stream(nome)(derivati dalla radice conRng.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 daFork(nome); i flussi fanno parte del salvataggio. - Vietati nella simulazione:
System.Random,Guid.NewGuid,DateTime.Now,Environment.TickCount,string.GetHashCode, iterazione suDictionary/HashSetper 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 daDMath, implementata in Core, perché le librerie C delle piattaforme possono differire nell'ultimo bit (ADR 0003). - Denaro in
longcentesimi (Money); quantità di merci intere, con accumulatori frazionari per la produzione. - Lo stato è in liste ordinate per id; i dizionari sono solo indici.
StateHashercalcola 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 indata/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) inDataValidator(ADR 0002). - Caricamento con
System.Text.Jsone source generator (DataJsonContext), nessuna reflection. GameData.Hash(XxHash64 dei file normalizzati) viaggia nelWelcome: client e server devono avere gli stessi dati.
6. Economia e contabilità
- Entità in
RailEnterprise.Core.Economy:Town,Industry,Hub,ResourceSite,Company(conLoan),CommuteContract,Market,Tariffs. - Ogni movimento di denaro passa dal registro (
MoneyLedger.Transfer) tra conti: compagnie, industrie e il contoEsterno(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
GoodsCountersregistra prodotto, consumato, deperito, importato, esportato: giacenza = prodotto + importato − consumato − deperito − esportato. È l'invariante «merci». - Interpretazioni delle formule della guida: ADR 0004.
7. Salvataggi
SaveFile: intestazioneRESVleggibile senza decomprimere, corpo Brotli scritto daWorldSerializerconSaveWriter(little endian, nessuna reflection).- Definizioni salvate per id testuale e rimappate al caricamento; terreno salvato per intero.
StateHasher= XxHash64 diWorldSerializer.WriteDynamic(stato senza terreno, impostazioni ed eventi; il terreno entra con il suo hash). Dettagli: ADR 0006.- Corpo versione 2 (F4):
MaintenanceSerializeraggiunge 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):
CorporateSerializeraggiunge 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, stampaLISTENING 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, budgetRE_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 frameHello, coda d'invio a due classi (affidabili e moti scartabili), ripresa consessionIdentro 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 suRequestDetail, gli avvisi di manutenzione (World.Alerts) comeMaintenanceAlert.SaveStore: salvataggi.vfsavein$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.shper il registry Gitea.
9. Client
- Progetto Godot 4.7 .NET in
client/RailEnterprise.Client(fuori dalla soluzione), compilato conGodot.NET.Sdk; referenzia Core e Protocol (net8.0). I file dati e gli schemi si copiano inres://dataa ogni build. Main→MenuScreen/ConnectScreen/GameScreen.LocalServerLauncheravvia il server come processo figlio per la partita locale.GameSessionapplica i messaggi aClientWorld(Protocol) sul thread principale; i comandi sono l'unico modo di cambiare il mondo; le anteprime del tracciato usanoTrackPreviewdi 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;LabelLayerdisegna le etichette in coordinate schermo.- HUD:
TopBar,Toolbar, pannello destro (pannelli degli strumenti e schede) conMinimap,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.