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>
130 lines
15 KiB
Markdown
130 lines
15 KiB
Markdown
# 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`.
|