- Base deterministica: Money, id tipizzati, DMath, XxHash64, calendario - 12 file dati con schemi, validatore di schema interno, validazione semantica e hash dei dati; viaferrea-tools validate-data - Generatore di mappa (rilievo, mare, priority-flood, fiumi, laghi, copertura, giacimenti, città, hub, industrie) e viaferrea-tools genmap - Economia: città, industrie, hub, mercato con componente mondiale, prezzi locali, tariffe, lavoro in sede e a piedi, trasporto locale, registro a partita doppia, prestiti, rating, difficoltà - Salvataggi Brotli con rimappatura per id e hash di stato giornaliero - viaferrea-tools simulate con KPI CSV; 45 test verdi; ADR 0002-0006 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0191R7vXgtbAvSV4V8tj8uzL
9.2 KiB
9.2 KiB
Via Ferrea — 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
ViaFerrea.Core (net10.0; net8.0) simulazione deterministica, dati, mappa, economia, rete, salvataggi
ViaFerrea.Protocol (net10.0; net8.0) frame binari, messaggi, SpanWriter/SpanReader → Core
ViaFerrea.Server (net10.0, Web SDK) Kestrel, WebSocket, GameLoop, API HTTP, autosave → Core, Protocol
ViaFerrea.Tools (net10.0) viaferrea-tools: validate-data, genmap, profile, simulate, bench, replay → Core, Protocol
ViaFerrea.Tests (net10.0) harness interno, test di unità, scenari → Core, Protocol, Server
client/ViaFerrea.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 |
|---|---|
ViaFerrea.Core.Common |
Rng (xoshiro256**), StableHash, XxHash64, DMath (funzioni trascendenti deterministiche), Money, identità tipizzate, Vec2. |
ViaFerrea.Core.Time |
GameClock, GameDate, costanti di calendario. |
ViaFerrea.Core.Data |
Definizioni immutabili caricate da data/*.json (GameData), contesto JSON con source generator, validatore di schema e validatore semantico. |
ViaFerrea.Core.Map |
Terrain (altezze ushort in decimetri, tipi cella byte, larghezza dei fiumi), MapGenerator (ADR 0005), ValueNoise, TerrainSampler, NameGenerator, chunk 64×64. |
ViaFerrea.Core.Economy |
Città, industrie, hub, mercato, compagnie, registro contabile a partita doppia, finanza. |
ViaFerrea.Core.Rail (F2) |
TrackPlanner, opere e cantieri, TrackGraph, stazioni, depositi, segnali, treni, linee, LineGraph, pacchetti, tariffe. |
ViaFerrea.Core.Commands |
Comandi di gioco (record immutabili) ed esiti. Sono l'unico modo di cambiare il mondo dall'esterno, anche per le IA. |
ViaFerrea.Core.Simulation |
World, WorldContext, SystemPipeline e Systems/, WorldFactory, IndustryPlacer, CommandProcessor, eventi in uscita. |
ViaFerrea.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), 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 |
LocalTransportSystem |
giorno | trasporto locale su strada tra produttori, consumatori e hub entro 3 km (posto di «Stations», ADR 0004) |
DemandSystem |
giorno | domanda delle città (con elasticità) e input richiesti dalle industrie |
EmploymentSystem |
giorno/mese | servizi cittadini, lavoratori in sede, contratti a piedi; presenze e coperture (posto di «Commuting») |
IndustrySystem |
giorno/trimestre/anno | produzione, esaurimento giacimenti, salari, crescita delle industrie servite, chiusure, nascite |
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 | cassa negativa e bancarotta, rate dei prestiti, rating, chiusura dei conti |
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: 239 tick su 240 costano pochi nanosecondi finché non arrivano i treni. 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, le IA dal proprio sistema; il sistema
Commandsla drena a inizio tick. 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
ViaFerrea.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à; da F2 stazioni, depositi, treni, pacchetti) 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: intestazioneVFSVleggibile 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.
8. Server (pianificato, F3)
GameLoopsu thread dedicato con accumulatore: a velocità v esegue v tick ogni 50 ms reali; se un tick supera il budget riduce la velocità effettiva e segnalaslownel resoconto giornaliero.SessionManager: WebSocket su/ws, autenticazione con token nell'Hello, coda di invio per sessione con backpressure, riconnessione consessionId, interesse per viewport.- API HTTP:
/health,/metrics(Prometheus),/api/saves.
9. Client (pianificato, F3)
- Scene Godot:
Main→Menu,Connect,Game(MapView+Hud+Panels/). - Livelli di rendering: terreno per chunk (texture con fasce altimetriche, hillshade, curve di livello), binari e opere, entità, treni interpolati; LOD a zoom ridotto.
LocalServerLauncheravvia il server come processo figlio per la partita in locale.
10. Prestazioni
- Treni e pacchetti in array di struct, nessuna allocazione nel tick.
- 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.