Files
Rail_Enterprise/docs/ARCHITECTURE.md
T
Claude 7cb98fa206 F1: economia headless, dati validati, generatore di mappa e salvataggi
- 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
2026-10-01 22:38:17 +00:00

9.2 KiB
Raw Blame History

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 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
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 controllano ctx.IsNewDay / ctx.IsNewMonth e ritornano subito negli altri tick: 239 tick su 240 costano pochi nanosecondi finché non arrivano i treni.
  • 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, le IA dal proprio sistema; il sistema Commands la drena a inizio tick. 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 ViaFerrea.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à; da F2 stazioni, depositi, treni, pacchetti) 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 VFSV 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.

8. Server (pianificato, F3)

  • GameLoop su 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 segnala slow nel resoconto giornaliero.
  • SessionManager: WebSocket su /ws, autenticazione con token nell'Hello, coda di invio per sessione con backpressure, riconnessione con sessionId, 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.
  • LocalServerLauncher avvia 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.