Dal livello che sblocca il commercio la compagnia può comprare e vendere merci in proprio. Così può fare arbitraggio tra un produttore con il magazzino pieno e un consumatore a secco anche dove il vettore non ha contratti. Le regole sono nell'ADR 0016. - Ogni stazione della compagnia ha un magazzino: 500 unità e una giacenza di 25 centesimi per unità al mese, in balance.json, blocco «trading». La merce in magazzino rientra nell'invariante delle merci. - BuyGoods compra al prezzo locale marginale dell'ADR 0004, unità per unità, partendo dal più economico, dai produttori del bacino e dagli hub. La merce presa dagli hub conta come importata. - SellGoods vende ai consumatori del bacino partendo dal prezzo più alto, entro lo spazio libero e la cassa di ciascuno. Vende anche agli hub, e quella merce conta come esportata. - Il denaro di entrambi i comandi passa dal registro, sulla voce «Commercio». - ShipGoods (comando 40) spedisce la merce propria come pacchetto senza tariffa né consumatore. Il pacchetto entra nel magazzino di destinazione, che riserva lo spazio alla partenza. Il percorso dei pacchetti già esistenti non cambia: l'accettazione F4 dà ancora 35/20 guasti senza la linea e 75/2 con la linea. - Il salvataggio passa al corpo versione 4 (TradingSerializer). I salvataggi più vecchi si caricano con i magazzini vuoti, e i magazzini entrano nell'hash di stato. - MarketReport porta i magazzini nel blocco 1. Il Mercato globale ha il riquadro «Compravendita in proprio». - Le IA non commerciano ancora. Refs #31. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
16 KiB
16 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;MarketOutlook(F6, ADR 0015) è l'analisi in sola lettura per il pannello «Mercato globale»: storico mensile, previsione dalla componente mondiale, destinazioni di vendita, hub, evento in corso, avanzamento verso il commercio. - 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à, magazzini delle compagnie nelle stazioni, pacchetti in stazione e a bordo dei treni) e
GoodsCountersregistra prodotto, consumato, deperito, importato, esportato: giacenza = prodotto + importato − consumato − deperito − esportato. È l'invariante «merci». - Compravendita in proprio (F6, ADR 0016):
TradingCommandHandlersesegueBuyGoods,SellGoodseShipGoodscon il prezzo locale marginale diSystems/TradingMath(unità per unità, controparti ordinate per prezzo). La merce comprata sta inStation.Stock; quella spedita viaggia in pacchetti conPacket.Owned, senza tariffa né consumatore, ed entra nel magazzino della stazione d'arrivo. Gli scambi con le industrie passano dal registro sulla voce «Commercio», quelli con gli hub contano come importazione ed esportazione;StationSystemaddebita ogni mese la giacenza dei magazzini. - 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). - Corpo versione 4 (F6):
TradingSerializeraggiunge i magazzini delle compagnie nelle stazioni (beni per id testuale) e gli id dei pacchetti di merce propria in stazione e a bordo; i salvataggi precedenti si caricano con i magazzini vuoti.WorldSerializer.Write(w, s, versione)scrive un corpo di una versione precedente per i test di migrazione (ADR 0016).
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.